DOMAIN:DESIGN:FIGMA_HANDOFF¶

OWNER: alexander (Design System Engineer, shared) ALSO_USED_BY: floris, floor, felice UPDATED: 2026-03-26 SCOPE: design-to-code workflow, Figma Dev Mode, component inspection, asset export, design QA PREREQUISITE: design-system-engineering.md (DESIGN.md is the SSOT for agents)

FIGMA_HANDOFF:CONTEXT_FOR_GE¶

CRITICAL: in GE's agentic workflow, DESIGN.md is the primary design specification — NOT Figma REASON: agents cannot see Figma files — they read structured text specifications ROLE_OF_FIGMA: Figma is alexander's design tool for visual exploration and human review ROLE_OF_DESIGN_MD: DESIGN.md is the machine-readable output that developers consume

FLOW:

Alexander designs in Figma
  → Dirk-Jan reviews Figma visuals (human approval)
  → Alexander translates to DESIGN.md (machine-readable spec)
  → Agents implement from DESIGN.md
  → Felice does visual QA comparing implementation to Figma

RULE: anything in Figma that is NOT in DESIGN.md does NOT exist for development agents RULE: any discrepancy between Figma and DESIGN.md — DESIGN.md wins for agents, Figma wins for visual intent

FIGMA_HANDOFF:DEV_MODE¶

WHAT_IS_DEV_MODE¶

WHAT: Figma's developer-facing environment for inspecting designs FEATURES: component properties, token values, spacing measurements, code snippets, status workflows ACCESS: requires Figma paid seat with Dev Mode enabled

DEV_MODE_CAPABILITIES¶

INSPECT: click any element to see its properties (color, spacing, typography, effects) FOCUS: isolate a component in Focus View to see it without surrounding context STATUS: designers mark frames as "Ready for dev" — only ready frames appear in Dev Mode view HISTORY: see when a frame was last edited, compare versions side-by-side CODE: copy CSS/Swift/Android code snippets (as starting point, not production code) TOKENS: when Figma Variables are used, Dev Mode shows token names instead of raw values

HOW_GE_USES_DEV_MODE¶

USE: alexander inspects his own designs to extract precise values for DESIGN.md USE: felice uses Dev Mode to compare implementation against design during visual QA USE: Dirk-Jan reviews designs in presentation mode (not Dev Mode) NOT_USED_BY: floris, floor, or any development agents — they use DESIGN.md

FIGMA_HANDOFF:COMPONENT_INSPECTION¶

WHAT_TO_EXTRACT¶

FROM_FIGMA: component name, variant, size FROM_FIGMA: color tokens (mapped to design token names) FROM_FIGMA: spacing (padding, margin, gap) FROM_FIGMA: typography (font family, size, weight, line height, letter spacing) FROM_FIGMA: border (width, color, radius) FROM_FIGMA: shadow (offset, blur, spread, color) FROM_FIGMA: layout (flex direction, alignment, gap) FROM_FIGMA: responsive behavior (constraints, auto-layout settings)

EXTRACTION_CHECKLIST¶

CHECK: component name matches shadcn/ui component name (if using standard component) CHECK: all colors map to defined design tokens (no raw hex values) CHECK: spacing values align to 4px grid CHECK: typography uses defined type scale CHECK: border radius uses defined radius tokens CHECK: hover/focus/active/disabled states are all designed CHECK: empty, loading, and error states are designed CHECK: responsive variants are specified (mobile, tablet, desktop)

FIGMA_HANDOFF:SPACING_AND_SIZING_EXTRACTION¶

READING_SPACING_IN_FIGMA¶

METHOD: select element, hold Alt/Option, hover over adjacent element to see distance METHOD: select frame with auto-layout to see padding, gap values METHOD: use Dev Mode inspect panel for precise measurements

MAPPING_TO_TOKENS¶

RULE: every extracted spacing value must map to a spacing token RULE: if a value does not map to an existing token, flag it — do not create ad-hoc values

Figma Value	Token
4px	--spacing-1
8px	--spacing-2
12px	--spacing-3
16px	--spacing-4
20px	--spacing-5
24px	--spacing-6
32px	--spacing-8
40px	--spacing-10
48px	--spacing-12
64px	--spacing-16

IF value does not match a token (e.g., 13px): OPTION_1: adjust design to nearest token value (12px or 16px) OPTION_2: add new token to primitive scale (requires alexander approval) OPTION_3: document as exception in DESIGN.md with justification

FIGMA_HANDOFF:ASSET_EXPORT¶

ICONS¶

FORMAT: SVG (always) SIZE: designed at 24x24 base, scalable OPTIMIZATION: run through SVGO before commit NAMING: kebab-case matching component usage (e.g., icon-arrow-right.svg) DELIVERY: committed to project repo in public/icons/ or equivalent ACCESSIBILITY: every icon used as meaningful content must have aria-label or accompanying text

IMAGES¶

FORMAT: WebP (primary), PNG (fallback), JPG (photos only) EXPORT: 1x and 2x resolution OPTIMIZATION: compress before commit (imagemin, squoosh) NAMING: descriptive kebab-case (e.g., hero-dashboard-preview.webp) RESPONSIVE: export at multiple widths for srcset

LOGOS¶

FORMAT: SVG (primary), PNG (fallback at multiple sizes) VARIANTS: full logo, icon only, monochrome, inverse (for dark backgrounds) DELIVERY: committed to project repo, referenced in DESIGN.md

ILLUSTRATIONS¶

FORMAT: SVG when possible, PNG for complex illustrations STYLE: defined in DESIGN.md (consistent illustration style per project) DELIVERY: committed to project repo

FIGMA_HANDOFF:DESIGN_SPECS_IN_DESIGN_MD¶

WHAT_ALEXANDER_WRITES¶

For every screen/component, DESIGN.md must include:

SECTION: component selection (which shadcn/ui component, or custom) SECTION: token assignments (which design tokens apply) SECTION: layout specification (flex/grid, alignment, gaps) SECTION: responsive behavior (what changes at each breakpoint) SECTION: state specifications (default, hover, focus, active, disabled, loading, error, empty) SECTION: accessibility notes (ARIA attributes, keyboard interaction, screen reader behavior) SECTION: animation specification (if any — with prefers-reduced-motion note)

EXAMPLE_SPEC¶

## SCREEN:DASHBOARD:PROJECT_CARD

COMPONENT: Card (shadcn/ui)
LAYOUT: vertical stack, gap --spacing-stack-md

ELEMENT: project-thumbnail
  TYPE: img
  SIZE: 100% width, aspect-ratio 16/9
  RADIUS: --radius-lg --radius-lg 0 0
  ALT: "{project.name} preview"

ELEMENT: project-title
  TYPE: h3
  FONT: --font-size-heading-subsection, weight 600
  COLOR: --color-text-primary
  TRUNCATE: single line with ellipsis

ELEMENT: project-status
  TYPE: Badge (shadcn/ui)
  VARIANT: "default" for active, "secondary" for draft, "destructive" for overdue
  A11Y: include text label, not color-only

ELEMENT: project-updated
  TYPE: p
  FONT: --font-size-caption
  COLOR: --color-text-secondary

STATE:HOVER: shadow --shadow-md, transition 150ms
STATE:LOADING: skeleton placeholder matching layout
STATE:EMPTY: "No projects yet" message with CTA

RESPONSIVE:
  DESKTOP: 3-column grid, gap --spacing-6
  TABLET: 2-column grid, gap --spacing-4
  MOBILE: 1-column stack, gap --spacing-4

FIGMA_HANDOFF:DEVELOPER_HANDOFF_CHECKLIST¶

BEFORE_MARKING_READY_FOR_DEV (Alexander)¶

CHECK: all components use Figma Variables (not raw values) CHECK: all states designed (default, hover, focus, active, disabled) CHECK: loading, error, and empty states designed CHECK: responsive variants for mobile, tablet, desktop CHECK: accessibility annotations present (focus order, screen reader text) CHECK: auto-layout used consistently (no absolute positioning except when necessary) CHECK: components are from shared library (not detached instances) CHECK: DESIGN.md updated with full specification for this screen/feature

BEFORE_STARTING_DEVELOPMENT (Floris/Floor)¶

CHECK: read DESIGN.md specification for the screen/feature CHECK: verify all referenced design tokens exist in the design system CHECK: verify all referenced shadcn/ui components are available CHECK: identify any custom components that need to be built CHECK: clarify any ambiguity with alexander BEFORE starting implementation

AFTER_IMPLEMENTATION (Felice — Visual QA)¶

CHECK: compare implementation side-by-side with Figma design CHECK: verify spacing matches (use browser DevTools overlay) CHECK: verify colors match design tokens (not hardcoded) CHECK: verify typography matches (size, weight, line height) CHECK: verify all states render correctly (hover, focus, error, loading, empty) CHECK: verify responsive behavior at all breakpoints CHECK: verify animations match specification (including reduced-motion)

FIGMA_HANDOFF:FIGMA_MCP_SERVER¶

WHAT_IT_IS¶

WHAT: Figma's MCP (Model Context Protocol) server brings Figma context into agentic coding tools STATUS: available in VS Code, Cursor, Windsurf, Claude CAPABILITY: read Figma file structure, extract component properties, generate code from designs

GE_POSITION¶

CURRENT: experimental — not yet integrated into GE's agentic pipeline REASON: DESIGN.md remains the SSOT — Figma MCP generates code as starting point, not production FUTURE: evaluate Figma MCP as input to alexander's DESIGN.md generation workflow WARNING: Figma MCP output requires significant refinement — it is not production-ready code

WHEN_TO_CONSIDER¶

CONSIDER: if Figma MCP improves to produce token-aware, accessible code CONSIDER: if Figma native Git integration stabilizes (design branches linked to code branches) DO_NOT: replace DESIGN.md with Figma MCP output — agents need structured specs, not generated code

FIGMA_HANDOFF:DESIGN_QA_PROCESS¶

WHO¶

REVIEWER: felice (Visual QA) REVIEWER: alexander (design sign-off) REVIEWER: julian (accessibility sign-off)

PROCESS¶

STEP: developer marks PR as ready for review STEP: felice compares implementation against Figma using Dev Mode STEP: felice opens issues for visual discrepancies STEP: alexander reviews design fidelity for complex/custom components STEP: julian runs accessibility spot-check (contrast, keyboard, screen reader) STEP: all three must approve before PR merges (for UI-visible changes)

COMMON_DISCREPANCIES¶

ISSUE: spacing is 2-4px off from design THRESHOLD: within 2px is acceptable, over 4px must be fixed ISSUE: wrong font weight (400 instead of 600) THRESHOLD: must match exactly ISSUE: wrong color shade (blue-500 instead of blue-600) THRESHOLD: must use correct token ISSUE: missing state (no loading state implemented) THRESHOLD: all designed states must be implemented

FIGMA_HANDOFF:AGENT_INSTRUCTIONS¶

FOR alexander: - Figma is YOUR tool — agents never touch it - every Figma design must be translated to DESIGN.md before developers can implement - use Figma Variables mapped to design token names - mark frames "Ready for dev" only when fully specified - export assets and commit to project repo

FOR floris, floor: - you implement from DESIGN.md, not from Figma - if DESIGN.md is unclear, ask alexander to clarify — do not guess from screenshots - never hardcode values — always use design tokens - flag missing specifications before starting implementation

FOR felice: - you are the bridge between Figma and implementation - use Dev Mode to compare implementation against design - log discrepancies as specific, measurable issues (e.g., "card padding is 12px, should be 16px") - verify responsive behavior at 320px, 768px, 1024px, 1440px

READ_ALSO: domains/design/design-system-engineering.md, domains/design/design-tokens.md, domains/design/component-library.md, domains/design/responsive-design.md