Guideline 01Canonical

Foundations

The visual, spatial, typographic, motion, media, and accessible accent-scheme decisions that every AI-Created interface inherits.

Owner: Design Systems
Last reviewed: August 2026
Review cadence: Quarterly and before any token release
Source of truth: styles/tokens.css and tailwind-preset.js

Required outcomes

A product can switch themes and accent schemes without local color overrides.

Design decisions map to named semantic tokens before component styling.

Layouts remain readable from 320px through the 1400px container maximum.

Token architecture

Use a three-level naming model so raw values can change without altering product intent.

Decision hierarchy

Level	Example	Who uses it	Rule
Reference	--ref-red-500	System maintainers	Stores a raw value. Never use directly in product UI.
Semantic	--color-action-primary	Designers and engineers	Names intent and owns light and dark mode behavior.
Component	Button / Primary / Background	Component authors	Maps a component decision to a semantic token.

Token rules

Name the purpose

A token should explain why the value exists, not what its current hex value resembles.

Change every scheme together

Every accent role is tuned and reviewed across all nine schemes and light/dark mode, including focus and selection; feedback semantics remain stable.

Avoid product aliases

Do not create a new token for one screen. Promote a value only after a repeated semantic need is demonstrated.

Keep compatibility aliases secondary

Existing red aliases remain supported public contracts. New work can prefer accent and action names when intent is unambiguous.

Color and contrast

Accent schemes, committed actions, destructive actions, neutral surfaces, and semantic feedback each have an explicit role.

Core semantic palette

Samples resolve live through the current theme.

Background

--color-bg

Page background and highest-level negative space.

Surface

--color-surface

Cards, panels, fields, and floating regions.

Surface 2

--color-surface2

Controls, inset regions, and subtle grouping.

Text

--color-text

Headings, labels, and critical information.

Accent

--color-accent

Links, emphasis, and non-destructive branded actions.

Action primary

--color-action-primary

High-emphasis action fill.

Action destructive

--color-action-destructive

Destructive action fill, distinct from ordinary commitment.

Control border

--color-control-border

Contrast-safe boundaries for inputs and outlined controls.

Success

--color-success

Completed or healthy outcomes only.

Warning

--color-warning

Recoverable risk or pending attention.

Info

--color-info

Contextual or process information.

Error

--color-error

Invalid input, failed operations, and destructive risk.

Color acceptance

Required

Body text meets 4.5:1 contrast.
Large text and icons conveying meaning meet 3:1 contrast.
Focus indicators meet 3:1 against adjacent colors.
Meaning never relies on color alone.

Avoid

Raw reference colors in product code.
Accent decoration competing with primary actions.
Tinted text on tinted surfaces without contrast validation.
Theme-specific assets without a paired alternative.
Letting accent schemes change destructive or feedback meanings.

Typography, spacing, and grid

Instrument Serif creates editorial moments. Space Grotesk carries every functional reading task.

Type roles

Role	Family	Typical size	Use
Display / Hero	Instrument Serif	60 to 96px	One primary narrative statement per page.
Display / Section	Instrument Serif	40 to 60px	Major chapter introductions.
Heading	Space Grotesk 500	20 to 32px	Functional page and card hierarchy.
Body	Space Grotesk 400	14 to 20px	Instructions, descriptions, and long-form content.
Metadata	System mono	10 to 12px	Tokens, statuses, keyboard keys, and code-adjacent labels.

Responsive layout contract

Range	Gutter	Columns	Behavior
320 to 767px	6vw	4	Stack content, preserve source order, use full-width controls when needed.
768 to 1023px	2vw	8	Introduce split regions only when each column remains readable.
1024 to 1399px	2vw	12	Enable persistent secondary navigation and dense matrices.
1400px and above	2vw	12	Cap primary content at 1400px and grow outer whitespace.

Composition rules

Use a 4px base unit

Tokenized radii and intentional optical adjustments may differ, but layout spacing should resolve to the base unit.

Prefer gap over margins

Parent layout owns relationships between siblings. Components own only their internal spacing.

Keep reading measures controlled

Body copy should usually remain between 45 and 75 characters per line.

Preserve hierarchy when stacking

Responsive changes may alter layout, never the semantic or focus order.

Shape, elevation, motion, icons, and media

Secondary visual systems remain restrained so content and interaction state stay primary.

System inventory

Area	Contract	Current support
Radius	4px small, 6px default, 10px large, full for pills	Canonical tokens
Elevation	Border first; shadow only when depth changes interaction meaning	Local Tailwind effects, not yet canonical tokens
Motion	200ms feedback, 300ms transitions, 500ms entrances	Canonical duration tokens and shared helpers
Icons	Lucide, 16px inline, 20px controls, 32px empty states	Code dependency; no separate icon package
Imagery	Theme-paired, art-directed, useful at crop extremes	ThemedHeroImage plus product-owned assets
Data visualization	Text, shape, and pattern reinforce color	Guidance only; no chart primitive yet