# Source Ux Design From Code

> Synchronize design system document with codebase changes. Usage /groundwork:source-ux-design-from-code

- **Type:** Skill
- **Install:** `agentstack add skill-etr-groundwork-source-ux-design-from-code`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [etr](https://agentstack.voostack.com/s/etr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [etr](https://github.com/etr)
- **Source:** https://github.com/etr/groundwork/tree/main/skills/source-ux-design-from-code

## Install

```sh
agentstack add skill-etr-groundwork-source-ux-design-from-code
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`  "You're working from `` (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)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/groundwork](https://github.com/etr/groundwork)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-etr-groundwork-source-ux-design-from-code
- Seller: https://agentstack.voostack.com/s/etr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.