AI Design Starter Playbook

# .claude/skills/brand/SKILL.md
---
name: brand
description: Brand and visual standards for this product.
  Use when designing, building, or reviewing any screen,
  component, or visual asset.
---

Read /skills/brand.md and follow it exactly. It defines
the color system, typography, iconography, illustration
style, and motion principles. Never deviate without
logging a decision.

# CLAUDE.md

## What this project is
[Product name]: [one sentence description].
Primary platform: mobile web (iOS Safari + Android Chrome).
Target users: [brief description].

## Tech stack
Framework: Next.js (App Router), latest stable at project start
Components: shadcn/ui; use only these. No custom components
  if a shadcn equivalent exists.
Styling: Tailwind CSS v4 (CSS-first config via @theme)
  + CSS custom properties in /styles/tokens.css
Language: TypeScript throughout. No plain JS files.
Package manager: pnpm

## Folder structure
/app          Next.js routes and pages
/components
  /ui         shadcn components (themed, do not modify structure)
  /[feature]  product-specific components
/styles
  tokens.css  single source of truth for all design tokens
  globals.css base styles and dark mode assignments
/skills       context files (read before relevant tasks)
/assets
  /icons      SVG icons
  /illustrations illustration assets
/tokens       generated JSON exports for engineering
/decisions    decision log and changelog

## Skill files read before relevant tasks
Brand + visual standards → /skills/brand.md
Accessibility rules → /skills/a11y.md
Voice and copy → /skills/copy.md
Performance budget → /skills/performance.md
Component library → /skills/components.md
Decision logging → /skills/decisions.md

## Absolute rules: never break these
1. Never hardcode color or spacing values. Use CSS variables only.
2. Never install a new npm package without asking first.
3. Never modify files in /components/ui directly; theme through tokens.
4. Never push directly to main. All work goes on feature branches.
5. Never ship the /canvas or /prototype routes; design tools only.
6. Always add prefers-reduced-motion to any animation.
7. All touch targets minimum 44x44px.

## Deploy
Platform: Vercel
Preview: auto-deploy on every branch push
Production: merge to main via PR only; engineering reviews first
Password-protected previews: ask Claude Code to add basic auth
  or use Vercel's built-in password feature.

## Current status
[Update this section weekly: what's in progress, what's next,
what decisions are currently open.]
Active branch: design-system/week-of-[date]
In progress: [flow or component name]
Open decisions: [list or "none"]

## Designer preferences
Prefers high-contrast, low-density layouts.
When in doubt, remove rather than add.
Favour conversational, warm UI over structured, form-like UI.
Never use placeholder copy; generate real copy for every screen.

# CLAUDE.md: the thin shim
@AGENTS.md

# Claude-specific additions only, e.g.:
Skill wrappers live in .claude/skills/; read them
automatically when relevant.

# or skip the file entirely and symlink:
ln -s AGENTS.md CLAUDE.md

Read /skills/brand.md, /skills/a11y.md, and /skills/copy.md.
Read all files in /app.

Act as a senior product designer doing a design critique.
Be honest and specific, not encouraging.

Review the current state of the product against:
1. Brand alignment: does it feel like the brand or generic?
2. Hierarchy: is it clear what the most important action
   is on each screen?
3. Consistency: where does the experience feel uneven?
4. Friction: where might a user hesitate or get confused?
5. Copy: anything that sounds off, vague, or un-human?
6. Missed opportunities: what's a better version of this
   that we haven't tried yet?

Be specific. Cite screens and components. Don't summarize
what's there; evaluate it.

# /skills/brand.md

## Identity
Product: [Name], [one-line description of what it does and for whom].
Positioning: [e.g. "the approachable alternative to X"].
Tone: [3 words, e.g. warm, direct, human].
Never: formal, legalistic, passive voice, jargon, corporate-speak.

## Logo
Primary file: /assets/logo/logo.svg
Wordmark only: /assets/logo/logo-wordmark.svg
Clear space: 16px minimum all sides.
Minimum size: 24px height on screen.
Approved on: white, [primary bg color], dark backgrounds.
Never: stretch, rotate, recolor, place on busy backgrounds,
  use the icon without the wordmark in UI contexts.

## Typography
Primary typeface: [Font name]
  Use for: all UI headings, labels, buttons, body.
  Weights in use: 400 (regular), 500 (medium), 600 (semibold).
  Never use 700+ weight; too heavy at mobile sizes.

Secondary typeface: [Font name or "none"]
  Use for: editorial moments only (marketing, splash screens).
  Never in: forms, navigation, data displays.

Type scale (px):
  xs: 12   captions, legal, metadata
  sm: 14   secondary body, form hints
  md: 16   primary body text (base)
  lg: 20   section leads, card titles
  xl: 24   screen titles
  2xl: 32  hero headings
  3xl: 40  marketing only

Line height: 1.5 body / 1.2 headings / 1.0 buttons and labels.
Letter spacing: -0.01em headings / normal body.

## Color system
# Primitives: raw values, never used directly in UI
brand-50:  [lightest tint]
brand-100: [light tint]
brand-500: [main brand color]   ← primary identity color
brand-900: [darkest shade]

neutral-0:   #FFFFFF
neutral-50:  [off-white main surface]
neutral-100: [light gray]
neutral-500: [mid gray]
neutral-900: [near-black primary text]

# Semantic: use these in components, never primitives
action-primary:    brand-500    ← CTAs, links, active states
action-on-primary: neutral-0    ← text on action-primary bg
surface-default:   neutral-50   ← page and card backgrounds
surface-raised:    neutral-0    ← elevated surfaces
text-primary:      neutral-900  ← body text
text-secondary:    neutral-500  ← supporting text
text-disabled:     neutral-300
border-default:    neutral-100
danger:            [red hex]    ← errors, destructive actions
warning:           [amber hex]  ← caution states
success:           [green hex]  ← confirmations

## Color proportions (per screen)
Neutral surfaces: ~80%, backgrounds, cards, inputs.
Brand primary: ~10%, CTAs, key highlights, active states only.
Accent/warm: ~10%, empty states, illustrations, celebrations.
Rule: if a screen feels colorful, there's too much brand color.

## Accessibility
Standard: WCAG 2.2 AA minimum on all text. AAA preferred for body.
Approved pairs (tested):
  [neutral-900] on [neutral-50]  ✓ AAA
  [neutral-0] on [brand-500]     ✓ AA
  [neutral-900] on [neutral-0]   ✓ AAA
Failing pairs (never use):
  [brand-500] on [neutral-50]    ✗ fails AA
  [neutral-500] on [neutral-0]   ✗ fails AA for small text

## Iconography
Library: Lucide React
Stroke weight: 1.5px, never change this.
Sizes: 16px (inline/compact) or 24px (standalone) only.
Style: always outline, never filled.
Custom icons: /assets/icons/, must match Lucide stroke style.
When no Lucide equivalent: use a simple geometric SVG from Claude,
  not an image or emoji.

## Illustration
Style: flat, minimal, warm; think editorial not technical.
Palette: brand palette only, no additional colors in illustrations.
Detail level: low, clarity over complexity at small sizes.
Subjects: objects and abstract shapes, avoid depicting people.
Files: /assets/illustrations/, WebP + SVG where possible.
Usage: empty states, onboarding, error screens, celebrations.

## Photography
Mood: natural light, real environments, candid not posed.
Subjects: [relevant to your product context].
Avoid: stock photo aesthetics, artificial staging, excessive filters.
Format: WebP, max 200kb, explicit width/height attributes always.

## Motion principles
Default: no animation unless it communicates state or transition.
Duration: 150–250ms for micro-interactions, 300ms for transitions.
Easing: ease-out for entrances, ease-in for exits.
Always add: prefers-reduced-motion override (see /skills/a11y.md).

Read /skills/brand.md carefully before starting.

Scaffold a design system using shadcn/ui and
Tailwind CSS v4 (CSS-first config, no tailwind.config file)
based on the brand defined in brand.md. Generate:

1. /styles/tokens.css
   CSS custom properties for all colors, type scale,
     spacing scale (4px base unit), border-radius, shadows.
   Define values in :root and .dark.

2. /styles/globals.css
   @import "tailwindcss";
   @theme inline block mapping Tailwind + shadcn tokens
     (--color-primary, --color-secondary, etc.)
     to our CSS variables from tokens.css.
   Base typography rules.

3. /components/ui/ themed shadcn components:
   Button, Input, Card, Badge, Alert, Select, Dialog.
   Install via the shadcn CLI; do not hand-write them.

4. /app/design-system/page.tsx
   Living style guide showing every token and component
     in context. Renders at /design-system route.

Follow color proportions in brand.md.
Flag any accessibility conflicts you find.

Read /styles/tokens.css and /styles/globals.css.

Generate /tokens/design-tokens.json in W3C Design Tokens
format (DTCG, stable spec 2025.10). Include:

- color: all values grouped by role
  (primitive → semantic → component-level)
- typography: families, size scale, weights,
  line heights, letter spacing
- spacing: full scale from 4px base unit
- border-radius: all radius values
- shadow: elevation tokens
- motion: duration and easing if defined

For each token include: value, type, description,
and the CSS variable name it maps to.

Also generate:
 /tokens/design-tokens.ios.json (pt units for iOS)
 /tokens/design-tokens.android.json (sp/dp for Android)

// design-tokens.json (DTCG format)
{
  "color": {
    "primitive": {
      "brand-500": {
        "value": "#______",
        "type": "color",
        "description": "Base primary brand color"
      }
    },
    "semantic": {
      "action-primary": {
        "value": "{color.primitive.brand-500}",
        "type": "color",
        "description": "CTAs, links, active states",
        "css-variable": "--color-action-primary"
      }
    }
  }
}

Read /styles/tokens.css and /skills/brand.md.

Run a full accessibility audit on the color token system:

1. Test every foreground/background color pair defined
   in the semantic layer against WCAG 2.2 contrast ratios.
   Flag: AA fail (<4.5:1 normal, <3:1 large text),
         AAA fail (<7:1 normal); note both thresholds.

2. Identify any semantic token combinations that are
   used together in components but have no contrast check.

3. Check that every interactive state (hover, focus,
   active, disabled) has sufficient contrast in both
   light and dark mode.

4. Output a report: passing pairs ✓, failing pairs ✗,
   and a suggested fix for each failure (adjusted hex
   value that passes AA while staying close to the brand).

Read all files in /components/ui.

For each component, audit:

FOCUS
 Does every interactive element have a visible focus ring?
 Is focus order logical within the component?
 Can the component be fully operated by keyboard alone?

ARIA
 Are roles, labels, and descriptions correctly applied?
 Do icon-only buttons have aria-label?
 Are error states announced to screen readers?

TOUCH TARGETS
 Are all tap targets at least 44x44px on mobile?
 Is there sufficient spacing between adjacent targets?

MOTION
 Does any animation respect prefers-reduced-motion?

Output per component: pass ✓ | fail ✗ | needs review ⚠
For each failure, cite the line and suggest the fix.

# /skills/a11y.md

## Standards
Target: WCAG 2.2 AA minimum. AAA where feasible.
Platform: mobile-first. All touch targets 44x44px minimum.

## Color
Never communicate meaning through color alone.
Always pair color with a label, icon, or pattern.
Approved contrast pairs: [generated from token audit]
Failing pairs never to use: [generated from token audit]

## Focus
Every interactive element must have a visible focus ring.
Use: outline: 2px solid var(--color-action-primary); outline-offset: 2px
Never remove outline without providing an alternative.

## ARIA
Icon-only buttons always need aria-label.
Form inputs always need associated label elements (not placeholder only).
Error messages use role="alert" so they're announced immediately.
Loading states use aria-live="polite".

## Motion
All animations must respect:
@media (prefers-reduced-motion: reduce) { animation: none; }

## Audit cadence
Run token audit: after any token change.
Run component audit: after any component update.
Run full screen audit: weekly, on the system branch.

Read /skills/a11y.md. Read all files in /app.

Run a full accessibility audit across all screens:

1. Re-check all color pairs in context (components
   on real backgrounds, not just isolated tokens).
2. Verify heading hierarchy per screen: no skipped levels.
3. Check that all images have meaningful alt text or
   are marked decorative with aria-hidden="true".
4. Verify every form has proper label associations,
   error handling, and success confirmation.
5. Check reading order matches visual order on mobile.

Output: screen-by-screen report with pass/fail/warn.
Group failures by severity: critical | moderate | minor.
Critical issues block the weekly merge.

Read /skills/brand.md, /styles/tokens.css, and all files
in /components/ui.

Generate a design system documentation site at /app/design-system.
Include:

1. Token reference: every color, spacing, radius, shadow,
   and typography token displayed in context with its CSS
   variable name and current value.

2. Component gallery: every shadcn component in use,
   rendered in our brand theme, with a code snippet showing
   how to use it.

3. Pattern library: any composite patterns in /components
   that combine multiple primitives (e.g. form layouts, card
   variants, empty states).

4. Changelog: pull from /decisions/changelog.md and render
   as a versioned list with dates and descriptions.

The site should use our existing tokens and components.
Deploy to /design-system route, accessible at the Vercel
preview URL without authentication.

Read the git diff between design-system/week-of-[date]
and main.

Write a changelog entry for /decisions/changelog.md.

Format:
## [date] - Week of [date]

### Added
- [new tokens, components, or patterns introduced]

### Changed
- [tokens or components with updated values or behavior]

### Deprecated
- [anything scheduled for removal, with replacement]

### Fixed
- [a11y issues, visual regressions, or token drift resolved]

Be specific: name the token or component, describe the
change, and explain why if the decision log has context.
Skip sections with no changes. Keep entries brief.

// flows.config.ts
export const flows = [
  {
    name: "[Flow 1 name]",
    screens: [Screen1, Screen2, Screen3, Screen4]
  },
  {
    name: "[Flow 2 name]",
    screens: [EntryScreen, FormScreen, ReviewScreen,
              PendingScreen, SuccessScreen, ErrorScreen]
  }
]

Build a canvas view at /app/canvas/page.tsx
that reads from flows.config.ts.

Requirements:
 Infinite canvas: pannable with click-drag, zoomable
  with scroll or pinch (CSS transform, no libraries).
 Each screen rendered at ~25% scale inside a labeled
  phone frame. Screen name shown below.
 Click any screen to expand full size in an overlay.
 Screens grouped by flow with flow label above each group.
  Arrange groups left to right.
 Mini-map in bottom-right showing canvas position.
 Toolbar: zoom in/out, fit-to-screen, flow-jump dropdown.

Add /canvas to CLAUDE.md as a protected design-only route;
never ships to production.

Build a prototype viewer at /app/prototype/[flow]/page.tsx
that reads from flows.config.ts.

Requirements:
 Centered 390px mobile frame on a neutral dark background.
 Tap/click advances to next screen. Back arrow goes back.
 Step counter at top of frame showing position in flow.
 Flow selector dropdown outside the frame.
 "Copy link" button copies URL with flow + step as query
  params; shared link opens at the exact screen.
 Left/right arrow key navigation.
 No UI chrome inside the phone frame.

Deploy at /prototype/[flow-1-name], /prototype/[flow-2-name].

# /locales/en.json: content tokens
{
  "onboarding": {
    "hero": {
      "headline": "Get started in minutes",
      "subtext": "No setup required. Connect your account and go.",
      "cta": "Create your account"
    },
    "steps": {
      "connect": "Connect your tools",
      "configure": "Set your preferences",
      "launch": "You're ready"
    }
  },
  "errors": {
    "auth.expired": "Your session expired. Please sign in again.",
    "form.required": "This field is required."
  }
}

# prompt to add locale switcher to canvas view
Add a locale switcher to /app/canvas/page.tsx.
- Render a dropdown in the top toolbar with all locales from /locales/
- Switching locale passes the selected language to all child screen components via context
- The switcher state persists in localStorage so it survives page reloads
- Default to 'en' if no preference is stored

Read all files in /app and /components.

Identify inconsistencies across these dimensions:
 Spacing: are margins and padding consistent across
  similar components?
 Typography: are heading levels used consistently?
 Buttons: are primary/secondary/ghost variants
  used correctly and consistently?
 Cards: how many different card treatments exist?
  Should any be consolidated?
 Empty states: consistent handling?
 Error and loading states: same approach per flow?

Output a report grouped by dimension.
For each issue, cite the specific files and suggest
the canonical pattern to adopt.

These are now the canonical components:
 ContentCard    → /components/ui/ContentCard.tsx
 StatusBadge    → /components/ui/StatusBadge.tsx
 FormStep       → /components/ui/FormStep.tsx
 EmptyState     → /components/ui/EmptyState.tsx

Scan all files in /app. Replace any inline implementations
of these patterns with imports of the canonical component.
Do not change visual output; only refactor structure.
List every file you changed.

# /skills/decisions.md

## Purpose
Log every significant design decision made during this project.
A decision is significant if it: changes a token value, introduces
or retires a component, establishes a new pattern, overrides a
brand rule, or resolves a conflict between design and engineering.

## Format: one entry per decision
Each entry must include:
 Date (YYYY-MM-DD)
 Area: token | component | pattern | flow | brand | a11y
 Decision: what was decided, in one clear sentence
 Rationale: why, the constraint, tradeoff, or insight
 Affected: which files, components, or screens this touches
 Status: active | superseded | under review
 Decided by: designer name or "Claude (auto)"

## When to log
Log immediately when: a pattern is consolidated, a token is
changed, a component is retired, an escalation is resolved,
or a new canonical component is established.

## File location
All entries live in /decisions/log.json (structured)
and /decisions/CHANGELOG.md (human-readable summary).

# add to CLAUDE.md:
After completing any task that involves a design decision
(token change, component update, pattern consolidation,
escalation resolution), append an entry to
/decisions/log.json following the format in
/skills/decisions.md. Do this automatically; do not
ask for confirmation unless the decision area is "brand"
or "a11y", which require designer sign-off.

Read /decisions/log.json.

Generate /decisions/CHANGELOG.md structured as follows:

## [Version / week tag] [date]

### Tokens
 [list token changes with rationale summary]

### Components
 [new, updated, or retired components with rationale]

### Patterns
 [pattern consolidations or new patterns established]

### Escalations resolved
 [decisions that required designer sign-off]

### Open / under review
 [anything logged as "under review" status]

Keep each entry to one line. Link to the affected file
where relevant. Mark designer-approved items with ✓.

Extend /app/canvas/page.tsx to add a version history panel.

Requirements:

Version panel (right sidebar, collapsible):
 Reads from /decisions/log.json
 Lists entries grouped by week/version tag, newest first
 Each entry shows: date, area badge, decision (one line),
  decided-by label
 Clicking an entry highlights the affected screens
  on the canvas with a colored overlay
 Filter by area: token | component | pattern | flow | all

Version switcher (toolbar):
 Dropdown of all git tags with "design-system/" prefix
 Selecting a tag checks out that version and reloads
  the canvas so you can see exactly what the system
  looked like at any past milestone
 "Current" option always returns to HEAD

Changelog tab (bottom drawer):
 Renders /decisions/CHANGELOG.md as formatted HTML
 Searchable by keyword
 Exportable as PDF for stakeholder sharing

# /skills/copy.md

## Voice
[Your product voice in 3 words, e.g. warm, direct, human.]
Never: formal, legalistic, passive voice, jargon.

## Tone by context
Onboarding: encouraging, low-stakes, welcoming.
Errors: calm, specific, actionable. Never blame the user.
Success states: brief, warm; don't over-celebrate.
Empty states: helpful, not apologetic. Show the path forward.
Destructive actions: clear and specific. State what will be lost.

## Button labels
Always verb-first and specific: "Save changes", not "OK".
Primary CTA: describes the outcome, not the action.
  Good: "Send money" / Bad: "Submit"
Destructive: states what happens. "Delete account", not "Confirm".
Cancel: always "Cancel", never "No" or "Go back".

## Error messages
Structure: [what happened] + [why] + [what to do].
Never show raw error codes to users.
Always offer a path forward: a retry, a support link, or next step.

## Character limits (mobile)
Screen titles: 24 chars max.
Subtitles / descriptors: 60 chars max.
Button labels: 20 chars max.
Toast notifications: 48 chars max.
Empty state body: 80 chars max.

## Things to never say
"Something went wrong" (too vague)
"Please try again later" (no timeline)
"Invalid input" (doesn't say what's invalid)
"Are you sure?" (not specific enough for destructive actions)

Read /skills/copy.md. Read all files in /app.

Audit all copy across every screen for:

1. Voice violations: anything that sounds formal, cold,
   or uses passive voice. Quote the offending string and
   suggest a rewrite.

2. Button label inconsistencies: same action labeled
   differently across screens. List all button labels
   grouped by action type.

3. Error messages without a clear path forward: flag
   any error that doesn't tell the user what to do next.

4. Character limit violations: flag any string that
   exceeds the limits in copy.md.

5. Placeholder text still in production: any string
   containing "Lorem", "TBD", "TODO", or "[".

Output: grouped by issue type, with file and line reference,
and a suggested fix for each.

Read all files in /app.

Generate /tokens/content-inventory.json, a structured
export of every user-facing string in the app:

{
  "screen": "payment-error",
  "element": "error-title",
  "string": "Payment didn't go through",
  "context": "shown after a failed card charge",
  "character-count": 30,
  "last-updated": "2026-01-15"
}

Group by screen. Flag any string over the character
limits defined in /skills/copy.md.

Read all files in /app and /components/ui.

Generate /skills/components.md, a skill file documenting
every component in /components/ui with:
 What it's for (one sentence)
 When to use it vs. alternatives
 Required and optional props
 A usage example
 Anything that should never be done with it

Write it so a designer new to this codebase could read it
and know exactly what to reach for and when.

# /skills/performance.md

## Budget targets
JS bundle (initial load): < 200kb gzipped
CSS bundle: < 50kb gzipped
Largest Contentful Paint (LCP): < 2.5s on 4G mobile
Cumulative Layout Shift (CLS): < 0.1
Time to Interactive (TTI): < 3.5s on mid-range device

## Images
All images served as WebP or AVIF.
Max image weight: 200kb per asset.
All images must have explicit width and height to prevent CLS.
Use next/image (or equivalent) for automatic optimization.

## Dependencies
No new npm package without justification logged to decision log.
Prefer tree-shakeable libraries.
No package that duplicates functionality already in the stack.

## Audit cadence
Run before every weekly system branch merge.
Any budget breach blocks the merge until resolved or
a conscious exception is logged to the decision log.

Read /skills/performance.md.

Run a performance audit on the current branch:

1. BUNDLE ANALYSIS
   Run: npx next build && npx @next/bundle-analyzer
   Flag any route whose JS exceeds 200kb gzipped.
   Identify the top 3 contributors to bundle size.

2. UNUSED DEPENDENCIES
   Scan package.json against actual imports across /app
   and /components. List any package imported nowhere.

3. DUPLICATE FUNCTIONALITY
   Flag any two packages that do the same job
   (e.g. two date libraries, two animation libraries).

4. IMAGE AUDIT
   Find any <img> tags not using the optimized
   image component. Find images without explicit
   width/height. Find any image over 200kb.

5. CSS AUDIT
   Find any inline styles that duplicate values
   already defined in tokens.css.
   Find any hardcoded color or spacing values
   that should reference a CSS variable.

Output: pass ✓ | exceeds budget ✗ | warning ⚠
For each failure, cite the file and suggest the fix.

# add to CLAUDE.md
Engineering repo: ../[repo-name] (read-only reference)
Before designing any component that engineering already owns,
read the relevant file in ../[repo-name]/src first.
Never create a file in ../[repo-name] directly.
All design work stays in this repo [your-design-repo].

# example session opener
Read ../[repo-name]/src/types/transaction.ts
and ../[repo-name]/src/api/transactions.ts.

Before I design the transaction history screen:
1. What fields are available on a transaction object?
2. What are the possible status values?
3. What edge cases should I design for (empty, error,
   partial data, very long merchant names)?
4. Are there any fields I might want to show that
   don't exist in the current data model?

# design PR description template: ask Claude to fill in
## What changed
[Visual description of the change: what users see differently]

## Implementation notes
[How it was built: component choices, token usage, state logic]
[Any deviations from the existing pattern and why]

## What to verify
- [ ] Visual: [specific thing to check in browser]
- [ ] A11y: [specific thing to check: contrast, focus, ARIA]
- [ ] Edge cases: [list from data shape analysis]
- [ ] Mobile: [anything to check specifically on small screens]

## Design decision log
[Link to relevant entries in /decisions/CHANGELOG.md]

Read ../[repo-name]/src/[path-to-affected-files].
Read my changes in /app/[screen].tsx.

Before I open a PR, review my changes as an engineer would:

1. COMPATIBILITY: does my implementation use the same
   patterns, naming conventions, and abstractions as the
   surrounding engineering code? Flag any inconsistency.

2. COMPLETENESS: are there states, edge cases, or error
   conditions the engineering code handles that my design
   doesn't account for?

3. PERFORMANCE: any obvious inefficiencies? Unnecessary
   re-renders, missing memoization, heavy inline operations?

4. ACCESSIBILITY: does this meet the standards in
   /skills/a11y.md? Any focus, ARIA, or contrast issues?

5. BREAKING CHANGES: does anything I've changed affect
   other screens that use the same component or token?
   List every file that could be affected.

6. VISUAL VERIFICATION: run the app and walk the affected
   screens in the browser. Screenshot every state and
   compare against the current production version. Flag
   any unintended visual change, however small.

Output: ready to submit ✓ | needs revision ✗ | review note ⚠
For each issue, cite the specific line and suggest the fix.

# designer-owned
local → vercel preview (feature branch URL)

# engineering-owned
staging → production

# never push directly to main
git checkout -b feature/name
# build → push → Vercel auto-deploys preview URL

# weekly sync routine: run every Monday morning
git fetch origin
git checkout main
git pull origin main

# check what changed since your last session
git log --oneline --since="7 days ago"

# then ask Claude Code:
Read the git log from the past week.
Summarize what changed across /components, /styles,
and /app. Flag anything that may affect the design
system or existing screen layouts.

# start of each day: branch from latest main
git checkout main && git pull origin main
git checkout -b design/2026-01-15-[task-name]

# end of day: push and open a draft PR
git add -A
git commit -m "design: [what changed]"
git push origin design/2026-01-15-[task-name]

# weekly system branch
git checkout main && git pull origin main
git checkout -b design-system/week-of-2026-01-15

# then ask Claude Code:
Read all changes made to /components and /styles
across this week's feature branches. Identify any new
patterns, components, or style values that should be
promoted into the design system. List them with a
recommendation for each: promote, consolidate, or discard.

Read the diff between design-system/week-of-[date] and main.

Classify every change by scope:

SAFE: cosmetic or additive. No existing screens affected.
  → Apply automatically. No review needed.
  Examples: new component added, token value tweaked slightly,
  new utility class, copy fix.

REVIEW: affects existing components or token values.
  Existing screens may look different.
  → Apply, then flag for visual review in the browser.
  Examples: spacing scale change, border-radius update,
  button variant modified, type scale adjusted.

REFACTOR: a pattern has changed enough that screens using
  the old pattern need to be updated to stay consistent.
  → Apply refactor across all affected files, then flag
  a summary of what was changed for designer sign-off.
  Examples: card component restructured, form pattern updated,
  navigation component rebuilt.

ESCALATE: breaking change or significant design decision
  that affects major flows or brand-level tokens.
  → Do not apply. Write a clear brief explaining what
  changed, what is affected, and what decision is needed.
  Flag directly to the designer for a human call.
  Examples: primary color value changed, type scale
  restructured, component removed, major layout pattern shift.

The [ComponentName] pattern has been updated.
The new canonical version is in /components/ui/[ComponentName].tsx.

1. Scan all files in /app for usages of the old pattern.
2. Refactor each to use the updated component.
3. Do not change any logic, copy, or non-visual behavior.
4. After refactoring, output a list of every file changed
   with a one-line note on what was updated in each.
5. Flag any file where the refactor was ambiguous or
   where the old usage didn't map cleanly to the new pattern.

# end of week: merge system branch to main
git checkout design-system/week-of-[date]
git rebase main  # keep history clean
git push origin design-system/week-of-[date]

# open PR, ask Claude Code to write the description:
Read the diff between design-system/week-of-[date] and main.
Write a PR description that summarizes:
 New components or patterns added
 Components refactored and why
 Token changes made
 Any open decisions that were escalated
 What designers should visually verify after merge