Foundations

Design principles

Three governing constraints. These are not guidelines — they are the system.

Math-perfect layouts. Standard spacing tokens. Grid-based containment. If a className exceeds 80 characters, it belongs in a component.

GSAP for orchestrated animations. CSS for micro-states only. All scroll reveals and staggers are GSAP-driven.

#FFF

#FFFFFF is the canvas — not a placeholder. Museum-grade elegance. No shadows. Physicality through borders only.

Zero-tolerance constraints

Violations block the build pipeline. Enforced by automated linting.

No dark modeAll dark: classes banned. UI is strictly #FFFFFF.dark:*

No drop shadowsUse border-gray-100 for separation.shadow-*

No inline CSSUse design tokens or Tailwind utilities.style={{}}

No raw elementsUse primitives from src/components/ui.<button>, <input>

No arbitrary valuesOut-of-system colors and sizes blocked by AST parser.text-[#000]

No manual overridesCrash the linter.uppercase, italic, tracking-*

No hardcoded i18nAll text via useI18n() from translations.ts.String literals

<h1> – <h6>Content hierarchy

<p>Body text / reading content

<a>Navigation to URL

<button>JS / form action

<section>Content block with heading

<nav>Navigation landmark

<main>Primary page content

<div>Last resort — layout only

Use .section-container for max-width

Use .section-v-lg for section padding

Use border-gray-100 for separation

Extract repeated patterns to primitives

Use useI18n() for all visible text

Don't

Use shadow-md or shadow-lg

Write classNames longer than 80 chars

Use p-[12px] or text-[#000]

Hardcode English strings in JSX

Use native button or input tags