# Ux Design

> Create design system with foundations, brand identity, and UX patterns. Usage /groundwork:ux-design

- **Type:** Skill
- **Install:** `agentstack add skill-etr-groundwork-ux-design`
- **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/ux-design

## Install

```sh
agentstack add skill-etr-groundwork-ux-design
```

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

## About

# Design System Skill

Establishes a complete design system through guided collaboration: foundations, brand identity, and UX patterns.

**Accessibility standard:** Design to the bar your patterns will be reviewed against. Treat `${CLAUDE_PLUGIN_ROOT}/references/checklists/accessibility.md` as the WCAG 2.1 AA standard your color choices, components, focus behavior, and patterns must meet — the same checklist `design-consistency-checker` enforces.

## 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`  "I'll go with [X] because [reason]. I can adjust later if needed."

Document and move on.

## Design Philosophy

Every design system should have a **distinctive identity**, not just be functional. The goal is a system that someone could recognize — "that's [product name]" — from its visual identity alone.

**Anti-generic principle:** Never default to the most common choices just because they're safe. If you find yourself reaching for Inter + enterprise blue + clean minimal, stop and ask why. Those choices should require justification, not be the path of least resistance.

**Tonal direction:** Every design system should commit to a recognizable aesthetic posture — not a vague descriptor like "professional" or "modern" (which describe everything and nothing), but a specific tonal direction:

- Brutally minimal, maximalist, retro-futuristic, organic warmth, quiet luxury, playful, editorial, brutalist, art deco, soft atmospheric, industrial, geometric bold

The tonal direction is derived from the product's persona, vision, and competitive context. It guides every downstream decision — color strategy, typography personality, spatial character, motion style.

**Memorability test:** After defining the identity, ask: "Would a user recognize this product from its visual identity alone?" If swapping the logo onto a competitor's site would go unnoticed, the identity isn't distinctive enough.

**Distinctiveness and accessibility are not in tension.** Bold color choices can meet WCAG AA. Characterful typography can be highly readable. Atmospheric surfaces can have clear contrast. Never trade accessibility for aesthetics — find the intersection.

## File Locations

- **Input:**
  - `{{specs_dir}}/product_specs.md` (PRD with personas, vision, NFRs)
  - `{{specs_dir}}/architecture.md` (technical constraints, API patterns)
- **Output:**
  - `{{specs_dir}}/design_system.md`
  - `{{specs_dir}}/ux-preview.html` (visual reference, regenerated when design system changes)
- **Transient:**
  - `{{specs_dir}}/design-comparison.html` (color/font comparison, deleted after identity is chosen)
  - `{{specs_dir}}/atmosphere-comparison.html` (atmosphere comparison, deleted after atmosphere is chosen)
  - `{{specs_dir}}/pattern-showcase.html` (complete system preview, deleted after Step 8 documentation)

## Step 0: Resolve Project Context

**Before anything else, resolve the project context:**

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 to item 3.
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 `` (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. **Check `{{specs_dir}}/`:** Does a specs directory exist?
   - If yes → Single-project repo, proceed normally.
   - If no → Ask the user: "Is this a single-project repo or a monorepo with multiple projects?"
     - **Single project** → Proceed normally (specs will be created at `{{specs_dir}}/`)
     - **Monorepo** → Invoke `Skill(skill="groundwork:setup-repo")` to create `.groundwork.yml`, then continue.

## Prerequisites

Check for PRD first. Look for `{{specs_dir}}/product_specs.md` (single file) or `{{specs_dir}}/product_specs/` (directory). If neither exists, prompt user to run `/groundwork:design-product` first.

When reading the PRD:
- **Single file:** Read `{{specs_dir}}/product_specs.md`
- **Directory:** Aggregate all `.md` files from `{{specs_dir}}/product_specs/` with `_index.md` first, then numerically-prefixed files, then alphabetically

Architecture file is optional but helpful for UX pattern decisions.

---

## Phase 1: Foundations

### Step 1: Context Gathering

Extract design-relevant context from PRD + a few targeted questions.

**From PRD (already available):**
- Personas -> accessibility needs, expertise level
- Product vision -> personality keywords
- NFRs -> any explicit accessibility requirements

**Targeted Questions (only what's missing):**

> "Before we define the design system, a few quick questions:
> 1. Do you have existing brand colors/fonts, or starting fresh?
> 2. Any specific accessibility requirements? (WCAG level, legal compliance)
> 3. Is this mobile-first, desktop-first, or balanced?"

Move on quickly after gathering constraints.

### Step 2: Propose Design Principles

Based on context, propose principles and explain why. One principle should address **visual identity and aesthetic commitment** — not as decoration, but as a functional design value.

Also derive a **tonal direction** from the PRD's persona and vision. Avoid vague non-directions like "professional", "modern", or "clean" — these describe nearly every product and guide no decisions. Instead, commit to a specific aesthetic posture (see the tonal direction list in Design Philosophy above).

> "Based on [specific context from PRD], I recommend these guiding principles:
>
> **DP-001: Clarity First**
> Your [persona] users need to make quick decisions - clarity beats cleverness.
>
> **DP-002: [Principle Name]**
> Because [specific reason tied to their context].
>
> **DP-003: Distinctive Identity**
> [Product] should be visually recognizable — its personality should come through in every screen, not just the marketing site. This means committing to [tonal direction] as our aesthetic posture.
>
> **Tonal Direction: [specific direction]**
> Derived from [persona characteristic] and [product vision element]. This will guide our color strategy, typography choices, spatial feel, and motion character.
>
> Does this direction feel right? I can adjust if something's off."

**Handle Feedback:**
- User agrees -> Document and proceed to Phase 2
- User pushes back -> Adjust specific principle, don't restart

### Step 3: Establish Tokens

Define foundational token categories without waiting for approval on each:

**Spacing Scale (4px base):**
- `--space-1`: 4px through `--space-16`: 64px

**Elevation Scale:**
- `--elevation-0` (flat) through `--elevation-3` (modals)

**Border Radius:**
- `--radius-none` (0) through `--radius-full` (pills)

**Token Architecture Principles:**
- **Two-layer hierarchy:** Define primitive tokens (raw values like `--blue-500`) and semantic tokens (contextual names like `--color-primary`). Only the semantic layer changes for dark mode.
- **Semantic names:** `--space-sm` communicates intent better than `--spacing-8`. Names describe purpose, not pixel values.
- **Gap over margins:** Prefer CSS `gap` for spacing between siblings — eliminates margin collapse and simplifies composition.
- **Semantic z-index scale:** Define named layers (dropdown, sticky, modal-backdrop, modal, toast, tooltip) rather than arbitrary numbers.

See `${CLAUDE_PLUGIN_ROOT}/references/design-system/spatial-design-guide.md` for full spatial system rationale (4pt grid, optical adjustments, container queries).

Present as a cohesive system. Only adjust if user has concerns.

---

## Phase 2: Brand Identity

### Step 4: Propose Identity Options

Before proposing options, confirm the **tonal direction** established in Step 2. Each option should be a genuine exploration of that direction (or a deliberate contrast if offering range), not a convergence on "clean professional minimal."

Propose 2-4 complete visual identity options, each pairing a color strategy with typography that suits its personality. Draw from the product context, personas, and design principles.

**Color System Guidance:**
- **Use OKLCH color space** for palette generation — perceptually uniform (unlike HSL where "50% lightness" varies wildly across hues). Define palettes in OKLCH, output hex/RGB for implementation.
- **Tinted neutrals:** Never use pure gray. Add a subtle brand hue to the neutral scale (chroma ~0.01 in OKLCH). Creates warmth and cohesion without visible color.
- **Never pure black or white:** `#000000` and `#ffffff` don't exist in nature. Use tinted near-black/near-white from the neutral scale.
- **60-30-10 visual weight:** Neutral surfaces 60%, secondary/structural color 30%, accent 10%. Accent works because it's rare.
- **Alpha is a design smell:** If using `rgba()` or `opacity` for color variations, the palette is incomplete. Define explicit tokens for every needed shade.

See `${CLAUDE_PLUGIN_ROOT}/references/design-system/color-and-contrast-guide.md` for dangerous color combinations, dark mode strategy, and the two-layer token approach.

**Anti-pattern warnings:**
- Do not propose options where all use the same font family
- Do not copy palettes from famous brands (see "Colors to Avoid as Primary" in color reference)
- Do not let all options converge on the same personality — if they all feel "clean and minimal," the exercise failed
- At least one option should use a characterful or unexpected font pairing

> "Based on [context] and our **[tonal direction]** direction, here are identity options to compare:
>
> **Option A: [Name] — [Personality tag]**
> **Tonal Direction:** [specific direction this option embodies]
> Colors: Primary [hex], Secondary [hex], Accent [hex]
> Color Strategy: [e.g., Dominant + Sharp Accent, Monochrome + One]
> Fonts: [Heading font] / [Body font]
> **Visual Atmosphere:** [texture/surface concept — e.g., "subtle grain texture on surfaces, sharp card shadows"]
> **Spatial Character:** [layout personality — e.g., "generous whitespace, asymmetric hero layouts"]
> Personality: [1-sentence description]
>
> **Option B: [Name] — [Personality tag]**
> **Tonal Direction:** [specific direction]
> Colors: Primary [hex], Secondary [hex], Accent [hex]
> Color Strategy: [approach]
> Fonts: [Heading font] / [Body font]
> **Visual Atmosphere:** [different texture/surface concept]
> **Spatial Character:** [different layout personality]
> Personality: [1-sentence description]
>
> **Option C: [Name] — [Personality tag]** *(if warranted)*
> ...
>
> I'll generate a visual comparison so you can see these side-by-side in your browser."

**Handle Feedback:**
- User has specific colors/fonts → Incorporate as an additional candidate
- User eliminates options → Note preferences, carry forward survivors
- User wants different direction → Propose new candidates

Aim for 2-4 candidates total (avoids decision fatigue). Include user-provided colors/fonts as a candidate if offered.

### Step 5: Generate Visual Comparison

Generate `{{specs_dir}}/design-comparison.html` — a self-contained file that renders identical UI components under each candidate identity option, side-by-side, with a decision helper table.

**Architecture — data-driven, single render function:**

1. **CSS custom properties per scheme** — each scheme defines color variables (`--bg-primary`, `--bg-secondary`, `--bg-elevated`, `--text-primary`, `--text-secondary`, `--accent`, `--accent-hover`, `--accent-fg`, `--glass`, `--glass-border`, `--success`, `--success-muted`, `--focus-ring`) AND font overrides (`--font-heading`, `--font-body`).

2. **JavaScript scheme array** — each entry contains:
   - `id`, `name`, `subtitle` (short description)
   - `bgHex`, `accentHex`, `textHex` (for contrast computation)
   - `vars` object mapping CSS custom properties to values
   - `fonts` object with `heading` and `body` font-family strings
   - `mood` array of personality tags
   - `audience`, `personality` descriptions
   - `atmosphere` — a brief description of the visual texture/surface feel (e.g., "subtle grain texture, sharp shadows")
   - `spatialCharacter` — the layout personality (e.g., "generous whitespace, centered compositions")

3. **Single `renderColumn(scheme)` function** — generates identical components per scheme:
   - Navigation bar with logo mark, nav links, avatar
   - Button row (primary, outline, ghost)
   - Glass card with heading, body text, badge
   - Form input with label and placeholder
   - Badge row (default, success, outline)
   - Progress bar with label
   - Content card with image placeholder, title, actions
   - Apply a subtle background texture or overlay per scheme (e.g., noise, gradient wash, grain) based on `scheme.atmosphere` to give each column a different *feel*, not just different colors

4. **Decision helper table** at the bottom with computed rows:
   - Base colors (swatches + hex codes)
   - Text-on-background WCAG contrast ratio (computed, with AA pass/fail badge)
   - Accent-on-background WCAG contrast ratio (computed, with AA pass/fail badge)
   - Mood tags
   - Audience fit
   - Font pairing (heading + body font names)
   - Atmosphere (visual texture/surface description)
   - Spatial character (layout personality)

5. **Self-contained** — no external dependencies except Google Fonts `` tags for candidate fonts. All CSS and JS inline.

6. **Responsive grid** — columns per scheme count (`cols-2`, `cols-3`, `cols-4`) with responsive breakpoints.

**Font loading:** Add a single `` to Google Fonts loading all candidate heading and body fonts. Apply per-scheme via `--font-heading` / `--font-body` CSS custom properties and a `.has-custom-fonts` class on each scheme column.

**WCAG contrast computation:** Include `hexToRgb()`, `srgbToLinear()`, `luminance()`, and `contrastRatio()` functions inline. Display results as `N.N:1 AA Pass` (green) or `N.N:1 AA Fail` (red).

**After generating:**

> "I've generated the visual comparison at `{{specs_dir}}/design-comparison.html`. Open it in your browser to see the identity options side-by-side."

**Handle evaluation feedback:**
- User picks a winner → Document as BRD decisions, define semantic colors and type scale, proceed to Step 6
- User wants tweaks → Regenerate with adjustments
- User likes colors from one option + fonts from another → Regenerate a mixed comparison
- User can't decide → Generate a focused 2-scheme comparison

**After identity is chosen, define the full palette and type scale:**

Semantic colors (propose based on chosen palette temperature):

| Semantic | Color | Usage |
|----------|-------|-------|
| Success | Green | Confirmations, completed states |
| Warning | Amber | Cautions, pending actions |
| Error | Red | Errors, destructive actions |
| Info | Blue | Informational messages |

Neutral palette: Define gray scale for text, backgrounds, borders based on chosen primary color temperature.

Type scale based on chosen body font:

| Token | Size | Usage |
|-------|------|-------|
| `--text-xs` | 12px | Captions, labels |
| `--text-sm` | 14px | Secondary text |
| `--text-base` | 16px | Body text |
| `--text-lg` | 18px | Lead paragraphs |
| `--text-xl` |

…

## 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-ux-design
- 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%.