frontend-design

Create working React and Tailwind interfaces that fit the product, preserve explicit constraints, and make the primary task clear. Read only the references relevant to the requested work.

Match the requested scope

For advice, comparison of workflows, or questions about which skill to use, answer without executing those skills. Do not edit files, persist context, create reports, or start an interview. For an explicit review, inspect and report. Implement fixes only when the user requests them or has already authorized them. Reuse prior authorization within its scope.

Context Gathering Protocol

Gather only the context needed for the requested decision. Use this order:

1. Reuse the user's current instructions, prior answers, and any direction or creative authority already granted.
2. Resolve the target application's context using project context. Read its .better-react-web-ui.md, applicable parent defaults, matching page brief, and existing design documents. Legacy files are fallback inputs within the same scope.
3. Inspect the affected code, callers, assets, and existing design system. Treat observed implementation as evidence of the current system, not proof of unstated audience needs.
4. Ask only about missing facts that materially change the work. Label reasonable assumptions and proceed with reversible choices within the authorized scope.

For a new design direction, establish the audience, intended task, and brand tone. Under explicit creative delegation, choose and record reasonable assumptions without another approval checkpoint. Never invent user answers or product facts.

For a focused repair, use the relevant code and constraints. Do not require a brand interview before fixing keyboard focus, overflow, or a measured performance defect.

Use $setup when the user requests persistent project context or when substantial design work needs missing context recorded. The absence of a context file alone does not require setup. Preserve existing context when updating it.

Set priorities

Preserve the existing visual system unless the user requests a change. For an open direction, choose a coherent style through design directions. Establish hierarchy with spacing, grouping, type, and contrast before adding decoration.

Distinguish requirements from preferences:

• Preserve accessibility, truthful content, functional controls, and explicit user constraints.
• Treat aesthetic guidance as defaults for open decisions. Inter, Arial, system fonts, pure white, pure black, gradients, cards, and familiar layouts are valid when they fit the brand and task.
• Use AI slop detection to diagnose generic composition, unsupported claims, or unnecessary decoration. A font or color alone is not a defect.
• Keep core workflows familiar and readable even when the marketing page uses expressive imagery or motion.

Prioritize clarity, task completion, and error prevention over visual novelty. Never fabricate customers, testimonials, metrics, capabilities, urgency, or scarcity. Keep prices, consent, destructive consequences, and cancellation paths clear. See interface honesty.

Match the implementation

Detect the existing React framework, Tailwind configuration, components, tokens, and data flow before editing. Reuse suitable code and installed dependencies. Respect explicit stack choices for new projects. Use framework defaults only for unspecified choices.

Consult framework official docs before framework-specific decisions. For Next.js, read relevant bundled documentation at node_modules/next/dist/docs/ when available. Prefer that version-matched source over memory.

Use component and block strategy and React shadcn accelerators when existing components or blocks fit the task. For custom primitives, read component anatomy and component accessibility. Preserve mature library semantics rather than rewriting them for appearance.

In Astro projects, add React islands only for interactions that need them. Keep implementation complexity proportionate to the requested result.

Implement the requested result

1. Identify the target page, flow, or component and the visitor's task on that page. Preserve fixed content, section order, and interaction behavior. For substantial work, reuse or prepare the optional page brief described in project context.
2. Choose a direction within the user's authority. For one requested artifact, implement directly. Use $add-ui for comparison when the user asks for alternatives, honoring the requested count. Do not add a selection checkpoint after the user has chosen or delegated a direction.
3. Build the smallest complete version with real source files and working actions. Establish a constrained spacing, type, color, radius, and elevation system before decorative details. When following an approved visual reference, use reference fidelity.
4. Cover relevant loading, empty, error, success, and responsive states. Use optimistic updates only when failures can be recovered without misleading the user or losing data.
5. Verify the result in the target project. Report what changed, the checks performed, and any untested behavior.

For substantial missing context, use design process and UX strategy. Do not turn a focused repair into a redesign.

Load references by task

Use the reference index for specialized topics such as authentication, commerce, data visualization, onboarding, permissions, and localization. Do not load the entire reference library for every task.

Verify before delivery

Follow visual verification for evidence, fix status, and unavailable-tool handling. Scale the following checks to the affected feature.

• Check that the primary action is clear and functional. Keep labels and content truthful.
• Check desktop and phone layouts, long content, and zoom for clipping, overflow, and lost functionality.
• Test keyboard operation, visible focus, accessible names, contrast, and relevant error recovery.
• With reduced motion enabled, keep all meaningful content visible and reachable. Decorative animation must not gate content access.
• Load initially visible and likely LCP images eagerly. Lazy-load suitable below-fold media. Reserve dimensions to avoid layout shifts.
• Base performance findings on measurements. Add memoization or temporary will-change only when profiling supports it.
• Use the project's existing checks and respect its command restrictions. Do not claim browser, accessibility, or performance results from source inspection alone.
• Review whether typography, spacing, color, and interaction decisions fit the product. Preserve approved brand choices even when a different style is your personal preference.