nezam-design-to-code-handoff

skill_id	nezam-design-to-code-handoff
name	nezam-Design To Code Handoff
tier	3
description	Transfers finalized design specs to development with full context: ground-truth component references, recursive import trees, token maps, and RTL verification.
version	2.0.0
updated	"2026-05-12T00:00:00.000Z"
changelog	null

Design to Code Handoff

Purpose

Eliminate the "Lost in Translation" gap between design and development by transferring not just specs but full context: the exact existing component structure, complete token map, recursive import tree, and RTL requirements. Developers receive everything needed for 100% fidelity implementation with zero ambiguity.

Trigger Conditions

• A design variation has been selected via design/design-iteration-protocol.
• /PLAN design phase is complete and development is ready to begin.
• A component or screen is being implemented for the first time.

Prerequisites

• .cursor/context/design-init/ files are current (all 6 files exist and are not stale).
• DESIGN.md is finalized.
• Selected variation spec exists in .cursor/context/design-init/variation-<screen>-*.md.
• .nezam/core/plans/design/DESIGN_CHOICES.yaml reflects the approved selection.

Procedure

1. Ground-Truth Reference (non-skippable)

Before specifying anything new, locate the closest existing component in .cursor/context/design-init/components.md.

• Document the exact current markup structure (element hierarchy, tag names).
• Document the complete class list (every Tailwind class or CSS class applied).
• Document the token usage (which CSS variables from theme.md are consumed).
• The new component must match this structure unless a deliberate, documented deviation is approved. Deviations are noted in the handoff doc as: DEVIATION: [what changed] — REASON: [why].

2. Recursive Import Tracing

For the component being handed off:

1. List all direct UI imports (components imported by this component).
2. For each direct import, list its imports (one level deeper).
3. Continue until you reach leaf components (no further UI imports).
4. Document the full tree in format:

   <TargetComponent>
   ├── <SubComponentA> (from components.md line XX)
   │   └── <LeafComponent> (from components.md line XX)
   └── <SubComponentB> (from components.md line XX)
   

5. Do not hand off a partial tree. Every node in the tree must be accounted for.

3. Context File Selection

Include these context files in the handoff document (reference by path, not by copying):

Scenario	Required context files
New UI component	theme.md + component's own source + all direct UI imports
New page	layouts.md + theme.md + page's dependency tree from pages.md
Modifying existing component	theme.md + component source + full import tree
New token needed	theme.md + DESIGN.md + token proposal

4. Large File Handling

For files >1000 lines:

• Extract only the relevant component section (from its opening tag/function to its closing).
• Always include the full import block at the top of that section.
• Never truncate token definitions — include the complete token map even if long.

5. Spec Document

Write .nezam/core/plans/design/HANDOFF_<screen-slug>.md containing:

# Handoff: <Screen/Component Name>

## Ground Truth Reference
[Closest existing component path + markup structure + class list + tokens consumed]

## Deviation Log
[Any approved deviations from ground truth — EMPTY if none]

## Import Tree
[Full recursive import tree]

## Context Files
[List of files developers must read]

## Component Spec
[Spacing, typography, colors — all referenced as tokens, none hardcoded]
[All states: default, hover, focus, active, disabled, loading, error, empty]
[Responsive: desktop (1440px) + mobile (390px)]
[RTL: directional property handling if rtl_aware]

## Token Map
[Every token consumed — token name → value from theme.md]

## Acceptance Criteria
[Testable assertions for QA]

6. Asset Preparation

• Icons/images: SVG or WebP, paths documented.
• Fonts: licensed, paths provided.
• All assets follow the token naming convention.

Output Artifacts

• .nezam/core/plans/design/HANDOFF_<screen-slug>.md
• .nezam/core/plans/design/COMPONENT_INVENTORY.md (updated)
• Updated root DESIGN.md (if new tokens were introduced)

Validation Checklist

• Ground-truth reference documents the closest existing component
• Any deviation from ground truth is explicitly logged with reason
• Import tree is complete (all nodes accounted for, no partial tree)
• All token references are from theme.md — zero hardcoded hex/px/rem values
• All component states are specified (default, hover, focus, active, disabled, loading, error, empty)
• Responsive specs cover desktop (1440px) and mobile (390px)
• RTL mirror verified for all directional properties (if rtl_aware: true)
• Context file list is complete per the selection table above
• Acceptance criteria are testable assertions (not vague descriptions)

Handoff Target

development — the implementing engineer or coding agent receives the HANDOFF doc and implements from it directly.