design-engineering

name	design-engineering
description	Practice the design-engineering discipline — bridging design intent and implementation, working directly in code, component exploration workflow, design tool to code handoff, and building UI systems that stay true to their design spec. Use when asked about "design engineering", "design engineer", "design in code", "design-to-dev handoff", "bridge design and development", "design system in code", "component playground", "Storybook for design", "Figma to code", "interactive prototyping in code", or "when to use design tools vs code". Do NOT use for: building an actual design system token spec — see design-system-gen. Do NOT use for: specific animation implementation — see motion-design.
origin	adapted:MIT © emilkowalski
license	MIT © 2026 Vũ Văn Tâm
version	1.0.0
compatibility	React, Storybook v8, Radix UI. Principles are framework-agnostic.

When to Use

• Use when: design files don't match what's built and nobody notices until demo
• Use when: component variants are inconsistently implemented across pages
• Use when: you need to decide whether to prototype in Figma or code
• Use when: building a component that needs to feel exactly right before shipping
• Do NOT use for: WCAG audit — see accessibility-audit
• Do NOT use for: animation performance — see fixing-motion-performance

---

What Design Engineering Is

Designer  ──────────────────►  Developer
(intent)   handoff gap lost      (implementation)

Design Engineer:
  ─ Thinks in both intent and constraints simultaneously
  ─ Makes decisions in code that designers make in tools
  ─ Builds components that look exactly like the design — by choice, not accident
  ─ Knows which details matter (spacing, timing, interaction states)
    and which can be deferred

The gap isn't skill — it's communication. Design engineers speak both languages fluently enough to close it themselves.

---

When to Design in Code vs Design Tool

Situation	Tool
Exploring layout and whitespace	Figma / design tool
Defining color, typography, brand	Design tool
Static screens for stakeholder review	Design tool
Micro-interactions and timing	Code (too slow in Figma)
Responsive behavior	Code
Complex states (loading, error, empty)	Code
Accessibility (focus, keyboard)	Code — can't test in Figma
Final production component	Code

---

Component Exploration Workflow

1. Start with the happy path — render one complete state in isolation
2. Add all variant states: default / hover / active / disabled / loading / error
3. Test with real content: long strings, empty strings, missing images, RTL
4. Add motion last — wire timing and spring after all states are correct
5. Audit in isolation (Storybook) before integrating into a page

---

Storybook as Design-Engineering Playground

// Button.stories.tsx — document all states designers care about
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: { control: 'select', options: ['default', 'destructive', 'ghost', 'outline'] },
    size:    { control: 'select', options: ['sm', 'default', 'lg', 'icon'] },
    disabled:{ control: 'boolean' },
  },
};
export default meta;
type Story = StoryObj<typeof Button>;

export const AllVariants: Story = {
  render: () => (
    <div className=>
      Primary
      Secondary
      Ghost
      Delete
      Disabled
    
  ),
};


  :  = {
  :  ,
};

---

Precision Handoff — Checklist

Before calling a component "done", verify:
  □ Spacing matches spec exactly (use 4/8pt grid — not "looks about right")
  □ All interactive states are implemented: default, hover, focus, active, disabled
  □ Loading and error states exist — not just happy path
  □ Empty state matches design intent (not "no items" in system default)
  □ Component handles long content gracefully (truncation, wrapping)
  □ Responsive breakpoints match design breakpoints
  □ Dark mode tokens used — not hardcoded colors
  □ Component is accessible: keyboard operable, screen reader tested
  □ Animation timing matches design spec (or is explicitly adjusted and approved)

---

Pixel Precision Techniques

// Measure against design with opacity overlay
// In DevTools: set element opacity to 0.5, screenshot from Figma underneath

// 8pt grid — space in multiples of 8 (or 4 for fine-grain)
const SPACING = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32, '2xl': 48, '3xl': 64 };

// Line-height as a multiplier (not px) — scales with font size
h1 { font-size: 2.5rem; line-height: 1.2; }   /* = 48px line height at 40px font */

// Optical alignment — sometimes visual center ≠ geometric center
.icon-in-button {
  margin-top: -1px;    /* icons often sit 1px low optically */
}

---

Design Token Consumption (Not Creation)

// Use tokens, don't create them — design engineer consumes the system
// ✅ Use semantic tokens
className="text-foreground bg-background border-border"

// ❌ Invent new one-off values
style={{ color: '#1a1a2e', background: '#f8f9fa' }}

// When a value doesn't exist in tokens: bring it to the design system discussion
// Don't add it unilaterally — it creates drift

---

Anti-Fake-Pass Rules

Before claiming design engineering work is done, you MUST show:

• All states implemented: default, hover, focus, active, disabled, loading, error
• Component runs in Storybook (or equivalent) with all states visible
• Spacing uses 4/8pt grid — no arbitrary pixel values
• No hardcoded color values — only design tokens
• Long content tested: long labels, empty content, missing images
• Responsive tested at all design breakpoints (not just desktop)
• Accessibility tested: keyboard navigation + screen reader pass

Reference: gates/anti-fake-pass-gate.md