Frontend Craft

Use this for frontend and product-experience work across web apps, SaaS interfaces, dashboards, marketing surfaces, and AI-assisted UI.

Project Fit Check

Before designing or changing UI:

1. Scan the existing product surface, routes, components, tokens, styles, localization files, tests, and design docs.
2. Detect the framework and styling system before importing libraries or inventing primitives.
3. Follow local component, icon, copy, accessibility, motion, and responsive conventions. Improve them only when the task requires it.
4. If design-system docs are missing, infer patterns from the existing UI and state the inference when it affects the result.
5. If the repo has its own UX review checklist, merge it with this skill instead of replacing it.

Core Stance

• Design flows before screens.
• Build the actual usable experience, not a decorative landing shell.
• Solve the happy path and the state path: loading, empty, error, success, and recovery.
• Use visual taste in service of clarity, trust, speed, and action.
• Mobile is not a small desktop. Touch, reach, network, battery, and distraction matter.
• UI copy is product behavior. Buttons, errors, empty states, and confirmations must help the user proceed or recover.
• State each page's one purpose in one sentence. If the object of that purpose is not in the first screenful, the layout is wrong; everything else steps back.
• Every action ends on a surface that shows its result and the next step worth taking. No blank page, no silent return, no dead end.
• No control needs instructions to be found or operated. If it does, fix the label, placement, or affordance. Domain consequences may still be explained next to the action, never the control itself.

Read First

1. Repo agent instructions (AGENTS.md, CLAUDE.md, etc.)
2. Domain glossary (CONTEXT.md) and current product/design docs
3. Existing components, tokens, message catalogs, routes, and tests
4. Package manifest before importing any dependency
5. Accessibility, i18n, and design-system conventions already present

Pair with coding-discipline for implementation and completion-gate before claiming done when those Skills are available. This Skill remains usable on its own.

Thin UI, full product behavior

• Keep domain policy, authorization decisions, durable workflow state, and persistence semantics out of UI components and framework glue.
• Keep presentation, input handling, accessibility, immediate feedback, latency masking, and genuinely local interaction state in the UI.
• Consume task-shaped read models and send intent-shaped mutations or commands when they make the user's job and the system contract clearer than generic CRUD forms over persistence records.
• Build and test vertical behavior through the real public boundary. Do not split ownership into frontend and backend handoffs when one end-to-end slice gives faster evidence.
• Choose rendering, state, caching, and component patterns for this product and its measured constraints. Framework patterns are tools, not the design.
• Challenge the surface with slow networks, large or awkward data, repeated actions, multiple clients or tabs, partial failure, and narrow or low-power devices where those conditions are plausible.

Experience Contract

Every flow needs:

1. Entry point
2. User intent and known context
3. Primary action
4. Immediate feedback
5. Outcome
6. Natural next step or exit

Use:

• hub-and-spoke for dashboards and detail views
• linear flow for onboarding, forms, checkout, and setup
• tabs only for 3 to 5 stable top-level areas
• progressive disclosure when complexity would otherwise overload the screen

Visual Direction

Default SaaS/product surfaces should be calm, utilitarian, and high craft:

• crisp hierarchy
• restrained color
• semantic tokens
• strong contrast
• stable layout dimensions
• clear affordances
• no decoration without function

Avoid:

• generic centered hero sections when a real product surface is needed
• generic purple or blue gradients used only to signal "AI"
• nested cards
• three equal feature cards as the default layout
• stock-like visuals that hide the actual product
• text that describes how to use obvious UI controls

Frontend Defaults

• Prefer existing framework patterns and primitives.
• Use server-rendered/static components by default; isolate client components or islands only where interactivity requires them.
• Check package.json before importing libraries.
• Use CSS variables or design tokens for colors, spacing, radius, and motion.
• Hold every text-on-surface pair to WCAG AAA (7:1, or 4.5:1 for large text) in light and dark, and enforce it with an automated test, not review: list every text token on every surface it is drawn on (translucent tints composited over their base), compute the ratio for both schemes, and fail the build below AAA. Disabled controls are exempt. Text without an explicit color must inherit a theme token from the root, not a framework default.
• Use icons from the installed icon system instead of emojis for UI controls.
• Use stable dimensions for buttons, toolbars, rows, grids, counters, and dynamic labels.
• Do not animate layout properties; use transform and opacity.
• Respect prefers-reduced-motion.

State Discipline

Every async or data-dependent surface needs:

• Loading: skeletons that match the final layout; avoid generic full-page spinners.
• Empty: friendly observation, useful context, and a next action.
• Error: plain-language problem plus recovery; localize partial failures to the affected region.
• Success: lightweight confirmation; undo for reversible destructive actions.

Do not ship a polished happy path with broken silence everywhere else.

Copy Rules

• Name the action: "Review changes", "Create workspace", "Retry import".
• Avoid generic labels like "Submit", "OK", and "Continue" when the action can be named.
• Use plain product language from the domain glossary.
• Do not expose raw internal errors, job names, provider stack traces, or agent jargon in user-facing copy.
• If the repo is localized, update all required locales in the established message system.
• Blame the system, not the user, when recovery is possible.

Mobile Rules

• Minimum touch target: 44px.
• Primary actions should be reachable in normal thumb zones.
• No hover-only affordances for critical actions.
• Avoid horizontal overflow at 320-375px.
• Check phone UI at the target device width and again at an OS text scale of about 1.3. Scale with page zoom; a root font-size change misses px-sized layouts. Assert that visible control boxes do not overlap (clip to scroll containers), targets stay at 44px, and the page does not scroll horizontally.
• Reserve space for async content to prevent layout jumps.
• Keep forms short; use progressive disclosure for advanced inputs.
• Safe areas matter for sticky bottom actions.

AI Interface Rules

• Make uncertainty visible.
• Keep provenance, review, undo, or restore available for AI-generated changes that affect user trust.
• Do not fake AI results, citations, progress, or confidence.
• Prefer concrete progress labels over generic spinners.
• Do not let AI chrome compete with the user's primary object of work.
• Preserve user agency: suggestions should be easy to accept, reject, edit, or ignore.

Guiding Screens

When a screen tells someone what to do next (task, status, approval, or review flows), read GUIDING-SCREENS.md: three first-viewport answers, server-computed acts, links to where a person checks, two registers, and suggestions that name the act of their button.

Review Checklist

• Does the screen answer one primary question, and does the entry point promise that question?
• Does each primary action land on a surface that shows its result and the next step?
• Which control needs instructions to be found or operated, and what label, placement, or affordance removes that need?
• Is the primary action obvious, reachable, and accurately labeled?
• Does the flow have an exit and a recovery path?
• Are loading, empty, error, and success states present?
• Does mobile collapse cleanly without hidden actions or horizontal scroll?
• Are focus, labels, roles, contrast, keyboard access, and reduced motion handled?
• Does the implementation follow existing tokens and component patterns?
• Is every new dependency justified?

Red Flags

Stop and revise when you see:

• happy-path-only UI
• hidden or generic error handling
• hover-only mobile-critical actions
• hardcoded colors where tokens exist
• icons or emojis used inconsistently
• UI copy added outside the repo's localization system
• AI surfaces with no review, provenance, or recovery
• animation that delays the user's work
• an action that ends on a blank page or a silent return
• a tooltip or tour that explains how to find or operate a control