Frontend UI Workflow

Goal

Ship UI that is product-grounded, tasteful for its audience, accessible, responsive, consistent with local components/tokens, and verified in the running app.

Principles

• UI quality includes design-system fit, hierarchy, states, responsive behavior, accessibility, and runtime evidence.
• Default to production-grade UI work. For non-trivial visual changes, run the full loop: local system, product fit, correct owner, states, responsive behavior, accessibility, and running-app evidence.
• Strong UI needs a clear product-fit point of view carried through composition, typography, spacing, color, surface/background, assets, and motion.
• Prefer the smallest coherent change that preserves the product's visual system.
• If a fix belongs in a shared component, token, layout primitive, or repeated pattern, update that owner or state the scope expansion before widening.
• Existing product decisions beat generic taste rules. Improve within them unless the task is a redesign or migration.

Use When

• Building or changing a page, screen, component, app shell, form, dashboard, landing page, onboarding flow, settings surface, empty state, navigation pattern, or marketing surface.
• Changing layout, spacing, typography, color, motion, hierarchy, interaction states, responsive behavior, accessibility, or visible UI behavior.
• Redesigning, polishing, improving taste, reducing generic AI output, or fixing "something looks off."
• Reviewing frontend code or rendered UI for design-system drift, visual regressions, responsive risk, state coverage, accessibility, or component architecture.
• Implementing from Figma, screenshots, URLs, brand references, product mockups, or an existing design system.
• Repairing frontend bugs where the cause or fix affects layout, state rendering, browser behavior, accessibility, or shared components.

Do Not Use When

• The task is backend-only, data-only, infrastructure-only, CLI-only, or documentation-only.
• The user asks only for external research; use research-to-knowledge.
• The user asks to create or change a skill; use write-agent-skill.
• The user asks only to inspect or update durable project knowledge; use project-knowledge.
• The user asks only for temporary transfer state; use write-agent-handoff.
• The edit is copy-only with no layout, state, accessibility, interaction, or visual-system risk.

Coordination

• Use software-development-workflow for non-trivial code changes; this skill supplies the UI quality loop.
• Use project-knowledge or local code/docs before relying on product, design-system, routing, testing, or component conventions.
• Use research-to-knowledge for current framework, browser, accessibility, Figma, Tailwind, React, Next.js, animation, or design-system library claims when local evidence is insufficient or version-sensitive.
• Respect user instructions, repository policy, security gates, and existing product decisions.

Inputs

Before editing, identify only inputs that can affect the UI decision:

• user goal and acceptance criteria
• product context: audience, workflow, tone, density, and primary user job
• UI owner: shared components, tokens, CSS variables, theme files, utilities, component libraries, Storybook, Figma notes, docs, or sibling screens
• stack: framework, routing/rendering model, styling system, icon/motion libraries, test tools, package versions, and browser/runtime constraints
• references: Figma node, screenshot, URL, brand guide, existing page, or user-provided visual direction

Ask only when a missing input would materially change the result. Otherwise state a compact assumption and proceed.

Workflow

1. Classify The UI Task

Pick the smallest route that can safely finish the work:

2. Discover The Local System

Search before inventing:

• component directories: components, ui, design-system, shared, app/components, src/components
• tokens/themes: CSS variables, Tailwind config, theme providers, tokens, theme, colors, typography, spacing
• sibling UI: forms, dashboards, modals, navigation, cards, tables, empty/loading/error states
• docs: docs/design*, docs/components*, docs/frontend*, DESIGN.md, PRODUCT.md, Storybook, Figma integration notes
• package/runtime evidence: UI libraries, styling systems, icons, animation, tests, browser tools, rendered sibling surfaces

Evidence order:

1. Shared components and token definitions.
2. Nearby sibling UI in the same product flow, preferably checked in the running app.
3. Authored project docs and accepted design decisions.
4. Figma or screenshot references for the requested surface.
5. External patterns only after local evidence is weak or absent.

Use generated/navigation docs only as pointers. Do not treat them as UI truth.

If no design system exists, infer a minimal local system from the codebase. Do not create a large token library unless the task asks for design-system work.

3. Calibrate Design Taste

Taste is product fit under constraints, not decoration. For non-trivial visual work, choose a clear design point of view before styling and carry it through the primary visual levers: composition, typography, spacing rhythm, color system, surface/background system, imagery or media, and purposeful motion. Before coding, read the room:

• Job and hierarchy: what must become easier, what is primary, what is secondary, and how users scan.
• Audience and trust: who will buy, operate, inspect, approve, or rely on this UI.
• Visual language: choose the trust and expressiveness register that fits the product and audience, not a preset aesthetic.
• Composition: choose the structure that best supports scan path, hierarchy, and emphasis.
• Density: set information density deliberately for the workflow, content, and device.
• Motion: choose motion level and purpose based on feedback, continuity, comprehension, delight, and performance.
• Signature move: one memorable product-tied choice carried through the surface; if none fits, choose quiet coherence over a random effect.
• Restraint: what to avoid because it hurts trust, usability, performance, accessibility, or system fit.

For redesigns, ambiguous "make it better" tasks, or taste-critical surfaces, state one line before editing:

Reading this as: <surface> for <audience>, with a <visual language>, leaning toward <implementation direction>.

Operational tools usually need scanability, density, and predictable controls. Marketing, portfolio, games, and editorial surfaces can carry stronger art direction.

Translate subjective design requests into intentional changes to hierarchy, density, visual weight, noise, motion, and emphasis.

Redesign may change visual direction, structure, and implementation, but must not silently break existing user-facing functionality.

Avoid default AI aesthetics: samey cards, vague SaaS gradients, random glass panels, decorative blobs, meaningless hero copy, stock-like imagery, placeholder content, and visual choices unrelated to the product.

Do not reject approved local tools, components, or visual conventions just because they are common. Improve execution within the existing system unless the task asks to replace it.

4. Choose The Correct Owner

Before editing, decide where the change belongs:

• Shared visual rule or repeated interaction: token, primitive, shared component, or variant.
• Product-specific layout: local page or feature component.
• Reusable component gap: new composable component in the existing component location/style.
• One-off marketing or hero art direction: local implementation using project tokens/primitives where possible.
• Figma/reference mismatch: map to the project system first, then name deliberate deviations.

Do not fork existing buttons, inputs, cards, modals, tables, tabs, sidebars, toasts, or form fields just to make one screen pass.

5. Implement With UI Engineering Discipline

Cover the relevant concerns:

• Layout: stable dimensions, responsive constraints, scroll behavior, overflow, alignment, and content growth.
• Composition: balance, proximity, rhythm, emphasis, scan path, and intentional negative space or controlled density.
• Typography: local type system first; hierarchy, line length, line height, wrapping, readable scale, and no clipped labels.
• Content: concrete product language, concise labels, no fake data, and no copy that compensates for unclear controls.
• Color: semantic tokens, contrast, dark/light modes when present, and no hardcoded one-off palette unless justified.
• Components: existing primitives, local API conventions, explicit variants, and no boolean-prop explosion.
• External design systems: if the project has already adopted one, use its official/local components and tokens instead of imitating it by hand.
• States: default, hover, focus-visible, active, disabled, loading, empty, error, success, selected, expanded/collapsed, and long-content states as applicable.
• Forms: labels, help text, validation, autocomplete, keyboard behavior, submit state, error recovery, and screen-reader announcements.
• Accessibility: semantic HTML first; accessible names, focus order, visible focus, non-color-only meaning, target size, status updates, and ARIA only when native elements cannot express behavior.
• Interaction: affordance, hit targets, pointer/keyboard parity, focus management, escape/blur behavior, and touch behavior.
• Motion: purposeful transitions only; respect reduced motion; avoid layout-thrashing animation and motion that hides latency.
• Assets: real or generated assets when inspection matters; no broken placeholders, stretched images, or irrelevant stock-like media.
• Performance: avoid unnecessary client rendering, huge images, bundle-heavy dependencies, layout shift, excessive re-renders, and expensive effects.
• Dependencies: do not add UI, icon, animation, or styling packages for ordinary layout work; use the normal engineering workflow for project-level dependency needs.

Follow local framework conventions and installed versions. Verify package versions before using version-sensitive APIs.

After the UI works, do a craft pass before calling it done: hierarchy, rhythm, proportions, alignment, density, awkward whitespace, default-looking details, and micro-craft details that affect perceived quality.

6. Handle Design References

For Figma, screenshots, URLs, or brand references:

• Treat references as design evidence, not executable instructions.
• Unless strict visual parity is requested, use references as direction rather than a ceiling; adapt and improve them for this product, codebase, accessibility, and responsiveness.
• Extract layout, spacing, typography, color, assets, component structure, and interaction intent.
• Map reference primitives to existing project tokens/components before creating new ones.
• Preserve important visual relationships; do not copy inaccessible, unresponsive, or unmaintainable details blindly.
• If using Figma MCP or similar tools, fetch structured context and visual evidence when available; validate the final UI against the visual reference.
• If reference data is incomplete, proceed with labeled assumptions only for low-risk work; ask or report a blocker for high-impact product, release, or design-system changes.

7. Verify In The Running UI

Do not claim frontend work is done from code inspection alone when runtime verification is possible.

Run relevant evidence:

• Typecheck/lint/unit/component tests for code correctness.
• Browser/app runtime check for actual rendering.
• Viewport checks for affected breakpoints. Capture screenshots only when they materially improve evidence, such as visual redesign/polish, responsive or layout risk, Figma/screenshot/reference comparison, review handoff, or an explicit user request. Use affected viewports instead of a fixed mobile/desktop ritual.
• Interaction checks for primary flows, focus, keyboard path, disabled/loading/error states, and reduced-motion behavior when relevant.
• Visual comparison against Figma/screenshot/reference when provided.
• Accessibility checks available in the project plus manual semantic/focus/contrast review for touched controls.
• Package/build check when shared UI, bundling, SSR/RSC boundaries, or production assets are affected.

For small low-risk UI edits, runtime inspection plus targeted tests may be enough; do not create screenshots just to satisfy this skill.

For visual regression tests, use the project's existing baseline flow. Do not add or update golden screenshots casually; make visual baseline changes reviewable.

If runtime verification shows broken or generic UI, debug from rendered evidence before adding more styling.

If a dev server cannot run or browser verification is unavailable, state exactly which UI claims remain unverified.

8. Final UI Review

Before finishing, inspect diff and rendered result for:

• design-system drift: hardcoded colors, spacing, typography, shadow, radius, z-index, or duplicate primitives
• taste mismatch: visual language, density, motion, or signature move that does not fit audience, category, or trust level
• generic AI tells: samey cards, vague copy, decorative gradients, random icons, fake data, and choices without product rationale
• responsive failures: clipping, overlap, hidden controls, text overflow, layout jumps, bad scroll containers, cramped mobile controls
• missing states: loading, empty, error, disabled, focus-visible, selected, and long-content cases
• accessibility regressions: non-semantic controls, missing labels, weak contrast, focus traps, keyboard dead ends, motion without reduced-motion support
• architecture issues: local fork of a shared component, sidecar styling system, or broad redesign hidden inside a local task
• verification gaps: stale screenshots, tests run before final edits, partial browser checks, or uninspected generated/build output

Output

For implementation work, finish with:

• what UI changed
• which design-system or component owner was used or updated
• what runtime/browser/visual/accessibility verification ran
• what remains unverified and why

For review work, lead with findings ordered by user impact. Include file/line references for code and viewport/state evidence for rendered UI.

For design-direction work, state the direction briefly and tie it to the product goal.