Skip to content

borghei/Claude-Skills / markdown-html/design-system

design-system

Verified

Design tokens, light/dark theming, and WCAG contrast validation for HTML documents and decks, compiled into one inlinable CSS bundle. Use when theming a report or deck, auditing contrast, or fixing dark-mode color drift.

references/token-architecture.md

View on GitHub
# Token Architecture for Document Theming

This reference covers how to structure a design-token file for **documents and
presentations rendered as HTML** — reports, whitepapers, memos, slide decks. It
is not a product UI component system. There are no buttons, no form states, no
component variants. The surface area is narrower and the constraints are
different: a document is read linearly, printed, exported to PDF, and often
viewed at a size the author never anticipated.

## The three-layer model

Every mature token file separates three layers. Collapsing them is the single
most common cause of a theme that cannot be re-skinned.

| Layer | Name | Example | Changes when |
|-------|------|---------|--------------|
| 1 | **Primitive** | `neutral.900 = #0f172a` | Never, once picked |
| 2 | **Semantic role** | `text = neutral.900` | You re-skin the theme |
| 3 | **Component binding** | `blockquote border = var(--color-accent)` | You redesign a component |

### Why the middle layer is non-negotiable

If a stylesheet writes `color: #0f172a` directly, every dark-mode override has to
restate every rule. If it writes `color: var(--color-text)`, dark mode is a single
block that redefines eleven custom properties. The measured difference on a
typical document stylesheet is roughly 400 lines of duplicated CSS versus 15.

**[PROVEN] Bind components to semantic roles, never to primitives.**
The linter's `ROLE_LITERAL` warning exists to enforce this.

### Naming the semantic layer

Name a role for **what it does**, not what it looks like:

| Good | Bad | Why |
|------|-----|-----|
| `text-muted` | `gray-text` | In dark mode the muted text is light, not gray-dark |
| `surface-raised` | `light-panel` | It is the darker panel in dark mode |
| `danger` | `red` | Reviewers change the hue; the meaning stays |
| `accent` | `blue-600` | Re-skinning to a brand color leaves the name wrong |

A role name that contains a color word will eventually lie. A role name that
contains a mode word (`light-`, `dark-`) has smuggled the mode into the wrong
layer — the mode belongs in the `roles.light` / `roles.dark` maps.

## The minimum viable role set for documents

Eleven roles cover essentially every long-form document. Adding more is usually a
sign that a component binding leaked into the semantic layer.

| Role | Purpose | Typical light | Typical dark |
|------|---------|---------------|--------------|
| `surface` | Page background | ramp 0 | ramp 1000 |
| `surface-raised` | Callouts, table stripes, code wells | ramp 100 | ramp 800 |
| `text` | Body copy and headings | ramp 900 | ramp 100 |
| `text-muted` | Captions, footnotes, metadata | ramp 600 | ramp 400 |
| `border` | Rules, table lines, dividers | ramp 400 | ramp 700 |
| `link` | Inline anchors | accent 600 | accent 300 |
| `accent` | Blockquote bars, active nav, focus ring | accent 600 | accent 300 |
| `code-surface` | Code block background | ramp 100 | ramp 800 |
| `code-text` | Code foreground | ramp 800 | ramp 100 |
| `warn` | Caution callouts | warn 600 | warn 300 |
| `danger` | Error callouts | danger 600 | danger 300 |

### The inversion rule

Notice the pattern in the table: **dark mode is not the light ramp with the
lightness flipped — it is the light ramp read from the other end.** A role that
points at `neutral.900` in light points at roughly `neutral.100` in dark. A role
that points at `accent.600` in light points at `accent.300` in dark, because
saturated mid-tones that read well on white are too dim on near-black.

**[PROVEN] Move accent colors 2-3 steps lighter in dark mode, not 1.**
An accent at the same step in both modes will pass contrast in light and fail in
dark, or vice versa. `accent.600` on white is 5.9:1; `accent.600` on near-black
is 3.4:1 — a failure for body text.

## Color ramps

### Step numbering

Use the 0-1000 convention where **higher numbers are darker**. This is the
dominant convention and it survives the addition of new stops: if you need
something between 600 and 700 you add 650, and nothing renumbers.

The linter's `RAMP_ORDER` check enforces monotonic darkening by computing WCAG
relative luminance for each stop and verifying it decreases as the step number
rises. A ramp that brightens mid-way is almost always a paste error, and it makes
every subsequent contrast intuition wrong.

### How many stops

| Ramp type | Stops needed | Rationale |
|-----------|--------------|-----------|
| Neutral | 8-11 | Carries surface, raised, border, muted, text in both modes |
| Accent | 4-5 | Needs a light-mode-safe dark stop and a dark-mode-safe light stop |
| Warn / danger | 2-4 | One dark stop, one light stop, optional surfaces |

A neutral ramp with fewer than 8 stops forces roles to share values, which
collapses the visual hierarchy between `surface-raised` and `border`.

### Perceptual spacing

Hex ramps generated by linear interpolation in sRGB clump in the midtones and
spread at the ends — the gap between 700 and 800 looks larger than between 100
and 200. Two workable approaches:

1. **[RECOMMENDED] Hand-tune against luminance.** Aim for the relative luminance
   of each stop to fall roughly on a geometric progression. Run the linter and
   read the ramp order output; adjust until each adjacent pair differs by a
   similar contrast ratio (~1.25-1.4x is a comfortable step).
2. **[PROVEN] Adopt a published neutral ramp.** For a document theme, the neutral
   ramp is doing unglamorous work. Borrowing a well-tuned open neutral scale and
   spending the design effort on the accent is the higher-leverage choice.

### Contrast budget per adjacent step

A useful heuristic when hand-tuning: one 100-step of a well-formed neutral ramp
is worth approximately **1.25-1.4x of contrast ratio**. So if `text-muted` at
step 500 gives 4.1:1 on white and you need 4.5:1, moving to step 600 lands you
near 5.4:1 — one step is enough, two overshoots into looking like body text.

## The type scale

### Modular scale mechanics

A modular scale is one base size multiplied by a ratio, repeatedly. `theme_builder.py`
anchors the scale at the step literally named `base` and walks outward:

```
size(n) = base_px * ratio^(index(n) - index("base"))
```

### Choosing the ratio

| Ratio | Name | Use for | Effect |
|-------|------|---------|--------|
| 1.125 | Major second | Dense reference docs, data-heavy memos | Barely distinguishable levels; needs weight/color to separate |
| 1.200 | Minor third | Technical documentation | Tight, utilitarian, many usable levels |
| **1.250** | **Major third** | **Reports, whitepapers — the default** | Clear hierarchy, H1 stays a sane size |
| 1.333 | Perfect fourth | Slide decks, marketing docs | Dramatic; H1 gets large fast |
| 1.500 | Perfect fifth | Title slides only | Unusable for documents; steps explode |

**[PROVEN] Use 1.25 for documents and 1.333 for slides.** The reason is the step
count: a document needs 7-8 usable steps from caption to H1, and at 1.5 the top
step of an 8-step scale is 12x the base — 200px+ body-relative. At 1.25 an 8-step
scale spans roughly 0.64x to 3.05x, which is the range a report actually uses.

The linter rejects ratios outside 1.05-1.7 as `TYPO_RATIO` because both ends
produce scales no document can use.

### Base size

**16px is the floor, 17-18px is right for long-form.** Browsers default to 16px
and users who have raised their default expect it honored. Setting a base below
16px is the `TYPO_BASE` warning; it fails the spirit of WCAG 1.4.4 (resize text)
even when technically zoomable.

### Measure

Line length is measured in characters (`ch` units), not pixels, because it must
track the font size. The comfortable band is **55-85 characters**; 66-75 is the
target for continuous prose. Outside 55-85 the linter emits `TYPO_MEASURE`.

- Below 55ch the eye makes too many return sweeps; reading speed drops and
  hyphenation artifacts multiply.
- Above 85ch the return sweep loses the line; readers re-read lines.

Set it once as `--measure` and apply it to the content container, not to `body`,
so full-bleed figures and tables can escape it.

### Line height

| Content | Line height | Why |
|---------|-------------|-----|
| Body prose | 1.5-1.7 | WCAG 1.4.12 requires 1.5 to be *supportable*; shipping 1.6 means users adjusting text spacing do not break the layout |
| Headings | 1.1-1.25 | Large type needs proportionally less leading or it fragments |
| Code blocks | 1.4-1.5 | Monospace with long lines needs more than headings, less than prose |
| Slide bullets | 1.3-1.4 | Read at distance in short bursts |

Line height is unitless so it multiplies the element's own font size. Setting
`line-height: 24px` breaks the moment a heading inherits it.

## The spacing scale

### Base unit

**Use an 8px base with half steps.** 8 divides evenly into common layout widths,
composes with a 4px half-step for fine adjustments, and produces round numbers at
every multiple. A 4px base is defensible for very dense documents but doubles the
number of steps you must name.

The steps in the sample file — `0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12` — are
deliberately non-linear. Early steps are dense because that is where fine
adjustment happens (padding, gaps); later steps jump because section separation
does not need 40px *and* 48px.

### Vertical rhythm for documents

The single most valuable spacing rule in a document theme:

**Space above a heading must exceed space below it.** A heading belongs to the
content that follows it. `margin: var(--space-4) 0 var(--space-2)` — 32px above,
16px below at an 8px base — makes the grouping unambiguous. Equal margins make
every heading look orphaned between two sections.

| Element | Above | Below |
|---------|-------|-------|
| H1 | space-6 | space-3 |
| H2 | space-4 | space-2 |
| H3 | space-3 | space-1.5 |
| Paragraph | 0 | space-2 |
| Figure / table | space-3 | space-3 |

## Dark mode delivery

Emit **three** blocks, not one. Each does a different job:

```css
:root { /* light values + color-scheme: light dark */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }
:root[data-theme="dark"] { /* dark values */ }
:root[data-theme="light"] { /* light values */ }
```

- The media query respects the OS preference with no JavaScript.
- The `data-theme` attribute selectors let an explicit toggle **override** the OS
  preference in both directions. Shipping only `[data-theme="dark"]` means a user
  on a dark OS cannot force light — the media query keeps winning.
- `color-scheme: light dark` tells the browser to theme form controls,
  scrollbars, and the canvas background. Omitting it produces the classic white
  flash before CSS parses and white scrollbars beside a dark page.

**[PROVEN] The explicit-attribute blocks must come after the media query** so
specificity and order both favor an explicit user choice.

### The flash-of-wrong-theme problem

A themed document rendered as a single self-contained file has no chance to run
JavaScript before first paint if the toggle script sits at the end of `<body>`.
Either accept the OS preference alone (no toggle, zero flash), or place a tiny
inline script in `<head>` that stamps `data-theme` from storage before the body
parses. There is no third option that avoids the flash.

## Print and PDF considerations

Documents get printed. Tokens that only exist as screen values produce unreadable
output when a dark theme meets a printer.

**[PROVEN] Force the light role set inside `@media print`.** Never let dark mode
reach paper — it wastes toner, and most browsers strip background colors by
default, which leaves light text on white.

```css
@media print {
  :root { /* restate light values unconditionally */ }
}
```

Additional print token needs: page margins, a page size, and orphan/widow
control. These are document-level concerns rather than color tokens, but they
belong in the same generated bundle so the artifact stays one file.

## Anti-patterns in token files

### The mode-in-the-name role
Defining `light-text` and `dark-text` as separate roles instead of one `text`
role with two mode values. Every component binding then needs a conditional, and
the whole point of custom properties is lost.

### The 40-role sprawl
Adding a role per component (`table-header-bg`, `figure-caption-color`,
`toc-link-hover`). Roles are a vocabulary, not a mapping table. If a component
needs a color, bind it to an existing semantic role. Eleven roles is enough for a
document; twenty is a smell; forty means layer 2 and layer 3 have merged.

### Untested dark mode
Authoring in light mode, mechanically inverting for dark, never rendering it. The
contrast validator checks both modes for exactly this reason — the failures are
almost always in the mode the author did not look at.

### The literal hex escape hatch
Hard-coding one color "just this once" because no role fits. That color will not
respond to theming and will be found months later as the one element that stays
dark in light mode. Add the role, or reuse one.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall