nezam-wireframe-pipeline

skill_id	nezam-wireframe-pipeline
name	nezam-Wireframe Pipeline
tier	3
description	Unified wireframe generation and spec engine with mandatory pixel-perfect reproduction gate, design-system fidelity enforcement, and 2-variation discipline.
version	4.0.0
updated	"2026-05-12T00:00:00.000Z"
changelog	null

Wireframe Pipeline

Purpose

Unified design-to-spec engine. Produces implementation-ready contracts from any source (Figma, Excalidraw, text interview). Enforces design-system fidelity as a hard constraint — not a guideline.

Phase 0: Ground Truth Gate (mandatory — runs before any wireframe work)

This phase cannot be skipped for existing screens. It can only be skipped for fully new greenfield screens with zero existing reference.

1. Run design/design-context-init if .cursor/context/design-init/ files are missing or stale.
2. Locate the current implementation of the target screen in pages.md and components.md.
3. Reproduce the current screen at 100% fidelity using existing tokens and components. No improvements, no corrections — faithful reproduction only.
4. Write the reproduction as baseline-<screen-slug>.md in .cursor/context/design-init/.
5. Document any design problems found as annotations in the baseline (not fixes).
6. Only proceed to Phase 1 after the baseline is written and confirmed.

DESIGN.md is a hard constraint from this point forward:

• Every wireframe element must be expressible using tokens defined in DESIGN.md and theme.md.
• Any element that requires a value not in DESIGN.md is a token gap — flag it explicitly with TOKEN GAP: [what is missing]. Do not work around it with one-off values.
• Token gaps must be resolved via design/design-token-architecture before the wireframe is finalized.

Phase 1: Ingestion & Analysis

Identify the source of truth for the UI design.

Mode A: Figma MCP (Primary)

• Use Figma MCP to read frame data.
• Extract: names, components, layout constraints, auto-layout rules.
• Map to NEZAM vocabulary in DESIGN.md.

Mode B: Excalidraw/Penpot JSON

• Parse element IDs, labels, groupings, and spatial arrangement.
• Infer layout intent and generate structure.

Mode C: Text Interview (Fallback)

• Conduct structured interview to define layout goals and component placement.
• Flag output as source: text-interview.

Phase 2: High-Fidelity Generation with Variation Discipline

Generate wireframes following the 2-variation rule.

Variation discipline (non-negotiable):

• Always produce exactly 2 variations per wireframe iteration. Never 1. Never 3+.
• Variation A: evolutionary — closest to existing design system, changes one element.
• Variation B: progressive — pushes one design dimension deliberately.
• Never present a single wireframe as "the design."

Iteration mode:

• Branch mode (default): Variations extend from the Phase 0 baseline. Use for exploring alternatives.
• Replace mode: A new direction replaces the baseline entirely. Use ONLY when baseline is confirmed broken by UX research. Document the replace-mode decision in the wireframe spec header.

Quality Standard

1. Grid structure: column count, named zones.
2. Component slots: named with variant — all from components.md.
3. Content hierarchy: H1/H2/H3/body/caption zones.
4. All interaction states: default, hover, focus, active, loading, empty, error.
5. Spacing annotations: named tokens from theme.md (xs/sm/md/lg/xl) — never raw px values.
6. Responsive pair: desktop (1440px) + mobile (390px).
7. Accessibility map: tab order, landmarks, ARIA roles.
8. Token compliance: every color, spacing, and radius value maps to a named token.

Phase 3: Deterministic Spec Conversion

Transform wireframes into explicit component contracts.

Output Artifacts

1. .nezam/core/plans/design/WIREFRAMES.md: Full wireframes and specs (both variations).
2. .nezam/core/plans/design/DESIGN_CHOICES.yaml: Locked selection data.
3. .nezam/core/plans/design/COMPONENT_INVENTORY.md: Every component, variant, and state.
4. Updated root DESIGN.md: New tokens if token gaps were resolved.
5. .cursor/context/design-init/baseline-<screen-slug>.md: Phase 0 reproduction.
6. .cursor/context/design-init/variation-<screen-slug>-A.md and -B.md.

Component Spec Format (YAML)

screen_id: nezam-"[id]"
layout_intent: "[purpose]"
iteration_mode: "branch | replace"
baseline_ref: ".cursor/context/design-init/baseline-[slug].md"
components:
  - name: "nezam-"nezam-[Name]"
    variants: ["default", "variant"]
    states: ["default", "loading", "error", "empty"]
    props_contract: ["prop1", "prop2"]
    tokens_consumed: ["--color-primary", "--spacing-md"]
responsive_rules: ["rules"]
interaction_notes: ["notes"]
accessibility_notes: ["notes"]
direction_notes: ["rtl/ltr handling"]
token_gaps: []

Validation Checklist

• Phase 0 baseline exists (or greenfield exception is documented)
• DESIGN.md was consulted — every value maps to a token
• Token gaps are explicitly flagged (not silently worked around)
• Exactly 2 variations produced
• Iteration mode (branch/replace) is documented in spec header
• Both variations differ by exactly one design dimension
• All spacing annotations use named tokens, not raw px values
• Responsive specs cover desktop (1440px) and mobile (390px)
• RTL handling is documented for all directional elements

Trigger

• Invoked during /PLAN design or whenever wireframe/spec generation is required.
• Standalone activation via wireframe-pipeline.