DESIGN.md · diff

git:20260906.bedc43d to git:20261020.50a7cf7

15 added, 11 removed. Audit A to A.

# Suede Creator Skills Design System

## Register And Scene

Brand register. A builder is evaluating an agent toolkit on a laptop or phone,

often in a dark workspace, and needs confidence before running install commands.

The interface should feel like a compact release dossier: dark, precise,

evidence-led, and easy to scan.

## Palette

| Role | Value | Use |

| --- | --- | --- |

| Background | `#080808` | Page canvas |

| Surface | `#111111` | Panels and grouped content |

| Card | `#161616` | Raised content |

| Border | `#222222` | Hairlines and separation |

| Primary text | `#f0ece4` | Headings and essential text |

| Secondary text | `#888880` | Supporting text that must remain AA-readable |

| Gold | `#c8a96e` | Primary brand accent and action emphasis |

| Risk red | `#8b1a1a` | Failure, risk, and strict grading accents only |

## Typography

- Display headings are set in Fraunces, a variable editorial serif,

self-hosted at `docs/assets/fonts/fraunces-var.woff2` (roman, ~66KB) with

an italic cut used on the homepage hero (`fraunces-var-italic.woff2`).

OFL-licensed; the license text lives in `licenses/fraunces-OFL.txt`.

Weight sits between 560 and 650 with `-0.01em` to `-0.02em` tracking and

`font-optical-sizing: auto`, so the face gains contrast at poster sizes.

- The pairing is deliberate tension: editorial serif display over the

operator-grade mono/terminal layer. Component titles (cards, rows, TOC

entries) stay on the system sans stack so the serif keeps section-level

authority; body copy never uses the serif.

- System sans stack for body: dependable loading and a product-native feel.

- Body copy stays between 65 and 75 characters per line with `1.6-1.7`

line-height.

- Monospace is reserved for commands, code, terminal labels, and the proof

tape.

## Spacing And Shape

- Four-point spacing foundation exposed as `--space-*` tokens.

- Corners remain tight: 2-4px for controls and panels.

- Gold is used as a decision, not spread evenly across every surface.

## Motion

- Content is visible by default. Motion may translate or soften content into

place but must never gate visibility.

- Use exponential ease-out and provide a reduced-motion path.

- Marquee and ambient hero motion are decorative and must not carry meaning.

## Interaction

- Primary actions and mobile controls provide at least a 44px target.

- Every link, button, and summary has a visible gold focus ring.

- Labels describe state changes, including open/close mobile navigation.

- Install commands remain selectable and copyable without hiding the raw text.

## Components

- Global navigation and mobile menu.

- Proof tape: full-width telemetry strip between nav and hero. A CSS-only

marquee of real, on-page numbers (skills, commits, dollars recovered,

uploads). Numbers in gold, labels in dim mono. Pauses on hover; the

reduced-motion variant freezes into a centered wrapping row. Every figure

on the tape must appear, sourced, further down the page.

- Proof-led hero with terminal install panel. The headline reserves the

Fraunces italic plus a red underline for the single risk phrase; red stays

a border/fill color and the text remains cream. Film grain at low opacity

keeps the near-black canvas from reading as a flat fill.

- Catalog toolbar on the skills index: hidden until JS reveals it, then a

bordered panel that sticks under the nav at desktop and stays static on

- phones so it never eats the viewport. Search glyph, mono input with a `/`

- hint, clear button, live count via `aria-live`, and six specialty chips that

- track the section under the bar (`aria-current="location"`). Every query

- term must match; matches wrap in `<mark class="hl">`; empty lanes and

- specialties collapse; the query round-trips through `?q=`; `/` or Ctrl/Cmd+K

- focuses, Esc clears, Enter opens a lone match, and the arrow keys walk the

- visible rows.

- - Catalog ledger: each specialty carries a fixed two-digit ordinal and a

- Fraunces head; each row carries a running mono index from a CSS counter, a

- gold inset rule on hover and focus, and a `src` link to its GitHub folder

- that appears on hover, focus-within, or touch.

+ phones so it never eats the viewport. One row at desktop: search glyph, a

+ short mono input with a `/` hint and clear button, the six specialty chips

+ that track the section under the bar (`aria-current="location"`), and a

+ live count via `aria-live`. Below 980px the input takes the full width and

+ the chips drop to a second line. Every query term must match; matches wrap

+ in `<mark class="hl">`; empty lanes and specialties collapse; the query

+ round-trips through `?q=`; `/` or Ctrl/Cmd+K focuses, Esc clears, Enter

+ opens a lone match, and the arrow keys walk the visible rows.

+ - Catalog ledger: three heading sizes and nothing else. Each specialty has a

+ Fraunces head in cream, a muted "N skills" count, and a single gold rule;

+ each lane has a sans head with a muted count and a hairline; each row is

+ the skill name in cream mono beside its one-line description, with a quiet

+ `src` link to its GitHub folder always visible at the right. Gold appears

+ only on the specialty rule and on hover or focus, so a 76-row list does not

+ read as 76 accents. No ordinals, row numbers, or arrows.

- Lane map: one SVG bar per specialty, each a link to its section, filling

from the axis on first view (`.js-on` gated, so no-JS and reduced-motion

visits see full bars). Bar length is proportional to skill count.

- Scroll reveal and entrance: `.reveal` / `.reveal-group` translate into place

on first intersection; the hero rises in on load. Both are transform and

blur only, never opacity, and both switch off under reduced motion.

- Back-to-top pill after the first screen of catalog; the nav gains a shadow

once scrolled; the catalog changelog carries the homepage ledger's

type-coded spine nodes via `:has()`.

- Mobile navigation is one `<details class="nav-disclosure">` pattern on every

page, including the generated book. The markup ships `open`, so a visit with

JavaScript disabled still reaches every link; JS collapses it at 768px and

under, and keeps the summary's `aria-label` swapping between "Open

navigation menu" and "Close navigation menu". The summary carries

`.nav-hamburger` at a 44px square with the three bars crossing into an X

when open. Desktop keeps the inline row: the disclosure is

`display: contents` and the summary is hidden, so layout is unchanged.

This replaced a homepage menu that could not open without JS and an interior

nav that simply wrapped its links, giving three different nav heights and

eating roughly a fifth of a phone viewport on the catalog.

- Changelog ship log: timeline ledger of real commits with type-coded spine

nodes, commit-activity sparkline, last-shipped freshness pill, and type

filter chips. Entries carry real dates and short hashes linking to GitHub;

filters and relative time are progressive enhancement.

- Benchmark tiles and disclosed scorecard.

- Skill catalog lanes and rows.

- Install terminals and alternative install paths.

- Evidence panels, FAQ disclosures, and footer identity.