mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-20 21:12:30 +01:00
tokens.md 260 -> 219 + operability.md 69
nielsen-audit.md 258 -> 154 + shipped-record.md 122
README.md 257 -> 172 + operability-patterns.md 95
Worked the requested order rather than cutting straight to a split.
(a) Automate: the categorical ramp's four constraints were restated in prose
with the measured margins hand-copied (ΔE 34.6/26.0/25.6/27.4, etc).
ramp_check.py prints every one of those numbers and fails if any
regresses, so the prose now points at the command instead of duplicating
its output. The two consequences the numbers do not state — why the ramp
is mid-toned, and why lightness falls monotonically — stay in prose.
(b) Dedup: measured, not assumed. Zero paragraphs are shared between the
three files; README already delegates the rules to tokens.md and shows
only per-stack code. Nothing to remove.
(c/d) Split on meaning: tokens.md is "frozen values", so the behavioural
requirements that *use* those tokens moved to operability.md, with the
per-stack code for them in operability-patterns.md. nielsen-audit.md is a
live grid, so completed phases moved to shipped-record.md — following the
existing phase3-record.md convention, not a new one.
The focus-ring token row had to stay in tokens.md: palette_check.py parses
that file, and moving the row made the check fail with "MISSING md:focus-ring"
— a token it cannot see is a token nothing compares across the four stacks.
The rationale lives in operability.md and the row links to it.
palette_check and ramp_check both at 0 failing checks; every relative link
between the docs resolves.
`bash scripts/check_file_length.sh --all` now exits 0.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CFSGeWxHPY5rHUGrPqhcmG
220 lines
10 KiB
Markdown
220 lines
10 KiB
Markdown
# 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).
|
||
|
||
> **This table is checked, not trusted.**
|
||
> `scripts/palette_check.py` parses all four token sources — this file,
|
||
> `web_ui/src/tokens.css`, `design_system/lib/src/tokens.dart` and gatelock's
|
||
> `LockConfig` — and fails on any hex that disagrees across them, *including a
|
||
> hex edited only here*. It also fails on a colour token that no stack's map
|
||
> accounts for, so adding a token to one stack and forgetting the others is a
|
||
> CI failure rather than silent drift. Runs in `.github/workflows/palette-drift.yml`,
|
||
> deliberately with no `paths:` filter: drift is a disagreement *between*
|
||
> packages, so a path-scoped trigger would skip exactly the edit that causes it.
|
||
> Editing any value below means editing it in all four places. 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.
|
||
|
||
## Categorical ramp
|
||
|
||
For **charts, tags and category dots** — anything that needs N mutually
|
||
distinguishable colours with no inherent meaning. Never for semantic state:
|
||
success/warning/danger still own that, and mixing the two vocabularies is what
|
||
makes a "red" category read as an error.
|
||
|
||
| Token | Hex | L\* |
|
||
| ------- | --------- | --- |
|
||
| `cat-1` | `#C57293` | 58 |
|
||
| `cat-2` | `#398FC0` | 56 |
|
||
| `cat-3` | `#C85A32` | 52 |
|
||
| `cat-4` | `#228736` | 49 |
|
||
| `cat-5` | `#8D58BB` | 47 |
|
||
| `cat-6` | `#686D2C` | 44 |
|
||
|
||
**This ramp deliberately leaves the warm wedge**, and it is the only token group
|
||
that does. Accent/success/warning/danger cluster in red-orange-yellow-olive and
|
||
are separated mainly by lightness — a tradeoff that works when meaning carries
|
||
the signal. A categorical ramp has no meaning to lean on, so hue separation *is*
|
||
the requirement. Treating this as drift and "correcting" it back toward the
|
||
wedge would destroy the only property it has.
|
||
|
||
Chosen by search under four hard constraints, not by eye: pairwise CIE ΔE ≥ 20
|
||
under normal vision *and* simulated deuteranopia/protanopia/tritanopia, ≥ 3:1
|
||
against **both** backgrounds, monotonically decreasing lightness, and muted
|
||
saturation.
|
||
|
||
**Do not copy the measured margins into this file.** Run the check — it prints
|
||
every one of them and fails if any regresses:
|
||
|
||
```
|
||
python3 unified-design-system/scripts/ramp_check.py
|
||
```
|
||
|
||
Two consequences worth keeping in prose, because the numbers alone do not say
|
||
them. The both-backgrounds rule is the binding constraint: colours legible on
|
||
a near-black *and* a near-white field only exist around L\* 44–59, which is why
|
||
the ramp is mid-toned rather than spanning light to dark. And because lightness
|
||
falls monotonically, hue and lightness encode redundantly, so `cat-1…6` still
|
||
reads as an ordinal scale in greyscale or under severe CVD.
|
||
|
||
Use them **in order** for ordered data, and *by position* for unordered data —
|
||
never pick "the green one" because green means good, which is the semantic
|
||
vocabulary leaking back in. Need a seventh category? That is a signal to group
|
||
the tail into "other", not to extend the ramp: a 7th hue cannot clear ΔE 20
|
||
against all six under CVD within the L\* 44–59 band.
|
||
|
||
## 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).
|
||
|
||
### The sizes above are **pixels**. On Tk that means a negative number.
|
||
|
||
Tk encodes the unit in the *sign* of the font size: **positive = points,
|
||
negative = pixels**. So `("Arial", 16)` is 16 **points**, not 16 pixels, and
|
||
renders ~37% larger than this scale specifies. Measured:
|
||
|
||
| Spec | `size=16` (points) | `size=-16` (pixels) |
|
||
| ---- | ------------------ | ------------------- |
|
||
| `linespace` | 26px | 19px |
|
||
| `ascent` | 21px | 15px |
|
||
|
||
Always write the negative form in Tk — `font=(family, -16)` for `body`. Passing
|
||
the positive px value straight through inflates every string in the app by a
|
||
third, which is enough on its own to push a 768px-tall layout off-screen (it
|
||
did: it was the root cause of the diet-guard meal gate needing 974px in a 724px
|
||
pane). This is a silent failure — nothing errors, the text is just wrong-sized —
|
||
so it is checked by the gate rather than left to review.
|
||
|
||
Flutter `fontSize` and CSS `px` are already pixels; no sign convention there.
|
||
|
||
## 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.
|
||
|
||
## Focus ring
|
||
|
||
| Token | Value | Notes |
|
||
| ------------ | ---------- | -------------------------------------------- |
|
||
| `focus-ring` | `#B8862E` (= `accent`) | 2px, offset 1px. |
|
||
|
||
Why the platform default is not good enough, and the Tk
|
||
`highlightcolor`/`highlightbackground` trap, are in
|
||
[`operability.md`](operability.md#the-focus-ring-token).
|
||
|
||
## Operability and screen size
|
||
|
||
Keyboard-only reachability and the small-screen budget are requirements, not
|
||
suggestions: several of these apps are lockers that hold a global input grab,
|
||
so a control only a pointer can reach is a bricked machine. Both, plus the
|
||
`focus-ring` token, are in [`operability.md`](operability.md).
|