Design System Workflow

Initialize or extend the project's design system with properly accessible, consistent UI components using Tailwind CSS and shadcn/ui.

Step 0: Verify Feature Branch

Ensure we are on a feature branch based on the latest

main

bash

git fetch origin main

If on

main

, create a new feature branch:

bash

git checkout -b feature/design-system origin/main

If already on a feature branch, rebase onto latest

origin/main

bash

git status --porcelain

If the working tree is dirty, stash before rebasing:

bash

git stash push -m "setup-design-system: stash before rebase"
git rebase origin/main
git stash pop

If the working tree is clean, rebase directly:

bash

git rebase origin/main

Step 1: Assess Current State

Check if a design system already exists:

Look for
```
packages/ui/
```
directory structure
Check for shadcn/ui configuration (
```
components.json
```
)
Check Tailwind configuration (
```
src/index.css
```
for
```
@theme
```
directives in v4, or
```
tailwind.config.*
```
for v3)
Identify existing components and their patterns
Check for design tokens (colors, spacing, typography definitions)

Ask the user:

Initializing a new design system or extending the existing one?
If extending: what components or patterns are needed?
Any brand guidelines, color palette, or Figma designs to reference?
Dark mode support needed?

Step 2: Product Council Design Review (for initialization or major changes)

If initializing the design system or making significant structural changes, activate a Product Council subset:

Model Selection: See the Model Selection section in README.md for mapping agent model specs to Task tool parameters.

Design Lead (Lead) — consult: ui-design

Brand Identity: Color palette, typography, visual language
Component Hierarchy: Primitives vs composed components
Design Tokens: Token architecture (colors, spacing, typography, shadows)
Recommendations: Design system structure and principles

Frontend Specialist — consult: frontend-mobile-development

Technical Architecture: Component library structure, build pipeline
Framework Integration: Vite + React 19 compatibility, tree-shaking
Recommendations: Implementation patterns, tooling choices

Product Strategist

User-Facing Priorities: Which components are needed first?
Brand Consistency: Does this align with product vision?
Recommendations: Prioritization of design system investment

CHECKPOINT: Present the design system architecture proposal to the user. Wait for approval of structure and token definitions before building.

Step 3: Design System Infrastructure

If initializing a new design system:

Invoke

/ui-design:design-system-setup

for initialization guidance.

Set up the foundation:

Design Tokens

Color palette (primary, secondary, neutral, semantic: success/warning/error/info)
Typography scale (font families, sizes, weights, line heights)
Spacing scale (consistent spacing values: 0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64)
Border radii (none, sm, md, lg, xl, full)
Shadows (sm, md, lg, xl)
Breakpoints (sm, md, lg, xl, 2xl)

Tailwind Configuration Using

/frontend-mobile-development:tailwind-design-system

Extend the Tailwind theme with design tokens
Configure shadcn/ui with project-specific theme colors
Set up CSS custom properties for runtime theming
Configure dark mode strategy (class-based or media-query)

Component Structure

packages/ui/src/
├── components/
│   ├── primitives/    # Button, Input, Badge, Label, Switch
│   ├── layout/        # Container, Grid, Stack, Spacer, Divider
│   ├── navigation/    # Navbar, Sidebar, Breadcrumb, Tabs
│   ├── feedback/      # Alert, Toast, Modal, Dialog, Skeleton
│   ├── data-display/  # Card, Table, List, Avatar, Tooltip
│   └── forms/         # Form, FormField, Select, Checkbox, Radio
├── tokens/            # Design token definitions
├── hooks/             # Shared UI hooks (useMediaQuery, useTheme)
└── utils/             # UI utilities (cn, cva variants)

If extending an existing design system:

Read the existing patterns and conventions before adding new components. Match the established API patterns.

Step 4: Build Components

For each component needed, follow this process:

4a. Component Design

Invoke

/ui-design:create-component

for guided component creation.

Define the component API:

Props interface: All configurable options with TypeScript types
Variants: Size, color, and style variants (using cva or tailwind-variants)
Default values: Sensible defaults that work out-of-the-box
Composition: How it works with child components

4b. Implementation

Build each component with:

Full TypeScript typing (no
```
any
```
types)
Tailwind CSS styling with shadcn/ui patterns
```
React.forwardRef
```
for ref forwarding
```
className
```
prop merged with
```
cn()
```
utility for style overrides
Responsive behavior using Tailwind breakpoints

4c. Accessibility

Every component must include:

Semantic HTML elements (button, nav, dialog, etc.)
ARIA attributes (aria-label, aria-describedby, role, etc.)
Keyboard navigation (Tab, Enter, Escape, Arrow keys as appropriate)
Focus management (visible focus ring, focus trap for modals)
Screen reader announcements for dynamic content
Color contrast meeting WCAG AA (4.5:1 for text, 3:1 for large text)
Touch target minimum size (44x44px for interactive elements)

4d. Tests

For each component, write:

Render test: Component renders without errors
Props test: All variants and prop combinations render correctly
Interaction test: Click, hover, keyboard interactions work
Accessibility test: ARIA attributes present, keyboard nav works

CHECKPOINT: After each component (or batch of related components), present the implementation to the user for visual review. Show the component API, variants, and accessibility features.

Step 5: Accessibility Audit

After all components are built, run a comprehensive accessibility audit:

Invoke

/ui-design:accessibility-audit

on all new/modified components.

Check for:

WCAG 2.1 AA compliance (minimum standard)
Color contrast: All text meets contrast ratios
Keyboard navigation: Complete keyboard operability
Screen reader: All interactive elements announced correctly
Focus management: Logical focus order, visible focus indicators
Motion: Respect
```
prefers-reduced-motion
```
media query
Touch targets: Minimum 44x44px on mobile

CHECKPOINT: Present accessibility audit findings. User approves the accessibility posture or requests changes.

Step 6: Design Review

Invoke

/ui-design:design-review

to review the overall design system for:

Consistency: All components follow the same patterns
Naming: Props, variants, and CSS classes follow conventions
API patterns: Consistent prop interfaces across components
Visual coherence: Components look like they belong together
Completeness: Common use cases are covered

Address any findings from the review.

Step 7: Documentation

Document the design system:

Component catalog: Each component with props table, usage examples, and do/don't patterns
Design tokens: Complete reference of colors, typography, spacing
Accessibility guide: Per-component accessibility notes and testing instructions
Getting started: How to import and use components in the app

Step 8: Commit

Commit with conventional commit format:

For new design system:

feat(ui): initialize design system with core components

For new components:

feat(ui): add <component-name> component

For design token changes:

feat(ui): update design tokens for <change-description>

Step 9: Hand Off — STOP Here

[!CAUTION] This skill's work is done. Do NOT proceed to create a pull request, push to remote, or run a code review. Those are separate skills with their own workflows and checkpoints.

Present the next step to the user:

Recommended: Run
```
/review-code
```
for multi-perspective quality and accessibility review before submitting
If building a feature that uses these components: Continue with
```
/build-feature
```
to implement the feature, then run
```
/review-code
```
If this is standalone design system work: Run
```
/review-code
```
→
```
/submit-pr
```

[!TIP] Pipeline:
/plan-feature
→
/build-feature
or
/build-api
→
/review-code
→
/submit-pr
/setup-design-system
can be run at any point in the pipeline or independently. You are here — proceed to
/review-code
when ready.

Do not push the branch, create a PR, or invoke
/submit-pr
from within this skill.

setup-design-system

NPX Install

Tags

SKILL.md Content

Design System Workflow

Step 0: Verify Feature Branch

Step 1: Assess Current State

Step 2: Product Council Design Review (for initialization or major changes)

Design Lead (Lead) — consult: ui-design

Frontend Specialist — consult: frontend-mobile-development

Product Strategist

CHECKPOINT: Present the design system architecture proposal to the user. Wait for approval of structure and token definitions before building.

Step 3: Design System Infrastructure

If initializing a new design system:

If extending an existing design system:

Step 4: Build Components

4a. Component Design

4b. Implementation

4c. Accessibility

4d. Tests

CHECKPOINT: After each component (or batch of related components), present the implementation to the user for visual review. Show the component API, variants, and accessibility features.

Step 5: Accessibility Audit

CHECKPOINT: Present accessibility audit findings. User approves the accessibility posture or requests changes.

Step 6: Design Review

Step 7: Documentation

Step 8: Commit

Step 9: Hand Off — STOP Here