The neutral, mostly-black-and-white visual language for **whynot** — Tegwick's prototype and market-signal organisation. Wireframe-leaning. Quiet. Built for artefacts that should look deliberately unfinished.
> A prototype is a question made tangible. — `whynot-control/INTENT.md`
Framework-agnostic by design. Consumers do **not** re-implement components per framework — they use the same `<wn-button>` everywhere.
## Read first
| File | What's in it |
|---|---|
| `DesignSystemIntroduction.md` | How this repo relates to `whynot-control`, the Claude atelier, and consuming apps. Three-layer architecture, propagation pipeline, versioning, A1 staging. |
| `MultiFrameworkSupport.md` | How to consume from React, Django, HTMX, Vue, plain HTML. Per-framework setup, SSR specifics, hydration story. |
| `SKILL.md` | Agent Skill manifest, cross-compatible with Claude Code. Drop into `.claude/skills/` of any consuming repo. |
| This README | Full design language: tokens, components, content rules, iconography. |
| `CONTRIBUTING.md` | How to propose, review, and ship a change. |
| `BOOTSTRAP.md` | First-push instructions for priming this repo. Delete after use. |
The voice is **quiet, structured, evidence-oriented, and careful about overclaiming**. It comes directly out of the `AGENT_RULES.md` and `OPERATING_MODEL.md`:
> Agent outputs should be concise, evidence-oriented, explicit about uncertainty, and careful to separate idea, hypothesis, signal, and decision.
>
> — `whynot-control/AGENT_RULES.md`
The voice should sound like a careful field-notebook — not a startup landing page, not a product manifesto, not marketing copy.
### Casing
- **Sentence case** for headings, buttons, labels, links — *not* Title Case. ("Smallest useful test", not "Smallest Useful Test".)
- **lowercase** for the organization name in body: `whynot`, never `WhyNot` or `WHYNOT`. The logo wordmark may use `WhyWhyNot` for legacy reasons.
- **UPPERCASE** is reserved for short eyebrow labels (`PROTOTYPE`, `SIGNAL S2`, `STAGE`, `IN BETA`) — set in mono, with letterspacing.
- **`code-case`** for repo names, doc names, folder names: `whynot-control`, `INTENT.md`, `inbox/`. Always in monospace.
### Person
**Third person, with the project as subject.** Avoid "we", avoid "you", avoid "I".
- ✅ "A prototype is a question made tangible."
- ✅ "The repository helps the user capture unusual but potentially useful ideas."
- ❌ "We help you discover weird ideas."
- ❌ "You'll love how easy this is."
Direct second-person is reserved for *imperatives in a checklist* (e.g. "Read `INTENT.md`.").
### Tone
- **Curious, not enthusiastic.** "This may be worth a closer look" beats "🚀 huge if true!".
- **Hedged, not promotional.** Use *may*, *could*, *seems*, *appears to*. Avoid *will*, *guaranteed*, *the best*.
- **Distinguish idea / hypothesis / signal / decision.** Never collapse them.
- **Lack of signal is also information.** Silence is a finding, not a failure.
### Phrasing patterns to imitate
Lifted from the existing control documents:
- "A prototype is a question made tangible."
- "Signal beats enthusiasm."
- "Signals are evidence, not vibes."
- "Capture is not commitment."
- "Low-cost learning first."
- "A prototype can be interesting and still be parked."
The pattern is: **short declarative claim → small qualifier or counter-claim**. Two beats, no exclamation.
| "🎉 Launched!" | "Promoted to Helix on 2026-03-12. See `DECISIONS.md`." |
### Emoji & punctuation
- **No emoji** in body copy, headings, or UI.
- **`?` and `!`** are the brand's punctuation — they appear in the logo and may appear, sparingly, in display headlines (`try($idea) until success;`, `why? why not!`).
- **`→`** (U+2192) for "promotes to / goes to" links between stages. Not `->`.
- **`—`** (em dash) for parenthetical, not `--`.
---
## VISUAL FOUNDATIONS
### Overall posture
The system reads like **engineering graph paper** — precise hairlines, lots of whitespace, monospace labels in margins, content blocks that look like fields in a form rather than cards in a feed. The aesthetic is closer to a Bauhaus wall-chart or a `man` page than to a SaaS dashboard.
### Color
- **Mostly black on white**, with a few flat greys.
- **One accent only**: a warm yellow (`--hi: #FFE14A`) lifted from the LEGO brick in the logo. It appears as **highlighter / annotation / signal-marker** — never as a button fill, never as a hero background.
- **No gradients.** Anywhere. Including subtle ones.
- **No tinted whites** — `--paper` is a true `#FFFFFF`; `--paper-2` and `--paper-3` are barely-warm off-whites (`#FAFAF7`, `#F4F4EF`) reserved for sheets and recessed code blocks.
- Status colors (S0–S4 signal strength) are **rendered as desaturated grey ramps**, not red/yellow/green. S4 ("commercial signal") is the only one that uses the yellow accent, because that's the threshold where a prototype actually matters commercially.
- **Family**: native system stacks — `--ff-sans` (`ui-sans-serif, system-ui, …`) for UI/body, `--ff-mono` (`ui-monospace, …`) for labels, code, and stage markers, `--ff-serif` (`ui-serif, Georgia, …`) for the occasional editorial pull-quote. **No webfont is loaded.** (See font note below for the history.)
- **Weights**: 300 (display only), 400 (body), 500 (UI / headings), 600 (occasional emphasis). Never 700+ — too marketing.
- **Tracking**: tight on display (`-0.035em`), neutral on body, **wide on uppercase labels** (`0.08em` — this is the one signature move).
- **Eyebrows everywhere**: short uppercase mono labels above titles (`STAGE`, `SIGNAL`, `PROTOTYPE`). They are the system's main rhythmic element.
### Spacing
- **4px base unit**, exposed as `--sp-1` (4) through `--sp-10` (128).
- Generous: a content block typically has `--sp-7` (48px) of internal padding. Lists separated by `--sp-5` (24px) minimum.
- **Section breaks are big** (`--sp-9`, 96px). Reads like a printed report.
### Backgrounds
- **`--paper` (#FFFFFF) by default.** Period.
- **`--paper-2`** for full-width "sheet" sections (e.g. between hero and content).
- **`--paper-3`** for recessed surfaces only — code blocks, inline pre, inset cards.
- **No images as backgrounds.** No hand-drawn illustrations. No repeating patterns. No textures. No noise. No grain. (Exception: a 1px hairline grid may be used on a literal "wireframe" mock; see `preview/grid-paper.html`.)
### Animation
- **Minimal.** This is a document system, not a product UI.
- Transitions on hover only: `120ms ease` on `text-decoration-color` for links, `border-color` for inputs.
- **No spring physics, no bounce, no fade-in-on-scroll.** Anything that draws attention is not in the spirit of "low-cost learning first".
- Exception: the cursor-blink animation on a `<TerminalLine>` is permitted because it's a literal terminal motif.
### Hover & press states
- **Links** — underline color goes from `--border-strong` to `--fg-1` on hover.
- **Buttons (primary, dark)** — `--ink` → `--ink-2` on hover. On press, no transform, just `--ink` (back to baseline).
- **Cards** — *do not have hover states.* They are documents, not interactive surfaces. Exception: prototype cards in an index list get a 1px black left border on hover.
- **No scale transforms**, no shadow lifts, no glow effects.
### Borders
- **1px solid `--border` (#E5E5E2)** is the default. Used everywhere.
- **`--border-strong` (#C9C9C5)** for section dividers and the outline of a primary block.
- **Hairline `--border-soft` (#F0F0EC)** for internal rules within a card.
- **No double borders, no inset borders, no dashed borders** except in one specific case: dashed `--border-strong` is used to indicate "placeholder / not yet defined" content (see Components / Empty State).
### Shadows
- **`--shadow-0`: none.** This is the default. Most cards and panels have no shadow.
- **`--shadow-1`: `0 1px 0 var(--line)`** — a 1px bottom-line, used in place of bottom-border on sticky headers.
- **`--shadow-3`** is reserved for *floating* elements only (a popover, a focus-trapped modal). Even then it's a soft 4-12px diffuse shadow at 10% opacity — never a "card lift" shadow.
### Protection gradients vs capsules
- **No protection gradients.** Backgrounds are solid; never overlay a gradient to "rescue" text from a busy background, because backgrounds are never busy.
- **Capsules (pills with rounded ends)** are used only for `--label` and tag elements — never for buttons. Buttons are slightly rounded rectangles (`--r-2`, 4px).
### Layout rules
- **Single-column reading width** of ~640px for body, ~880px for documents with sidebars.
- **Constant page padding** of `--sp-7` (48px) on desktop, `--sp-4` (16px) on mobile.
- **Sticky element**: top navigation bar, height 56px, bottom hairline.
- **Sidebar (where used)**: 256px fixed width, `--paper-2` background, no border on right (uses whitespace to separate from main).
- **Grids** for structured data only — never as a "card wall". 12-column with 24px gutters.
### Transparency & blur
- **Almost never used.** No frosted glass. No backdrop-filter.
- One permitted use: a `rgba(255,255,255,0.92)` on the sticky top nav so that scrolled content is faintly visible behind it. No blur.
### Imagery
- **Black & white only.** All photography (when used) is rendered with `filter: grayscale(1) contrast(0.95)` — slightly low-contrast, like a Risograph print.
- **Aspect ratios**: 4:3 (preferred — feels like a document figure), 1:1 (for portraits / icons). Never 16:9 in body.
- **No people-stock-photography.** Prefer objects, diagrams, or screenshots.
- **No AI-generated imagery** unless explicitly labelled as such with a `[generated]` caption.
### Corner radii
- **`--r-1` (2px)** for inputs and tags.
- **`--r-2` (4px)** for buttons and small cards.
- **`--r-3` (8px)** for large cards and modals.
- **`--r-pill` (999px)** for label capsules only.
- **`--r-0` (0px / square)** is the default for documents, sheets, and any element wider than ~600px. Big things are square.
### Cards
A "card" in this system is **a bordered rectangle**, not a shadowed object floating off the page.
- 1px `--border` outline.
-`--paper` background.
- 4px or 8px radius depending on size.
- **No shadow.**
- Internal padding `--sp-5` (24px) minimum.
- A monospace eyebrow at top-left + a stage label at top-right is the canonical card header.
- On hover (when interactive): the top-left eyebrow tints to `--fg-1`, and a 2px black bar appears flush against the left edge. Nothing else moves.
---
## ICONOGRAPHY
The codebase did **not** ship an icon font, an icon sprite, or any SVG icons — `whynot-control` is a documents-only repo. The only visual asset is the LEGO-brick logo.
### Approach
- **Lucide icons via CDN** is the chosen icon set. It matches the system's stroke weight (1.5px), neutral geometry, and "wireframe artefact" feel better than Material, Heroicons, or Phosphor. Load with `<script src="https://unpkg.com/lucide@latest"></script>` and call `lucide.createIcons()`.
- **Stroke weight is always 1.5px.** Override Lucide's default 2px via `stroke-width="1.5"` on each `<svg>` or via CSS.
- **Color**: `currentColor`. Icons inherit from text. No two-tone, no fills.
- **Size**: 16px (inline), 20px (button), 24px (heading-adjacent), 32px (feature). Never larger — large icons read as decoration, and decoration is not in the spirit.
### When to use icons
- In navigation labels, button labels, and inline status — **only when the icon adds parsing speed**. If the word reads faster than the icon, skip the icon.
- In document margins to mark stage transitions (e.g. `→ Helix`).
- **Not** as decorative chrome on cards.
- **Not** as "feature icons" in a 3-up grid on a marketing page (this system has no marketing pages).
### Emoji
- **Never.** Emoji are not used anywhere — in copy, labels, alt text, or as fallback for missing icons.
### Unicode characters used as icons
These are allowed and preferred over raster icons in some contexts:
| Char | Used for |
|---|---|
| `→` | "promotes to" / pipeline arrow |
| `←` | back / previous |
| `·` | inline bullet separator (in nav, in meta lines) |
| `—` | em dash, in metadata |
| `?``!` | the brand's signature punctuation, in display headlines only |
| `§` | section marker, in long documents |
### The logo
- The primary mark is **the LEGO brick with `?` and `!` underneath**, in pure black & white. `assets/whynot-logo.png` (300×300 raster, transparent background).
- For very small uses (favicon, footer mark), a **simplified mark** is recommended: just the `?!` pair in `IBM Plex Sans 600`, with the brick implied by a 2×4 dot grid above. See `preview/logo.html`.
- The brick should **never be coloured** (no LEGO-red, LEGO-blue, etc). It is always black-outlined on white, or white-outlined on black.
- Minimum size: 32px square. Below that, fall back to the `?!` wordmark.
The token layer uses **native system font stacks** — `--ff-sans` (`ui-sans-serif, system-ui, …`), `--ff-mono` (`ui-monospace, …`), `--ff-serif` (`ui-serif, Georgia, …`). **No webfont is loaded.** These stacks were synced from the canonical React designbook (WHYNOT-WP-0002 T06); they keep the neutral, technical-document feel while staying offline-safe and dependency-free.
History: **IBM Plex Sans / Mono / Serif** was the earlier pairing — a neutral IBM technical-document family with shared metrics across sans/mono/serif, SIL OFL, available on Google Fonts. It was dropped in favour of system stacks. To reintroduce a brand webfont, add an `@font-face` block and point `--ff-sans` / `--ff-mono` / `--ff-serif` at it in `colors_and_type.css` — everything downstream follows.
