frontend-designer

Build and audit React, Tailwind, shadcn/ui interfaces. Scaffold, create components/pages, theme, refactor, verify rendered UI. Use when building UI. NOT for backend, tests, state, routing, or DevOps.

frontend-designer 2870 words MIT v1.0.0 wyattowalsh opus Custom

Build and audit React, Tailwind, shadcn/ui interfaces. Scaffold, create components/pages, theme, refactor, verify rendered UI. Use when building UI. NOT for backend, tests, state, routing, or DevOps.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill frontend-designer -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent opencode

Use: /frontend-designer <mode> [target]

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

What It Does

Build production-grade frontend interfaces with modern React, TailwindCSS v4, and shadcn/ui. Six modes from project scaffolding to rendered UI audit.

Modes

`$ARGUMENTS` pattern	Mode	Start at
`scaffold <name>` / `init <name>`	Scaffold	Mode A
`component <name>` / `create <name>`	Component	Mode B
`page <name>` / `view <name>` / `screen <name>`	Page/View	Mode F
`theme` / `theme <path>` / `tokens` / `tokens <path>`	Theme	Mode C
`refactor <path>` / `style <path>`	Refactor	Mode D
`audit` / `audit <path>`	Audit	Mode E
Natural language UI description (“build a sidebar”, “design a card”)	Auto: Component	Mode B
Natural language page/view description (“build a landing page”, “design a dashboard”)	Auto: Page/View	Mode F
Path to existing `.tsx`/`.jsx`/`.css` file or directory	Auto: Refactor	Mode D
Error message / “not working” / “broken”	Auto: Audit	Mode E
”backend” / “API” / “database” / “DevOps” / testing / state / routing / build tooling	Refuse	Redirect to relevant skill
Empty	Gallery	Show modes with example invocations

Critical Rules

Never use tailwind.config.js in Tailwind v4 — CSS-first with @import "tailwindcss" and @theme {} exclusively
Framework-aware component model — In Next.js/Remix: minimize "use client", Server Components are default. In Vite+React: "use client" is unnecessary, all components are client
Use Radix primitives via shadcn/ui for interactive components — never build custom dialogs, popovers, dropdowns, or tooltips from scratch
Design tokens in CSS custom properties via @theme {} — never hardcode colors, spacing, or font values
Container queries for component responsiveness — media queries for page layout and user preferences (prefers-color-scheme, prefers-reduced-motion, hover, pointer)
@supports guards for progressive enhancement — mandatory for contrast-color(), anchor positioning, scroll-driven animations, @scope
Logical properties for RTL readiness — margin-inline-start not margin-left, padding-block not padding-top
Never default to Inter/Roboto/Arial/system-ui — select distinctive fonts; Monaspace for code contexts
Accessibility non-negotiable — keyboard nav, ARIA, focus management, WCAG AA contrast (4.5:1 text, 3:1 large text)
Consult live docs only when needed — references are stable; fetch Context7/WebSearch only for unexpected behavior or uncovered features
Body stays under 500 lines — deep technical details go to reference files
Audit mode is read-only — never modify code in audit mode
Rendered UI must be proven — do not declare frontend work complete without the Visual Acceptance Gate or an explicit blocker

General
Claude Code

Field	Value
Name	`frontend-designer`
License	MIT
Version	1.0.0
Author	wyattowalsh

Field	Value
Model	`opus`
Argument Hint	`[mode] [target]`

View Full SKILL.md

---
name: frontend-designer
description: >-
  Build and audit React, Tailwind, shadcn/ui interfaces. Scaffold, create
  components/pages, theme, refactor, verify rendered UI. Use when building UI.
  NOT for backend, tests, state, routing, or DevOps.
argument-hint: "<mode> [target]"
model: opus
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# Frontend Designer

Build production-grade frontend interfaces with modern React, TailwindCSS v4, and shadcn/ui. Six modes from project scaffolding to rendered UI audit.

**Input:** `$ARGUMENTS` — mode keyword + target, natural language UI description, or file path.

---

## Canonical Vocabulary

| Term | Meaning | NOT |
|------|---------|-----|
| **server component** | React component rendered on the server; default in Next.js/Remix App Router | "SSR component" |
| **client component** | React component with `"use client"` directive; runs in the browser | "CSR component" |
| **design token** | CSS custom property holding a design decision (color, spacing, font) | "CSS variable" (too generic) |
| **theme** | Complete set of design tokens configured in `@theme {}` | "skin", "palette" |
| **component** | Reusable UI building block (React component + styles) | "widget", "module" |
| **primitive** | Radix UI base component providing behavior without styling | "base component" |
| **registry** | shadcn/ui component distribution endpoint (local or remote) | "package", "library" |
| **container query** | CSS `@container` rule for component-scoped responsive design | "media query" (page-scoped) |
| **action** | React 19 Server Action: async function executed server-side via form | "API call", "handler" |
| **scaffold** | Create a new project with full stack configuration | "bootstrap", "setup" |
| **refactor** | Modernize existing frontend code to current best practices | "rewrite" |
| **audit** | Read-only analysis of frontend codebase quality and patterns | "review", "scan" |
| **utility class** | Tailwind CSS class mapping to a single CSS declaration | "helper class" |
| **logical property** | CSS property using start/end instead of left/right for RTL | "directional property" |
| **texture healing** | Monaspace technique for adjusting glyph spacing in monospace | — |

---

## Dispatch

Route `$ARGUMENTS` to the appropriate mode:

| `$ARGUMENTS` pattern | Mode | Start at |
|----------------------|------|----------|
| `scaffold <name>` / `init <name>` | **Scaffold** | Mode A |
| `component <name>` / `create <name>` | **Component** | Mode B |
| `page <name>` / `view <name>` / `screen <name>` | **Page/View** | Mode F |
| `theme` / `theme <path>` / `tokens` / `tokens <path>` | **Theme** | Mode C |
| `refactor <path>` / `style <path>` | **Refactor** | Mode D |
| `audit` / `audit <path>` | **Audit** | Mode E |
| Natural language UI description ("build a sidebar", "design a card") | Auto: **Component** | Mode B |
| Natural language page/view description ("build a landing page", "design a dashboard") | Auto: **Page/View** | Mode F |
| Path to existing `.tsx`/`.jsx`/`.css` file or directory | Auto: **Refactor** | Mode D |
| Error message / "not working" / "broken" | Auto: **Audit** | Mode E |
| "backend" / "API" / "database" / "DevOps" / testing / state / routing / build tooling | **Refuse** | Redirect to relevant skill |
| Empty | **Gallery** | Show modes with example invocations |

### Classification Gate

For ambiguous inputs, disambiguate before routing:

| Signal | Route to |
|--------|----------|
| Error, broken, bug, crash, "doesn't work" | Audit |
| Test runner, state library, router, bundler, package manager, CI | Refuse or redirect |
| Upgrade, modernize, migrate, update, convert | Refactor |
| Colors, dark mode, tokens, palette, branding | Theme |
| Landing page, dashboard, settings, checkout, profile, app shell, route, screen | Page/View |
| Build, create, design, add, new + component noun | Component |
| Setup, init, start, new project | Scaffold |
| Mixed signals | Ask user which mode |

---

## Live Documentation (Optional)

Consult live docs **only when**: user reports unexpected behavior, a reference notes a pre-release API, or user asks about features not covered in bundled references.

1. **Context7** — `resolve-library-id` for "tailwindcss", "shadcn-ui", or "react", then `query-docs`.
2. **WebSearch** — `site:tailwindcss.com`, `site:ui.shadcn.com`, or `site:react.dev` for specific topics.
3. If live docs contradict bundled references, **live docs win**.

---

## Mode A: Scaffold

**Goal:** Create a new project with the full modern frontend stack.

**Load:** `references/tailwind-v4.md`, `references/vite-config.md`, `references/shadcn-patterns.md`, `references/typography.md`, `references/aesthetic-guide.md`

### A.1 Framework Selection

Ask or detect:

| Framework | When |
|-----------|------|
| **Vite + React** | SPA, no SSR needed, fastest setup |
| **Next.js App Router** | SSR/SSG, Server Components, production web apps |
| **Remix** | Full-stack, nested routing, progressive enhancement |

Default to **Vite + React** unless user specifies otherwise.

### A.2 Tailwind v4 Setup

CSS-first configuration — no `tailwind.config.js`:

```css
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 260);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  --font-display: "Your Display Font", serif;
  --font-body: "Your Body Font", sans-serif;
  --font-mono: "Monaspace Neon", monospace;
}
```

### A.3 shadcn/ui Init

```bash
npx shadcn@latest init
```

Configure `components.json` for project structure. Install core components: `button`, `input`, `card`, `dialog`, `dropdown-menu`, `toast`.

### A.4 Typography

- **Code/mono:** Monaspace Neon (or Argon, Krypton, Radon, Xenon per aesthetic)
- **Display:** Distinctive, characterful — never Inter, Roboto, Arial, system-ui
- **Body:** Clean, readable — pair with display font for contrast
- Load `references/typography.md` for @font-face setup and fluid type scale.

### A.5 Aesthetic Direction

Run the domain-fit gate and design thinking exercise (see Aesthetic Direction section below). Commit to an appropriate direction before writing UI code.

### A.6 File Structure

```
src/
  components/ui/     # shadcn/ui components (managed by CLI)
  components/        # Custom project components
  lib/               # Utilities, helpers
  hooks/             # Custom React hooks
  styles/            # Global CSS, @theme, @font-face
  app/ or pages/     # Routes (framework-dependent)
```

### A.7 Completion

Run the Visual Acceptance Gate before declaring scaffolded UI complete.

---

## Mode B: Component

**Goal:** Design and build a single component with production quality.

**Load:** `references/react-19.md`, `references/shadcn-patterns.md`, `references/modern-css.md`
**Conditional:** Load `references/aesthetic-guide.md` for visual/landing/hero/marketing components. Skip for utility components, forms, data tables.

### B.1 Classify Component

| Context | Default | "use client" needed? |
|---------|---------|---------------------|
| **Next.js / Remix App Router** | Server Component | Only if using hooks, event handlers, or browser APIs |
| **Vite + React** | Client Component | No — `"use client"` is unnecessary, all components are client |

For compound components (e.g., `<Tabs>`, `<Accordion>`): separate server wrapper from client interactive parts.

### B.2 Design Intent

Gather before building:
- **Purpose:** What problem does this solve? Who uses it?
- **Interactions:** Click, hover, drag, keyboard, touch?
- **Responsive behavior:** How does it adapt across container sizes?
- **Accessibility:** Required ARIA roles, keyboard patterns?

### B.3 Primitive Selection

Check if shadcn/ui provides the component or a close base. If interactive (dialog, dropdown, popover, tooltip, tabs, accordion, toggle), **use Radix UI primitives via shadcn/ui** — never build from scratch.

Load `references/shadcn-patterns.md` for CLI commands and customization patterns.

### B.4 Implement

- Style with Tailwind v4 utility classes + CSS custom properties from `@theme {}`
- Responsiveness: use `@container` queries for component-level adaptation, not media queries
- Modern CSS: `:has()` for parent-based styling, view transitions for state changes
- Keep component files focused — extract hooks and utilities to separate files

### B.5 Accessibility

Non-negotiable for every interactive component:
- Keyboard navigation (Tab, Enter, Escape, Arrow keys as appropriate)
- ARIA attributes (roles, labels, descriptions, live regions)
- Focus management (trap in modals, restore on close)
- Color contrast: WCAG AA minimum (4.5:1 text, 3:1 large text/UI)

### B.6 Completion

Run the Visual Acceptance Gate for any rendered component or component demo.

---

## Mode C: Theme

**Goal:** Configure or reconfigure the project's design token system.

**Load:** `references/tailwind-v4.md`, `references/modern-css.md`, `references/typography.md`

### C.1 Sub-dispatch

If `$ARGUMENTS` contains `tokens`: run token extraction workflow:
1. Grep for hardcoded color values (hex, rgb, hsl) across `.tsx`, `.jsx`, `.css` files
2. Grep for hardcoded spacing/font values not using Tailwind utilities
3. Organize into three layers: **primitive** (raw values) → **semantic** (purpose-named) → **component** (scoped overrides)
4. Generate `@theme {}` block with organized custom properties

### C.2 Color System

Use `oklch` for perceptually uniform color manipulation:

```css
@theme {
  --color-primary: oklch(0.6 0.2 260);
  --color-primary-light: color-mix(in oklch, var(--color-primary) 70%, white);
  --color-primary-dark: color-mix(in oklch, var(--color-primary) 70%, black);
}
```

**contrast-color() is experimental** — Firefox 146+ and Safari TP only. Use manual fallbacks:

```css
/* Fallback for contrast-color() */
--color-on-primary: oklch(1 0 0); /* manually chosen for contrast */
```

### C.3 Dark Mode

CSS custom properties strategy with Tailwind v4:

```css
@custom-variant dark (&:where(.dark, .dark *));
```

Override tokens on the `.dark` selector:

```css
.dark {
  --color-surface: oklch(0.15 0 0);
  --color-text: oklch(0.95 0 0);
}
```

### C.4 Typography Scale

Fluid type scale with `clamp()`:

```css
@theme {
  --text-base: clamp(1rem, 0.5vw + 0.875rem, 1.125rem);
  --text-lg: clamp(1.125rem, 0.75vw + 1rem, 1.25rem);
  --text-xl: clamp(1.25rem, 1vw + 1.125rem, 1.5rem);
}
```

### C.5 RTL Preparation

Audit and convert directional properties to logical equivalents:

| Physical | Logical |
|----------|---------|
| `margin-left` | `margin-inline-start` |
| `padding-right` | `padding-inline-end` |
| `text-align: left` | `text-align: start` |
| `float: right` | `float: inline-end` |

---

## Mode D: Refactor

**Goal:** Modernize existing frontend code to current best practices.

**Load:** `references/tailwind-v4.md`, `references/react-19.md`, `references/modern-css.md`, `references/anti-patterns.md`

### D.1 Pre-scan Checklist

Before any changes, scan the project:

- [ ] Glob for `tailwind.config.js` or `tailwind.config.ts` — v3 legacy config?
- [ ] Grep for `"use client"` count across `.tsx`/`.jsx` files
- [ ] Grep for `@media` vs `@container` ratio — component responsiveness pattern?
- [ ] Grep for hardcoded hex/rgb/hsl color values outside CSS custom properties
- [ ] Grep for `font-family` declarations — are distinctive fonts used or defaults?
- [ ] Check `package.json` for React version, Tailwind version, Vite version

### D.2 Migration Patterns

| From | To | Reference |
|------|----|-----------|
| `tailwind.config.js` | CSS-first `@import "tailwindcss"` + `@theme {}` | `references/tailwind-v4.md` |
| `@media` for component sizing | `@container` queries | `references/modern-css.md` |
| Manual dropdowns/modals | Radix primitives via shadcn/ui | `references/shadcn-patterns.md` |
| Hardcoded colors | Design tokens in `@theme {}` | Mode C |
| Class components | Function components + hooks | `references/react-19.md` |
| Excessive `"use client"` | Server Components where possible (Next.js/Remix only) | `references/react-19.md` |

### D.3 Workflow

1. Present file-by-file migration plan → **user approval gate**
2. Execute changes, one file at a time
3. Verify after each file: project checks pass and the Visual Acceptance Gate shows no regressions
4. Re-run pre-scan checklist to confirm improvement

---

## Mode E: Audit

**Goal:** Read-only analysis of frontend codebase quality. **Never modify code.**

**Load:** `references/anti-patterns.md`

### E.1 Pre-scan

Run the same checklist as Mode D (§D.1).

### E.2 Score Dimensions

| Dimension | What to check |
|-----------|---------------|
| Stack currency | Tailwind v4 CSS-first? React 19? Latest shadcn/ui? |
| Component patterns | Server vs client split? Radix primitives? Compound components? |
| Design tokens | @theme usage? Hardcoded values? Token layers? |
| CSS modernness | Container queries? :has()? Logical properties? @supports guards? |
| Typography | Distinctive fonts? Monaspace for code? Fluid type scale? |
| Accessibility | ARIA attributes? Keyboard nav? Focus management? Contrast ratios? |
| Visual proof | Screenshots/browser inspection? Mobile/desktop states? Overflow, overlap, focus, reduced motion? |

### E.3 Report Format

```markdown
## Frontend Audit Report

### Critical (must fix)
- [finding with evidence]

### Warning (should fix)
- [finding with evidence]

### Suggestion (nice to have)
- [finding with evidence]

### Strengths
- [well-implemented patterns]

### Recommended Actions
- [action] → use `/frontend-designer refactor <path>`
- [action] → use `/frontend-designer theme`
```

---

## Mode F: Page/View

**Goal:** Design and build a full page, route, screen, dashboard, landing page, or app shell.

**Load:** `references/react-19.md`, `references/shadcn-patterns.md`, `references/modern-css.md`, `references/typography.md`
**Conditional:** Load `references/aesthetic-guide.md` for marketing, hero, editorial, portfolio, game, or brand-heavy pages.

### F.1 Classify Page Context

Gather before building:
- **Domain:** SaaS/admin/ops/docs/finance vs marketing/portfolio/editorial/game/product showcase
- **User job:** Primary action, repeated workflow, scan/comparison need, decision point
- **Composition:** Layout shell, route slots, navigation, responsive breakpoints, loading/empty/error states
- **Integration:** Framework routing convention, Server/Client boundary, data placeholders, component reuse

### F.2 Design and Implement

1. Run the Aesthetic Direction domain-fit gate.
2. Compose from shadcn/ui primitives and existing project components before custom UI.
3. Keep page-level layout responsive with media queries and component internals responsive with container queries.
4. Include meaningful loading, empty, and error states when the page represents data.
5. Run the Visual Acceptance Gate before declaring complete.

---

## Visual Acceptance Gate

Run for Scaffold, Component, Page/View, and Refactor outputs whenever a rendered surface exists.

1. Start or use the project dev server when feasible; otherwise state why live rendering was not possible.
2. Inspect at one mobile width and one desktop width.
3. Capture or describe visual evidence for the changed surface.
4. Verify no incoherent overlap, clipped text, horizontal overflow, layout jump, or unreadable state.
5. Check keyboard focus order, visible focus indicators, Escape/arrow behavior where relevant, and reduced-motion behavior for animation.
6. Check WCAG AA contrast: 4.5:1 for normal text, 3:1 for large text and UI indicators.
7. Run the project’s relevant smoke/build command when available.

---

## Aesthetic Direction

Before building visual components or pages, choose the direction that fits the domain and audience:

| Domain | Default direction |
|--------|-------------------|
| SaaS, CRM, admin, finance, ops, docs | Restrained, dense, scannable, predictable |
| Marketing, portfolio, editorial, brand, product showcase | Expressive, asset-led, memorable |
| Games, toys, experiments, art tools | Playful, immersive, highly interactive |

**Design Thinking:**
1. **Purpose** — What problem does this interface solve? Who uses it?
2. **Tone** — Pick a tone appropriate to the domain; use extreme aesthetics only when the product context supports them
3. **Constraints** — Framework, performance budget, accessibility requirements
4. **Differentiation** — What makes this unforgettable? The one thing someone remembers?

**Anti-Slop Rules:**
- NEVER default to Inter, Roboto, Arial, or system fonts
- NEVER use purple gradients on white backgrounds
- NEVER produce cookie-cutter layouts that could come from any AI
- NEVER converge on the same aesthetic across generations — vary themes, fonts, palettes
- Match implementation complexity to vision: maximalism needs elaborate code; minimalism needs precision

Full aesthetic catalog, color theory, motion design, spatial composition: load `references/aesthetic-guide.md`.

---

## Scope Boundaries

**Supersedes:** The `frontend-design` skill. All aesthetic guidance is now here.

**NOT for:**
- Backend APIs, database design, DevOps configuration
- Testing frameworks (Jest, Vitest) — use standard testing patterns
- State management libraries (Zustand, Redux, Jotai) — choose per project needs
- Routing (React Router, TanStack Router) — framework-specific docs
- Full SSR framework setup (Next.js, Remix config beyond React 19 patterns)
- Build tooling, package management — defer to `javascript-conventions`

---

## Reference File Index

Load on demand during the relevant mode. Do NOT load all at once.

| File | Content | Load during |
|------|---------|-------------|
| `references/tailwind-v4.md` | CSS-first config, @theme, @import, Oxide engine, dark mode, container queries, v3→v4 migration | Scaffold, Theme, Refactor |
| `references/shadcn-patterns.md` | CLI commands, components.json, RTL, registries, Radix primitives, compound components, forms | Scaffold, Component |
| `references/react-19.md` | Server vs Client decision tree (framework-dependent), Actions, useActionState, use(), Suspense | Component, Refactor |
| `references/modern-css.md` | Container queries, :has(), @scope, view transitions, scroll-driven animations, anchor positioning, color-mix(), @layer | Component, Theme, Refactor |
| `references/typography.md` | Monaspace superfamily, variable fonts, @font-face, font pairing, fluid type scale with clamp() | Scaffold, Theme, Component (visual) |
| `references/aesthetic-guide.md` | Design thinking, aesthetic catalog, color theory, motion, spatial composition, anti-slop rules | Component (visual/landing/hero), Scaffold |
| `references/vite-config.md` | Current Vite setup, plugins, CSS handling, asset optimization, env variable security | Scaffold |
| `references/anti-patterns.md` | Detection criteria and fixes for common frontend anti-patterns | Audit, Refactor |

---

## Validation Contract

Run before declaring this skill complete after edits:

```bash
uv run wagents validate
uv run wagents eval validate
uv run python path/to/audit.py skills/frontend-designer/ --format json
uv run wagents package frontend-designer --dry-run
uv run pytest -q tests/test_frontend_designer_scan.py
uv run wagents readme --check
```

Completion criteria: all commands pass with zero errors, audit score is A (90+), and docs-steward has handled generated docs if skill docs changed.

---

## Critical Rules

1. **Never use `tailwind.config.js` in Tailwind v4** — CSS-first with `@import "tailwindcss"` and `@theme {}` exclusively
2. **Framework-aware component model** — In Next.js/Remix: minimize `"use client"`, Server Components are default. In Vite+React: `"use client"` is unnecessary, all components are client
3. **Use Radix primitives via shadcn/ui** for interactive components — never build custom dialogs, popovers, dropdowns, or tooltips from scratch
4. **Design tokens in CSS custom properties** via `@theme {}` — never hardcode colors, spacing, or font values
5. **Container queries for component responsiveness** — media queries for page layout and user preferences (`prefers-color-scheme`, `prefers-reduced-motion`, `hover`, `pointer`)
6. **`@supports` guards for progressive enhancement** — mandatory for `contrast-color()`, anchor positioning, scroll-driven animations, `@scope`
7. **Logical properties for RTL readiness** — `margin-inline-start` not `margin-left`, `padding-block` not `padding-top`
8. **Never default to Inter/Roboto/Arial/system-ui** — select distinctive fonts; Monaspace for code contexts
9. **Accessibility non-negotiable** — keyboard nav, ARIA, focus management, WCAG AA contrast (4.5:1 text, 3:1 large text)
10. **Consult live docs only when needed** — references are stable; fetch Context7/WebSearch only for unexpected behavior or uncovered features
11. **Body stays under 500 lines** — deep technical details go to reference files
12. **Audit mode is read-only** — never modify code in audit mode
13. **Rendered UI must be proven** — do not declare frontend work complete without the Visual Acceptance Gate or an explicit blocker

Download from GitHub

Resources

All Skills Browse the full skill catalog.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

View source on GitHub

frontend-designer

Quick Start

What It Does

Modes

Critical Rules

Resources

Graph View

Skills

Agents

MCP Servers