March 25: Tokens, Palettes, and the Class of 2026
Session cleanup day — added z-index and spacing tokens, killed dead CSS, capped the auto palette at blue so single-channel composites stop going purple, and patched the guided step-card styles that the token refactor accidentally deleted.
Developer Journal
Z-index and spacing tokens
The design system was missing z-index and spacing tokens, which meant every layered component (modals, toasts, dropdowns, floating action bars) had a hand-picked z-index and every spacing value was a hardcoded px. Easy to introduce drift, hard to reason about stacking order.
Added a canonical z-index scale (--z-base, --z-dropdown, --z-modal, --z-toast) and a spacing scale (--space-1 through --space-16) on a 4px base. Migrated the callers that were obvious. Also deleted a pile of dead CSS — rules for components that had been removed or renamed in earlier refactors. The stylesheet is a few hundred lines lighter.
Capping the auto palette at blue
The auto color recipe assigns hues to channels by wavelength order. For a 4-channel composite the spread ran from red at the longest wavelength to purple (~280°) at the shortest. Purple channels always looked muddy next to the yellow/green mids because the eye perceives purple as darker than its luminance suggests, and the channel signal rarely justified the saturation.
Capped the top of the auto ramp at blue (240°) instead of purple (280°). The spread is now red → orange → yellow → green → cyan → blue, which feels like a more natural scientific palette and stops short-wavelength channels from disappearing into the background. Single-channel composites that used to render as pure blue-purple now render as clean blue, which matches how most published JWST imagery handles short-wavelength data.
The guided step-card regression
The z-index/spacing token refactor (#917) accidentally took the .step-card__container CSS with it — the rule looked dead during cleanup because no lint rule flagged it, but the guided create flow was actually using it via a composed class name. The card containers rendered as unstyled blocks until the fix landed in #921.
This is exactly the kind of thing the self-review rule about "multi-consumer features need all consumers verified" is supposed to catch. The guided create flow uses its own wrapper component that references the shared step-card class, which grep missed because the class name was constructed rather than written literally. Adding a note to the design system maintenance checklist: when removing CSS, grep for the bare class name and for any pattern that constructs it dynamically.
Skill maintenance sweep
Session cleanup lumped together a pile of low-priority fixes — skill prompt corrections (the plan-eng-review skill had a stale path reference), design system refresh (regenerated the token reference doc from source), and pruning the recipe-grader Claude Code tree that had accumulated abandoned branches. Nothing individually worth its own PR, all worth getting out of the queue.
What shipped
| PR | Title |
|---|---|
| #921 | fix: restore guided step card container styles deleted by #917 |
| #919 | fix: cap auto palette at blue (240°) instead of purple (280°) |
| #918 | chore: session cleanup — skill fixes, design system refresh, recipe-grader tree |
| #917 | refactor: add z-index/spacing tokens and remove dead CSS |