Customization Mandate

Core Principle

BEFORE building pages, customize ALL base UI components.

Every component must be visually distinct -- derived from the project's design-dna tokens. No default styling from component libraries (shadcn, Radix, etc.) should remain visible in the final product.

"Take pride in the originality of the designs."

Workflow

Phase 0: Component Customization (BEFORE Page Implementation)

1. Read design-dna.json -- extract colors, typography, spacing, border-radius, shadows, motion tokens
2. Identify all base components the project will use
3. Customize each component to reflect the design-dna identity
4. Verify: No component should look like its library default

Phase 1+: Page Implementation

Only AFTER Phase 0 is complete. Pages consume already-customized components.

Component Checklist

Customize these components BEFORE building pages:

Interactive Elements

• Button (primary, secondary, ghost, destructive variants)
• Link / anchor styles
• Toggle / switch
• Checkbox
• Radio button
• Select / dropdown

Form Elements

• Input (text, email, password, number)
• Textarea
• Form error states
• Form labels
• Form helper text

Display Components

• Card (with hover state)
• Badge / tag / chip
• Avatar
• Tooltip
• Alert / callout
• Separator / divider

Navigation

• Navigation bar / header
• Footer
• Breadcrumbs
• Tabs
• Sidebar (if applicable)

Overlay Components

• Dialog / modal
• Sheet / drawer
• Toast / notification
• Popover
• Command palette (if applicable)

Layout Components

• Section container
• Content wrapper
• Grid system

Customization Sources

All customizations derive from design-dna tokens:

Anti-Defaults

Colors to Avoid (Unless Specified in Design-DNA)

• Purple / indigo / violet (shadcn defaults)
• Blue (#3b82f6 / Tailwind blue-500)
• Generic gray scales without character

Patterns to Avoid

• Default border-radius (6px from shadcn)
• Default shadow (shadow-sm/shadow-md from Tailwind)
• Default focus rings without brand color
• Generic hover: opacity changes without personality
• Emojis in UI elements

The Test

For each component ask: "Could this component belong to ANY project?"

• If YES: it is not customized enough
• If NO: it reflects this project's identity

Verification

After customization phase, verify:

1. Visual distinctiveness: Screenshot components -- they should not look like library defaults
2. Token compliance: Grep for hardcoded color/spacing values -- there should be none
3. Consistency: All components share the same design language (border-radius, shadow style, color palette)
4. States: Every interactive component has hover, focus, active, and disabled states customized
5. Dark mode (if applicable): Token switching works for all components

Example: Button Customization

/* WRONG: Default shadcn button */
.button {
  border-radius: 6px;
  background: hsl(222.2, 84%, 4.9%);
  padding: 8px 16px;
}

/* RIGHT: Design-DNA driven button */
.button {
  border-radius: var(--radius-md);
  background: var(--color-primary);
  padding: var(--space-2) var(--space-4);
  font-family: var(--font-body);
  font-weight: var(--font-weight-medium);
  letter-spacing: var(--letter-spacing-wide);
  transition: background var(--motion-duration-fast) var(--motion-easing-entrance),
              transform var(--motion-duration-fast) var(--motion-easing-entrance);
}
.button:hover {
  background: var(--color-primary-hover);
  transform: translateY(-1px);
}
.button:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}