docs: design guidelines + LLM design-generator prompt

.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

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.

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.

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).