Skip to main content

ADR 0001: Design tooling

  • Status: Proposed (awaiting the design + engineering leads)
  • Date: 2026-07-22
  • Deciders: design lead + engineering lead — to be named on acceptance
  • Type: design / toolkit

Context​

The Design phase needs a tooling decision before StudyBuddy starts, because it shapes every design template and skill: how screen specs reference components and tokens, how prototypes are generated for SME validation, and what the design skills read and write. The design phase playbook currently flags this as its one open dependency. Constraints: agents must be able to both generate and consume design artefacts (text-first, diffable); designers must be able to work at their normal speed; tokens need a single source of truth that Build inherits.

Options considered​

  1. Code-first prototypes — agent-native: prototypes and tokens live in code, artefacts diff in PRs, and there is no export step between design and Build. Weaker for non-engineers — designers and SMEs cannot directly manipulate the artefacts, and visual exploration is slower than in a design canvas.
  2. Figma-first with token export / MCP into the agent workflow — designer-native and the industry standard, with the richest exploration environment; tokens and specs flow to agents via export or MCP. Adds an export/sync seam — and seams are where drift lives: every round-trip between canvas and repo is a chance for the two to disagree. Licence cost is real but secondary.
  3. Hybrid — Figma for exploration, code-first for validated flows. Gets each tool where it is strongest, but risks two sources of truth unless the handover point is a hard rule rather than a habit.

Decision​

Left open. Recommendation: trial option 3 (hybrid) during StudyBuddy's Design phase, with one explicit rule — Figma artefacts are exploratory and die at validation; from the moment a flow is validated, the repo (flows, screen specs, tokens in code) is the only source of truth, and the design handoff pack is assembled from the repo alone. Record the trial's outcome by amending this ADR to Accepted or superseding it.

Awaiting decision

This ADR is Proposed, not Accepted. The design and engineering leads must weigh the trial recommendation, name themselves as deciders, and accept or redirect it — it is deliberately not decided by this document.

Consequences​

  • Positive: design templates and skills can proceed tool-neutrally (they already assume repo-stored, text-first artefacts); StudyBuddy generates real evidence instead of a whiteboard debate.
  • Negative / accepted cost: the trial means running two environments for one phase, and the "dies at validation" rule needs actual enforcement (a check in the Design Review gate, not goodwill).
  • Follow-ups: name the deciders; define the trial's success measures before StudyBuddy Design begins; update the design phase playbook and the design templates once decided.

Revisit by​

End of StudyBuddy's Design phase — the trial outcome either upgrades this ADR to Accepted (with the chosen option) or supersedes it. Per the decision-records standard, history is never edited — only superseded.