git:20260622.e142476 to git:20260624.e533827

---

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}}`.**

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)