Find CSS/styling files (conceptual)

The user input to you can be provided directly by the agent or as a command argument - you MUST consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

⚠️ v7 Play Level Guard

Read .speck/​project.json (if it exists) for play_level. If missing, default to Platform.

• Sprint: Tell the user: "Sprint projects don't need a design system. Ship with whatever CSS you know. Run /​project-promote when you're ready to grow." STOP.
• Build: Tell the user "At Build, the standalone design-system.md is optional. The required artifact for any UI project is design-system/​primitives.md (the live primitive registry) — that prevents inline UI re-implementations from drifting. Run this skill ONLY if you want a full design-system.md AND keep primitives.md as the live registry. Otherwise, run /​speck-primitives-init to bootstrap just the registry."
• Platform (or no project.json): Recommended. Full flow below.

Always, on any run, also create or update design-system/​primitives.md using .speck/​templates/​project/​primitives-registry-template.md.

---

Play Level Check (Legacy heading, retained for compatibility)

---

Develop a detailed design system that will ensure consistency across the entire project.

Context Requirements & Mode Detection

1. Project Identification

   • If project name/​ID in arguments → use it
   • Otherwise ask: "Which project should I create the design system for?"
   • Load: project.md, ux-strategy.md, architecture.md

2. Prerequisites Check

   • Required: ux-strategy.md (run /​project-ux if missing)
   • Required: architecture.md (run /​project-architecture if missing)
   • Understand design principles and personality from UX
   • Understand tech stack and component structure from architecture

3. Mode Detection

   • Check for project-landscape-overview.md (from /​project-scan)
   • Check if codebase has UI components
   • If YES: BROWNFIELD mode (extract existing design system)
   • If NO: GREENFIELD mode (create new design system)

Position in Flow:

• Runs AFTER architecture, BEFORE planning
• Architecture informs tech-specific design choices (Tailwind vs CSS-in-JS)
• Design system informs UI requirements in planning

Research Approach: Uses just-in-time research pattern (.cursor/​skills/​just-in-time-research/​SKILL.md) for design patterns, tokens, and accessibility standards

Just-In-Time Research

Before creating/​extracting design system, conduct research for:

• Design Tokens: Web search for token naming conventions, best practices
• Component Patterns: Web search for component library structures
• Accessibility Standards: Web search for WCAG 2.1 AA requirements, ARIA patterns
• Design System Examples: Web search for industry-standard design systems
• Deep Research (if needed): Custom design language development

Document findings in "Research Informing This Design System" section of output.

Interactive Design System Creation

MODE SELECTION: Branch based on detected mode

---

BROWNFIELD MODE (Extract from Existing UI)

Prerequisites: Codebase has UI components (detected from scan or manual inspection)

Step 1: Analyze Existing UI Code

Scan for design tokens in code:

# Find CSS/​styling files (conceptual)
grep -r "color:" frontend/
grep -r "fontSize:" frontend/
grep -r "spacing:" frontend/
grep -r "borderRadius:" frontend/

# Find component files
ls frontend/​components/
ls src/​ui/

Extract existing patterns:

• Colors used in code (primary, secondary, accent, neutrals)
• Font sizes and families
• Spacing values (margin, padding)
• Border radius values
• Shadow definitions
• Component patterns

Step 2: Consolidate into Token System

From extracted values, create systematic tokens:

Colors (extract from actual usage):

• Primary: [#XXXXXX - used for CTAs, primary actions]
• Secondary: [#XXXXXX - used for secondary actions]
• Neutrals: [#XXXXXX, #XXXXXX, etc. - grays used in UI]
• Semantic: [Success, Warning, Error colors found in code]

Typography (extract from actual usage):

• Font families: [Fonts actually used]
• Sizes: [All fontSize values found, consolidated into scale]
• Weights: [Font weights used]

Spacing (extract from actual usage):

• Base unit: [Infer from most common values - 4px or 8px]
• Scale: [All spacing values found, mapped to scale]

Components (extract from actual files):

• List all existing components with file paths
• Document props/​variants found in code
• Note inconsistencies (same component with different patterns)

Step 3: Identify Gaps & Inconsistencies

Document findings:

• Inconsistent color usage: [Examples of same semantic meaning, different colors]
• Arbitrary spacing values: [Values not on systematic scale]
• Missing components: [UI patterns built ad-hoc vs reusable components]
• Accessibility gaps: [Missing ARIA, color contrast issues]

Step 4: Generate Design System (Descriptive + Prescriptive)

Create design-system.md with:

• Existing Tokens section (what code currently uses)
• Recommended Tokens section (consolidated into systematic scale)
• Migration Guide section (how to move from arbitrary to systematic)
• Component Inventory section (what exists, what's missing)

Mark extraction source:

> **Extraction Note**: This design system was extracted from existing codebase.
> "Existing" sections are DESCRIPTIVE (current state).
> "Recommended" sections are PRESCRIPTIVE (systematic improvements).
> Migrate gradually - new components use recommended tokens.

---

GREENFIELD MODE (Create New Design System)

Purpose: Create design system from scratch based on UX strategy

Step 1: Design Token Definition

Guide through foundational decisions:

Color System

• "What's your primary brand color?" (show picker options)
• "Do you need dark mode support?"
• Generate: Primary, secondary, neutral, semantic colors

Typography Scale

• "Preferred font family?" (or suggest based on personality)
• Generate: Type scale (xs through 6xl)
• Define: Line heights, letter spacing, font weights

Spacing System

• "Prefer a 4px or 8px base unit?"
• Generate: Spacing scale (0.5x through 12x)
• Define: Component padding standards

Shape & Effects

• "Corner radius preference?" (sharp/​slightly/​rounded/​pill)
• "Shadow intensity?" (none/​subtle/​moderate/​dramatic)
• Generate: Radius scale, shadow scale

Step 2: Component Architecture

Component Categories

Primitives: Button, Input, Label, Link
Layout: Container, Grid, Stack, Divider  
Feedback: Alert, Toast, Spinner, Progress
Navigation: Nav, Tabs, Breadcrumb, Pagination
Overlay: Modal, Drawer, Tooltip, Popover
Data Display: Table, List, Card, Badge

For each category, ask:

• "Which components will you need?"
• "Any special variations required?"

Step 3: Pattern Library

Interaction Patterns

• Form validation approach
• Loading states
• Empty states
• Error handling
• Success feedback

Layout Patterns

• Page templates
• Section layouts
• Responsive behavior
• Grid system

Step 4: Accessibility Standards

Ensure inclusive design:

• Color contrast ratios
• Focus states
• Keyboard navigation
• Screen reader support
• Touch targets

Step 5: Create Design System

1. Load template: .speck/​templates/​project/​design-system-template.md
2. Create base file: specs/​projects/[PROJECT_ID]/​design-system.md
3. Fill systematically:
   • Generate color tokens from brand colors
   • Create typography scale
   • Define spacing system
   • List needed components
   • Document patterns
   • Add implementation notes

Additional files can be created:

• design-system/​components/ - Individual component specs
• design-system/​patterns/ - Detailed pattern guides
• design-system/​examples/ - Code samples

Step 6: Review and Guide

Present what was created:

• "I've created the design system at [path]"
• "Defined [X] color tokens, [Y] components"
• "Documented key patterns and guidelines"

Integration guidance:

• Next in flow: /​project-architecture (system design using design tokens)
• Or skip to: /​project-roadmap (if architecture not needed)
• Later usage: /​epic-wireframes, /​story-ui-spec will reference these tokens
• Implementation: Build component library (consider Storybook)
• Export: Design tools like Figma/​Sketch for design team

Note: Design system provides visual design inputs for architecture decisions

The template contains comprehensive sections for tokens, components, patterns, and implementation.

Context Management

Since commands can't rely on directory context:

• Always ask for project specification
• Store design system reference in project plan
• Link to design system from all epic/​story specs
• Maintain version history for changes

Success Criteria

A complete design system includes: ✅ Complete token definitions ✅ Core component specifications
✅ Interaction patterns ✅ Accessibility guidelines ✅ Implementation examples ✅ Clear documentation