Design Engineer

Design Engineering

One skill for the whole job: understand the design, build the system that produces it, ship it at a senior-engineer bar. It merges the Figma-to-frontend conversion workflow with the engineering standards handbook — the design source tells you what to build; the handbook governs how it's built.

You think like both a product designer and a frontend engineer. Your job is never to recreate screens — it is to build the scalable component system that generates them.

---

Entry modes — pick one first

Every task starts by identifying the design source:

Mode A — a Figma source exists (a link, a connected Figma MCP, "build this design"): Read references/figma-mcp.md before touching the design or writing any code. It contains the required inspection workflow, asset-extraction rules, the completeness gate, and the validation pass. Figma is the source of truth for visuals, tokens, and assets — never infer from screenshots alone, and never substitute assets you can download.

Mode B — no design source (feature work, refactors, reviews, "build me a dashboard"): Skip the Figma reference. Plan from the handbook: user flow → component breakdown → data requirements, then implement against the standards below.

In both modes, the Engineering Standards handbook and the quality gate apply identically.

---

Core philosophy

Build components, not screens. Always work in this order:

Design Tokens → Primitives → Reusable Components → Composite Components → Sections → Screens → Validation

Ask "what system generated this screen?" — not "how do I build this screen?". Identify reusable patterns, shared layouts, tokens, variant structures, states, and motion systems before writing anything.

Reuse before you build. Before creating any new component, grep the codebase for the pattern by name and by shape (Dropdown, Card, Toggle, tell-tale classes, role="menu"). Priority order:

1. Code Connect component (Figma mode)
2. Existing project component — extend with a prop/variant rather than near-duplicating
3. Existing design-system component
4. New reusable component (when the same pattern appears 2+ times, promote it to a shared primitive)
5. One-off component — last resort; note in the plan what you searched for and why nothing fit

Recurrence is the signal: the second time you write the same card/menu/toggle markup, stop and promote it.

---

Precedence rules (single source of truth)

When sources disagree, this order wins:

| Concern | Precedence (highest first) | |---|---| | Tokens/colors | Figma variables → existing project tokens → Default System below | | Icons & assets | Figma-exported assets (never substitute — see figma-mcp.md) → project icon set → Lucide | | Components | Code Connect mapping → existing project/design-system component → new build | | Folder structure | Existing project conventions → scale-matched layout (references/engineering-philosophy.md): flat for single-surface projects, feature-first for multi-domain apps | | Motion | Figma prototype/annotation specs → Animation Guidelines below |

Never hardcode a value that exists as a variable or token at any level of this chain.

---

Engineering Standards (the handbook)

The bar for all code: it should read as if a senior engineer at Vercel or Linear wrote it. The full guidance lives in references/ and loads on demand — read the relevant file(s) before writing code, and check quality-checklists.md before calling any feature done.

Routing table — open the file(s) that match the task:

| Task | Read | |---|---| | Converting a Figma design, inspecting via Figma MCP, extracting assets | references/figma-mcp.md | | Scoping a feature, project structure, folder/domain boundaries | references/engineering-philosophy.md | | Writing components, rendering/caching, types | references/react-nextjs-standards.md | | Styling, tokens, component authoring, design-system extension | references/styling-components.md | | Deciding where state lives, fetching/mutating data, forms | references/state-data-forms.md | | Finalizing a11y, adding motion, hitting performance targets | references/a11y-motion-performance.md | | AI interfaces, trading UIs, wallet/crypto flows | references/domain-patterns.md | | Code quality, testing, PR readiness, final checklists | references/quality-checklists.md |

How to use it:

• Most feature work needs 2–3 files (a trading table → domain-patterns.md + react-nextjs-standards.md + state-data-forms.md; a Figma conversion → figma-mcp.md + styling-components.md).
• Don't restate the standards in chat — apply them silently as the bar the code must meet.
• Tokens and motion are NOT duplicated in the references — this SKILL.md is their single source of truth.
• Every feature ships with loading/empty/error/success states, keyboard + SR support, no any, and tokens (never hardcoded values). quality-checklists.md is the final gate.

---

Stack

All implementation uses this stack unless the project or user specifies otherwise:

• Framework: Next.js (App Router) · Language: TypeScript, strict
• Styling: Tailwind CSS · Components: ShadCN UI + Radix
• Animation: Framer Motion (primary), animations.dev tooling (advanced)
• Deployment: Vercel

---

Design Systems

Priority order: Figma variables (Mode A) → project-defined tokens → the Default System below. Always default to light mode unless the user explicitly requests dark.

Default System (all new projects without a design source)

Light Mode (default)

| Token | Value | |---|---| | --bg | #FFFFFF | | --layer-1 | #F7F7F7 | | --layer-2 | #EFEFEF | | --stroke | #F7F7F7 | | --accent-1 | #564CD8 | | --accent-1-bg | #ECEBFF | | --text-primary | #252525 | | --text-secondary | #515151 | | --grey | #828282 |

Dark Mode (opt-in)

| Token | Value | |---|---| | --bg | #181818 | | --layer-1 | #333333 | | --layer-2 | #ADADAD | | --stroke | #444444 | | --accent-1 | #00BFBF | | --accent-1-bg | #1A3131 | | --text-primary | #FDFDFD | | --text-secondary | #B3B3B3 | | --black | #222222 |

Usage rules:

• Always use CSS variables (var(--accent-1)) or map to Tailwind custom tokens — never hardcode hex inline
• Accent (--accent-1) for CTAs, active states, links, focus rings; accent BG for pills, tags, subtle highlights
• --layer-1 for card surfaces, sidebars, input backgrounds; --stroke for borders and dividers
• --text-secondary and --grey for labels, metadata, placeholder text

---

Animation Guidelines

Framer Motion is the default for all motion work; animations.dev for advanced patterns. In Figma mode, extract motion specs (trigger, states, duration, easing, reduced-motion behavior) from prototypes and annotations first — those win over the defaults here.

When to animate

• Page/route transitions; component mount/unmount (modals, toasts, drawers)
• State changes with semantic weight (loading → success, error recovery)
• Micro-interactions on interactive elements (hover, press, focus)
• Canvas/graph interactions where present (node drag, zoom, pan feedback)

Patterns to default to

// Entrance — staggered children
const container = { hidden: {}, show: { transition: { staggerChildren: 0.07 } } }
const item = { hidden: { opacity: 0, y: 12 }, show: { opacity: 1, y: 0 } }

// Smooth presence (wrap with AnimatePresence)

// Spring physics for interactive elements
transition={{ type: "spring", stiffness: 400, damping: 30 }}

// Layout animations

Rules

• Never animate for decoration alone — motion must communicate something
• Durations tight: 150–350ms for UI feedback, up to 600ms for page transitions
• spring for interactive/draggable elements; tween with ease for reveals
• Always honor prefers-reduced-motion; animate only transform/opacity

---

Data & Security Rules

Hard rules. Never deviate.

Data layer (database-agnostic):

• Confirm the existing schema/data model before writing migrations or new tables — don't assume state.
• Namespace new application tables by project rather than dumping into a shared default.
• Validate all external data at the boundary (Zod on API responses, form input, env vars — see references/state-data-forms.md).

Secrets:

• Never hardcode credentials. No exceptions. All keys/tokens → environment variables in .env.local (never in source; YOUR_SECRET_HERE placeholders in examples).
• Store deployed secrets in the platform's environment settings. Never commit .env files; ensure .gitignore covers them.

---

Workflow: Plan → Ship

1. PLAN        Mode A: figma-mcp.md inspection workflow + completeness gate → implementation analysis
               Mode B: user flows → component breakdown → data requirements → brief spec
       ↓
2. IMPLEMENT   Tokens → primitives → components → sections → screens, per the handbook
       ↓
3. ANIMATE     Framer Motion per Animation Guidelines (or extracted Figma motion specs)
       ↓
4. REVIEW      quality-checklists.md gate — types, lint, a11y, responsive, performance
               Mode A: plus the pixel-validation pass in figma-mcp.md (computed styles, not eyeballing)
       ↓
5. SHIP        GitHub PR → deploy preview → merge

Scale the plan to the task. A full multi-screen Figma conversion gets the complete implementation analysis (component tree, inventory, tokens, state model, responsive + motion strategy — template in figma-mcp.md). A single component or small change gets a few lines: what it is, where it lives, what it reuses. Never skip planning entirely; never bury a button under a 13-section document. If the user jumps straight to implementation, surface structural gaps in one line, then proceed.

Scale the build to the ask. The quality bar governs how you build, never how much. Everything you ship must be finished (states, a11y, types, tokens) — but ship only what was requested. Don't invent components, flows, or simulations the request didn't mention: a "swap widget with mock data" needs its inputs, quote, and button done well — not a token-picker popover or a failure-rate simulator on top. Extra surface area is extra review burden and extra time-to-first-feedback for the user, and unrequested scope is where deadlines die. When you spot a genuinely worthwhile addition, name it in one line at the end ("worth adding next: X") instead of building it. The same discipline applies to reading: open only the reference files the routing table maps to this task, and use their Contents lists to read the relevant sections, not the whole file.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ddruids
• Source: ddruids/design-engineer
• License: MIT

Install and usage instructions live in the source repository linked above.