ADR-062: Pezza Design System Adoption

Records the Pezza rebrand as the binding design language for this site, supersedes the cold-minimal sections of the inherited token, motion, font, and icon ADRs, dims the focus ring on light for 3:1 contrast, and takes ownership of the published ADR route.

Last updated

Status

Accepted

Context

This site was scaffolded from the Astro Performance Starter on 2026-07-07 and rebranded the same day to the Pezza design system: a true-grayscale ink ramp, one Crossfade Cyan accent used as a cursor (links on hover, focus rings, the reading playhead) and never as decoration, Space Grotesk for display and UI, Space Mono for the metadata register, Inter for long-form prose only, flat hairline cards, and motion that is gated and finite.

The code was rebranded; the decision log was not. Only ADR-032 received an amendment. The inherited records that define the visual language still describe the starter’s cold-minimal proposal:

  • ADR-047 maps roles to a slate/violet palette and reserves brand scales for gradients.
  • ADR-048 mandates a grain overlay, one rotating conic glow border per view, two looping sheens, and a cursor spotlight.
  • ADR-053 names Geist as the display face.
  • ADR-055 fixes stroke icons at width 2 and permits ✓ / ⚠ glyphs as form-state indicators.
  • The proposal specs under docs/archive-2026-06-cold-minimal-proposals/ show a violet-to-crimson gradient headline as the “single expressive moment”.

Under the constitution’s rule 1 and ADR-039, Accepted ADRs are binding. An agent following them would reintroduce gradients, grain, loops, and a second hue. The 2026-09-02 design audit also computed that the ring role (accent-500 in both themes) measures 1.51:1 against the light ground, below the 3:1 that WCAG 2.4.11 / 1.4.11 require for focus indicators, and found the site’s own /adr/ route still describing itself as the starter’s log.

Decision Drivers

  • Agents must be able to trust the log: the binding rules have to describe the shipped brand, or halt-on-violation halts on the wrong thing.
  • Accent discipline: the accent stays a cursor; dimming it on light for contrast is already the pattern the link role uses.
  • One record, not five edits: the rebrand is one decision and should read as one.
  • Ownership: publishing ADRs is on-thesis for this site (“architecture is the interface”), but inherited records must be marked as inherited.

Considered Options

Option 1: Amend each inherited ADR individually

Pros: each record stays self-contained.

Cons: five near-identical amendments; the rebrand has no single home; future readers reconstruct the decision from fragments.

Option 2: One superseding ADR plus a status pointer on each affected record (chosen)

Pros: one document states the brand; the inherited records keep their history and point forward; cheapest to maintain.

Cons: readers of an inherited ADR must follow one link.

Option 3: Delete or rewrite the inherited ADRs

Cons: violates the never-renumber, never-delete convention in docs/adr/README.md and erases the rationale behind defaults the site still inherits.

Decision

Adopt Option 2. The Pezza design system, as packaged in the pezza-design skill and bridged through tokens/base.json / tokens/semantic.json, is the binding design language for this site. Where the following inherited records conflict with it, this record wins:

Inherited recordSection supersededPezza rule that replaces it
ADR-047Palette rename map; semantic role mapping; “brand scales retained for gradients”Ink ramp carries every surface, border, and both brand scales; no gradients; accent surfaces only through link and ring
ADR-048Techniques 4–7 (conic glow loop, sheen loops, grain, cursor spotlight); decorative-loop capNo infinite loops in product UI; surfaces are flat, photography carries texture; the sanctioned motions are draw-on, crossfade-wipe, the finite hero cursor, and the scroll-driven playhead
ADR-053Family names (Geist display)Space Grotesk display/UI, Space Mono metadata, Inter prose only
ADR-055Stroke width 2; typographic ✓ / ⚠ exceptionMonoline stroke 1.6, round caps and joins; no emoji or glyph icons, monoline SVG only (arrow-left, linkedin, sun, moon, monitor, menu added to the registry)

Everything else in those records (token pipeline, role-based naming, CSS-native motion, the Fonts API delivery, the single Icon.astro registry) stays in force.

Token changes

  • ring on light resolves to accent-700 (was accent-500): 5.06:1 against ink-50 and 5.42:1 against white. Dark keeps accent-500 at 12.2:1. link already used this pattern.
  • The motion duration tokens are exposed as duration-fast / duration-base / duration-slow utilities in global.css (Tailwind v4 has no --duration-* theme namespace), and component transitions use them instead of literal 200/300ms.
  • fontSize and spacing in tokens/base.json deliberately keep the Tailwind chassis ladder rather than Pezza’s own px values, so the starter’s utility classes keep their meaning. Only colour, radius, shadow, and motion mirror the skill’s CSS.

Chrome rules made explicit

  • Cards are flat: hairline border, no shadow at rest, hover darkens the border. No image zoom or lift on hover; press is the only scale.
  • Prose links rest as ink with a hairline underline; accent on hover only. No prose-a:text-link overrides.
  • Text over photography sits on a protection gradient or on its own ground; the home lanes strip therefore lives outside the hero.
  • Icons are monoline SVG from the registry; typographic arrows and glyph bullets are not used as iconography.

The /adr/ route

This site owns the published decision log. ADR-000 through ADR-060 are marked “Inherited” in the index; ADR-061 onward are this site’s own. The route is linked from the footer as “Decisions”.

Consequences

Positive

  • The binding rules match the shipped brand; halt-on-violation halts on the right thing.
  • Focus indicators clear WCAG 1.4.11 in both themes.
  • Sixteen unused starter components that carried the old language (tinted feature cards, gradient separators, the contact form’s infinite spinner) are removed with their tests.

Negative

  • Readers of ADR-047/048/053/055 must follow the status pointer here.
  • The light-mode focus ring is a darker teal rather than the electric cyan.

Neutral

  • The cold-minimal proposal specs are kept under docs/archive-2026-06-cold-minimal-proposals/ for history; nothing links to them as current guidance.

Validation

  • pnpm design:validate passes with ring included in the gated pairs.
  • src/__tests__/design-tokens.test.ts pins ring light to accent-700.
  • Component microtests pin: flat Card/PostCard/Button chrome, 1.6 stroke icons, heading levels on cards.
  • Lighthouse accessibility stays ≥ 98 on every route (existing CI gate).

References

  • pezza-design skill: SKILL.md hard rules 1–11, readme.md visual foundations
  • 2026-09-02 design audit (Pezza Portfolio Audit)
  • ADR-032 — the one record already amended for Pezza

Date: 2026-09-02
Participants: Chris Pezza
Outcome: Accepted