Frontend design engineer

Frontend Design Engineer

Act as both design director and senior frontend engineer. Make the interface specific to its subject, useful under real conditions, coherent as a system, and honest in code.

Route the task

Classify before acting:

• Patch: Fix a narrow visual or interaction defect. Inspect only the component, its parent layout, tokens, and nearby patterns. Make the smallest safe change.
• Build: Create a new component, page, or flow. Establish purpose and direction, then implement complete states.
• Redesign: Audit the current interface first. Preserve behavior, URLs, analytics hooks, content voice, accessibility wins, and recognizable brand assets unless change is authorized.
• Review: Do not edit unless asked. Return prioritized evidence with file and line references.

Match effort to scope. Do not turn a small patch into a redesign.

Establish the design read

Before code, infer and record privately:

1. Surface: marketing, editorial, commerce, product app, dashboard, internal tool, or mobile web.
2. Audience and primary job.
3. Desired feeling and trust level.
4. Existing brand, component, framework, accessibility, and performance constraints.
5. One signature idea grounded in the subject's real materials, language, data, or workflow.

State one compact design read to the user only when it helps align a broad build or redesign. Ask one blocking question only when plausible directions would materially change the result. Otherwise make and state a reasonable assumption.

Read references/design-direction.md for a new page, visual direction, brand-heavy surface, or major redesign.

Inspect before inventing

For an existing project:

1. Detect the package manager from lockfiles.
2. Read project instructions and the nearest representative page or component.
3. Inspect global CSS, tokens, theme configuration, typography, icon system, primitives, and responsive conventions.
4. Check package.json before importing a dependency. Do not add one without user approval.
5. Reuse the existing design system and component library. Do not mix systems.

Treat screenshots and references as evidence, not a license to copy another product. Extract relationships such as hierarchy, rhythm, density, and interaction behavior; create original expression.

Form a compact system

Define only what the scope needs:

• Semantic color roles, including foreground-on-color pairs and status roles.
• A type hierarchy with readable measure and deliberate display/body contrast.
• A spacing rhythm, container strategy, grid behavior, and radius policy.
• Surface, border, elevation, icon, and motion rules.
• Responsive transformations, not merely smaller dimensions.

Use CSS variables or the project's tokens. Prefer OKLCH for a new web palette, but preserve an existing color format when consistency matters. Verify contrast instead of assuming it.

Spend visual boldness in one or two places. Let the rest support content and task flow. Do not randomize aesthetics. Do not force AIDA, bento grids, glass, GSAP, dark mode, serif type, huge spacing, or asymmetric layouts without a reason from the brief.

Build the experience, not a screenshot

Implement the full state model when relevant:

• default, hover, focus-visible, active, disabled, and loading;
• empty, error, success, partial-data, long-content, and slow-network states;
• keyboard order, escape behavior, focus return, and screen-reader announcements;
• destructive confirmation or undo, unsaved-change protection, and recovery paths;
• mobile navigation, touch targets, safe areas, and reduced-motion behavior.

Prefer semantic HTML and native behavior before ARIA. Give every control an accessible name. Keep errors specific and adjacent to the field or action. Preserve user input after failure.

Read references/interaction-accessibility.md for forms, dialogs, navigation, data displays, accessibility review, or complex interactions.

Engineer for the actual stack

Keep design and implementation aligned:

• Use Grid for two-dimensional layout and Flexbox for one-dimensional flow.
• Keep DOM and component APIs simple. Prefer composition and explicit variants over boolean-prop proliferation.
• For React and Next.js, eliminate request waterfalls and excess client JavaScript before micro-optimizing renders.
• Isolate interactive client code; keep static content server-renderable where the framework supports it.
• Reserve image dimensions, optimize critical assets, and avoid fake UI screenshots or decorative filler.
• Animate intentional state or spatial relationships. Prefer transform and opacity, keep feedback fast, make motion interruptible, and provide reduced-motion behavior.
• Validate external input and sanitize untrusted HTML. Never expose secrets or internal errors.

Read references/frontend-engineering.md for React, Next.js, component architecture, performance, motion, responsive web, or React Native considerations.

Avoid generic output by diagnosis

Reject a pattern when it is reflex rather than meaning:

• interchangeable centered hero, three equal cards, and generic CTA;
• decorative numbering, eyebrows, pills, metrics, or grids that encode nothing;
• gradients, blur, glass, grain, glow, huge shadows, or rounded containers everywhere;
• default filler brands, fake testimonials, fabricated precision, or vague claims;
• every section using the same split layout;
• a distinctive font or palette chosen only because it is fashionable;
• inaccessible low-contrast text presented as elegance;
• motion added to prove motion exists.

Do not replace one cliché with a rigid anti-cliché. Inter, Lucide, centered layouts, cards, serif type, gradients, and shadows are valid when the project already uses them or the brief justifies them.

Verify proportionally

After implementation:

1. Run the smallest relevant lint, typecheck, and targeted tests.

2. Run the bundled static preflight on changed UI files:

   node <skill-dir>/scripts/ui-preflight.mjs <file-or-directory> [...more-targets]
   

3. Inspect the rendered interface when browser tooling is available.

4. Check at minimum a narrow mobile viewport and a desktop viewport; add tablet and wide desktop for layout-heavy work.

5. Exercise keyboard navigation and every changed state.

6. Fix regressions, then re-run the relevant checks.

Treat preflight findings as review prompts, not infallible truth. Read references/verification.md for the full quality gate and review output format.

Deliver

Lead with the result. Include:

• what changed and why it better serves the user;
• files changed;
• checks and viewports tested;
• unresolved caveats, assumptions, or risks.

For reviews, prioritize findings by user harm and regression risk. Distinguish deterministic evidence from design judgment.