frontend-design

name	frontend-design
description	Sets the visual direction for a new or redesigned surface, with production quality that avoids generic AI aesthetics. Use when building a new page, app, or marketing surface, defining visual identity, or doing a design pass ("make this look good"). Do not load it for routine UI edits: adding a field to an existing form, fixing spacing, wiring a button, or changing copy.
scope	dev
license	Complete terms in LICENSE.txt
source	https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
local-changes	Description narrowed and Verification rescoped deliberately; an upstream sync must not restore the broad auto-load triggers or screenshot-everything step.
metadata	{"internal":true}

Frontend Design

This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with strong product judgment, excellent accessibility, and a clear visual point of view.

The user may ask for a component, page, full app, dashboard, marketing surface, or restyle. Before coding, understand the audience and pick a direction that fits the product instead of defaulting to generic SaaS polish.

Design Thinking

Before coding, decide:

• Purpose: What workflow does this surface make easier? What is the primary action?
• Audience: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
• Tone: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
• Information hierarchy: What must be visible in the first five seconds, and what should be progressively disclosed?
• Differentiation: What makes this feel designed for this exact domain?

Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.

Minimalism And Progressive Disclosure

Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.

Progressive Disclosure Is A Design Requirement

Treat an all-at-once interface as a defect to fix during design, not as a styling preference. Before coding, inventory every piece of content and action on the surface, then assign each one to the smallest useful visibility level:

1. Immediate — the page title, current state, one primary action, and the compact context needed to choose what to do next.
2. Expanded — the details needed for the selected item or active workflow.
3. On demand — advanced settings, diagnostics, credentials, metadata, destructive actions, documentation, and rarely used tools.

Use single-select accordions or simple disclosure rows for sibling panels when the user is choosing one item at a time. Inside an expanded panel, keep another layer for independent concerns instead of dumping every form, explanation, and secondary action into the first reveal. Prefer one flat panel with alignment, dividers, and whitespace over nested cards; provider or product icons should not receive decorative borders or containers unless the container communicates state or interaction. A collapsed row should still show the item name, status, and a concise summary so the user can scan the whole surface without opening everything.

Before shipping, ask: “What can disappear until the user asks for it?” Then verify collapsed, expanded, loading, empty, error, and narrow-width states. If the first viewport contains multiple forms, repeated explanatory copy, documentation links, and controls for unrelated tasks, the surface has not passed this requirement yet.

• Start by subtracting: Before adding a visible control, banner, toolbar row, card, or explanatory block, ask what can be removed, merged, renamed, or moved into an existing affordance.
• One primary action: Each surface should have one dominant next action. Secondary actions belong in menus, popovers, command palettes, disclosure rows, or contextual hover/focus states unless they are used constantly.
• Progressively disclose rare work: Advanced options, diagnostics, metadata, settings, import/export, destructive actions, and inspection tools should stay tucked away until requested. Prefer small icon triggers with tooltips, popovers, drawers, or detail panels over permanent chrome.
• Keep chrome quiet: Avoid new always-visible bars, badges, callouts, helper text, and counters unless they prevent mistakes or are central to repeated use. Status can often be a dot, ring, muted count, or tooltip.
• Favor content over containers: Do not wrap every section in a card. Use whitespace, alignment, typography, dividers, and full-width bands before adding boxes.
• Design for repeated use: Production app UI should feel calm after the hundredth use. If a control shouts, animates, explains itself, or occupies a full row for an occasional action, hide or compress it.
• Make absence intentional: Empty states should be sparse and action-oriented. Do not fill blank space with marketing copy, decorative art, or lists of features just because the screen feels empty.
• Use familiar primitives: Icon buttons need clear tooltips. Menus, popovers, tabs, switches, and segmented controls should carry complexity instead of exposing every option at once.

Aesthetic Guidelines

• Typography: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
• Color and theme: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
• Motion: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never transition-all — list the properties that actually change (e.g. transition-[opacity,transform]). Use the shared easing tokens defined in packages/core/src/styles/agent-native.css instead of hand-typing curves: var(--ease-drawer) (260ms, drawers/app chrome), var(--ease-collapse) (200ms, expand/collapse), var(--ease-out-strong) (snappy entrances) — in Tailwind, ease-[var(--ease-collapse)]. Enter/exit with ease-out, never ease-in. Overlays that zoom in must set the Radix origin var (e.g. origin-[--radix-popover-content-transform-origin]). Animate transform/opacity, not width/height/padding/box-shadow. Gate looping or large-movement animations with motion-reduce:. Command palettes and keyboard-triggered actions get no animation.
• Composition: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
• Visual assets: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
• Responsive fit: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.

Beat convergence, not just defaults. You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.

Agent-Native UI Rules

• Agent-native apps use React and Vite. The default adapter uses Tailwind CSS, shadcn/ui, and @tabler/icons-react, but an app may register a different company design system in app/design-system.ts.
• Use the app's design-system seam for standard UI. Inspect app/design-system.ts, ToolkitProvider, and the local UI adapter directory before choosing a primitive. Use shadcn primitives when they are the active adapter; use the registered company components when they are not.
• When touching shadcn/ui components, also read shadcn-ui if it exists. That skill covers components.json, CLI docs, component composition, theming, and registry workflows.
• Check app/components/ui/ before importing a shadcn component. If a primitive is missing, add it from the app root with pnpm dlx shadcn@latest add <component>, then review the generated file.
• Pages, routes, and domain components must import controls through the app's local adapter path, usually @/components/ui/*. Never import @agent-native/toolkit/ui/* directly in app product code.
• Toolkit/Core feature presentation flows through the semantic components from @agent-native/toolkit/design-system. Their props express intent, emphasis, size, controlled values, and behavior; they do not require Tailwind, CVA, or className.
• For deeper feature customization, consume the feature-level headless controller through its product render slot. The same controller must power the default and custom views. Eject the smallest supported unit only after tokens, semantic components, controllers, and slots are insufficient.
• Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
• Never use browser dialogs (window.alert, window.confirm, window.prompt). Use AlertDialog, Dialog, or app-specific confirmation UI.
• Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
• Use useActionQuery and useActionMutation from @agent-native/core/client for action-backed UI. Standard CRUD should go through actions, not custom /api/ routes.
• Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

shadcn/ui Design Rules

• Use built-in component variants first (variant, size) before overriding classes.
• Use semantic tokens (bg-background, text-muted-foreground, border-border, bg-primary) instead of raw Tailwind colors for app chrome and reusable components.
• Use gap-* in flex/grid layouts instead of space-x-* or space-y-*.
• Use size-* when width and height are equal, and truncate instead of spelling out overflow/ellipsis/nowrap.
• Use cn() from the local utils alias for conditional classes.
• Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use sr-only only when the visible design already communicates the title.
• Put menu/list items inside their group primitives: SelectGroup, DropdownMenuGroup, CommandGroup, and equivalents.
• Use full Card composition when the content has a title, description, content, or actions. Do not dump complex cards into a single CardContent.
• Use ToggleGroup for small option sets, Switch for binary settings, Checkbox for multi-select, RadioGroup for one-of-many, and Slider/inputs for numeric values.
• For forms, prefer the app's existing shadcn form pattern. If newer Field, FieldGroup, or InputGroup primitives are installed or appropriate to add, use them instead of raw layout divs.
• Loading states use Skeleton, Progress, Spinner, or the app's existing loading primitives. Empty states should have one clear next action.

Anti-Patterns

Avoid:

• Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
• Custom reimplementations of shadcn primitives.
• Raw color overrides on shared components when semantic tokens or variants would work.
• New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
• Full-width banners, persistent helper rows, decorative cards, or explanatory chrome for status that could be a compact affordance.
• Treating progressive disclosure as optional. If a control is not part of the main daily workflow, hide it until context, hover, focus, or explicit user intent makes it relevant.
• UI cards nested inside other cards.
• Text or icons that resize or shift fixed-format UI on hover/loading.

Verification

Match verification effort to the size of the change. For one component, one form, one page, or a restyle, run the app's existing checks — formatter, pnpm typecheck, existing tests — and stop there.

Escalate to browser verification only when the user asks for it, or when the change is a multi-step user-visible flow that cannot be confirmed any other way. Never author a new Playwright/Puppeteer script, add a browser-automation dependency, or stand up an e2e harness to check work the user did not ask you to test that way; use an available browser tool, or say what you could not verify.

For substantial frontend work:

1. Run the relevant formatter/checks.
2. Start the dev server when the app needs one.
3. Verify with the available browser tooling at desktop and mobile widths.
4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
5. When registering or changing a company adapter, run @agent-native/toolkit/conformance, including mixed-overlay focus, portalContainer, and z-index stacking checks.

Related Skills

• shadcn-ui — shadcn CLI, component docs, composition rules, theming, and registries
• customizing-agent-native — Design-system registration, feature controllers, product slots, conformance, and ejection
• self-modifying-code — The agent can edit source code to apply design changes
• storing-data — All data lives in SQL; use actions for data access
• actions — useActionQuery/useActionMutation hooks for frontend data fetching