The agent that turns websites into APIs!
docs: design guidelines + LLM design-generator prompt (#91)
kalil0321e1a107338fcb
diff --git a/.gitignore b/.gitignoreindex 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.mddiff --git a/design/PROMPT.md b/design/PROMPT.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.**