utils/unified-design-system/tokens.md
Krzysztof kuhy Rudnicki a50d27688f Consolidate unified-design-system docs into this monorepo
Moves the design-system rules, frozen token table, and annotated
component references out of ~/.claude/skills/ and the two Claude
Artifacts into a proper subdir here, matching the existing
gatelock/crdt-sync/guard-lib pattern of one-subdir-per-shared-library.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-22 21:23:47 +02:00

124 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Unified design tokens (frozen values)
Concrete instantiation of `safe-design-rules`' 28 rules. One identical
palette across every repo/stack (Flutter, web, Python/Tkinter) — not just
shared rules, the same hex values everywhere, including Flutter launcher-icon
glyphs (`app-icon` skill). Anchored on the shared icon charcoal `#211D1B` so
the UI palette and the icon family cohere instead of adding a second
"near-black." Warm-tinted throughout (rule 10) — superseded from an earlier
cool-tinted draft; every neutral is a byte-reversed (RRGGBB→BBGGRR) mirror of
that draft's value, so relative lightness/contrast steps are unchanged, only
the tint shifts from blue toward red/brown.
## Neutrals
| Token | Hex | Notes |
| ------------------ | --------- | ------------------------------------------------- |
| `ink` | `#211D1B` | Dark bg. Same value as the icon charcoal. |
| `ink-raised-1` | `#2B2624` | Dark elevated surface, step 1. |
| `ink-raised-2` | `#38312E` | Dark elevated surface, step 2 (≤12% luma vs bg). |
| `line-dark` | `#463E3A` | Border on dark surfaces. |
| `text-on-dark` | `#ECEAE9` | Primary text on dark. Near-white, not pure. |
| `muted-on-dark` | `#AAA09A` | Secondary/caption text on dark. |
| `paper` | `#F6F4F3` | Light bg. |
| `paper-raised` | `#FCFBFB` | Light elevated surface — lighter than bg (rule 15). |
| `line-light` | `#E0DAD7` | Border on light surfaces (≥3:1 vs bg and card). |
| `text-on-light` | `#211D1B` | Reuses `ink` — deliberate symmetry. |
| `muted-on-light` | `#70625B` | Secondary/caption text on light. |
## Accent + semantic roles
One set, used identically everywhere — UI, icons, everything. All four now
cluster in the red-orange-yellow-olive wedge, distinguished mainly by
lightness (danger 130 < accent 143 < success ~150 < warning 171 — a flagged,
deliberate tradeoff, not an oversight): a colorblind/at-a-glance
distinguishing risk the user accepted over keeping green/red as a semantic
exception.
| Token | Hex |
| --------- | --------- |
| `accent` | `#B8862E` |
| `info` | `#B8862E` (= accent) |
| `success` | `#8A9A3C` |
| `warning` | `#E0A63C` |
| `danger` | `#E2585F` |
| `on-fill` | `#211D1B` (= `ink`) |
`on-fill`: text/icon color for anything drawn **on top of** a filled
accent/success/warning/danger surface (a primary button, a filled badge) —
never `text-on-dark`. All four fill colors sit in the same mid-light
lightness band (that's the accent/success/warning/danger clustering noted
above), so near-white text under-contrasts on every one of them (measured
2.2:1–3.6:1 against WCAG's 4.5:1 body-text floor); `ink` text passes on all
four (5.8:1–9.7:1). This is a closed rule, not a per-color judgment call —
never pick text color per fill, always `on-fill`.
Do not confuse `on-fill` with text on a **scrim/overlay** (a dark
semi-transparent backdrop behind a modal or a translucent control chip over
an image) — those stay `text-on-dark` (near-white), fixed regardless of
page theme, since the scrim itself is always dark. `on-fill` only applies to
the four *opaque* semantic fills above.
## Spacing scale (4px base)
`xs 4 · sm 8 · md 16 · lg 24 · xl 32 · xxl 48`
Every spacing/sizing value in a file should land on this scale. Round
outliers to the nearest step rather than introducing a new one.
## Corner radius scale
`sm 8` (buttons, inputs, chips) · `md 12` (cards) · `lg 16` (sheets, dialogs).
Nesting (rule 24): an inner element's radius = outer radius − the gap between
inner and outer edges, computed per instance — not a fixed constant. E.g. an
`lg` (16px) container with 4px of padding before its child starts should give
that child a 12px radius, not reuse 16 or invent an unrelated value.
## Typography scale
| Role | Size (px) | Tracking |
| ---------- | --------- | ---------------------------------- |
| `display` | 32 | tight (e.g. −0.2px) |
| `title` | 24 | tight (e.g. −0.1px) |
| `subtitle` | 20 | default |
| `body` | 16 | default — the floor (rule 20) |
| `label` | 14 | loose (+0.05–0.1em), chrome only |
| `caption` | 12 | loose (+0.1–0.2em), chrome only |
`body` (16px) is the minimum for anything a user actually reads.
`label`/`caption` are for UI chrome (timestamps, badges, tags) — never for
primary reading content.
Two typefaces max (rule 23): one system sans stack for all UI text
(`-apple-system, "Segoe UI", Roboto, system-ui, sans-serif` on web; platform
default on Flutter/Tk), one monospace stack reserved for code/data-dense
contexts only.
Line length (rule 21): prose/paragraph blocks capped at `max-width: 40rem`
(~640px, ~65–70 characters).
## Buttons
Horizontal padding = 2× vertical (rule 22). Canonical: vertical `12px`,
horizontal `24px` (both on the spacing scale: 12 = 3×4, 24 = 6×4).
## Shadow policy (rules 16, 26, 27)
Pick exactly one depth technique per surface — never a shadow and a lighter
fill on the same element, never a border-only style next to a shadowed one
at the same z-level.
- **Dark surfaces: no shadows, ever.** Elevation is `ink-raised-1`/`-2` fill
steps only.
- **Light surfaces**: shadows allowed *only* on floating/overlay elements
(dropdown menus, modal dialogs) — never on inline cards or list rows.
Two tiers, blur = 2× offset, tinted from `ink` (never pure black):
- Level 1 (e.g. a dropdown): `0 2px 4px rgba(33, 29, 27, 0.12)`
- Level 2 (e.g. a modal): `0 4px 8px rgba(33, 29, 27, 0.16)`
## Icon-next-to-text contrast (rule 28)
Icons adjacent to text render at ~72% opacity of the text's color, or use the
`muted` role instead of the full-strength text role — never equal contrast.