Skip to content

The agent that turns websites into APIs!

docs: consolidate System_Design.md into design/design-system.md

kalil0321a7357ef32368
diff --git a/System_Design.md b/System_Design.md
deleted file mode 100644
index 8466af3..0000000
--- a/System_Design.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# System Design
-
-Quick reference for the design system used by `reverse-api-website`.
-
-## Core Colors
-
-These are the canonical color tokens defined in `website/src/app/global.css`.
-
-| Token | Light | Dark | Usage |
-| --- | --- | --- | --- |
-| `--color-ink` | `#1f1f1f` | `#fff7f0` | Primary text, dark surfaces, strong borders |
-| `--color-ink-soft` | `#1f1f1fcc` | `#fff7f0bb` | Secondary text |
-| `--color-cream` | `#fff7f0` | `#14110e` | Main background |
-| `--color-cream-soft` | `#fef8ee` | `#1c1814` | Slightly raised surfaces |
-| `--color-orange` | `#ffe7d4` | `#3a1d0e` | Warm secondary section color |
-| `--color-sky` | `#d6efff` | `#0d1b2e` | CTA section color |
-| `--color-mint` | `#d5f1de` | `#0e2419` | Positive accent / completed state |
-| `--color-washed` | `#f5f2ee` | `#1a1612` | Washed neutral background |
-
-## Functional Colors
-
-Tokens used by Fumadocs and shared components.
-
-| Token | Light | Dark | Usage |
-| --- | --- | --- | --- |
-| `--color-fd-background` | `#fff7f0` | `#14110e` | App background |
-| `--color-fd-foreground` | `#1f1f1f` | `#fff7f0` | App foreground text |
-| `--color-fd-primary` | `#e50d75` | `#ff3d8b` | Pink accent, asterisk, links, CTA shadows |
-| `--color-fd-primary-foreground` | `#fff7f0` | `#14110e` | Text on primary accent |
-| `--color-fd-ring` | `#e50d75` | `#ff3d8b` | Focus ring |
-| `--color-fd-accent` | `#ffe1eb` | `#2a1a22` | Soft accent |
-| `--color-fd-accent-foreground` | `#1f1f1f` | `#fff7f0` | Text on accent |
-| `--color-fd-card` | `#ffffff` | `#1c1814` | Cards |
-| `--color-fd-card-foreground` | `#1f1f1f` | `#fff7f0` | Text on cards |
-| `--color-fd-muted` | `#f5f2ee` | `#1a1612` | Muted backgrounds |
-| `--color-fd-muted-foreground` | `#1f1f1f99` | `#fff7f0aa` | Muted text |
-| `--color-fd-border` | `#1f1f1f1a` | `#fff7f014` | Subtle borders |
-
-## Backgrounds And Gradients
-
-Utilities defined in `global.css`.
-
-- `bg-color-mesh` light: `#fec5d4`, `#fff0e1`, `#ffd9c2`, `#fde0d3`, then `--color-cream`.
-- `bg-color-mesh` dark: `#3a1822`, `#2a1f15`, `#2d1810`, `#281410`, then `--color-cream`.
-- `bg-pastel-radial` light: `#c3f2d0`, `#b7ebff`, `#fee3cc`.
-- `bg-pastel-radial` dark: `#1a2a22`, `#0d1b2e`, `#2a1810`.
-- `bg-grid`, `bg-engineering`, `bg-dots`, `bg-scanlines`: patterns based on `color-mix(... var(--color-ink) ... transparent)`.
-
-## Visible Hardcoded Colors
-
-Some components still use inline colors, mostly lab variants and a few visual blocks.
-
-- Home / current CTA: `#0d0a07`, `#14110e`, `#1f1f1f`, `#e50d75`, plus several `rgba(255,247,240,...)` and `rgba(0,0,0,...)` opacity values.
-- Footer: `#0d0a07`, `rgba(229,13,117,0.28)`, `rgba(136,93,197,0.18)`, `rgba(255,247,240,...)`.
-- App icon: `#e50d75`.
-- Lab / non-canonical variants: `#0073e6`, `#080808`, `#0e0e0e`, `#1a1a1a`, `#2a2a2a`, `#6030b0`, `#885dc5`, `#a00060`, `#c00080`, `#c00a74`, `#c20000`, `#f0e8d4`, `#f5eedc`, `#f7f3ee`, `#faf8f4`, `#fff`, `#fffef9`, `#060504`, `#0a0806`, `#0d0907`, `#0e0c0a`, `#10100c`, `#131109`, `#1e1409`.
-
-## Fonts
-
-Fonts are loaded in `website/src/app/layout.tsx` via `next/font/google`.
-
-| Token | Font | Fallback | Usage |
-| --- | --- | --- | --- |
-| `--font-sans` | `Inter` | `ui-sans-serif`, `system-ui`, `sans-serif` | Body text, layout, buttons |
-| `--font-display` | `Fraunces` | `ui-serif`, `Georgia`, `Times New Roman`, `serif` | `rae` logo, headlines, asterisk, editorial accents |
-| `--font-mono` | `JetBrains Mono` | `SF Mono`, `Menlo`, `Monaco`, `Consolas`, `monospace` | Code, labels, eyebrows, numbers |
-
-Frequently used Fraunces settings:
-
-- `opsz`: `144`
-- `SOFT`: often `30`, `40`, `50`, or `100`
-- `WONK`: `0` or `1`
-- Italic is used for headlines and the brand asterisk.
-
-## Icons
-
-### Brand Icon
-
-- Asterisk `*` set in italic `Fraunces`.
-- Used in the header logo, hero/CTA decorations, marquee, and `website/src/app/icon.tsx`.
-- Main color: `--color-fd-primary` (`#e50d75` in light mode, `#ff3d8b` in dark mode).
-- The app icon loads only the `*` glyph from Fraunces.
-
-### Custom SVG Icons
-
-- `GithubIcon`: inline SVG in `site-nav.tsx` and `page.tsx`.
-- Color: `currentColor`, inherited from text classes such as `text-ink-soft` and `hover:text-ink`.
-
-### Lucide Icons
-
-Library: `lucide-react`.
-
-- `ArrowRightIcon`: CTA buttons, “Read the docs”, “Get started”, error pages.
-- `SunIcon`: light theme switcher.
-- `MoonIcon`: dark theme switcher.
-- `RotateCcwIcon`: error page.
-- `CopyIcon`: `InstallCommand` component.
-- `CheckIcon`: `InstallCommand` component.
-- `MenuIcon`: header variants in `components/lab`.
-
-## Recurring Shapes And Patterns
-
-- Buttons: `0.5rem` radius, pink offset shadow for primary buttons.
-- Hero / landing cards: `1.5rem` radius, `ink/10` border, soft shadow.
-- Tiles: `1.25rem` radius.
-- Docs media: `0.75rem` radius.
-- Header: glass background with `backdrop-blur-xl`, `backdrop-saturate-150`, and `color-mix(... --color-cream ... transparent)`.
-- Decorations: Fraunces asterisks, scanlines, grids, dots, pastel mesh.
diff --git a/design/PROMPT.md b/design/PROMPT.md
index 014a4eb..9ac4a15 100644
--- a/design/PROMPT.md
+++ b/design/PROMPT.md
@@ -73,9 +73,9 @@ 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
+{{For on-brand rae work, PASTE the contents of `design-system.md` — its Reference
+section (the canonical tokens, fonts + Fraunces axes, icons, shapes) plus 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
@@ -94,7 +94,7 @@ 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`
+- **Feed it the real system.** Pasting `design-system.md` (Reference + rules)
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.
diff --git a/design/README.md b/design/README.md
index 07eed48..69450bf 100644
--- a/design/README.md
+++ b/design/README.md
@@ -5,16 +5,17 @@ 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.
+- **design-system.md** — the full design system for `rae`: a **Reference**
+ section with the exact tokens/fonts/icons/shapes (mirrored from
+ `website/src/app/global.css`), then the *opinionated layer* on top — 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 canonical token/asset reference lives in [`design-system.md`](./design-system.md)**
+> — its Reference section has the exact palette, functional tokens, fonts +
+> Fraunces axes, icon inventory, and shape/radius specs, mirrored from
+> `website/src/app/global.css`. Need a hex or a radius → read it there.
---
@@ -104,8 +105,8 @@ 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.
+ captured in `design-system.md` (raw tokens in the Reference section, plus 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.
diff --git a/design/design-system.md b/design/design-system.md
index d8c556e..7893f8f 100644
--- a/design/design-system.md
+++ b/design/design-system.md
@@ -1,13 +1,9 @@
-# rae — design system (the opinionated layer)
+# rae — design system
-> **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 single reference for the design system used by `reverse-api-website`: the
+raw tokens/assets **and** the opinionated layer on top of them. The tables in
+**Reference** are mirrored from `website/src/app/global.css`; **Rules of use**
+and everything below it is the personality, judgement, and *why*.
The personality in one line: **warm editorial-tech** — a cream paper canvas, a
high-character serif (Fraunces) used big and italic, monospace for technical
@@ -16,7 +12,120 @@ Playful but precise.
---
-## Rules of use (the judgement `System_Design.md` doesn't encode)
+## Reference
+
+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`; always use the **token**, never the raw hex.
+
+### Core Colors
+
+These are the canonical color tokens defined in `website/src/app/global.css`.
+
+| Token | Light | Dark | Usage |
+| --- | --- | --- | --- |
+| `--color-ink` | `#1f1f1f` | `#fff7f0` | Primary text, dark surfaces, strong borders |
+| `--color-ink-soft` | `#1f1f1fcc` | `#fff7f0bb` | Secondary text |
+| `--color-cream` | `#fff7f0` | `#14110e` | Main background |
+| `--color-cream-soft` | `#fef8ee` | `#1c1814` | Slightly raised surfaces |
+| `--color-orange` | `#ffe7d4` | `#3a1d0e` | Warm secondary section color |
+| `--color-sky` | `#d6efff` | `#0d1b2e` | CTA section color |
+| `--color-mint` | `#d5f1de` | `#0e2419` | Positive accent / completed state |
+| `--color-washed` | `#f5f2ee` | `#1a1612` | Washed neutral background |
+
+### Functional Colors
+
+Tokens used by Fumadocs and shared components.
+
+| Token | Light | Dark | Usage |
+| --- | --- | --- | --- |
+| `--color-fd-background` | `#fff7f0` | `#14110e` | App background |
+| `--color-fd-foreground` | `#1f1f1f` | `#fff7f0` | App foreground text |
+| `--color-fd-primary` | `#e50d75` | `#ff3d8b` | Pink accent, asterisk, links, CTA shadows |
+| `--color-fd-primary-foreground` | `#fff7f0` | `#14110e` | Text on primary accent |
+| `--color-fd-ring` | `#e50d75` | `#ff3d8b` | Focus ring |
+| `--color-fd-accent` | `#ffe1eb` | `#2a1a22` | Soft accent |
+| `--color-fd-accent-foreground` | `#1f1f1f` | `#fff7f0` | Text on accent |
+| `--color-fd-card` | `#ffffff` | `#1c1814` | Cards |
+| `--color-fd-card-foreground` | `#1f1f1f` | `#fff7f0` | Text on cards |
+| `--color-fd-muted` | `#f5f2ee` | `#1a1612` | Muted backgrounds |
+| `--color-fd-muted-foreground` | `#1f1f1f99` | `#fff7f0aa` | Muted text |
+| `--color-fd-border` | `#1f1f1f1a` | `#fff7f014` | Subtle borders |
+
+### Backgrounds And Gradients
+
+Utilities defined in `global.css`.
+
+- `bg-color-mesh` light: `#fec5d4`, `#fff0e1`, `#ffd9c2`, `#fde0d3`, then `--color-cream`.
+- `bg-color-mesh` dark: `#3a1822`, `#2a1f15`, `#2d1810`, `#281410`, then `--color-cream`.
+- `bg-pastel-radial` light: `#c3f2d0`, `#b7ebff`, `#fee3cc`.
+- `bg-pastel-radial` dark: `#1a2a22`, `#0d1b2e`, `#2a1810`.
+- `bg-grid`, `bg-engineering`, `bg-dots`, `bg-scanlines`: patterns based on `color-mix(... var(--color-ink) ... transparent)`.
+
+### Visible Hardcoded Colors
+
+Some components still use inline colors, mostly lab variants and a few visual blocks.
+
+- Home / current CTA: `#0d0a07`, `#14110e`, `#1f1f1f`, `#e50d75`, plus several `rgba(255,247,240,...)` and `rgba(0,0,0,...)` opacity values.
+- Footer: `#0d0a07`, `rgba(229,13,117,0.28)`, `rgba(136,93,197,0.18)`, `rgba(255,247,240,...)`.
+- App icon: `#e50d75`.
+- Lab / non-canonical variants: `#0073e6`, `#080808`, `#0e0e0e`, `#1a1a1a`, `#2a2a2a`, `#6030b0`, `#885dc5`, `#a00060`, `#c00080`, `#c00a74`, `#c20000`, `#f0e8d4`, `#f5eedc`, `#f7f3ee`, `#faf8f4`, `#fff`, `#fffef9`, `#060504`, `#0a0806`, `#0d0907`, `#0e0c0a`, `#10100c`, `#131109`, `#1e1409`.
+
+### Fonts
+
+Fonts are loaded in `website/src/app/layout.tsx` via `next/font/google`.
+
+| Token | Font | Fallback | Usage |
+| --- | --- | --- | --- |
+| `--font-sans` | `Inter` | `ui-sans-serif`, `system-ui`, `sans-serif` | Body text, layout, buttons |
+| `--font-display` | `Fraunces` | `ui-serif`, `Georgia`, `Times New Roman`, `serif` | `rae` logo, headlines, asterisk, editorial accents |
+| `--font-mono` | `JetBrains Mono` | `SF Mono`, `Menlo`, `Monaco`, `Consolas`, `monospace` | Code, labels, eyebrows, numbers |
+
+Frequently used Fraunces settings:
+
+- `opsz`: `144`
+- `SOFT`: often `30`, `40`, `50`, or `100`
+- `WONK`: `0` or `1`
+- Italic is used for headlines and the brand asterisk.
+
+### Icons
+
+#### Brand Icon
+
+- Asterisk `*` set in italic `Fraunces`.
+- Used in the header logo, hero/CTA decorations, marquee, and `website/src/app/icon.tsx`.
+- Main color: `--color-fd-primary` (`#e50d75` in light mode, `#ff3d8b` in dark mode).
+- The app icon loads only the `*` glyph from Fraunces.
+
+#### Custom SVG Icons
+
+- `GithubIcon`: inline SVG in `site-nav.tsx` and `page.tsx`.
+- Color: `currentColor`, inherited from text classes such as `text-ink-soft` and `hover:text-ink`.
+
+#### Lucide Icons
+
+Library: `lucide-react`.
+
+- `ArrowRightIcon`: CTA buttons, “Read the docs”, “Get started”, error pages.
+- `SunIcon`: light theme switcher.
+- `MoonIcon`: dark theme switcher.
+- `RotateCcwIcon`: error page.
+- `CopyIcon`: `InstallCommand` component.
+- `CheckIcon`: `InstallCommand` component.
+- `MenuIcon`: header variants in `components/lab`.
+
+### Recurring Shapes And Patterns
+
+- Buttons: `0.5rem` radius, pink offset shadow for primary buttons.
+- Hero / landing cards: `1.5rem` radius, `ink/10` border, soft shadow.
+- Tiles: `1.25rem` radius.
+- Docs media: `0.75rem` radius.
+- Header: glass background with `backdrop-blur-xl`, `backdrop-saturate-150`, and `color-mix(... --color-cream ... transparent)`.
+- Decorations: Fraunces asterisks, scanlines, grids, dots, pastel mesh.
+
+---
+
+## Rules of use (the judgement the tokens don't encode)
**Palette**
- The page is always `cream`. Full-bleed sections alternate among the soft
@@ -32,9 +141,9 @@ Playful but precise.
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.
+ it reads as a real object sitting on any background. These are the
+ "Visible Hardcoded Colors" listed in the Reference above; that list should stay
+ *short* and deliberate, not grow.
**Type**
- Headings are **display serif (Fraunces) with one word in pink italic** via
@@ -44,7 +153,7 @@ Playful but precise.
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`.)
+ axes for workhorse headings. (Exact axis values are in the Reference above.)
**The asterisk motif `*`**
- The recurring brand mark. A Fraunces italic `*` in pink. Float it in section
@@ -57,11 +166,11 @@ Playful but precise.
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.
+- Keep radii consistent (the set is in the Reference above), not random per element.
---
-## Motion (not covered in System_Design.md)
+## Motion
- **Seamless marquee:** `marquee-track` + `@keyframes marquee-scroll` translate
`-50%`. Bake spacing into each cell (`pr-*`), **never a flex `gap` on the
@@ -81,7 +190,7 @@ 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*:
+The Icons reference above 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,
diff --git a/src/reverse_api/theme.py b/src/reverse_api/theme.py
index 553a459..fca847a 100644
--- a/src/reverse_api/theme.py
+++ b/src/reverse_api/theme.py
@@ -1,4 +1,4 @@
-"""Design tokens for the CLI, aligned with System_Design.md (dark / terminal)."""
+"""Design tokens for the CLI, aligned with design/design-system.md (dark / terminal)."""
# Core palette (website dark mode)
COLOR_INK = "#fff7f0"