Skills

frontend-designer

Installation
SKILL.md

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:

@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

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:

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

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

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

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
Related skills

More from wyattowalsh/agents

Installs
43
Repository
wyattowalsh/agents
GitHub Stars
3
First Seen
Feb 23, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn