Designer-to-developer handoff process

develop specs/develop/handoff-process.kmd

Explicit workflow for moving a design from "ratified" (spec PR merged, Figma file finalized) to "shipped in product" (component preview matches spec, a11y audit passes, consumer ticket closed). Mirrors Cedar (REI) and Anvil (ServiceTitan) governance.

When this spec applies

Primary triggers

All triggers

Spec — Designer-to-developer handoff process

Status: v0.1.0 — Draft. Lightweight workflow for the current small contributor team; expand into a richer process when the contributor base grows.

R1 — "Ready for dev" definition

A design item is "ready for dev" when ALL of:

  • Spec PR is merged into master (specs/<area>/<slug>.kmd).
  • Tokens enumerated in the spec exist in internal/kinds/verge.go (or are explicitly opted out as out-of-Verge in the spec).
  • Figma file URL is added to the spec frontmatter as figma_url: (if any) — optional during the no-Figma-kit phase, required once the Figma kit pipeline lands (projects/koder-stack#157).
  • An implementation ticket is opened in the relevant engines/sdk/koder_kit/backlog/pending/ or engines/sdk/koder_web_kit/backlog/pending/.

R2 — Dev responsibility

When a developer takes a ready-for-dev ticket they MUST:

  1. Read the spec end-to-end before writing code.
  2. Implement to the spec; raise ambiguities back via a comment on the spec PR or a follow-up spec PR — never resolve ambiguity silently in code.
  3. Run make verge-contrast-audit and any spec-relevant audit.
  4. Produce a preview URL (local dev server, deployed stg, or screenshot) the spec author can compare against the spec.
  5. Mark data-ouia-safe="true" per specs/testing/ouia-test-hooks.kmd once the component is ready.

R3 — Designer responsibility (review)

When a developer requests review the designer MUST within 5 business days:

  • Compare preview to spec line-by-line.
  • File concrete gap list (no "feels off"; specific deltas).
  • Either approve the impl PR or open follow-up tickets for gaps.

R4 — Definition of "done"

A handoff ticket is done when:

  • Implementation PR merged.
  • Preview matches spec (designer signs off).
  • a11y audit passes (Lighthouse a11y ≥ 0.95).
  • OUIA hooks present per spec/testing/ouia-test-hooks.kmd.
  • Spec ticket moves from in-progress/ to done/.

R5 — Escalation

If review SLA missed: developer pings spec author via Koder Talk #kds channel. If unresolved after 3 business days more: spec author escalates to Koder Stack maintainer; maintainer reassigns or merges provisionally with an open follow-up ticket.

R6 — Async-first

All handoff communication MUST happen in writing (PR comments, ticket comments, Talk channel). No undocumented voice/video decisions.

Não-escopo

  • Hiring / onboarding new contributors (separate policies/contribution.kmd).
  • Per-product release coordination (handled in product backlog).

References