Skip to content
Pulci Nella — the Clownware markPulci Nella — the Clownware markClownware Docs

ADR-049: The Showcase Is the Living Style Guide

Status

Section titled “Status”

Accepted (amended 2026-07-05 by ADR-060: the page hosts two sanctioned, labelled demo islands — MotionLab client:idle and SignalsCounter client:visible — as a closed exception to the zero-JS validation below)

Context

Section titled “Context”

After the v2 cold-minimal migration (ADR-047/048), the design system was documented in three overlapping places: /showcase (a component gallery + partial token swatches), the “Design System” pillar of /how-it-works (a narrative token-pipeline tour), and prototype mockups. A design brief proposed a single “living style guide” — one page that demonstrates the system by being styled entirely by it (a narrative hero, full palettes, a type specimen, a motion section, the component gallery).

The brief’s mockup was visually compelling but factually frozen on the pre-v2 world: it labelled palettes gray/moonstone/imperialRed/orangeWeb, showed --bg/--fg var shorthands, defaulted the display face to Space Grotesk, said “Astro 5”, and claimed “Under 15KB CSS gzipped”. Adopting its copy verbatim would ship inaccurate documentation.

Decision Drivers

Section titled “Decision Drivers”
  • Single source of reference: one canonical page, not three overlapping ones.
  • Accuracy that can’t rot: a style guide that silently drifts from the shipped tokens is worse than none.
  • Zero-JS baseline: the page must not regress the starter’s no-hydration default.
  • Reuse over rebuild: lean on existing primitives, not a from-scratch copy of the mockup.

Considered Options

Section titled “Considered Options”

Option 1: New separate /design-system page

Section titled “Option 1: New separate /design-system page”

A third page beside /showcase (components) and /how-it-works. Con: more nav surface and more overlap to keep in sync.

Option 2: Fold specimens into /how-it-works

Section titled “Option 2: Fold specimens into /how-it-works”

Con: bloats the architecture tour; mixes “how it works” prose with “here it is” specimens.

Option 3: Evolve /showcase into the living style guide (chosen)

Section titled “Option 3: Evolve /showcase into the living style guide (chosen)”

Restructure /showcase to System / Color / Type / Motion / Components, keeping the existing component gallery as the Components section. /how-it-works keeps its narrative pillar and links here.

Decision

Section titled “Decision”

Evolve /showcase into the canonical living style guide (Option 3), under three rules:

Accuracy by construction (token-driven specimens)

Section titled “Accuracy by construction (token-driven specimens)”

Specimens read live token output, so the page always portrays exactly what ships:

  • PaletteBand renders each family’s 50–950 band from hsl(var(--color-{family}-{step})).
  • TypeSpecimen sizes rows with the text-* utilities (the --text-* tokens) and picks the face with font-display / font-text (the fontFamily token group).
  • ColorTokenSwatch role chips read the live --color-* role vars.
  • Unit tests assert these components emit no hardcoded colour/size literals (drift guards).

Narrative copy is corrected to ship-truth (slate/violet/rose/amber, --color-*, Geist, Astro 7 (amended 2026-08-13 with the ADR-062 upgrade), ~26KB CSS / 50KB budget, two faces).

Zero-JS, static comparisons

Section titled “Zero-JS, static comparisons”

No live toggles. The gradient is shown as a static A-vs-B OKLCH comparison (via an arc prop on AnimatedGradientText) and the type specimen renders in the shipped Geist — the “re-themes itself” story is told in copy and the EDIT→BUILD→GATE→SHIP flow, not a runtime switch. This keeps the page’s “0 KB new JS” property and honours ADR-026’s two-faces rule (Space Grotesk is not added). (Amended: the two labelled demo islands sanctioned by ADR-060 are the closed exception to the no-live-toggles rule.)

Delegation

Section titled “Delegation”

/how-it-works keeps the conceptual token-pipeline narrative (with its code snippets corrected to v2) and links to the style guide. The site nav label changes “Components” → “Design System” (URL /showcase/ unchanged).

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  • One canonical, self-demonstrating reference that re-skins purely by editing tokens/.
  • Documentation that cannot drift from the shipped system (token-driven + drift-guard tests).
  • No new hydration; the zero-JS baseline holds.

Negative

Section titled “Negative”
  • A substantial one-time page rebuild and two new specimen components.
  • Showcase e2e specs that asserted the old section list/title needed updating.

Neutral

Section titled “Neutral”
  • The component gallery is unchanged — only regrouped under a Components section.

Validation

Section titled “Validation”
  • Accuracy sweep: the page contains no stale terms (moonstone, Space Grotesk, Astro 5, --bg, 15KB); specimens emit only hsl(var(--color-…)) / text-* utilities.
  • Token-driven proof: a PaletteBand cell computes the live palette colour; a TypeSpecimen row renders in Geist at the token size; role chips flip with the theme.
  • Zero-JS: the built page adds no new client: island beyond the two demo islands sanctioned by ADR-060.
  • Gate: pnpm quality:ci + pnpm design:validate pass; CSS stays < 50KB.

Amendment (2026-06-07) — sole component catalog

Section titled “Amendment (2026-06-07) — sole component catalog”

/showcase is now the single component catalog. The astrobook dependency and its docs:components / docs:components:build scripts have been removed: astrobook was an unused second catalog (no config, no stories, no CI usage) duplicating what the living style guide already provides with zero extra dependencies. New primitives are demonstrated by adding them to the Components section of /showcase, not by reintroducing a separate story runner. Completing the per-component coverage of that section is tracked separately as Found Work.

References

Section titled “References”

Enforcement

Section titled “Enforcement”
  • Not machine-checkable: that the showcase faithfully renders the live token system is drift-resistant by construction (specimens source tokens); completeness and structure are review concerns.
  • Graduation log: (empty at creation; entries added when a check changes status)

Date: 2026-06-06
Participants: Chris Pezza, template maintainers
Outcome: Accepted