From 5c03321c76510d869eff8dc9633ba55e490ddceb Mon Sep 17 00:00:00 2001 From: LinzLos <223187540+LinzLos@users.noreply.github.com> Date: Sat, 19 Sep 2026 12:01:25 -0700 Subject: [PATCH] Docs site: every number rendered, six components documented, one finding-ID space MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit scripts/render-docs.py replaces render-readme.py and writes the token, component, pattern, and finding counts and the version into the README, the intro page, the components page, the audit card, and docs.js. Foundations gains an Every-token table rendered from tokens.css (186; the curated sections show 92). Divider, Kbd, Spinner, Status Bar, and Status Dot get sections — six shipped class families had no page. The audit's v1.3/v1.5 findings are renumbered F-018–F-023; F-013–F-017 stay with the a11y page and the changelog. Intro page no longer says brand is forest green. 'What I won't ship' is dated Decisions; 'What's next' points at the hub docket. Tiny Wire.html (orphan single-file copy) removed. Sidebar rail in the nav. --- CHANGELOG.md | 8 + README.md | 2 +- Tiny Wire.html | 1579 -------------------------------------- docs/audit.html | 65 +- docs/components.html | 118 ++- docs/docs.js | 10 +- docs/foundations.html | 201 +++++ docs/index.html | 53 +- scripts/render-docs.py | 264 +++++++ scripts/render-readme.py | 156 ---- 10 files changed, 626 insertions(+), 1830 deletions(-) delete mode 100644 Tiny Wire.html create mode 100644 scripts/render-docs.py delete mode 100755 scripts/render-readme.py diff --git a/CHANGELOG.md b/CHANGELOG.md index e9fcb15..40a5a40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,17 +8,25 @@ All notable changes to **Tiny Wire** are tracked here. Versioning follows [SemVe #### Added +- **Components page**: Divider, Kbd, Spinner, Status Bar, and Status Dot get sections. `components.css` shipped six class families with no place a reader could find them; one consumer rebuilt `.status-stat` locally for exactly that reason. +- **Foundations**: an Every-token table at the end of the page, rendered from `lib/tokens.css` — all 186, light and dark, by tier. The curated sections above it show 92. - **CONSUMING.md**: a `Promotion` section stating how candidates are judged — the four-question sameness test, the glyph rule for visual atoms, and two thresholds: present in ≥ 2 consumers promotes; ≥ 2 copies inside one consumer consolidates there. The hub's heuristic line now states the numbers instead of `N`; the Layer 3 build-order line no longer names examples (all three had failed verification) and points at the candidates table instead; the "status pill 3/3" row is split into a passive status chip and an interactive live indicator, one consumer each — the dot itself already ships as `.monitoring-dot`. - **Card**: `.card-value` and `.card-delta` (+ `-success` / `-danger`) — the stat tile. Three consumers and both docs pages had each built this from inline styles; it now ships. Badge slot is a `.tag` in `.card-header`, so nothing new there. #### Changed - **README, `lib/CONSUMING.md`, the hub, and CONTRIBUTING** restructured for legibility. Each names its reader and opens in plain words. The `lib/` file list has one home (CONSUMING § The lib unit); the other three link to it. CONSUMING's rules are written as invariants — what must hold, what breaks if it doesn't, what checks it — marked `deterministic` or `judgment`. The hub reads state → contract → decisions → verified clean → coverage; its architecture / roadmap section is cut, and the one settled decision from it (components are authored once) is kept as a dated entry. +- **Every typed number in the docs is rendered**: `scripts/render-docs.py` (replaces `render-readme.py`) writes the token, component, pattern, and finding counts and the version into the README, the intro page, the components page, the audit card, and `docs.js`. Hand edits between the markers are overwritten. +- **Audit page**: "What I won't ship" is now "Decisions", each dated to the release it was made at; the icon decision is amended for Phosphor. "What's next" points at the hub's candidates table instead of carrying its own roadmap. - **README counts are rendered**, not typed: `scripts/render-readme.py` counts tokens in `lib/tokens.css`, documented components on the components page, and patterns, and rewrites the block between markers. It counts 186 tokens (the README said "~180"; the count is now exact and re-rendered on every run) and lists the class families `components.css` ships that have no docs section yet. - **Consumer profiles** are named `static` and `react` instead of A and B, in `lib/CONSUMING.md` and the hub. The letters only meant something to whoever wrote them. #### Fixed +- **Intro page** said brand is forest green; it has been cobalt since v1.5. Its counts (16 findings, 28 components, three files in `lib/`) were typed and stale; they are rendered or linked now. +- **Finding IDs**: the audit page's v1.3 and v1.5 findings reused F-013–F-018, which the a11y page and this changelog already used for the v1.1 contrast findings. The audit's are renumbered F-018–F-023; the a11y page keeps the originals. One ID space. +- **`Tiny Wire.html`** at the repo root — a 1,579-line single-file copy of the system with its own token values, linked from nowhere — is removed. Git history keeps it. +- **Sidebar rail** example page is in the nav. - **CONTRIBUTING** pointed token additions at `lib/globals.css`; tokens are declared in `lib/tokens.css`. The project-structure tree that repeated the `lib/` list is replaced by a link. - **Patterns**: the dashboard pattern's stat cards used `.p-stat-*` classes that existed only inside `docs/patterns.html`, so the pattern couldn't be lifted as promised. They now use the shipped Card parts. Positive deltas move from `--brand` to `--success-dark`, matching `.tag-success` per the v1.5 semantic-color pass. diff --git a/README.md b/README.md index 49531c0..6a003c2 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ TinyWire is a design system for the interfaces where people operate complex soft - **186 tokens** in `lib/tokens.css`, three tiers (primitive → semantic → component), light and dark -- **30 documented components** on the [components page](docs/components.html) — `lib/components.css` ships 38 class families; 6 have no section yet +- **35 documented components** on the [components page](docs/components.html) — `lib/components.css` ships 38 class families - **5 patterns**: Dashboard · Data Table with Filters · Empty states · Login · Settings - **2 fonts**: Bricolage Grotesque (display) + DM Sans (body) diff --git a/Tiny Wire.html b/Tiny Wire.html deleted file mode 100644 index 71eaade..0000000 --- a/Tiny Wire.html +++ /dev/null @@ -1,1579 +0,0 @@ - - - - - - -Tiny Wire — Design System - - - - - - - - - - - -
- - -
-
Design System
-
Tiny Wire
-
A minimal, warm-toned design system built for dense operational interfaces. Two fonts, a coherent color language, and a small set of reusable components.
-
- - -
-
Usage
-
Drop globals.css into any project. All tokens are CSS custom properties on :root.
- -
-/* 1. Import the token file */ -@import './tokens/globals.css'; - -/* 2. Import fonts in your <head> */ -/* Bricolage Grotesque + DM Sans from Google Fonts */ - -/* 3. Use tokens anywhere */ -.my-card { - background: var(--surface); - border: 1px solid var(--border); - border-radius: var(--radius-md); - padding: var(--space-16); - box-shadow: var(--shadow-card); -} -
- -
-/* JS / TS — import tokens object */ -import tokens from './tokens/design-tokens.js' - -// Access any value -const brand = tokens.colors.brand // '#2F4BA6' -const base = tokens.typography.fontSize.base // 13 -
-
- - -
-
Colors
-
A warm neutral base with a cobalt brand, green reserved strictly for success/trust states, orange-red danger, and categorical data colors. All hues share a muted, slightly desaturated quality.
- -
Surfaces
-
-
-
-
Surface
--surface
-
-
-
-
Surface Subtle
--surface-subtle
-
-
-
-
Surface Page
--surface-page
-
-
-
-
Surface Muted
--surface-muted
-
-
- -
Borders
-
-
-
-
Border
--border
-
-
-
-
Border Light
--border-light
-
-
-
-
Border Dashed
--border-dashed
-
-
- -
Text
-
-
-
-
Primary
--text-primary
-
-
-
-
Secondary
--text-secondary
-
-
-
-
Tertiary
--text-tertiary
-
-
-
-
Inverse
--text-inverse
-
-
- -
Brand — Cobalt
-
-
-
-
Brand
--brand
-
-
-
-
Brand Light
--brand-light
-
-
-
-
Brand Mid
--brand-mid
-
-
-
-
Brand Dark
--brand-dark
-
-
- -
Success — Green (reserved)
-
-
-
-
Success
--success
-
-
-
-
Success Light
--success-light
-
-
-
-
Success Mid
--success-mid
-
-
-
-
Success Dark
--success-dark
-
-
- -
Status — Danger
-
-
-
-
Danger
--danger
-
-
-
-
Danger Light
--danger-light
-
-
-
-
Danger Mid
--danger-mid
-
-
- -
Status — Warning
-
-
-
-
Warning
--warning
-
-
-
-
Warning Light
--warning-light
-
-
-
-
Warning Mid
--warning-mid
-
-
- -
Status — Info & Accent
-
-
-
-
Info
--info
-
-
-
-
Info Light
--info-light
-
-
-
-
Info Mid
--info-mid
-
-
-
-
Accent
--accent
-
-
-
-
Accent Light
--accent-light
-
-
- -
Data / Charts
-
-
-
-
Inflow
--data-inflow
-
-
-
-
Outflow
--data-outflow
-
-
-
-
Target
--data-target
-
-
-
-
Chart Blue
--chart-blue
-
-
-
-
Chart Azure
--chart-azure
-
-
-
- - -
-
Typography
-
Bricolage Grotesque for headings and display numerics. DM Sans for all body copy, labels, and UI text. Both loaded from Google Fonts.
- -
Font Families
-
-
-
--font-heading
-
Bricolage Grotesque
-
Display · Numerics · Headings
-
-
-
--font-body
-
DM Sans
-
Body · Labels · UI text
-
-
- -
Size Scale
-
-
--text-3xl
26px
The quick brown fox
-
--text-2xl
20px
The quick brown fox
-
--text-xl
18px
The quick brown fox
-
--text-lg
16px
The quick brown fox
-
--text-base
13px
The quick brown fox jumps over the lazy dog
-
--text-md
12px
The quick brown fox jumps over the lazy dog
-
--text-sm
11px
Label caps · Section heading
-
--text-xs
10px
Caption · Overline
-
--text-2xs
9px
Tag · Badge
-
- -
Weights
-
-
--weight-lightLight 300
-
--weight-regularRegular 400
-
--weight-mediumMedium 500
-
--weight-semiboldSemibold 600
-
--weight-boldBold 700
-
-
- - -
-
Spacing
-
A tight scale built for dense UI. All values are in px.
-
-
--space-22px
-
--space-44px
-
--space-55px
-
--space-66px
-
--space-88px
-
--space-1010px
-
--space-1212px
-
--space-1414px
-
--space-1616px
-
--space-1818px
-
--space-2020px
-
--space-2424px
-
-
- - -
-
Border Radius
-
Five steps from tight to pill. --radius (10px) is the default card radius.
-
-
--radius-xs
4px
-
--radius-sm
6px
-
--radius-md
8px
-
--radius
10px
-
--radius-full
9999px
-
-
- - -
-
Shadows
-
Subtle, layered shadows. Never black — always transparent washes.
-
-
--shadow-card
-
--shadow-nav
-
--shadow-toggle
-
--shadow-hover
-
--shadow-modal
-
--shadow-dropdown
-
--shadow-overlay
-
-
- - -
-
Animation
-
Spring easing for entrances, standard ease for micro-interactions. Click a box to replay.
- -
Easings
-
-
--ease-springcubic-bezier(0.16, 1, 0.3, 1) — overshoots slightly, feels alive
-
--ease-outease-out — clean deceleration
-
--ease-standardease — general-purpose transitions
-
- -
Durations
-
-
--duration-fast0.18s — hover states, micro color changes
-
--duration-base0.22s — filter entrances
-
--duration-moderate0.30s — modals, expandable regions
-
--duration-slow0.35s — page transitions
-
- -
Keyframe Classes
-
-
-
-
.page-enter
-
pageIn · slow · spring
-
-
-
-
.filter-enter
-
filterIn · base · ease-out
-
-
-
-
.modal-enter
-
modalIn · moderate · spring
-
-
-
-
.fade-up
-
fadeUp · moderate · spring
-
-
-
- - -
-
Buttons
-
Five variants covering the full action spectrum from primary confirmation to destructive hard-stop.
-
- - - - - -
-
/* HTML */ -<button class="btn-primary">Apply changes</button> -<button class="btn-danger">Confirm delete</button> -<button class="btn-stop">Stop all dialing</button> -<button class="btn-rollback">Rollback</button> -<button class="btn-ghost">Cancel</button>
-
- - -
-
Tags & Badges
-
Tags are loud: all-caps, colored fill. Badges are quiet: muted, used for metadata like "rolled back".
-
- Hard stop - Active - Info - Review - rolled back - v1.2 -
-
class="tag tag-danger" /* orange-red · Hard stop, Error */ -class="tag tag-success" /* green · Active, OK */ -class="tag tag-info" /* navy · Informational */ -class="tag tag-warn" /* warm brown · Caution */ -class="badge" /* muted · Metadata */
-
- - -
-
Status Chips
-
Pill-shaped semantic status indicators. Always paired with a dot that inherits currentColor.
-
- Dialing active - Warning - Critical - Stopped - Monitoring -
-
<span class="status-chip status-chip--ok"> - <span class="status-chip-dot"></span> - Dialing active -</span> -/* Variants: --ok --warn --critical --stopped --info */
-
- - -
-
Status Dots
-
Inline status indicators. The animated monitoring-dot has a pulsing halo for live-feed contexts.
-
-
dot-green
-
dot-amber
-
dot-red
-
dot-blue
-
dot-muted
-
monitoring-dot (live)
-
-
- - -
-
Inputs & Selects
-
32px tall, 6px radius. Full width by default; .input-sm for inline numeric fields (72px wide). Focus state swaps border to --text-tertiary.
-
-
- - -

Helper text goes below the input.

-
-
-
- - -
-
- - -
-
-
-
- - -
-
Cards
-
The primary container unit. White surface, 1px border, 8px radius, 16px padding. Disabled state dims to 45% opacity.
-
-
-
Section title
-

Card content goes here. Helper text and form fields live inside.

-
-
-
Disabled card
-

Controls are locked in this state.

-
-
-
<div class="card">...</div> -<div class="card card-disabled">...</div> /* opacity:0.45 + no pointer events */
-
- - -
-
Slider
-
A custom range input styled with a pill track and circular thumb. The value display uses --font-heading for a numeric display feel.
-
-
-
Dial speed
-
- - 1.2 -
-
- 1.0 - 2.0 -
-
-
-
- - -
-
Alerts & Validation
-
Inline messages for validation states, system feedback, and contextual warnings. All use color-mix to derive tinted backgrounds from the semantic color.
-
-
Warn threshold must be below the pause threshold.
-
Current rate (3.2%) already meets this threshold — system is now in warn.
-
Targeting is active — priority routing applied to this segment.
-
Evaluation window closes in 47 minutes.
-
-
class="alert alert-danger" -class="alert alert-warn" -class="alert alert-success" -class="alert alert-info"
-
- - -
-
Banners
-
Full-width contextual banners for system-wide state changes. The pulsing dot signals an active condition.
-
-
- - Dialing stopped - Hard stop - · - Technical issue · resumes in 14:22 - -
-
-
-
-
- - Targeting High-value renewals - -
-
-
- - -
-
Status Bar
-
A compact inline strip showing live system readings. Rules separate stat groups. The monitoring dot animates when the system is active.
-
-
-
- Dialing active - -
- Failed connections - 3.2% - warn 4% · pause 5% -
- -
- - Monitoring -
-
-
-
-
- - - - - -
-
Table
-
Borderless rows, caps header, subtle dividers. Used for change logs, audit trails, and tabular data.
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WhenWhoWhat
11/26/25, 10:49 AMYouDial speed: 1.0 → 1.2
11/26/25, 9:49 AMT. OkaforRolled back: "Protect against overdialing: 2 → 3" rolled back
11/26/25, 9:22 AMT. OkaforProtect against overdialing: 2 → 3
-
-
-
- -
- - -
-
Tweaks
-
- - -
-
- - -
-
- - -
-
- - - - diff --git a/docs/audit.html b/docs/audit.html index b5b7a63..d5838f0 100644 --- a/docs/audit.html +++ b/docs/audit.html @@ -306,13 +306,13 @@

v1.5 — Reserve green

IDFindingSeverityStatus - F-017 + F-022 Green carried both the brand accent and the "safe / attested" status meaning — overloaded, so the trust signal never popped. Reserved green for a new --success family; brand + all interaction moved to cobalt; back-compat aliases kept. Medium Fixed - F-018 + F-023 The green-as-text contrast issue moved with the role: --success (green-500) as text on light tints is still ~3.5:1. Guidance shipped — --success-dark for text, bare --success for non-text (dots, borders, fills); a lint rule against bare --success on text is queued. Low Deferred · lint rule @@ -339,25 +339,25 @@

v1.3 — Pedigree pass

IDFindingSeverityStatus - F-013 + F-018 Dark --text-tertiary failed AA on --surface-inset (4.05:1). Lifted #948682 → #A0928E; the live checker now passes every pair in both themes. High Fixed - F-014 + F-019 lib/tokens.js had drifted from globals.css — three values (light/dark tertiary, dark disabled) shipped pre-AA hexes to JS consumers. Resynced. Medium Fixed - F-015 + F-020 The .select chevron was a hardcoded #8A7E7D (a stale token value) that read low-contrast in dark mode. Repointed to a mid-neutral legible in both themes. Medium Fixed - F-016 + F-021 Floating overlays stacked a solid border and a full elevation shadow — a doubled container signal. Border → --border-hairline; elevation does the lifting. Low Fixed @@ -378,6 +378,7 @@

v1.2 — Sidebar rail

v1.1 — Findings

Twelve issues, grouped by theme. Click a filter to scope the list. Every fixed finding links to the line that changed.

+

The live checker's five findings from the same release, F-013 – F-017, are on the A11y check page and keep those IDs. The audit's later findings start at F-018 — one ID space across both pages.

Filter @@ -877,26 +878,30 @@

How I audit

- -

What I won't ship (and why)

-

A design system is as much about what you refuse to add as what's in. These came up during the audit and stayed out.

+ +

Decisions

+

A design system is as much about what you refuse to add as what's in. These came up during audits and were decided; each says when. The findings above are the checked part of this page — this section is the judgment part.

A third type weight ramp

Bricolage + DM Sans is the system. Adding a mono display family "for code-forward dashboards" was floated and rejected — every font is a maintenance contract.

+
Decided at v1.1 · 2026-05-20
A separate "compact" density

Tiny Wire is already dense by default (13px base, 32px controls). A "compact" override would double the surface area of every state matrix. If 13px is too big, override the token at scope.

+
Decided at v1.1 · 2026-05-20
Hand-drawn iconography
-

Examples use Lucide-style strokes inline. The system doesn't ship icons — bundling a set means owning a set. Consumers pick their own.

+

The system doesn't draw an icon set — owning a set means maintaining a set. Amended: it names one library, Phosphor, and will ship size and stroke conventions, so consumers stop hand-drawing. Still no bundled glyphs.

+
Decided at v1.1 · 2026-05-20 · amended 2026-09-18
A second brand colour

The temptation is real — every operational tool has a "secondary accent" moment. But every additional brand-mapped token doubles the override matrix for re-skinning. Override --brand at the consumer's scope instead.

+
Decided at v1.1 · 2026-05-20
@@ -904,45 +909,7 @@

What I won't ship (and why)

What's next

-

The next release is in flight. The deferred findings get their fix, plus the additions below.

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TargetTypeNotesStatus
ARIA documentation passDocsToast, spinner, skeleton, alert — one block per component on the components page.In progress
Segmented controlNew componentA formal name for what .btn-group + .btn.active is doing. Comes with keyboard arrow nav.Drafting
Date / range pickerNew componentThe most-requested gap from the v1.0 feedback round.Drafting
Theme builderToolingLive token editor in the docs site. Drop a brand colour, see every component re-skin.Backlog
Focus-trap RFC (TW-018)SpecThe "does Tiny Wire ship JS?" decision. Drafting.Backlog
-
+

Not a roadmap. The candidates table in the Design System Hub is what's next — every row is something a real app built, counted, and sorted by how many apps built it. Deferred findings above keep their IDs until they close.

Every release ships with a page like this. The point isn't the changelog — every repo has one of those. The point is to make the reasoning visible: what changed, what didn't, and what I refused to add.

diff --git a/docs/components.html b/docs/components.html index 9218c3e..a4feb0d 100644 --- a/docs/components.html +++ b/docs/components.html @@ -21,7 +21,7 @@
Components

Component library

-

30 components covering forms, feedback, navigation, overlays, and data. Every component is plain HTML + a class — no framework, no runtime. Click "Code" on any demo to copy the markup.

+

35 documented components covering forms, feedback, navigation, overlays, and data. Every component is plain HTML + a class — no framework, no runtime. Click "Code" on any demo to copy the markup.

Accordion

.accordion · .accordion-item · .accordion-trigger · .accordion-content
@@ -491,6 +491,28 @@

Dialog

</div>
+

Divider

+
.separator · .separator-strong · .separator-v
+

A hairline between things. Horizontal by default; .separator-strong for a heavier line; .separator-v for a vertical rule inside a row. It carries no meaning of its own — if the break matters to a screen reader, use a heading or a landmark instead.

+
+
+

Above the line

+
+

Below the line, then a stronger one

+
+
LeftRight
+
+
+
+ + +
+
+ 
<hr class="separator">
+<hr class="separator separator-strong">
+<span class="separator-v"></span>
+
+
.menu · .menu-item · .menu-label · .menu-separator

List-of-actions menu. Supports icons, keyboard shortcuts, grouped sections, and a destructive variant.

@@ -657,6 +679,25 @@

Input group (addons)

</div> +

Kbd

+
kbd · .kbd
+

A key. The native <kbd> element is styled directly; the class does the same for a span. The Command palette's ⌘K badge is this.

+
+
+ Search ⌘K + Save ⌘S + Close Esc +
+
+
+ + +
+
+ 
<kbd>⌘</kbd><kbd>K</kbd>
+<span class="kbd">Esc</span>
+
+

Pagination

.pagination · .pagination-item · .pagination-ellipsis
@@ -939,6 +980,56 @@

Slider

</div>
+

Spinner

+
.spinner · .spinner-sm · .spinner-lg
+

An in-progress ring in three sizes. Put it beside a label, or inside a button while it waits. Give it role="status" and an aria-label — the ring itself says nothing.

+
+
+ + + + +
+
+
+ + +
+
+ 
<span class="spinner" role="status" aria-label="Loading"></span>
+<button class="btn btn-secondary" disabled><span class="spinner spinner-sm"></span> Saving…</button>
+
+ +

Status Bar

+
.status-bar · .status-stat · .status-stat-label · .status-stat-value · .status-stat-context · .status-bar-rule
+

A row of small stats with rules between them — the strip under a dashboard header. Each .status-stat is a label, a value in tabular numerals, and optional context.

+
+
+
+
Queue1,284open
+ +
Agents 12live
+ +
SLA98.2%
+
+
+
+
+ + +
+
+ 
<div class="status-bar">
+  <div class="status-stat">
+    <span class="status-stat-label">Queue</span>
+    <span class="status-stat-value">1,284</span>
+    <span class="status-stat-context">open</span>
+  </div>
+  <span class="status-bar-rule"></span>
+  …
+</div>
+
+

Status Chip

.chip .chip-ok | .chip-warn | .chip-critical | .chip-info | .chip-stopped

Pill-shaped semantic status indicators. Always pair with a .chip-dot that inherits the chip color.

@@ -973,6 +1064,29 @@

Status dots

+

Status Dot

+
.dot .dot-green | .dot-warn | .dot-amber | .dot-red | .dot-blue | .dot-muted · .monitoring-dot
+

A colored dot that means a state. .dot-* is still; .monitoring-dot pulses for something live right now. Both are decorative — the meaning goes in text beside them, never in the color alone. The Status Chip is a dot with its label built in.

+
+
+ Healthy + Degraded + Chart amber + Down + Info + Off + Live +
+
+
+ + +
+
+ 
<span class="dot dot-green"></span> Healthy
+<span class="monitoring-dot"></span> Live
+
+

Switch

.switch

Toggle for boolean settings. Use when the state takes effect immediately; use Checkbox when paired with a form submission.

@@ -1092,7 +1206,7 @@

Tag & Badge

New Default rolled back - v1.3 + v1.5
diff --git a/docs/docs.js b/docs/docs.js index 3262765..25b52b3 100644 --- a/docs/docs.js +++ b/docs/docs.js @@ -7,9 +7,9 @@ const root = document.documentElement; // ─── Single source of truth for the current version ──────────────────── - // Bump this ONE constant each release. It drives the sidebar below and every + // Rendered from /VERSION — do not edit by hand. It drives the sidebar below and every // element marked [data-tw-version] across the docs (see init()). - const VERSION = 'v1.5'; + const VERSION = /* record:version start */'v1.5'/* record:version end */; // rendered from /VERSION by scripts/render-docs.py // ─── Sidebar template ────────────────────────────────────────────────── const SIDEBAR_HTML = ` @@ -68,9 +68,11 @@ Checkbox Command Dialog + Divider Dropdown Menu Empty State Input + Kbd Pagination Popover Progress @@ -78,9 +80,13 @@ Select Sheet Sidebar + Sidebar rail (example) Skeleton Slider + Spinner + Status Bar Status Chip + Status Dot Switch Table Tabs diff --git a/docs/foundations.html b/docs/foundations.html index 98ba3b7..d86b1c8 100644 --- a/docs/foundations.html +++ b/docs/foundations.html @@ -219,6 +219,207 @@

Typography

--weight-boldBold 700 — page titles, hero
+

Every token

+

The sections above explain the tokens that matter most. This table is all of them — rendered from lib/tokens.css by scripts/render-docs.py, so it cannot fall behind the file. Dark shows only where it differs from light.

+ + +
Tier 1 — Primitives
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TokenLightDark
--warm-0#FFFFFF—
--warm-50#F7F4F2—
--warm-100#F1EDEB—
--warm-150#EBE6E3—
--warm-200#E5DFDC—
--warm-300#D6CFCB—
--warm-400#C2B9B5—
--warm-500#A89E99—
--warm-600#8A7F7B—
--warm-700#6E625F—
--warm-800#5C504F—
--warm-900#3A302E—
--warm-950#1E1918—
--cobalt-50#EEF1FB#1A2342
--cobalt-100#DBE2F4—
--cobalt-200#BCC9EA#2E3F6B
--cobalt-300#93A8DE—
--cobalt-400#6E86D2—
--cobalt-500#4761BE—
--cobalt-600#2F4BA6#8AA0DE
--cobalt-700#243B83#7E96D8
--cobalt-800#1C2F66—
--cobalt-900#16244E—
--green-100#F2F6F2#1F2A1F
--green-300#C8D9C7#3F603E
--green-500#629460#8FB68D
--green-700#3F603E#C8D9C7
--clay-100#F4EFEA#251D19
--clay-300#DCC9B5#4A3A24
--clay-600#9A6B33#C9A063
--clay-700#6B4B3E—
--red-100#FBEFEB#2E1C13
--red-300#EBB39D#6E3217
--red-500#CE430A#E66B36
--azure-500#0EA5E9#3DBEF5
--azure-light#EBF7FD—
--amber-chart#B98326#D4A04A
--violet-chart#6B4B8A#9F7CBC
--elevation-sm0 1px 2px rgba(30,25,24,0.05), 0 1px 1px rgba(30,25,24,0.04)0 1px 2px rgba(0,0,0,0.40), 0 1px 1px rgba(0,0,0,0.30)
--elevation-md0 2px 4px rgba(30,25,24,0.05), 0 6px 16px rgba(30,25,24,0.06)0 2px 4px rgba(0,0,0,0.40), 0 6px 16px rgba(0,0,0,0.40)
--elevation-lg0 8px 24px rgba(30,25,24,0.10)0 8px 24px rgba(0,0,0,0.50)
--elevation-xl0 16px 40px rgba(30,25,24,0.14), 0 2px 6px rgba(30,25,24,0.06)0 16px 40px rgba(0,0,0,0.60), 0 2px 6px rgba(0,0,0,0.30)
+
Tier 2 — Semantic
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TokenLightDark
--surfacevar(--warm-0)#1F1A18
--surface-subtlevar(--warm-50)#19130F
--surface-pagevar(--warm-50)#16110F
--surface-mutedvar(--warm-100)#2A211E
--surface-insetvar(--warm-150)#322924
--bordervar(--warm-300)#3A312D
--border-lightvar(--warm-200)#2E2722
--border-dashedvar(--warm-500)#6B5C57
--border-strongvar(--warm-400)#4D423D
--border-hairlinecolor-mix(in srgb, var(--warm-950) 8%, transparent)color-mix(in srgb, #F4EEEC 9%, transparent)
--text-primaryvar(--warm-950)#F4EEEC
--text-secondaryvar(--warm-800)#C5B6B2
--text-tertiaryvar(--warm-700)#A0928E
--text-inverse#FFFFFF#1E1918
--text-disabled#B5ABA8#756763
--brandvar(--cobalt-600)—
--brand-lightvar(--cobalt-50)—
--brand-midvar(--cobalt-200)—
--brand-darkvar(--cobalt-700)—
--brand-fg#FFFFFF#03131C
--successvar(--green-500)—
--success-lightvar(--green-100)—
--success-midvar(--green-300)—
--success-darkvar(--green-700)—
--success-fg#FFFFFF#0E1A0D
--logovar(--brand)var(--text-primary)
--dangervar(--red-500)—
--danger-lightvar(--red-100)—
--danger-midvar(--red-300)—
--danger-fg#FFFFFF#190B05
--warningvar(--clay-600)—
--warning-lightvar(--clay-100)—
--warning-midvar(--clay-300)—
--warning-fg#FFFFFF#1A100C
--infovar(--cobalt-700)—
--info-lightvar(--cobalt-50)—
--info-midvar(--cobalt-200)—
--info-fg#FFFFFF#06101F
--accentvar(--cobalt-600)—
--accent-lightvar(--cobalt-50)—
--accent-fg#FFFFFF#03131C
--data-inflowvar(--red-500)—
--data-outflowvar(--green-500)—
--data-targetvar(--warm-500)#847671
--chart-bluevar(--cobalt-700)—
--chart-azurevar(--azure-500)—
--chart-ambervar(--amber-chart)—
--chart-violetvar(--violet-chart)—
--ringcolor-mix(in srgb, var(--accent) 55%, transparent)—
--ring-offsetvar(--surface)—
--font-heading'Bricolage Grotesque', system-ui, sans-serif—
--font-body'DM Sans', system-ui, sans-serif—
--font-monoui-monospace, 'SF Mono', Menlo, Consolas, monospace—
--text-2xs9px—
--text-xs10px—
--text-sm11px—
--text-md12px—
--text-base13px—
--text-lg16px—
--text-xl19px—
--text-2xl23px—
--text-3xl28px—
--text-4xl33px—
--text-5xl48px—
--weight-light300—
--weight-regular400—
--weight-medium500—
--weight-semibold600—
--weight-bold700—
--leading-tight1—
--leading-snug1.1—
--leading-compact1.3—
--leading-normal1.5—
--tracking-tight-0.02em—
--tracking-snug-0.01em—
--tracking-slight-0.005em—
--tracking-caps0.07em—
--numeric-tabular"tnum" 1, "lnum" 1—
--space-00px—
--space-22px—
--space-44px—
--space-54px—
--space-66px—
--space-78px—
--space-88px—
--space-1010px—
--space-1212px—
--space-1414px—
--space-1616px—
--space-1818px—
--space-2020px—
--space-2424px—
--space-3232px—
--space-4040px—
--space-4848px—
--space-6464px—
--radius-2xs2px—
--radius-xs4px—
--radius-sm6px—
--radius-md8px—
--radius8px—
--radius-lg12px—
--radius-full9999px—
--shadow-cardvar(--elevation-sm)—
--shadow-navvar(--elevation-sm)—
--shadow-togglevar(--elevation-sm)—
--shadow-hovervar(--elevation-md)—
--shadow-modalvar(--elevation-xl)—
--shadow-dropdownvar(--elevation-lg)—
--shadow-overlayvar(--elevation-lg)—
--shadow-focus0 0 0 3px var(--ring)—
--size-icon-sm13px—
--size-icon-base18px—
--size-icon-lg22px—
--size-avatar-sm24px—
--size-avatar-md30px—
--size-avatar-lg34px—
--size-control-sm24px—
--size-control-md32px—
--size-control-lg40px—
--size-status-dot-sm6px—
--size-status-dot-base7px—
--size-status-dot-lg8px—
--sidebar-w56px—
--topbar-h56px—
--ease-springcubic-bezier(0.16, 1, 0.3, 1)—
--ease-outease-out—
--ease-standardease—
--duration-fast0.15s—
--duration-base0.22s—
--duration-moderate0.30s—
--duration-slow0.40s—
--z-dropdown50—
--z-sticky100—
--z-overlay200—
--z-modal300—
--z-toast400—
--z-tooltip500—
+
Tier 3 — Component
+
+ + + + + + +
TokenLightDark
--button-bgvar(--brand)—
--button-fgvar(--brand-fg)—
--card-bgvar(--surface)—
--card-shadowvar(--shadow-card)—
--input-bgvar(--surface)—
--input-bordervar(--border)—
+ + diff --git a/docs/index.html b/docs/index.html index 1b54f5a..95ce1cd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -20,11 +20,10 @@
- Design System · v1.3 - Just shipped + Design System · v1.5

Tiny Wire

-

A minimal, warm-neutral design system with a single cobalt accent, built for dense operational interfaces. Two fonts, a three-tier token architecture, ~30 reusable components, and a token layer that swaps cleanly between light and dark.

+

A minimal, warm-neutral design system with a single cobalt accent, built for dense operational interfaces. Two fonts, 186 tokens in three tiers, 35 documented components, and a token layer that swaps cleanly between light and dark. The numbers on this page are rendered from the source, not typed.

@@ -34,8 +33,8 @@

Tiny Wire

Why this system exists
-

Most of the work I do lives behind NDAs — operational tools, internal control panels, monitoring dashboards. Tiny Wire is the public-safe twin: same constraints, same warm density, built so the process of designing and maintaining a system is visible without leaking a single line of client UI.

-

Read the audit to see what shipping and maintaining a system actually looks like — 16 findings, 14 fixes, 0 breaking changes across four releases.

+

Most of the work I do lives behind NDAs — operational tools, internal control panels, monitoring dashboards. Tiny Wire is the public-safe twin: same constraints, same warm density, built so the process of designing and maintaining a system is visible without leaking a single line of client UI. I build prototypes on it and fold what they teach me back in.

+

Read the audit to see what shipping and maintaining a system actually looks like — 23 findings with IDs, fixed or deferred with a reason, and no class removed since the first public release.

@@ -44,11 +43,11 @@

Tiny Wire

Foundations
-
Colors, type, spacing, radius, shadows, animation.
+
Colors, type, spacing, radius, shadows, animation — and every token, rendered from the source.
Components
-
28 atoms and composites, full state matrix.
+
35 documented components, full state matrix.
Patterns
@@ -57,15 +56,15 @@

Tiny Wire
Audit - v1.3 + v1.5
-
Release notes, findings, and how I think about maintenance.
+
Release notes, findings, decisions, and how I audit.

Quick start

-

Drop two CSS files into your project. No build step, no framework lock-in. Works in any HTML, React, Vue, or static site.

+

For a plain HTML page: two stylesheet links, no build step. Building a React or Tailwind app? Take tokens.css only — Consuming Tiny Wire says why.

1. Add fonts to your <head>

<link rel="preconnect" href="https://fonts.googleapis.com">
@@ -101,7 +100,7 @@ 
5. Access tokens from JS

 
   
   
Principles

-  
The constraints that keep Tiny Wire coherent — what gets in, and what doesn't.

+  
The constraints that keep Tiny Wire coherent — what gets in, and what doesn't. Each one is true of the current release; when one stops being true, it changes here.

 
   

     

@@ -110,7 +109,7 @@ 
Principles

     

     

       
Warm, not cold

-      
Neutrals lean warm (#F7F4F3 surface, #1E1918 ink). Brand is forest green, not corporate blue. Status colors are muted and earthy — danger is orange-red, warning is brown.

+      
Neutrals lean warm (#F7F4F3 surface, #1E1918 ink). Brand and interaction are one cobalt; green is reserved for success and trust, so it reads as a verdict. Status colors stay muted — danger is orange-red, warning a disciplined amber.

     

     

       
Two fonts, total

@@ -126,35 +125,7 @@ 
Principles

 
   
   
What's in the repo

-  
Three files in lib/ are all you need. The rest is docs.

-
-  

-    
-      
-      
-        
-          
-          
-          
-        
-        
-          
-          
-          
-        
-        
-          
-          
-          
-        
-        
-          
-          
-          
-        
-      
-    
FilePurposeSize
lib/globals.cssToken definitions (light + dark), reset, base typography, keyframes, animation utilities.~10 KB
lib/components.cssAll 30 components. Each consumes tokens — no hardcoded values.~38 KB
lib/tokens.jsSame tokens, exported as a JS object. Use in scripts, theme builders, generators.~3 KB
docs/This documentation site. Not required for consumers.—

-  

+  
lib/ is five files, and which ones you take depends on your profile. The one list — each file, what it is, who takes it — is in Consuming Tiny Wire, so it can't drift from this page. docs/ is this site; consumers don't need it.

 
   
Ready to build? Jump to Components for the full library, or Foundations for the token reference.

 
diff --git a/scripts/render-docs.py b/scripts/render-docs.py
new file mode 100644
index 0000000..4685ee9
--- /dev/null
+++ b/scripts/render-docs.py
@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Render every typed number in the docs from lib/ and the docs pages.
+
+    python3 scripts/render-docs.py           # check: exit 1 if anything is stale
+    python3 scripts/render-docs.py --write   # rewrite the rendered spots in place
+
+Each number means one thing:
+  tokens      custom properties declared in lib/tokens.css
+  components  
 sections on docs/components.html — the documented set
+  families    top-level class families in lib/components.css, minus parts
+  patterns    
 sections on docs/patterns.html
+  findings    distinct F-### ids across docs/audit.html and docs/a11y.html
+  version     /VERSION
+
+Rendered spots sit between markers. Blocks: ``
+in README.md, `` in docs/foundations.html.
+Inline: `186` and
+friends (n-components, n-families, n-patterns, n-findings, version) anywhere
+in the HTML; `/* record:version start */` in docs/docs.js.
+
+It also lists what lib/components.css ships that has no docs section of its
+own. That list should be empty; while it isn't, those are components a
+reader cannot find.
+"""
+import argparse
+import difflib
+import html
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# Class families that are parts of a form or a page, not components.
+PARTS = {"field", "helper", "label", "section"}
+# Heading word -> class family, where the two differ.
+ALIASES = {"button": "btn", "divider": "separator"}
+# Families that share one docs section with another family.
+SHARED = {"tabs": {"tab"}, "dot": {"monitoring"}}
+WORDS = {1: "one", 2: "two", 3: "three", 4: "four", 5: "five"}
+
+
+# ------------------------------------------------------------------ sources
+
+def strip_comments(css):
+    return re.sub(r"/\*.*?\*/", "", css, flags=re.S)
+
+
+def tokens():
+    """[(tier, name, light)] in file order, plus {name: dark}. Several
+    declarations can share a line, so match anywhere."""
+    css = (ROOT / "lib" / "tokens.css").read_text()
+    light, dark, tier = [], {}, "Tokens"
+    block = None
+    for line in css.splitlines():
+        if re.match(r"^:root\s*\{", line):
+            block = "light"
+        elif re.match(r"^:root\[data-theme=\"dark\"\]\s*\{", line):
+            block = "dark"
+        elif line.startswith("}"):
+            block = None
+        m = re.search(r"TIER (\d) — ([A-Z]+)", line)
+        if m:
+            tier = f"Tier {m.group(1)} — {m.group(2).title()}"
+        for name, value in re.findall(r"(--[a-z0-9-]+)\s*:\s*([^;]+);", strip_comments(line)):
+            if block == "light":
+                light.append((tier, name, value.strip()))
+            elif block == "dark":
+                dark[name] = value.strip()
+    return light, dark
+
+
+def token_tiers():
+    return sorted(set(re.findall(r"TIER (\d)", (ROOT / "lib" / "tokens.css").read_text())))
+
+
+def families():
+    """Top-level class families: the first segment of every class selector
+    that starts a rule or follows a comma."""
+    css = strip_comments((ROOT / "lib" / "components.css").read_text())
+    return sorted(set(re.findall(r"(?:^|,)\s*\.([a-z][a-z0-9]*)", css, re.M)))
+
+
+def sections(page):
+    """(heading, classes used under it) for every 
 on a docs page."""
+    text = (ROOT / "docs" / page).read_text()
+    out = []
+    for chunk in re.split(r"]*>", text)[1:]:
+        title = re.sub(r"<[^>]+>", "", chunk.split("
", 1)[0]).replace("&", "&").strip()
+        classes = set()
+        for attr in re.findall(r'class="([^"]*)"', chunk):
+            classes.update(attr.split())
+        out.append((title, classes))
+    return out
+
+
+def documented(secs, fams):
+    """family -> section title, when a heading names the family and the
+    section actually uses it."""
+    home = {}
+    for title, classes in secs:
+        words = [ALIASES.get(w.lower(), w.lower()) for w in re.split(r"[\s/&]+", title) if w]
+        for fam in fams:
+            if fam not in words:
+                continue
+            names = {fam} | SHARED.get(fam, set())
+            if names & classes or any(c.startswith(fam + "-") for c in classes):
+                for n in names:
+                    if n in fams:
+                        home.setdefault(n, title)
+    return home
+
+
+def shown_inside(fam, secs):
+    for title, classes in secs:
+        if fam in classes or any(c.startswith(fam + "-") for c in classes):
+            return title
+    return None
+
+
+def finding_ids():
+    ids = set()
+    for page in ("audit.html", "a11y.html"):
+        ids.update(re.findall(r"\bF-\d{3}\b", (ROOT / "docs" / page).read_text()))
+    return sorted(ids)
+
+
+def version():
+    return (ROOT / "VERSION").read_text().strip()
+
+
+# ------------------------------------------------------------------ renders
+
+def render_counts_md(n):
+    tier_word = WORDS.get(n["tiers"], str(n["tiers"]))
+    comp = (f"- **{n['components']} documented components** on the [components page](docs/components.html) — "
+            f"`lib/components.css` ships {n['families']} class families")
+    if n["undocumented"]:
+        comp += f"; {len(n['undocumented'])} have no section yet"
+    return "\n".join([
+        f"- **{n['tokens']} tokens** in `lib/tokens.css`, {tier_word} tiers (primitive → semantic → component), light and dark",
+        comp,
+        f"- **{n['patterns']} patterns**: " + " · ".join(n["pattern_titles"]),
+    ])
+
+
+def render_tokens_html(light, dark):
+    out = []
+    tier = None
+    for t, name, value in light:
+        if t != tier:
+            if tier is not None:
+                out.append("    
")
+            tier = t
+            out.append(f'  
{html.escape(t)}
')
+            out.append('  
'
+                       ''
+                       ''
+                       '')
+        d = dark.get(name)
+        dark_cell = f"{html.escape(d)}" if d and d != value else "—"
+        out.append(f'      '
+                   f''
+                   f'')
+    out.append("    
TokenLightDark
{html.escape(name)}{html.escape(value)}{dark_cell}
")
+    return "\n".join(out)
+
+
+# ------------------------------------------------------------------ splice
+
+def splice_block(text, name, body, open_=""):
+    start, end = f"{open_} record:{name} start {close}", f"{open_} record:{name} end {close}"
+    i, j = text.find(start), text.find(end)
+    if i < 0 or j < 0 or j < i:
+        return text, False
+    return text[: i + len(start)] + "\n" + body + "\n" + text[j:], True
+
+
+def splice_inline(text, name, value, open_=""):
+    start, end = f"{open_} record:{name} start {close}", f"{open_} record:{name} end {close}"
+    pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.S)
+    new, n = pattern.subn(start + value + end, text)
+    return new, n > 0
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--write", action="store_true", help="rewrite the rendered spots in place")
+    args = ap.parse_args()
+
+    light, dark = tokens()
+    fams = families()
+    comp_secs = sections("components.html")
+    patterns = sections("patterns.html")
+    home = documented(comp_secs, fams)
+    components = [f for f in fams if f not in PARTS]
+    undocumented = [f for f in components if f not in home]
+    n = {
+        "tokens": len({name for _, name, _ in light}),
+        "tiers": len(token_tiers()),
+        "components": len(comp_secs),
+        "families": len(components),
+        "undocumented": undocumented,
+        "patterns": len(patterns),
+        "pattern_titles": [t for t, _ in patterns],
+        "findings": len(finding_ids()),
+        "version": version(),
+    }
+
+    print(f"tokens {n['tokens']} ({n['tiers']} tiers) · documented components {n['components']} · "
+          f"class families {n['families']} (+{len(fams) - len(components)} parts) · "
+          f"patterns {n['patterns']} · findings {n['findings']} · v{n['version']}")
+    if undocumented:
+        print("\nSHIPPED, NO DOCS SECTION")
+        for fam in undocumented:
+            where = shown_inside(fam, comp_secs)
+            print(f"  .{fam:14} {'shown inside: ' + where if where else 'not on the docs page'}")
+    print()
+
+    inline = {
+        "n-tokens": str(n["tokens"]), "n-components": str(n["components"]),
+        "n-families": str(n["families"]), "n-patterns": str(n["patterns"]),
+        "n-findings": str(n["findings"]), "version": "v" + n["version"],
+    }
+    targets = [
+        ROOT / "README.md", ROOT / "docs" / "index.html", ROOT / "docs" / "components.html",
+        ROOT / "docs" / "foundations.html", ROOT / "docs" / "audit.html", ROOT / "docs" / "docs.js",
+    ]
+    stale = []
+    for path in targets:
+        if not path.exists():
+            continue
+        current = path.read_text()
+        rendered = current
+        if path.suffix == ".js":
+            rendered, _ = splice_inline(rendered, "version", f"'v{n['version']}'", "/*", "*/")
+        else:
+            rendered, _ = splice_block(rendered, "counts", render_counts_md(n))
+            rendered, _ = splice_block(rendered, "tokens", render_tokens_html(light, dark))
+            for key, value in inline.items():
+                rendered, _ = splice_inline(rendered, key, value)
+        if rendered == current:
+            continue
+        stale.append(path)
+        if args.write:
+            path.write_text(rendered)
+            print(f"rewrote {path.relative_to(ROOT)}")
+        else:
+            sys.stdout.writelines(difflib.unified_diff(
+                current.splitlines(keepends=True), rendered.splitlines(keepends=True),
+                fromfile=str(path.relative_to(ROOT)), tofile="rendered",
+            ))
+
+    if not stale:
+        print("docs are current")
+        return 0
+    if args.write:
+        return 0
+    print(f"\n{len(stale)} file(s) stale — run with --write to update", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/render-readme.py b/scripts/render-readme.py
deleted file mode 100755
index a77629f..0000000
--- a/scripts/render-readme.py
+++ /dev/null
@@ -1,156 +0,0 @@
-#!/usr/bin/env python3
-"""Render the README's counts from lib/ and the docs pages.
-
-    python3 scripts/render-readme.py           # check: exit 1 if the README is stale
-    python3 scripts/render-readme.py --write   # rewrite the counts block
-
-Each number means one thing:
-  tokens      unique custom-property names declared in lib/tokens.css
-  components  
 sections on docs/components.html — the documented set
-  patterns    
 sections on docs/patterns.html
-
-It also lists what lib/components.css ships that has no docs section of its
-own. That list should be empty; while it isn't, those are components a
-reader cannot find.
-"""
-import argparse
-import difflib
-import re
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-README = ROOT / "README.md"
-
-# Class families that are parts of a form or a page, not components.
-PARTS = {"field", "helper", "label", "section"}
-# Heading word -> class family, where the two differ.
-ALIASES = {"button": "btn"}
-# Families that share one docs section with another family.
-SHARED = {"tabs": {"tab"}}
-WORDS = {1: "one", 2: "two", 3: "three", 4: "four", 5: "five"}
-
-
-def strip_comments(css):
-    return re.sub(r"/\*.*?\*/", "", css, flags=re.S)
-
-
-def token_names():
-    """Every custom property declared in tokens.css — several sit on one
-    line (`--space-2: 2px; --space-4: 4px;`), so match anywhere, not at
-    line start."""
-    css = strip_comments((ROOT / "lib" / "tokens.css").read_text())
-    return sorted(set(re.findall(r"(--[a-z0-9-]+)\s*:", css)))
-
-
-def token_tiers():
-    css = (ROOT / "lib" / "tokens.css").read_text()
-    return sorted(set(re.findall(r"TIER (\d)", css)))
-
-
-def families():
-    """Top-level class families: the first segment of every class selector
-    that starts a rule or follows a comma at the top level."""
-    css = strip_comments((ROOT / "lib" / "components.css").read_text())
-    return sorted(set(re.findall(r"(?:^|,)\s*\.([a-z][a-z0-9]*)", css, re.M)))
-
-
-def sections(page):
-    """(heading, classes used under it) for every 
 on a docs page."""
-    html = (ROOT / "docs" / page).read_text()
-    out = []
-    for chunk in re.split(r"]*>", html)[1:]:
-        title = re.sub(r"<[^>]+>", "", chunk.split("
", 1)[0]).replace("&", "&").strip()
-        classes = set()
-        for attr in re.findall(r'class="([^"]*)"', chunk):
-            classes.update(attr.split())
-        out.append((title, classes))
-    return out
-
-
-def documented(secs, fams):
-    """family -> section title, when a heading names the family and the
-    section actually uses it."""
-    home = {}
-    for title, classes in secs:
-        words = [ALIASES.get(w.lower(), w.lower()) for w in re.split(r"[\s/&]+", title) if w]
-        for fam in fams:
-            if fam not in words:
-                continue
-            names = {fam} | SHARED.get(fam, set())
-            if names & classes or any(c.startswith(fam + "-") for c in classes):
-                for n in names:
-                    if n in fams:
-                        home.setdefault(n, title)
-    return home
-
-
-def shown_inside(fam, secs):
-    for title, classes in secs:
-        if fam in classes or any(c.startswith(fam + "-") for c in classes):
-            return title
-    return None
-
-
-def render(n_tokens, tiers, n_sections, n_families, undocumented, patterns):
-    tier_word = WORDS.get(len(tiers), str(len(tiers)))
-    comp = (f"- **{n_sections} documented components** on the [components page](docs/components.html) — "
-            f"`lib/components.css` ships {n_families} class families")
-    if undocumented:
-        comp += f"; {len(undocumented)} have no section yet"
-    return "\n".join([
-        f"- **{n_tokens} tokens** in `lib/tokens.css`, {tier_word} tiers (primitive → semantic → component), light and dark",
-        comp,
-        f"- **{len(patterns)} patterns**: " + " · ".join(t for t, _ in patterns),
-    ])
-
-
-def splice(text, block, body):
-    start, end = f"", f""
-    i, j = text.find(start), text.find(end)
-    if i < 0 or j < 0 or j < i:
-        sys.exit(f"README is missing the {start} … {end} markers")
-    return text[: i + len(start)] + "\n" + body + "\n" + text[j:]
-
-
-def main():
-    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--write", action="store_true", help="rewrite the counts block in README.md")
-    args = ap.parse_args()
-
-    tokens, tiers = token_names(), token_tiers()
-    fams = families()
-    comp_secs = sections("components.html")
-    patterns = sections("patterns.html")
-    home = documented(comp_secs, fams)
-    components = [f for f in fams if f not in PARTS]
-    undocumented = [f for f in components if f not in home]
-
-    print(f"tokens {len(tokens)} ({len(tiers)} tiers) · documented components {len(comp_secs)} · "
-          f"class families {len(components)} (+{len(fams) - len(components)} parts) · patterns {len(patterns)}")
-    if undocumented:
-        print("\nSHIPPED, NO DOCS SECTION")
-        for fam in undocumented:
-            where = shown_inside(fam, comp_secs)
-            print(f"  .{fam:14} {'shown inside: ' + where if where else 'not on the docs page'}")
-    print()
-
-    current = README.read_text()
-    rendered = splice(current, "counts", render(len(tokens), tiers, len(comp_secs), len(components), undocumented, patterns))
-    if rendered == current:
-        print("README is current")
-        return 0
-    if args.write:
-        README.write_text(rendered)
-        print("README rewritten")
-        return 0
-    sys.stdout.writelines(difflib.unified_diff(
-        current.splitlines(keepends=True), rendered.splitlines(keepends=True),
-        fromfile="README.md", tofile="rendered",
-    ))
-    print("\nREADME is stale — run with --write to update it", file=sys.stderr)
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())