nezam-design-iteration-protocol

skill_id	nezam-design-iteration-protocol
name	nezam-Design Iteration Protocol
description	Enforces the two-step design discipline: Step A pixel-perfect ground-truth reproduction → Step B exactly 2 branch variations. Applies to all design work in NEZAM.
version	1.0.0
updated	"2026-05-12T00:00:00.000Z"
changelog	null
owner	design-lead
tier	1
sdd_phase	Design
rtl_aware	true
certified	false
dependencies	null

Design Iteration Protocol

Purpose

Enforce a non-negotiable two-step discipline for all design work: first reproduce the current design at 100% fidelity (ground truth), then and only then produce exactly 2 structured variations. Prevents design drift, ensures baseline documentation, and enforces comparison-based decision making.

Trigger Conditions

• Starting any design iteration on an existing screen or component.
• Reviewing a design before handing off to development.
• Any design work requiring stakeholder review.
• Explicitly invoked via design-iteration-protocol.

Prerequisites

• .cursor/context/design-init/ files are current (run design-context-init first).
• DESIGN.md is finalized and current.
• The target screen/component is identified.

Procedure

Step A — Ground Truth Reproduction (non-skippable)

1. Locate the current implementation of the target screen/component in .cursor/context/design-init/components.md or pages.md.
2. Document the exact current state as a baseline spec:
   • Exact markup structure (element hierarchy).
   • Complete class list / token usage.
   • All states (default, hover, focus, active, disabled, loading, error, empty).
   • Responsive behavior (desktop and mobile).
3. Write the baseline spec to .cursor/context/design-init/baseline-<screen-slug>.md.
4. Do not interpret or improve — reproduce faithfully. If the current design has problems, document them as annotations, not corrections.
5. Get explicit approval of the baseline before proceeding to Step B. (In solo work: write "Baseline approved" in the spec file and proceed.)

Step A is skipped ONLY when: The target is a fully new screen with zero existing reference. Even then, run design-context-init first to understand the token/component environment.

Step B — Branch Variations (exactly 2)

1. Starting from the approved baseline, produce exactly 2 variations. Never 1. Never 3+.
2. Variation A — Evolutionary: Closest to the existing design system. Changes one element only (e.g., tighten spacing, update hierarchy, improve contrast). All tokens must come from theme.md.
3. Variation B — Progressive: Pushes one design dimension deliberately. Changes one axis boldly (e.g., layout density, visual weight, interaction pattern). Must still use existing tokens — if a new token is needed, propose it explicitly.
4. Each variation spec includes:
   • What changed (one sentence).
   • Why (design rationale, one sentence).
   • Token diff (which tokens are used differently vs baseline).
   • RTL impact (if rtl_aware: true — note any directional changes).
5. Write variation specs to:
   • .cursor/context/design-init/variation-<screen-slug>-A.md
   • .cursor/context/design-init/variation-<screen-slug>-B.md

Step C — Selection & Lock

1. Present both variations to the decision-maker (or self-select in solo work).
2. Document the selection in .nezam/core/plans/design/DESIGN_CHOICES.yaml.
3. The selected variation becomes the new baseline for the next iteration cycle.

Output Artifacts

• .cursor/context/design-init/baseline-<screen-slug>.md
• .cursor/context/design-init/variation-<screen-slug>-A.md
• .cursor/context/design-init/variation-<screen-slug>-B.md
• Updated .nezam/core/plans/design/DESIGN_CHOICES.yaml

Validation Checklist

• Baseline file exists and contains full current-state reproduction (not a redesign)
• Exactly 2 variations exist (not 1, not 3)
• Both variations use only tokens from theme.md (no hardcoded values)
• Each variation changes only one design dimension
• RTL impact is noted for each variation
• Selection is recorded in DESIGN_CHOICES.yaml

Handoff Target

Selected variation spec → design/design-to-code-handoff → development.