The Visual Language

Why Visual Decisions Before Code

AI agents make visual decisions independently. Without constraints, Agent A picks blue buttons while Agent B picks purple. Agent A uses 16px padding while Agent B uses 24px. Within two milestones, the product looks like it was built by five different people with five different opinions.

The visual language has three layers: brand tokens (colors, typography, spacing), a component inventory (what components exist and how they behave), and UX coherence guidelines (how the product feels in motion).

Brand Tokens

Brand tokens are the atomic visual decisions: colors, fonts, sizes, spacing, radii, shadows. They are defined as CSS custom properties in a tokens.css file that every component imports.

What to Define

/* Linear's visual identity as CSS custom properties */
:root {
  /* Accent */
  --color-accent: #5E6AD2;        /* Linear's signature indigo */
  --color-accent-hover: #6C78E0;
  --color-accent-subtle: rgba(94,106,210,0.12);

  /* Backgrounds (dark theme is primary for Linear) */
  --bg-page: #1A1A2E;
  --bg-sidebar: #14142B;
  --bg-card: #1E1E3F;
  --bg-elevated: #252547;

  /* Text */
  --text-primary: #E8E8F0;
  --text-secondary: #9898B0;
  --text-muted: #6B6B80;

  /* Typography */
  --font-sans: 'Inter', -apple-system, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  --text-xs: 0.75rem;
  --text-sm: 0.8125rem;
  --text-base: 0.875rem;   /* Linear uses 14px base, tighter than typical */
  --text-lg: 1rem;

  /* Spacing (4px base) */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
}

The Process

Step 1: Generate options visually. Do not pick colors from a palette chart. Build 3-4 rendered UI mockups (a sidebar, a card, a table row, a button group) with different color schemes. Compare them side by side. Pick the one that best matches the product positioning.

Step 2: Define every token. Once the direction is chosen, enumerate every token. Miss nothing. If a value is used in the UI, it must have a token. Hardcoded values (hex codes in component files, pixel values in CSS) are banned.

Step 3: Generate tokens.css. Output a single file that the codebase imports. This file is the single source of truth. Every component references tokens, never raw values.

Step 4: Lock it. Token changes ripple across the entire product. Do not tweak tokens during feature development. If a token needs changing, it is a deliberate, documented decision with a migration plan.

UI Component Plan

The component plan is a complete inventory of every UI component the product needs, organized into build waves by dependency order.

Three Component Categories

Primitives are the atoms: Button, Input, Badge, Avatar, Tooltip, Checkbox, Select, TextArea. Used everywhere. Built first. Zero product-specific logic.

Patterns are composed from primitives: DataTable, FilterBar, KanbanBoard, SlideOver, CommandPalette, EmptyState. Used on specific screen types. Built after primitives exist.

Overlays are layers above the page: Modal, Dialog, Dropdown, ContextMenu, Toast, Popover. Have their own z-index management. Built in parallel with patterns.

Library Decisions

For each component category, decide: build from scratch or use a library? The right answer depends on your product's UX requirements.

Build Waves

Components are built in dependency order. Wave 1 has no dependencies. Wave 2 depends on Wave 1. And so on.

UX Coherence Guidelines

Tokens define how things look. Coherence guidelines define how things feel. Two features built by different agents in different weeks must have identical loading behavior, identical error handling, and identical transition timing.

Loading Patterns

Define a single loading strategy for the entire product. Every screen follows the same pattern.

Error Handling Patterns

Define three tiers of error presentation:

• Transient errors (network glitch, timeout): Toast notification, bottom-right, auto-dismiss after 5s, with retry action.
• Persistent errors (validation failure, permission denied): Inline message below the affected field or section. Does not auto-dismiss. Clears when the user corrects the input.
• Catastrophic errors (page crash, data load failure): Full-page error state with branded illustration, clear message, and primary action (retry or go home).

Optimistic UI Strategy

Define when to use optimistic updates and which pattern to apply. This prevents agents from guessing.

Three optimistic patterns, each assigned per mutation in phase plans:

Animation Timing

Define a timing scale and stick to it. Every transition in the product uses one of these durations:

What You Leave With

These documents are excerpted into every frontend and full-stack phase plan. The phase plan's "Excerpted Guidelines" section copies the relevant rules verbatim so the executing agent does not need to reference external documents.