---
name: source-ux-design-from-code
description: Synchronize design system document with codebase changes. Usage /groundwork:source-ux-design-from-code
argument-hint: "[files...]"
allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "Skill"]
disable-model-invocation: true
---

# Sync Design System Skill

Keeps `{{specs_dir}}/design_system.md` synchronized with design implementation decisions made during sessions.

## Pre-flight: Model Recommendation

**Your current effort level is `{{effort_level}}`.**

Skip this step silently if effort is `high`, `xhigh`, or `max` (the scale is `low` < `medium` < `high` < `xhigh` < `max`, so `xhigh` and `max` are already above `high`) AND you are Sonnet or Opus.
If effort is `low` or `medium` (i.e. below `high`), you MUST show the recommendation prompt — regardless of model.
If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use `AskUserQuestion`:

```json
{
  "questions": [{
    "question": "Do you want to switch? Design token and pattern change categorization benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
    "header": "Recommended: Sonnet or Opus at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}
```

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

## Step 0: Resolve Project Context

**Before loading specs, ensure project context is resolved:**

1. **Monorepo check:** Does `.groundwork.yml` exist at the repo root?
   - If yes → Is `{{project_name}}` non-empty?
     - If empty → Invoke `Skill(skill="groundwork:select-project")` to select a project, then restart this skill.
     - If set → Project is `{{project_name}}`, specs at `{{specs_dir}}/`.
   - If no → Continue (single-project repo).
2. **CWD mismatch check (monorepo only):**
   - Skip if not in monorepo mode or if the project was just selected in item 1 above.
   - If CWD is the repo root → fine, proceed.
   - Check which project's path CWD falls inside (compare against all projects in `.groundwork.yml`).
   - If CWD is inside the selected project's path → fine, proceed.
   - If CWD is inside a different project's path → warn via `AskUserQuestion`:
     > "You're working from `<cwd>` (inside **[cwd-project]**), but the selected Groundwork project is **[selected-project]** (`[selected-project-path]/`). What would you like to do?"
     > - "Switch to [cwd-project]"
     > - "Stay with [selected-project]"
     If the user switches, invoke `Skill(skill="groundwork:select-project")`.
   - If CWD doesn't match any project → proceed without warning (shared directory).
3. Proceed with the resolved project context. All `{{specs_dir}}/` paths will resolve to the correct location.

## File Locations

- **Target:** Design system document (may be single file or directory)
  - Single file: `{{specs_dir}}/design_system.md`
  - Directory: `{{specs_dir}}/design_system/` (content split across files)
- **Context:** Current session history, codebase changes

**Detection:** Check for single file first (takes precedence), then directory.

## When to Trigger

This skill should activate when:
- User explicitly invokes `/groundwork:source-ux-design-from-code`
- Session involved design token changes (colors, spacing, typography)
- Component styling decisions were made
- UX patterns were implemented or modified
- Brand identity elements were added or changed

## Workflow Overview

1. **Analyze Session** - Review design-relevant changes this session
2. **Detect Changes** - Identify design system implications
3. **Propose Updates** - Draft decisions with appropriate IDs
4. **Apply Changes** - Update document with user approval

## Step 1: Analyze Session

Review the current session for:

**Token Changes:**
- New CSS custom properties or design tokens added
- Color values defined or modified
- Spacing/sizing values established
- Typography settings changed

**Component Styling:**
- New component variants created
- Styling patterns established
- Hover/focus/active states defined
- Responsive breakpoint adjustments

**UX Pattern Implementations:**
- Loading state patterns implemented
- Error handling UI added
- Empty state designs created
- Navigation patterns established
- Form validation approaches implemented
- Animation/motion added

**Brand Identity:**
- Logo usage implemented
- Color palette applied
- Font selections made
- Voice/tone established in UI copy

## Step 2: Detect Change Categories

| Category | Signal | Design System Section |
|----------|--------|----------------------|
| Design principle | Explicit "we should always..." statement | §1.2 Design Principles |
| Accessibility | ARIA labels, contrast fixes, focus states | §1.1 Accessibility Requirements |
| Spacing token | New spacing value, padding/margin pattern | §1.3 Token Categories (Spacing) |
| Elevation token | Shadow values, z-index decisions | §1.3 Token Categories (Elevation) |
| Border radius | Corner radius decisions | §1.3 Token Categories (Border Radius) |
| Color token | New color value, palette adjustment | §2.1 Color System |
| Typography | Font family, size, weight decisions | §2.2 Typography |
| Brand voice | UI copy patterns, tone decisions | §2.4 Brand Voice |
| Visual atmosphere | Surface treatments, textures, spatial character, tonal direction | §2.5 Visual Atmosphere |
| Navigation | Nav structure, menu patterns | §3.1 Navigation |
| Loading states | Skeleton, spinner, progress patterns | §3.2 Loading States |
| Error handling | Error display, validation feedback | §3.3 Error Handling |
| Empty states | No-data, first-run experiences | §3.4 Empty States |
| Form patterns | Input validation, form layout | §3.5 Form Patterns |
| Responsive | Breakpoint decisions, mobile adaptations | §3.6 Responsive Behavior |
| Motion | Animation timing, transitions, entrance patterns, hover signatures | §3.7 Motion & Interaction Character |
| Component | New component styling guidelines | §4 Component Guidelines |

## Step 3: Propose Updates

For each detected change, propose a specific update:

```markdown
## Proposed Design System Updates

### 1. New Design Principle

**Trigger:** You established that all interactive elements should have visible focus states.

**Proposed addition to §1.2 Design Principles:**

### DP-00X: Accessible Focus States

**Status:** Accepted
**Date:** [today]
**Context:** Implementing keyboard navigation revealed need for consistent focus indicators.

**Decision:** All interactive elements must have visible focus states with 3:1 contrast ratio.

**Rationale:** Supports keyboard-only users and WCAG 2.1 AA compliance.

---

### 2. New Color Token

**Trigger:** You added a new warning color for form validation.

**Proposed addition to §2.1 Color System:**

| Token | Value | Usage |
|-------|-------|-------|
| `--color-warning-light` | #FEF3C7 | Warning background |

**Proposed addition to §5 Decision Log (Brand Decisions):**

### BRD-00X: Warning Color Variant

**Status:** Accepted
**Date:** [today]
**Context:** Form validation needed softer warning background.

**Decision:** Added `--color-warning-light` (#FEF3C7) for warning backgrounds.

**Rationale:** Maintains warning semantic while providing softer background option.

---

### 3. UX Pattern Implementation

**Trigger:** You implemented skeleton loading screens for data tables.

**Proposed addition to §3.2 Loading States:**

**Data Tables:** Use skeleton rows matching table structure. Show 5 skeleton rows by default. Animate with subtle pulse.

**Proposed addition to §5 Decision Log (UX Decisions):**

### UXD-00X: Table Loading Pattern

**Status:** Accepted
**Date:** [today]
**Context:** Data tables needed loading feedback during API calls.

**Decision:** Use skeleton rows (5 default) with pulse animation for table loading states.

**Rationale:** Maintains layout stability and sets user expectations for content shape.

---

Approve these updates? (yes/no/modify)
```

## Step 4: Apply Changes

On approval:

1. **Detect spec format** - Check if design system is single file or directory
2. **Read current content:**
   - Single file: Read `{{specs_dir}}/design_system.md`
   - Directory: Aggregate all `.md` files from `{{specs_dir}}/design_system/`
3. **Route updates to appropriate files:**
   - **Single file mode:** Edit `{{specs_dir}}/design_system.md` directly
   - **Directory mode:** Route each update:
     - Design principles (DP-NNN) → `{{specs_dir}}/design_system/01-foundations.md`
     - Accessibility → `{{specs_dir}}/design_system/01-foundations.md`
     - Token changes → `{{specs_dir}}/design_system/01-foundations.md`
     - Color system (BRD-NNN) → `{{specs_dir}}/design_system/02-brand-identity.md`
     - Typography → `{{specs_dir}}/design_system/02-brand-identity.md`
     - Brand voice → `{{specs_dir}}/design_system/02-brand-identity.md`
     - UX patterns (UXD-NNN) → `{{specs_dir}}/design_system/03-ux-patterns.md`
     - Component guidelines → `{{specs_dir}}/design_system/04-components.md`
     - Decision log entries → `{{specs_dir}}/design_system/05-decisions.md`
4. Maintain decision ID sequences (find highest DP/BRD/UXD-NNN, increment)
5. Update "Last updated" timestamp
6. If `{{specs_dir}}/ux-preview.html` exists, regenerate it to reflect the updated design system decisions
7. Update "Status" if appropriate

**Important:**
- New decisions get the next available ID in their prefix sequence
- Never reuse deleted decision IDs (maintain traceability)
- Preserve existing content - add to sections, don't replace unless correcting errors

## Change Detection Heuristics

**Strong signals (likely design system change):**
- New CSS custom properties or variables defined
- Explicit design decisions ("let's use X for all buttons")
- Accessibility fixes (contrast, ARIA, focus states)
- New component variants with distinct styling
- Animation/transition values established
- Breakpoint or responsive behavior decisions

**Weak signals (maybe design system change):**
- One-off styling for specific component
- Temporary styling during development
- Framework default overrides
- Bug fixes to existing styles

Focus on strong signals. For weak signals, ask: "Is this a pattern we want to establish, or a one-time implementation detail?"

## Session Summary Format

At session end, provide summary:

```markdown
## Design System Sync Summary

**Session Date:** [date]

### Changes Detected:
1. [Change 1] → New principle DP-00X
2. [Change 2] → New color token BRD-00X
3. [Change 3] → UX pattern UXD-00X
4. [Change 4] → No design system impact (implementation detail)

### Design System Document:
- [X] Updated with approved changes
- [ ] No changes needed
- [ ] Changes pending user review

### Decision IDs Added/Modified:
- DP-00X (new)
- BRD-00X (new)
- UXD-00X (new)

### Open Items:
- [Any unresolved design questions from session]
```

---

## Interaction with Other Skills

This skill works in concert with:
- `/groundwork:ux-design` - For deliberate, interactive design system creation
- `/groundwork:source-product-specs-from-code` - PRD changes may affect design requirements
- `/groundwork:source-architecture-from-code` - Architecture changes may affect UX patterns

When multiple sync commands run:
1. Run `/groundwork:source-product-specs-from-code` first (product drives design)
2. Run `/groundwork:source-ux-design-from-code` second (design supports product)
3. Run `/groundwork:source-architecture-from-code` last (architecture implements both)