Skip to content

The agent that turns websites into APIs!

docs: design guidelines + LLM design-generator prompt (#91)

kalil0321e1a107338fcb
diff --git a/.gitignore b/.gitignore
index 6bea211..9772cd9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -118,3 +118,6 @@ macos/DerivedData/
# Claude Code harness internals
.claude/
+
+# keep the committed design prompt (the broad prompt*.md rule above would hide it)
+!design/PROMPT.md
diff --git a/design/PROMPT.md b/design/PROMPT.md
new file mode 100644
index 0000000..014a4eb
--- /dev/null
+++ b/design/PROMPT.md
@@ -0,0 +1,103 @@
+# The generator prompt
+
+Paste everything between the rulers into a capable LLM. Fill in the two
+`{{...}}` blocks. For on-brand `rae` work, also paste the contents of
+`design-system.md` where indicated. For a brand-new project, delete that line
+and let the model propose a system first.
+
+---
+
+You are a senior product designer and front-end engineer with a strong,
+specific point of view. Your job is to produce **distinctive, production-grade
+UI that does NOT look AI-generated.** Generic, templated, "AI-slop" output is a
+failure, even if it's technically clean.
+
+## What AI-slop looks like (never produce this)
+- Three or four identical feature cards in a row, a generic icon on top of each.
+- Default framework blue/violet as the primary color; everything the same
+ border-radius with the same soft drop-shadow.
+- One sans-serif doing all the typographic work; no display face, no point of view.
+- Centered hero → feature grid → pricing → FAQ in that exact order, no surprises.
+- Filler copy: "Empower your workflow", "Seamlessly integrate", "Supercharge".
+- Symmetry everywhere, no focal point, motion that's just "fade up on scroll."
+
+## The principles you design by
+1. **One strong, nameable idea per section.** Decide the concept in ≤3 words
+ ("split-flap departure board", "boarding-pass handoff", "alternating spine")
+ BEFORE you lay anything out. If you can't name it, it's generic — redo it.
+2. **Steal structure from the physical world.** Tickets, departure boards, slot
+ machines, circuit boards, film strips, passport stamps, dials, conveyor belts.
+ Ask "what real object is this data like?" These carry instant meaning.
+3. **Typographic point of view.** Pair a characterful DISPLAY face (a serif with
+ real personality — high contrast, expressive italic, optical sizing) with a
+ functional body face and a mono for technical texture. Use the display face big.
+4. **Constrained palette, used boldly.** One ink, one warm paper (not pure
+ #fff/#000), 3–4 soft accents, and exactly ONE loud accent that appears rarely
+ and always means something. Never the default framework blue. Prefer full-bleed
+ color blocks over timid tinted cards.
+5. **A signature motif, repeated.** One small recurring mark (an asterisk, a
+ specific arrow, a corner cut, a dotted seam) that rhymes across sections.
+6. **Asymmetry & rhythm over uniform grids.** Break the row-of-identical-cards.
+ Alternate sides, stagger heights, give one element more weight, offset on purpose.
+7. **Motion that means something.** A marquee = "ongoing"; hover-pause = "inspect";
+ a turning dial = "swappable". Cut motion that doesn't reinforce the concept.
+ Always respect `prefers-reduced-motion`.
+8. **Sweat the 5%.** 1.5px borders, hard offset shadows (`3px 3px 0`) not blurs,
+ optical letter-spacing on big type, hairline dividers, tiny wide-tracked mono
+ labels, edges that fade rather than hard-cut.
+9. **Tokens, not magic values.** Every color/font/radius comes from a named
+ variable so the whole thing stays coherent and theme-able. (Exception: an
+ intentionally "physical" object may use literal values to read as real.)
+10. **Generate many, keep few.** Breadth first, then ruthless selection.
+
+## How to respond
+Work **one section at a time**. For the section I give you, produce a
+**gallery of 8–15 genuinely different variants** — different *concepts*, not
+recolors of one idea. For EACH variant output:
+
+- **Name** (≤3 words) and a one-sentence description of the concept.
+- The **real-world metaphor** it borrows from (or "none — pure editorial").
+- The **implementation**: a self-contained {{FRAMEWORK — e.g. React + Tailwind
+ v4}} component. Use design tokens, not hardcoded values. Make it responsive,
+ accessible, and reduced-motion-safe.
+- A one-line note on **why it avoids AI-slop**.
+
+Lay them out as a labelled gallery (each variant in a titled frame) so they can
+be compared at a glance, exactly like an internal design "lab" page. Do not try
+to perfect one design — give me breadth so I can pick the 1–2 that sing. After
+the gallery, name your own top 2 picks and say why.
+
+Hard rules: no generic icon-on-top feature-card grids; no default blue; at least
+one variant must use a non-obvious physical-world metaphor; vary layout
+structure (not just color) between variants; every interactive/animated variant
+must degrade gracefully.
+
+## The design system to work within
+{{For on-brand rae work, PASTE the contents of `System_Design.md` (the canonical
+tokens, fonts + Fraunces axes, icons, shapes) AND `design-system.md` (the rules
+of use — palette discipline, the asterisk motif, neo-brutalist shadows, the
+no-lucide-on-brand stance). If starting a NEW project, instead write: "Propose a
+complete design system first (palette with one loud accent, a display+body+mono
+type trio, one signature motif, a shadow/shape language), then design the section
+within it."}}
+
+## The section to design
+{{DESCRIBE THE SECTION: what content it holds, the message it must land, where
+it sits on the page, any must-have elements. Example: "A 'works with your
+agent' section. Message: the tool ships no model of its own — it auto-detects
+and drives whichever AI coding agent you already use (Claude Code, Cursor,
+GitHub Copilot, OpenCode, and more). Sits between 'how it works' and the
+footer. Must use the real brand logos."}}
+
+---
+
+## Tips for driving this prompt well
+
+- **One section per request.** The quality drops if you ask for a whole page at once.
+- **Feed it the real system.** Pasting `System_Design.md` + `design-system.md`
+ is what keeps 12 variants coherent instead of 12 unrelated styles.
+- **Ask for more if nothing sings.** "Give me 10 more, weirder this time, lean
+ into physical-object metaphors" is a great follow-up.
+- **Then promote.** Take the 1–2 winners, ask the model to harden them
+ (tokens, dark mode, reduced-motion, build-clean), and ship those only.
+- **Keep the gallery disposable.** It's a sketchbook — don't ship it.
diff --git a/design/README.md b/design/README.md
new file mode 100644
index 0000000..07eed48
--- /dev/null
+++ b/design/README.md
@@ -0,0 +1,144 @@
+# Design guidelines — how to make work that doesn't look AI-generated
+
+This folder captures the approach behind the `rae` marketing site and its `/lab`
+design playground, so the same level of quality can be reproduced — by you, by
+other people, or by another LLM.
+
+- **README.md** (this file) — the methodology. The *why* and the *how*. Project-agnostic.
+- **design-system.md** — the *opinionated layer* on `rae`'s system: the rules of
+ use, the personality, the judgement. Project-specific.
+- **PROMPT.md** — a paste-into-any-LLM prompt that generates this caliber of design.
+- **examples.md** — a worked case study: the actual lab variants and why they work.
+
+> **The canonical token/asset reference is [`../System_Design.md`](../System_Design.md)**
+> — the exact palette, functional tokens, fonts + Fraunces axes, icon inventory,
+> and shape/radius specs, mirrored from `website/src/app/global.css`. The
+> `design-system.md` here deliberately does **not** repeat those tables; it adds
+> the usage rules on top. Need a hex or a radius → read `System_Design.md`.
+
+---
+
+## The core problem: "AI slop"
+
+Most LLM-generated UI converges on the same look: a centered hero, three
+equal feature cards with a generic icon on top, a pricing table, lots of
+`indigo-600`, evenly rounded corners, drop shadows everywhere, and zero point
+of view. It's competent and completely forgettable.
+
+The goal here is the opposite: **interfaces with a specific, deliberate
+personality** — work that looks like a human with taste made a hundred small
+decisions, because they did.
+
+---
+
+## The 10 principles
+
+### 1. Commit to one strong idea per section
+Every section should have a single concept you could name in three words.
+"Split-flap departure board." "Alternating spine timeline." "Boarding-pass
+handoff." If you can't name it, it's probably generic. The concept comes
+*before* the layout — decide what the section *is* metaphorically, then build it.
+
+> Bad: "a grid of the supported integrations."
+> Good: "an airport split-flap board where each integration is a departure."
+
+### 2. Steal structure from the physical world
+The most memorable variants borrow from objects people already understand:
+tickets, departure boards, slot machines, circuit boards, film strips, passport
+stamps, rotary dials. These carry built-in meaning and instantly feel
+intentional. When stuck, ask: *"What real-world object is this data like?"*
+
+### 3. Have a typographic point of view
+Generic design uses one sans-serif at three sizes. Distinctive design pairs a
+**characterful display face** (a serif with real personality — high contrast, an
+italic with flair, optical sizing) against a **functional body face** and a
+**mono** for technical texture. The display face is the voice; use it big and
+let it carry the brand.
+
+### 4. Constrain the palette, then use it boldly
+Pick a small palette (one ink, one paper, 3–4 soft accents, **one** loud accent)
+and commit. The loud accent appears rarely and always means something. Avoid the
+default framework blue. Warm neutrals (creams, off-whites) read more crafted than
+pure `#fff`/`#000`. Full-bleed color blocks beat timid tinted cards.
+
+### 5. Pick a signature motif and repeat it
+One small recurring element ties everything together: an asterisk, a specific
+arrow, a corner cut, a dotted seam. It should show up across sections like a
+visual rhyme. Repetition of a deliberate detail reads as "designed"; randomness
+reads as "generated."
+
+### 6. Asymmetry and rhythm over uniform grids
+Three identical cards in a row is the AI-slop default. Break it: alternate
+left/right, stagger heights, give one element more weight (a hero cell, a
+bento), offset things on purpose. Uniformity is safe and boring; controlled
+imbalance creates rhythm and draws the eye.
+
+### 7. Motion and interaction must mean something
+Animation is not decoration. A marquee implies "ongoing." A pause-on-hover
+implies "inspect this." A dial that turns implies "swappable." If an
+interaction doesn't reinforce the concept, cut it. And it must respect
+`prefers-reduced-motion`.
+
+### 8. Sweat the micro-details
+The gap between "fine" and "great" is in the 5%: a 1.5px border instead of 1px,
+a hard offset shadow (`3px 3px 0`) instead of a soft blur, optical letter-spacing
+on big type, a hairline divider, a mono label at `text-[10px]` with wide tracking,
+edges that fade instead of hard-cut. These are individually invisible and
+collectively everything.
+
+### 9. Design tokens, never magic values
+Pull every color, font, and radius from named variables — never hardcode a hex
+that should be a token. This keeps a sprawling design coherent and makes
+dark-mode / re-theming trivial. The one exception: an intentionally "physical"
+object (a dark terminal, a departure board) may use literal values because it's
+meant to read as a real-world thing on any background.
+
+### 10. Generate many, keep few
+Don't iterate one design to death. Produce **8–15 genuinely different takes** on
+the same content in a throwaway gallery (a `/lab` page), look at them together,
+and promote the 1–2 that sing. Breadth first, then ruthless selection. Most
+will be mediocre; that's the point — you're hunting for the two that aren't.
+
+---
+
+## The process that produced this site
+
+1. **Establish the system first.** Tokens, fonts, one motif, the palette —
+ captured in `../System_Design.md` (the raw tokens) and `design-system.md`
+ (the rules of use). Everything downstream pulls from it.
+2. **Build a `/lab`.** An internal, unlinked, gitignored route that's a gallery
+ of labelled variants. Each variant is wrapped in a frame with a one-line
+ description of its concept. This is the sketchbook.
+3. **Fan out.** For each section, write 5–15 variants with genuinely different
+ *concepts* (not just recolors). Name each one.
+4. **Review together, then cut.** Look at the whole gallery at once. Promote the
+ standouts into real components; delete the rest.
+5. **Polish the winner.** Port it out of the lab, swap magic values for tokens,
+ make it theme-aware and reduced-motion-safe, verify it builds.
+
+The lab is disposable scaffolding. Its value is the breadth of exploration, not
+the code — keep it local (gitignored), never ship it.
+
+---
+
+## Anti-patterns — if you're doing these, stop
+
+- Three (or four) identical feature cards, icon-on-top, in a tidy row.
+- A generic icon library used as decoration (lucide's `Bot` etc. — instant "AI").
+- Default framework blue / violet as the primary color.
+- Everything the same border-radius, same soft drop-shadow.
+- One sans-serif doing all the typographic work.
+- Centered-hero → features → pricing → FAQ, in that exact order, with no surprises.
+- Motion that's just "fade up on scroll" with no meaning.
+- Filler copy ("Empower your workflow", "Seamlessly integrate", "Supercharge").
+- Symmetry everywhere; no focal point; no point of view.
+
+---
+
+## How to use this with an LLM
+
+Open `PROMPT.md`, paste it into a capable model, and append your project's
+brief + (optionally) the contents of `design-system.md`. Ask it to produce a
+`/lab`-style gallery of named variants for one section at a time, then you pick.
+Quality comes from *breadth then selection* — instruct it to generate many,
+not to perfect one.
diff --git a/design/design-system.md b/design/design-system.md
new file mode 100644
index 0000000..d8c556e
--- /dev/null
+++ b/design/design-system.md
@@ -0,0 +1,105 @@
+# rae — design system (the opinionated layer)
+
+> **Canonical token/asset reference: [`../System_Design.md`](../System_Design.md).**
+> That file is the source of truth for the exact palette, functional tokens,
+> fonts + Fraunces axis values, icon inventory, and shape/radius specs — pulled
+> from `website/src/app/global.css`. **Don't duplicate it here.** When you need a
+> hex, a font fallback, or a radius, read it there.
+>
+> This file adds what `System_Design.md` doesn't: the *personality*, the *rules
+> of use*, and the *why*. It's the judgement layer on top of the raw tokens.
+
+The personality in one line: **warm editorial-tech** — a cream paper canvas, a
+high-character serif (Fraunces) used big and italic, monospace for technical
+texture, a single hot-pink accent, and neo-brutalist hard-offset shadows.
+Playful but precise.
+
+---
+
+## Rules of use (the judgement `System_Design.md` doesn't encode)
+
+**Palette**
+- The page is always `cream`. Full-bleed sections alternate among the soft
+ pastels (`orange` / `sky` / `mint` / `washed`) — never let two adjacent
+ sections share a background.
+- `fd-primary` (hot pink) is the **only** loud color and it's used *sparingly*:
+ the asterisk motif, **one** accent word per heading (via `<em>`), node dots,
+ the offset shadow on the primary button. If pink is showing up everywhere,
+ pull it back — its power is its rarity.
+- Borders are hairlines mixed from ink
+ (`color-mix(in oklch, var(--color-ink) 12%, transparent)`), not solid black.
+- Always use the **token** (`bg-cream`, `text-ink`, `text-fd-primary`), never the
+ raw hex — so dark mode and re-theming just work.
+- **The one exception:** an intentionally *physical* object — a dark terminal, the
+ departure board (`#0d0a07`, `#1c1c1c`) — may use literal near-black values, so
+ it reads as a real object sitting on any background. `System_Design.md` lists
+ these under "Visible Hardcoded Colors"; that list should stay *short* and
+ deliberate, not grow.
+
+**Type**
+- Headings are **display serif (Fraunces) with one word in pink italic** via
+ `<em>` — e.g. *"Works with the agent **you already use.**"* That single
+ contrast is the house style.
+- Mono (JetBrains) is for *technical texture*: eyebrows, tiny wide-tracked
+ labels, status chips, code, numbers. Reach for it to make something feel
+ "engineered."
+- Use the expressive italic axis (`'SOFT' 100, 'WONK' 1`) for flourish; steadier
+ axes for workhorse headings. (Exact values live in `System_Design.md`.)
+
+**The asterisk motif `*`**
+- The recurring brand mark. A Fraunces italic `*` in pink. Float it in section
+ corners at low opacity (`rotate-12` / `-rotate-12`), use it as the marquee
+ divider, keep it in the logo. **Reach for it before inventing a new
+ decoration** — it's the visual rhyme that ties unrelated sections together.
+
+**Shape & shadow (neo-brutalist)**
+- Prefer **hard offset shadows** (`3px 3px 0 0`, `4px 4px 0 0 var(--color-ink)`)
+ over soft blur. The primary button *presses* on hover (shadow collapses to
+ `1px 1px 0`, element nudges `translate(2px,2px)`).
+- Bold elements get a `1.5px` ink border; quiet cards get a hairline ink-mix.
+- Keep radii consistent (the set is in `System_Design.md`), not random per element.
+
+---
+
+## Motion (not covered in System_Design.md)
+
+- **Seamless marquee:** `marquee-track` + `@keyframes marquee-scroll` translate
+ `-50%`. Bake spacing into each cell (`pr-*`), **never a flex `gap` on the
+ animated track** — a gap breaks the loop's periodicity and it stutters. Repeat
+ the set enough times that one half exceeds the viewport, or you'll see an empty
+ gap before it repeats. `marquee-viewport:hover` pauses it.
+- Transitions are short (`~180ms`) with `cubic-bezier(0, 0, 0.2, 1)`.
+- **Every animation must degrade** under `@media (prefers-reduced-motion: reduce)`.
+- Motion must *mean* something (a marquee = "ongoing", hover-pause = "inspect", a
+ turning dial = "swappable"). Decorative motion gets cut.
+
+**Lightning CSS gotcha:** a custom rule whose first declaration is `display: flex`
+can be dropped when it collides with Tailwind's `flex` utility. Apply `flex` as a
+utility class on the element and keep the rest of the rule in CSS.
+
+---
+
+## Iconography stance (the opinion behind the inventory)
+
+`System_Design.md` lists *what* icons exist. The *rules*:
+
+- **No `lucide-react` on brand/marketing surfaces.** Its generic style (esp.
+ `Bot`) reads as AI-slop. (lucide is fine for plain UI affordances — copy,
+ theme toggle, arrows.) Brand/feature icons use **`@phosphor-icons/react`
+ duotone**.
+- **Real brand logos come from `simple-icons`** (monochrome single-path,
+ rendered at `currentColor`). If a brand is missing (e.g. OpenCode), **draw a
+ faithful custom mark from its favicon** — never substitute a generic glyph.
+ See `website/src/components/brand-logos.tsx`.
+
+---
+
+## Worked exemplar: "Works with your agent"
+
+Concept: an **airport split-flap departure board**. Each supported agent is a
+row — its real logo, its name spelled in individual flap tiles (`bg-[#1c1c1c]`,
+mono, inset bottom shadow), and a pink `SUPPORTED` status. The board is a dark
+physical object (`#0d0a07` rounded card) sitting on a `mint` section; one small
+display-serif heading with the pink-italic accent word sits underneath. See
+`website/src/components/works-with-agents.tsx`, and the full 16-variant
+exploration in [`examples.md`](./examples.md).
diff --git a/design/examples.md b/design/examples.md
new file mode 100644
index 0000000..5463baf
--- /dev/null
+++ b/design/examples.md
@@ -0,0 +1,109 @@
+# Case study — the rae `/lab` variant galleries
+
+The `rae` site was designed by building an internal, gitignored `/lab` route
+(`website/src/app/lab/page.tsx`) that held labelled galleries of variants for
+each section, then promoting the standouts into real components. This is that
+worked example: the concepts explored, what shipped, and why.
+
+> The lab itself is **not committed** (it's in `website/.gitignore`). It's a
+> sketchbook — its value is the breadth of exploration, not the code.
+
+---
+
+## Section 1 — feature marquee (under the hero)
+
+A scrolling band of trust-signal tags. Four variants explored:
+
+| Variant | Concept |
+|---|---|
+| M1 — Seamless mono ticker | dark band, mono tags, pink `*` dividers |
+| M2 — Terminal status bar | a pinned `● live` badge; tags stream like a CLI log |
+| M3 — Editorial serif | big Fraunces italic on cream, magazine masthead |
+| M4 — Dual counter-scroll | two rows drifting opposite directions |
+
+**Shipped: M1**, refined — `website/src/components/feature-marquee.tsx`. Tags:
+*MIT licensed · Runs locally · No telemetry · Works with agents*, each with a
+Phosphor **duotone** icon (no lucide), cream not pink.
+
+**Lessons that became rules:**
+- The original marquee stuttered because it put a flex `gap` *between* the two
+ duplicated halves — that breaks the `-50%` loop's periodicity. Fix: bake
+ spacing into each cell (`pr-*`), zero gap on the track.
+- With only four short tags, one half was narrower than the viewport, so you saw
+ an empty gap before it repeated. Fix: repeat the set N× per half until it
+ exceeds any screen.
+- Icons should be **one cream tone**, brighter than the text — not pink. A band
+ that's pink everywhere loses the accent.
+
+---
+
+## Section 2 — "how it works" (four steps)
+
+Started with the AI-slop default (four identical cards in a row) and deliberately
+replaced it. ~14 variants explored, including:
+
+S1 connected timeline · S3 editorial big-number · S4 interactive tabs (clean
+code card, **no fake terminal chrome**) · S5 pipeline node graph · S6 vertical
+rail with progress fill · S9 rotated index cards · S10 flow chips · S11 color-
+block quarters · S12 staggered staircase · **S13 alternating spine** · S14
+spec-sheet rows.
+
+**Shipped: S13 — alternating spine.** Steps zig-zag left/right off a vertical
+center line with pink node dots. See `HowItWorks` in
+`website/src/app/(home)/page.tsx`. (The step numbers were later removed — the
+dots carry the rhythm.)
+
+**Lesson:** the four-identical-cards layout is the thing to *avoid*. Asymmetry
+(the alternating spine) instantly reads as designed rather than generated.
+
+---
+
+## Section 3 — "works with your agent" (the standout)
+
+The brief: convey that rae ships no model — it auto-detects and drives whichever
+coding agent you already use (Claude Code, Cursor, GitHub Copilot, OpenCode).
+**16 variants** explored, each a different physical-world metaphor:
+
+| Variant | Metaphor |
+|---|---|
+| A1 — Orbit | logos orbit the rae `*` on dashed rings |
+| A3 — Plug & socket | each agent plugs into a rae socket |
+| A4 — Boarding-pass handoff | the brand's ticket motif: HAR → your agent → client.py |
+| A6 — Swappable slot | interactive `rae + [ agent ]` picker |
+| A8 — Sticker sheet | rotated die-cut logo stickers, offset shadows |
+| A9 — Relay baton | capture → agent writes → rae reviews |
+| A11 — Slot-machine reels | three reels of logos, "always lands on your agent" |
+| A12 — Conveyor belt | HAR rides a belt through the rae machine |
+| A13 — Constellation | agents as stars wired to a glowing rae core |
+| A14 — Rotary dial | a selector that points at your agent |
+| A15 — Passport stamps | inked "certified to run with" stamps |
+| A16 — Isometric blocks | agent blocks feeding the taller rae block |
+| A17 — Command palette | a ⌘K `rae use <agent>` picker |
+| A18 — Filmstrip | agents as frames with sprocket holes |
+| A19 — Circuit board | logos wired via PCB traces to the rae chip |
+| **A20 — Split-flap board** | **airport departure board; each agent is a "departure"** |
+
+**Shipped: A20 — split-flap departure board.**
+`website/src/components/works-with-agents.tsx`. Each agent is a row: real logo
+(simple-icons; a custom mark for OpenCode), its name in individual flap tiles
+(`bg-[#1c1c1c]`, mono, inset bottom shadow), a pink `SUPPORTED` status. The dark
+board sits as a physical object on a `mint` section, with one small display-serif
+heading underneath.
+
+**Lessons:**
+- Real brand logos > generic icons. Pull from `simple-icons`; for a missing
+ brand, draw a faithful custom mark from its favicon — don't substitute a
+ generic glyph.
+- The winner reused an existing motif (the boarding-pass/ticket already on the
+ page), which is why A4 and A20 both felt "of the brand." Reuse beats inventing.
+- Generating 16 and keeping 1 is the method, not waste. The split-flap idea
+ wasn't in the first batch of 10 — it came from a second "give me 10 more,
+ weirder" pass.
+
+---
+
+## The takeaway
+
+None of the shipped sections is "a card grid." Each is a *named object* from the
+physical world, executed inside one tight design system. That's the whole trick:
+**concept first, breadth of exploration, ruthless selection, then polish.**