version: "1.0.0" 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:

{
  "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).

1. 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).

1. 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

Step 3: Propose Updates

For each detected change, propose a specific update:

## 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/

1. 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

1. Maintain decision ID sequences (find highest DP/BRD/UXD-NNN, increment)
2. Update "Last updated" timestamp
3. If {{specs_dir}}/ux-preview.html exists, regenerate it to reflect the updated design system decisions
4. 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:

## 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)