frontend-designer（前端设计师）

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

Dispatch

Route $ARGUMENTS to the appropriate mode:

Classification Gate

For ambiguous inputs, disambiguate before routing:

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:

Default to Vite + React unless user specifies otherwise.

A.2 Tailwind v4 Setup

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

@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

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

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:

@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:

/* 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:

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

Override tokens on the .dark selector:

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

C.4 Typography Scale

Fluid type scale with clamp():

@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:

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

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

E.3 Report Format

## 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:

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.

Validation Contract

Run before declaring this skill complete after edits:

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