Minimal Design System

The whole rebrand

The warm brand file, condensed. Two neutral ramps re-hued, one accent pair, three radii. The comment at the top of the real file reads: “this file is that claim executed”.

/* docs/src/brand-warm.css, condensed */
:root[data-brand="warm"] {
  /* Layer 1: both neutral ramps, hue ~85 */
  --base-50:  oklch(0.985 0.003 85);
  --base-100: oklch(0.966 0.004 88);
  /* ...ten more base steps... */
  --ink-50:   oklch(0.985 0.003 85);
  /* ...ten more ink steps... */

  /* Layer 2: the accent pair, lime fill, olive text */
  --accent-lime:      oklch(0.841 0.238 128.85);
  --accent-lime-ink:  oklch(0.32 0.09 131);
  --button-primary:   var(--accent-lime);
  --text-on-accent:   var(--accent-lime-ink);

  /* Radius: one step up, ratio preserved */
  --radius-button: 12px; --radius-card: 20px; --radius-popup: 28px;
}
/* Components touched: 0 */

Same composition, two brands

The Requests block on the showcase: Card, Stat, Tabs, Table, Badge and Chart, no bespoke styling. Rendered neutral light and warm dark.

Two neutral ramps, and what a brand does to them

Real values. The neutral brand’s ramps are hex; the warm brand’s are oklch around hue 85. Surfaces read base, content reads ink, so a brand can warm the page without warming the text, or the other way round.

The ink-450 step was added on 2026-08-22 for one job: dark tertiary text.

Three real token chains

How a value reaches a component. The component never names Layer 1; it names Layer 3, which names Layer 2, which names the ramp step.

1. Layer 1

   --base-0

   Layer 2, light

   --surface-card

   Layer 3

   --card

   Component reads

   bg-card

   Card, Dialog, Popover

2. Layer 1

   --ink-950

   Layer 2, light

   --text-primary

   Layer 3

   --foreground

   Component reads

   text-foreground

   every body text

3. Layer 1

   --base-900

   Layer 2, dark override

   --surface-card

   Layer 3

   --card, re-declared in .dark

   Component reads

   bg-card

   same class, no change

Any stock shadcn component drops in unmodified and inherits the theme. The rule the repo gives agents is one line: if a change needs to touch Layer 3, the semantic layer is missing a token.

Dark mode that nests

Dark values never live in a component. They live in Layer 2 only. Nested dark works because var() substitutes at the element that declares it, so every alias whose target flips between modes is re-declared inside the dark block with the same expression, as the third chain above shows. A section can go dark inside a light page.

Dark made honest, 2026-08-22

Dark tertiary text before and after, with the kit’s own values. One new ramp step, zero component edits.

The first full dark audit the next day passed 279 of 279 stories in both themes. About 130 axe violations cleared by changing roughly five Layer 2 values. None of the fixes were per component.

Figma as a name contract

There is no sync pipeline. tokens.ts holds metadata only: the CSS property, its byte-exact Figma variable name, and a usage line. A mirror gate checks that every documented name exists in CSS and every CSS token is documented. Drift the other way is recorded by hand with a status per record. Storybook renders swatches from the CSS and names from the metadata, so the docs cannot disagree with the code. Since 10-21 a second set of eight rules holds the Figma components themselves to the code contracts.

One record, five readers

TOK-8, as it sits in rules/tokens.ts. The fix is a required field; a ban with no substitution is refused by the schema.

id

TOK-8 · blocker · detect: grep

title

No opacity modifier on a foreground. The dim belongs in Layer 2.

pattern

\b(?:text|fill|stroke|placeholder|decoration|caret)-(?!(?:xs|sm|base|lg|[2-9]?xl)/)[a-z][\w-]*/\d{1,3}\b

scope

src/components, src/lib, src/hooks · exempt: stories, tests, ai/sources.tsx

fix

Use the flat rung that owns the job (text-muted-foreground or text-text-secondary for quiet text, flat text-destructive, stroke-chart-grid for gridlines). If the dimmed value is genuinely new, declare the mix in Layer 2 the way --chart-grid does, and document it in tokens.ts. Never compose it in the component.

why

A composite resolves against whatever sits behind it, so its contrast is decided by the ground, not the token. Axe only measures the grounds stories happen to use, and never measures hover states. A /50 foreground shipping an AA failure under exactly this pattern is the recorded precedent.

npm run rules:emit writes rules/tokens.json, and five things read it:

• Detectorcheck:tokens, check:rules
• Write-time hookwarns in the agent session
• unslop skillthe audit before done
• CIstatic job, fails the PR
• Storybook Rules pagerendered live, for people

The catalogue

22 blockers, 4 warnings, 2 at review, 2 notes. STA-7 needs a rendered page, SYS-3 needs judgment, and the Figma rules need the Figma file, so CI cannot run them. They print as unchecked on every run, so “I did not check this” never looks like “this passed”.

Eight rule bodies, one line each in the always-on file

The agent instructions file was 31 KB and re-injected into every session. It was split into eight rule bodies behind one-line stubs, with a byte ceiling that only ratchets down and a provenance test: a rule can leave the always-on file only if a gate or a written “ungated” reason stays behind.

• Never hardcode. No raw hex, no oklch(), no palette classes, no arbitrary values, no opacity on a foreground.
• Motion. Four durations chosen by what is moving. Because every transition reads a token, one reduced-motion block disables motion kit-wide, including components that do not exist yet.
• Usage contracts. A per-component JSON with a purpose that must say when the component is the wrong choice, anti-patterns with a why, and relationships.
• Gates and baselines. The ledger of every gate, when it landed, and what it carries.
• Conformance ladder. A vendored checker with ten stages. Which claims are met, which are unchecked by design.
• Review rounds and blockers. A round budget and a shared definition of blocker.
• Traps. Seven bugs already paid for, so nobody rediscovers them by hand.
• Worktrees and installs. One checkout per task, and a hygiene report for stranded work.

A trap, as recorded

The first entry in traps.md. Tailwind v4 has an --ease-* theme namespace and no --duration-* one, so the motion table compiled to nothing for three days.

/* 2026-08-11 to 08-14: written everywhere,
   in effect nowhere */
@theme {
  --duration-fast: 100ms;
  --duration-base: 200ms;   /* compiles to NO utility */
  --duration-slow: 300ms;
}
/* every element wearing duration-base
   silently fell to the default duration */

/* PR #41, 2026-08-17 */
@utility duration-base {
  transition-duration: var(--duration-base);
}
/* ...and MOT-9: 22 numeric durations swept
   to tokens; rule record added so the hook
   and CI catch the next one */

The trap entry ends with the test: “compile globals.css and grep the output for the class before believing it exists.”

The portability gate: install the kit the way a stranger would

The consumer harness, as it runs in CI. Every step is real; the screenshots are uploaded as artifacts.

1. npm packthe kit as a tarball
2. Installinto a standalone Vite + Tailwind v4 app, node_modules wiped first
3. Re-themetheme.css: two neutral ramps, one brand ramp, one accent pair
4. tsc + buildthe consumer's own TypeScript, not the kit's
5. 9 probespaint, type, radius, focus ring, dark
6. axe × 2light and dark
7. Screenshotsbefore and after, uploaded as CI artifacts

/* harness/consumer/src/theme.css, condensed */
@import "@weeeha/ui/globals.css";
:root {
  /* two neutral ramps, warmed */
  --base-50: #fbf8f3; /* ... */ --base-950: #0f0d0a;
  --ink-50:  #faf7f2; /* ... */ --ink-950:  #0d0b09;
  /* one brand ramp */
  --accent-50: #fff7ed; /* ... */ --accent-950: #431407;
  /* the pair. Everything accent-coloured derives from it */
  --accent-solid:    var(--accent-800);
  --accent-on-solid: var(--accent-50);
}

What the harness found on its first day, 2026-08-18:

• Tailwind was not declared as a peer dependency. A consumer's build failed on line 1 of globals.css.
• The @source globs were too wide: 53 story-only utility classes shipped into consumer CSS. Narrowed to zero.
• A same-named tarball reported up to date and never reinstalled, so every measurement after the first tested the old kit.
• A half-rebrand: four of six accent tokens set by hand. The accent pair now makes that impossible, because the six derive from the two.

Capability contract: tags owe states

A story file declares capabilities. Each tag owes named stories, and CI derives the debt. The example is alert-dialog.stories.tsx on main.

// src/components/alert-dialog.stories.tsx
const meta = {
  parameters: {
    capabilities: ["interactive", "text-bearing"],
  },
}

// owed by "interactive"
export const Disabled: Story = { /* ... */ }      // line 66
// owed by "text-bearing"
export const LongContent: Story = { /* ... */ }   // line 101

text-bearing

LongContent

interactive

Disabled

validating

Invalid, Required

async

Loading, Failed

collection

Empty

Every story is also an axe test, in both themes. So “owes a Disabled story” means “the disabled state gets audited for contrast”, which is where disabled states usually fail.

Usage contract: what it is for, and when it is wrong

badge.meta.json, excerpted. The schema sets minimum lengths: an 80-character purpose, a 20-character intent per variant, a 20-character why per anti-pattern. The repo calls padding to pass “worse than failing”.

purpose

A small, non-interactive label for state, category or count, whose word carries the meaning while the variant only ranks its emphasis. It is the most over-used component in a kit: it looks decorative, so it accumulates on a screen until nothing is emphasised. It is the wrong choice for anything the reader is meant to click.

variant default

Solid accent fill, the strongest weight in the ramp. Reserve it for the one state that needs someone to act on it now.

variant ghost

No border and no fill at rest. For a state that has already resolved and no longer needs to be scanned for.

token

text-on-accent: kept as one pair with button-primary so the two cannot drift apart.

anti-pattern

aria-label on an icon-only badge. The badge is a bare span with no implicit role, and ARIA prohibits aria-label on a generic element. Assistive tech silently drops it and axe fails.

30 of 100 components carry one. The floor is 29 and can only rise. An agent placing a component is told to read the index first and at most two full contracts, never to survey the source folder.

Where the numbers moved

Light bar: when the gate landed. Dark bar: main on 2026-10-30. Bars share a scale within each row only.

• Stories failing axe

  22 → 0

  22 on 08-17, 0 on 08-18, has stayed 0

• Tokens with no consumer

  31 → 0

  31 found 08-21, 42 more found 09-04 and deleted, emptied 10-01

• Owed capability states

  74 → 24

  74 states in 40 files on 08-23

• Always-on agent file, bytes

  31,092 → 16,232

  ceiling 17,000, lowers only

• Tagged story files (floor)

  1 → 26

  1 on 08-18, 18 on 09-08, 26 on 09-09

• Components with a usage contract (floor)

  0 → 30

  schema landed 09-14, floor now 29

Each of these is a baseline that can only shrink. Colour and motion rules carry no baseline: those are strict.

One lap, as it happened

Build

In an earlier system, a sidebar shipped text-sidebar-foreground/50 for quiet text. The precedent is cited in the record.

Gate fails

Axe measured the composite on one ground and it failed AA. Hover grounds were never measured at all.

Fix

Replace the opacity with the flat rung that owns the job.

Encode

TOK-8, 2026-08-23: no opacity modifier on a foreground, blocker, grep, with the fix and the precedent written into the record.

Next lap

The hook warns at write time, CI fails on the pattern, the Rules page shows it, unslop audits for it.

Every gate is made to fail before it is trusted

Before a gate is adopted, someone breaks the code on purpose: append a raw hex to a component, watch the exit code, restore. The mutation is kept as a fixture test, and the fixture suites run in CI next to the gates. A gate that matched zero files used to pass. Since 2026-08-18, zero matched files is a failure.

How reviews are run

• A round budget. Rounds one and two fix everything worth fixing. From round three only blockers get fixed in the PR, and everything else becomes a linked follow-up, because each fix invites a finding about the fix. Two blocker classes were written for the agent era: contract prose the change made false, and a weakened test or gate.
• Findings are hypotheses. A review of a stale branch produced three findings. Rechecked against main, one reproduced and was repaired the same day with 23 new tests, each watched failing first. One was already fixed. One was stale. Reproduce before repairing is now a written rule.
• Open decisions stay open. A new contrast failure is a design decision, so agents propose values with ratios and wait. Never darken tokens quietly to make CI green. The five failing pairs from August were settled in two reviewed PRs, not by a script.

Conformance ladder

Ten stages in a vendored checker. The honest number is the highest contiguous stage, so a built stage 09 does not raise it.

Stages 02 and 03 have no probe yet, though their substance has landed as the rule records and the four gate moments above.