Spec — Designertodeveloper handoff process

*tatus* 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 outofVerge in the spec).

• Figma file URL is added to the spec frontmatter as figma_url:

  (if any) — optional during the noFigmakit 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 readyfordev ticket they MUST:

1. Read the spec endtoend 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 linebyline.
• 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 spectestingouiatesthooks.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).