# Ui Design Workflow

> >

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

## Install

```sh
agentstack add skill-frozenmoon-ui-design-workflow-ui-design-workflow
```

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

## About

# UI Design Workflow

Manage the full UI design workflow: Demo → Spec → Implement → Check → Iterate.
Supports both custom components and component libraries (shadcn/ui, Ant Design, Element Plus, etc.).

## Command Reference

| Command | Purpose | When to Use |
|---------|---------|-------------|
| `demo` | Analyze project + generate UI showcase | Early stage: establish style & component solution |
| `spec` | Generate spec document | After Demo is confirmed |
| `implement` | Build features per spec | Daily development |
| `check` | Audit spec compliance | Before PR, periodic review |
| `iterate` | Update the spec | When gaps are discovered |

---

## Command Details

### demo - Generate UI Components + Showcase Page

**Input**: User's UI style requirements (e.g., "minimal modern", "techy")

**Output**:
- **Real component files** in `src/components/ui/` (reusable across the project)
- **Two showcase pages** (separate pages, NOT tabs):
  - **Product Demo** (`/ui-showcase`) - Realistic demo of the actual product, adapts to project type (see below)
  - **Component Library** (`/ui-components`) - All components rendered in various states, independently iterable

**Flow selection** (auto-detect):
- Project has existing spec → **Flow B** (import existing components, generate demo)
- User specified a library → **Flow C** (use specified library, still confirm style)
- Project has significant existing UI (5+ components or 3+ pages) but no spec → **Flow D** (extract and document, see below)
- Otherwise → **Flow A** (from scratch)

**Flow D: Adopt Existing UI** (for projects with existing UI code but no spec):
1. **Deep scan**: Extract design tokens (colors, fonts, spacing, radius, shadows) and component inventory from existing code
2. **Present extraction results**: Show findings to user via `AskUserQuestion` for confirmation
3. **Gap analysis**: Identify missing tokens, inconsistent values, missing components
4. **User decides**: Fix gaps now or defer to `iterate`
5. **Generate spec**: `doc/ui-design-spec.md` based on extracted data (not invented)
6. **Optional showcase**: Ask if user wants a showcase page for existing components
7. **Update agent config**: Write spec reference to CLAUDE.md / AGENTS.md
- See [references/modes.md](references/modes.md) for detailed steps.

**Product Demo adapts to project type**:
- **Website / Landing Page** → Demo shows the actual website (hero, features, CTA, etc.)
- **Web App / SaaS / Dashboard** → Demo shows main app screens (dashboard, list page, detail page, etc.)
- **E-commerce** → Demo shows product listing, product detail, cart overview
- **Blog / Content site** → Demo shows article list, article detail
- **Portfolio** → Demo shows portfolio grid, project detail
- If project type is unclear from code analysis, **ask the user** what they are building

**Flow A (from scratch):**
1. **Project Analysis + Product Understanding**:
   - Read `package.json` to identify framework and existing dependencies
   - Scan code directory to identify existing patterns and tech stack
   - Determine project type (website, web app, SaaS, e-commerce, blog, etc.)
   - **⛔ If project type is unclear**: Ask the user what they are building (e.g., "Is this a website, a web app, a dashboard...? What are the main pages/features?"). This determines what the demo page will show.
   - **Scan existing components**: Find all components in the project, assess their consistency
2. **Present findings and auto-select component solution**:
   - Show existing component inventory and consistency assessment to user
   - Auto-select a component solution based on analysis (custom / shadcn/ui / Ant Design / other)
   - Auto-detect existing library dependencies and continue with them
   - If user already specified a library in the command, use it directly
   - **Do NOT ask the user to choose** — use the recommended solution by default. Advanced users will override if needed.
3. **⛔ Visual Style Preview (BLOCKING)** — Generate `style-preview.html` (standalone HTML, opens in any browser) with 3 diverse style direction previews. Each preview shows real fonts (Google Fonts), actual color palette, a mini Hero section, and atmosphere effects. User opens in browser, picks A/B/C, asks for a new batch, or describes their own direction. Then ask theme mode (light/dark/toggle). **DO NOT proceed without user's confirmed choice.** See [assets/style-preview-template.md](assets/style-preview-template.md) for the HTML template.
4. **Design Thinking** (read [references/frontend-aesthetics.md](references/frontend-aesthetics.md)):
   - Refine the user's chosen style direction into detailed design tokens
   - Define the memorable element — what makes this design unforgettable?
   - Finalize typography, color palette, atmospheric details — all coherent with the confirmed visual preview
5. **Create real component files** (the single source of truth):
   - Set up design tokens as CSS variables
   - Create each component as a real file in `src/components/ui/`
   - Components support all variants, states, transitions, and accessibility
   - Skip components that already exist in the project
6. **Create two showcase pages** (separate pages, NOT tabs):
   - **Product Demo** (`/ui-showcase`): Realistic demo adapted to the project type — website shows the website, app shows main app screens, etc. Built with real components.
   - **Component Library** (`/ui-components`): All components in every variant/state.
   - Both pages share a **navigation bar** with links to each other.
   - **Include existing project components** in Component Library page (do not modify them)
   - **Apply motion**: Orchestrate page load animations with staggered reveals
   - **Apply atmosphere**: Add background textures, gradients, or visual depth
7. **Run anti-AI-slop checklist** (see [references/frontend-aesthetics.md](references/frontend-aesthetics.md))
8. Iterate with user

**Existing component handling**:
- Preserve existing components as-is; do not modify during demo phase
- Only suggest fixes for severe issues (accessibility violations, broken layouts)
- Minor inconsistencies are noted for future `iterate` updates

**Output locations**:
- Components: `src/components/ui/*.tsx`
- Product Demo (Next.js): `app/ui-showcase/page.tsx` | (Vite): `src/pages/UIShowcase.tsx`
- Component Library (Next.js): `app/ui-components/page.tsx` | (Vite): `src/pages/UIComponents.tsx`

**Templates**: See [assets/components.md](assets/components.md) for component library structure
**Library guide**: See [assets/library-guide.md](assets/library-guide.md)

---

### spec - Generate Spec Document

**Prerequisite**: Confirmed Demo exists (component files + showcase page)

**Output**:
1. Spec document: `doc/ui-design-spec.md` (includes Component Registry)
2. Project integration: Update CLAUDE.md with spec reference

**Flow**:
1. Read component files and showcase code, extract design decisions
2. **Build Component Registry**: Scan all component files, record name → path → variants → states
3. **Record component solution**: Document the chosen solution in the spec
   - Solution type (custom / library name)
   - Library version (if applicable)
   - Theme configuration method and file path
4. Generate structured spec document (design tokens + registry, NOT code examples)
5. Update CLAUDE.md with spec reference

---

### implement - Build Features Per Spec

**Prerequisite**: Project has a UI spec with Component Registry

**Flow**:
1. **Must** read the project's UI spec document first
2. **Check Component Registry**: Find existing components that can be reused
   - If a needed component exists → read its source file, import and use it
   - If a needed component does NOT exist → create it following the spec's design tokens, then notify user to run `iterate` to register it
3. Implement the user's requested feature per spec
4. Ensure colors, spacing, and component styles comply with the spec

**Key**: Always check the Component Registry before creating any UI element. Reuse existing components — do not duplicate.

---

### check - Audit Spec Compliance

**Input**: File or directory to check

**Flow**:
1. Read the project's UI spec (including Component Registry)
2. Scan the specified code
3. Check for:
   - **Component reuse**: Are registry components being imported and used, or duplicated inline?
   - **Design tokens**: Are CSS variables used instead of hardcoded values?
   - **Spacing/radius**: Do values conform to the spec's grid system?
   - **Library compliance** (if applicable): Are library components used correctly?
4. Output violation report with component reuse rate

---

### iterate - Update the Spec

**Trigger**: New component created during `implement`, missing registry entry, design token change, or switching component solution

**Flow**:
1. Confirm with user what needs to be added/modified
2. If adding a new component: verify the file exists, add to Component Registry, add to showcase
3. If switching component solution, flag components that need migration
4. Update spec document (registry / tokens)
5. Update Demo showcase page (if needed)
6. Sync related implementation code (if needed)

---

## Design Principles (General)

> **Full details**: [assets/design-principles.md](assets/design-principles.md) — Must read before demo phase.
> **Aesthetics guide**: [references/frontend-aesthetics.md](references/frontend-aesthetics.md) — Core creative reference for all design work.

### Intentional Design (Core Principle)
- Every design must have a clear aesthetic direction and point of view
- Choose a bold tone: brutally minimal, luxury refined, editorial, organic, retro-futuristic, etc.
- Define the memorable element — the ONE thing someone will remember
- **NEVER produce generic AI aesthetics**: no Inter/Roboto fonts, no purple-on-white gradients, no cookie-cutter layouts

### Less is More (Token Principle)
- Default to the minimum viable set of design tokens
- Fewer named levels: border-radius 3, spacing 4, shadows 3, font weights 2
- Minimal tokens ≠ minimal aesthetics — a small set of well-chosen tokens creates more cohesion

### Component Solution
- **Custom components**: Hand-write all UI components, full control
- **Component library**: Use an existing library (shadcn/ui, Ant Design, Element Plus, etc.)
- Choice is made during demo stage, recorded in the spec document
- All subsequent stages automatically follow this choice

### Typography
- Choose **distinctive, characterful fonts** — never generic defaults
- Pair a display/heading font with a refined body font for contrast
- Vary font choices across different projects — never converge on the same "safe" pick
- Clear type scale hierarchy (Display → H1 → H2 → Body → Small)

### Color System
- **Dominant + accent model**: One dominant color for mood, sharp accents for focal points
- Build palettes that evoke an emotion — if you can't name the feeling, it's too generic
- **Avoid**: purple-blue gradients, teal/coral combos, unmodified Tailwind gray scales
- **System feedback**: Success, Error, Warning, Info

### Motion & Atmosphere
- Orchestrate page load with staggered reveals (highest impact)
- Add scroll-triggered reveals, surprising hover states
- Create atmospheric depth: gradient meshes, noise textures, radial highlights
- Avoid: solid white/dark backgrounds with no visual interest

### Responsive
- Mobile-first design
- Key breakpoints: sm(640px), md(768px), lg(1024px)

---

## File Structure

```
ui-design-workflow/
├── SKILL.md              # This file (overview)
├── README.md             # User documentation
├── assets/
│   ├── website.md        # Landing page reference (NOT used in demo flow — AI designs freely)
│   ├── components.md     # Component library template
│   ├── style-preview-template.md  # Visual style preview page (HTML + server)
│   ├── design-principles.md  # UI design principles (references aesthetics guide)
│   ├── spec-template.md  # Spec document template
│   └── library-guide.md  # Component library integration guide
└── references/
    ├── modes.md          # Detailed mode specifications
    └── frontend-aesthetics.md  # ⭐ Core creative aesthetics guide (anti-AI-slop)
```

---

## Quick Decision Guide

**User says "design UI"** → Use `demo` (analyze project, recommend component solution)
**User says "use shadcn/ui"** → Use `demo` (skip recommendation, use specified library)
**User says "generate spec"** → Use `spec`
**User says "implement feature"** → Use `implement` (read spec first, identify component solution)
**User says "check code"** → Use `check`
**User says "add component spec"** → Use `iterate`
**User says "switch to Ant Design"** → Use `iterate` (switch component solution)

## Source & license

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

- **Author:** [FrozenMoon](https://github.com/FrozenMoon)
- **Source:** [FrozenMoon/ui-design-workflow](https://github.com/FrozenMoon/ui-design-workflow)
- **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-frozenmoon-ui-design-workflow-ui-design-workflow
- Seller: https://agentstack.voostack.com/s/frozenmoon
- 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%.