Design-System Contract Finalized

Foundation complete

With the hero verified and the build green, the design-system contract has been formalized. This is the document every section builder reads before touching code — it defines the exact token names, utility classes, component APIs, and reveal patterns they are allowed to use. No visual decisions are made downstream; they compose from what exists here.

The palette decision

The 70/20/10 split is not a guideline — it is enforced by the token system. The graphite base (#0E0F12) covers 70% of the canvas. Off-white (#ECEDEE) and surface variants account for the structure. Acid-lime (#CBFF1F) appears in exactly three places by default: the scrub-progress rail in the hero, the “Reserve” pill in the nav, and the primary CTA button. Every other instance of lime must be justified as a locked-counter moment or a hover state.

This restraint is deliberate. When lime appears, it means something. A site where every interactive element is neon-lit has no power accent — it just has neon.

The instrument vocabulary

The recurring HUD motif is built from four primitives:

label-mono — Geist Mono, 11px, 0.18em tracking, steel by default. The kicker voice before every section heading. Add --accent for lime, --ink for off-white.

instrument-tick — a 1.25rem hairline tick rendered via ::before at the left of a label. Costs nothing, reads as “instrument readout.”

corner-ticks — CSS ::before/::after crop marks at all four corners of a panel. The primary signal that a surface is a measured, framed object rather than a decorative card.

panel — slate surface + hairline border + 6px radius. The base container for any spec readout, callout, or data cell.

Image pipeline

Thirty-one real images are verified in the build — all JPEG sources confirmed with file, optimized to AVIF + WebP via the optimize() utility at build time, zero external URLs, zero placeholders. The pipeline:

1. Source JPEGs in src/assets/images/ (never public/ — that bypasses Astro’s optimizer)
2. optimize(name, { width, alt, avifQuality, webpQuality }) called in .astro pages
3. Returns OptimizedImage { avif, webp, src, alt, width, height }
4. Passed as typed props into React islands — getImage() cannot be called inside islands

Shared-element transitions

Astro’s ClientRouter is active. GalleryCard sets viewTransitionName: gallery-img-${slug} and gallery-title-${slug} as the only sanctioned inline style (no Tailwind equivalent). Detail pages mirror these exact names on the matching image and title. The morph feels native-app, costs nothing in JS weight, and requires no animation library.

Section handoff

The foundation exports: VideoHero, Counter, InstrumentLabel, SpecRow, GalleryCard, MagneticButton, Reveal, Nav, Footer, Cursor. Plus the full token vocabulary, utility classes, and reveal system.

Section builders own discrete pages. They make zero visual decisions. They compose from the contract. That is the architecture.