Design Specialist

AG-DESIGN creates and maintains design systems, component specifications, design tokens, and ensures accessibility-first design across all products.

Capabilities

• Design System Creation: Design tokens, component library, design patterns
• Component Specifications: Full specs with states, variants, props, accessibility
• Design Documentation: Design-to-code handoff guides, component specs
• Accessibility-First Design: WCAG AA minimum, AAA preferred
• Design Tokens: Colors, typography, spacing, shadows, animations (single source of truth)
• Consistency Audits: Ensure design system usage across products
• Design System Versioning: Semantic versioning, changelog management

When to Use

Use AG-DESIGN when:

• Creating or maintaining a design system
• Designing new UI components or features
• Documenting component specifications for developers
• Conducting design consistency audits
• Ensuring accessibility compliance (WCAG AA/AAA)
• Defining design tokens and guidelines
• Creating design-to-code handoff documentation

How It Works

1. Context Loading: Reads expertise file and current design system state
2. Design Analysis: Reviews what components and tokens are needed
3. Specification: Creates full component specs with all states and variants
4. Documentation: Creates design tokens and design-to-code handoff guides
5. Accessibility Review: Audits for WCAG AA/AAA compliance
6. Consistency Check: Verifies design system usage is consistent
7. Coordination: Updates status.json and coordinates with AG-UI on implementation

Example

Copy# Via /babysit
/babysit
> "I need to design a new Button component with multiple variants"
 
# AG-DESIGN will:
# 1. Define Button component purpose and use cases
# 2. Create full specification (states, variants, props, accessibility)
# 3. Define design tokens (colors, typography, spacing)
# 4. Create design-to-code handoff guide
# 5. Conduct accessibility audit (contrast, focus, keyboard)
# 6. Provide specs to AG-UI for implementation

Key Behaviors

• Accessibility First: WCAG AA minimum, AAA preferred for all designs
• Fully Specified: Every component has complete specs (all states, variants)
• Token-Based: Colors, typography, spacing use design tokens (not hardcoded)
• Implementation-Aware: Designs are feasible to implement
• Consistency-Focused: Entire design system is coherent and consistent
• Documentation: All designs documented for handoff to developers

Tools Available

• Read, Write, Edit, Bash, Glob, Grep
• Access to Session Harness for verification

Design Tokens

Colors:

• Primary (main action color)
• Secondary (supporting actions)
• Accent (highlights)
• Status colors (error red, warning yellow, success green, info blue)
• Neutral grays (backgrounds, borders)

Typography:

• Font families (heading, body, monospace)
• Font sizes (scale: 12px, 14px, 16px, 18px, 20px, 24px, 32px)
• Font weights (400, 500, 600, 700)
• Line heights (1.2, 1.5, 1.8)

Spacing:

• Scale: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px
• Used for padding, margin, gaps

Other Tokens:

• Shadows (elevation levels 0-24)
• Borders (border radius, widths, styles)
• Animations (durations, easing)

Component Specifications

Complete Spec Includes:

• Component name and purpose
• States (default, hover, active, disabled, loading, error)
• Variants (sizes, colors, combinations)
• Props/properties with types and defaults
• Accessibility requirements (ARIA, focus, keyboard)
• Usage guidelines (when to use, when not to)
• Design tokens used
• Related components

Example Component Spec:

Copy## Button Component
 
Purpose: Primary interaction element for user actions
 
Props:
- variant: "primary" | "secondary" | "danger" (default: "primary")
- size: "sm" | "md" | "lg" (default: "md")
- disabled: boolean (default: false)
- loading: boolean (default: false)
- icon: ReactNode (optional)
- children: ReactNode (required)
 
States:
- Default: Uses primary color token
- Hover: 10% darker, cursor pointer
- Active: 20% darker
- Disabled: 40% opacity, cursor not-allowed
- Loading: Shows spinner, disabled state
 
Accessibility:
- Type: button
- ARIA label if no text
- Focus visible with 2px outline
- Enter/Space triggers click
- Tab order preserved
 
Tokens Used:
- Color: primary, secondary, danger
- Typography: button-md (14px, 600 weight)
- Spacing: md (16px)
- Shadow: elevation-2
 
Usage:
- Primary actions (sign up, submit)
- Secondary actions with variant="secondary"
- Destructive actions with variant="danger"
 
Do NOT Use For:
- Navigation (use Link component)
- Toggle states (use Toggle component)

Design Documentation

Design System Docs Structure:

• Overview and philosophy
• Token documentation (colors, typography, spacing)
• Component library (all components with specs)
• Design patterns (common interaction patterns)
• Do's and don'ts (usage guidelines)
• Accessibility guidelines
• Implementation guides (for developers)

Design-to-Code Handoff:

• Component spec (as above)
• Figma/design file link
• Design tokens required
• Developer guidelines
• Testing checklist
• Accessibility checklist

Accessibility (WCAG AA/AAA)

WCAG AA (Minimum):

• Color contrast ≥4.5:1 for text
• Color contrast ≥3:1 for UI components
• Focus visible indicators (≥2px outline)
• Keyboard accessible (all interactive elements)
• No color-only information (use icons, text, patterns)
• Motion can be disabled (prefers-reduced-motion)

WCAG AAA (Preferred):

• Color contrast ≥7:1 for text
• Color contrast ≥4.5:1 for UI components
• Enhanced focus indicators
• More granular motion controls

Design Review Checklist:

• Contrast ratios verified
• Focus states designed
• Keyboard navigation possible
• No color-only information
• Screen reader compatible (implied)
• Reduced motion respected

Design System Versioning

Semantic Versioning:

• MAJOR: Breaking changes (component removal, significant spec changes)
• MINOR: New components or non-breaking enhancements
• PATCH: Bug fixes and documentation updates

Changelog per Release:

• Added components
• Changed/updated components
• Deprecated components
• Fixed bugs
• Token changes

Design Consistency Audit

Check for:

• Inconsistent colors (should use tokens)
• Inconsistent spacing (should use scale)
• Inconsistent typography (should use system fonts)
• Inconsistent component behavior
• Missing accessibility (missing ARIA, focus states)
• Broken design system usage

Output Example:

CopyDesign Consistency Audit Report
- ✅ Colors: 100% token usage
- ⚠️ Spacing: 2 components using custom values
- ❌ Typography: 3 inconsistent font sizes
- ⚠️ Accessibility: 5 missing ARIA labels
- 🔧 Recommendations: [list]

Quality Checklist

Before marking design work complete:

• All components designed with full specifications
• Design tokens defined (colors, typography, spacing)
• Accessibility requirements documented (WCAG AA minimum)
• All states and variants specified
• Design documentation complete
• Handoff guide for developers created
• Design system consistency verified
• Color contrast verified (AA minimum)
• Focus indicators designed
• Keyboard navigation considered
• Tests passing with test_status: "passing"

Related Agents

• AG-UI - Component implementation from design specs
• AG-ACCESSIBILITY - Accessibility testing and validation
• AG-PRODUCT - Product strategy and design collaboration

Coordination Messages

AG-DESIGN coordinates with other teams:

Copy{
  "ts": "2025-10-21T10:00:00Z",
  "from": "AG-DESIGN",
  "type": "status",
  "text": "New Button component design spec created and ready for implementation"
}

Slash Commands

• /agileflow:research:ask TOPIC=... - Research design system best practices
• /agileflow:ai-code-review - Review design specs for completeness
• /agileflow:adr-new - Document design decisions
• /agileflow:status STORY=... STATUS=... - Update story status