For a shared component in a design system, what are the trade-offs of writing its spec before the code, after it, or alongside it?
answer
- cheap to change on paper
- reality lives in the code
- recording accidents as decisions
- skeleton first, finalise before stable
- new pattern versus extraction
basics
~20 sSpec-first aligns teams and settles accessibility cheaply but can ignore platform constraints. Code-first is fast and grounded but risks recording accidents as decisions. Co-authoring, a skeleton before code, refined by implementation and finalised before release, is the common balance.
solid answer
~40 s**Spec-first** gets design, engineering and accessibility decisions agreed while they are cheap to change, and suits new patterns several teams must agree on; its risk is a spec that ignores platform constraints and goes stale when code discovers them. **Code-first** is fast and grounded in what actually works, and suits extracting a component that already exists in several products; its risk is that the spec is written to match whatever shipped, recording accidents as decisions, with accessibility retrofitted or the spec never written at all. **Co-authored** is where most mature systems land: agree a skeleton, anatomy, variants, states and accessibility intent, before code; let implementation feed findings back; finalise the spec before the component is released as stable, with a changelog from then on.
go deeper
Recall the three timings, before, after and alongside the code, and one risk of each.
Explain which kind of component suits each timing and what a co-authored skeleton contains before code begins.
Show how you would run an extraction where existing builds disagree, and how you keep spec and component matched through release.
Set the default timing and the review gates for the whole system, balancing contributor speed against the cost of late disagreement.
## Three timings A shared component's spec can be written at three moments relative to its code. None is always right; each fits a different kind of component and team. ## Spec-first The spec is written and reviewed before any production code. - **Strengths:** decisions are cheapest on paper; product teams, platform engineers and accessibility specialists can agree the anatomy, states and behaviour before anyone builds; accessibility is designed in rather than bolted on. - **Weaknesses:** the spec can ask for things a platform cannot do cheaply; it goes stale as soon as implementation finds a problem, unless someone updates it; it can slow delivery while reviews run. - **Fits:** a **new pattern** several teams depend on, where disagreement discovered in code would be expensive. ## Code-first The component is built, often extracted from existing product code, and the spec is written afterwards. - **Strengths:** fast; grounded in what really works on each platform; natural when the system is extracting a component that three products already built. - **Weaknesses:** the spec tends to describe whatever shipped, so **accidents become decisions**; unhappy states and accessibility are retrofitted; designers are consulted late; and under deadline the spec is sometimes never written. - **Fits:** **extraction** and exploration, provided the spec is written as a deliberate review of the code rather than a transcript of it. ## Co-authored Design and engineering write the spec together, in stages, alongside the code. 1. Before code: agree a **skeleton**, purpose, anatomy, variants, the state list and accessibility intent (role or pattern, name source, keyboard). 2. During build: implementation findings flow back into the spec, such as a platform constraint, an extra state or a content edge case. 3. Before stable release: the spec is **finalised**, matched to the shipped component and reviewed. 4. After release: changes go through the spec and its **changelog** first. ## Comparison | Concern | Spec-first | Code-first | Co-authored | |---|---|---|---| | Cost of changing a decision | lowest | highest | low early, rising later | | Grounded in platform reality | weakest | strongest | strong | | Accessibility designed in | yes | often retrofitted | yes, via the skeleton | | Risk of stale spec | high without upkeep | low at first, spec may be missing | low if finalised | | Speed to first build | slowest | fastest | moderate | ## Choosing in practice In a utility company's billing portal, two components arrive at once: - a **usage meter** that three product teams have each built differently. Code-first extraction makes sense, but the spec should be written as a review: which of the three behaviours is right, and what did all three miss, such as the over-budget state. - an **autopay schedule picker** nobody has built yet, touching payments and dates. Spec-first, or a heavy skeleton, makes sense because disagreement found in code would be costly. Whichever timing is used, the rule that matters most is the same: **when the component is released as stable, the spec and the component match**, and later changes keep them matched. ## What interviewers listen for A strong answer names the risk of each timing rather than declaring a winner, links the choice to the kind of component, and knows that a spec written after the fact must still be a critical review, not a description of the build.
- The system is extracting a component from three product implementations that disagree. How do you write its spec?Treat the three as evidence, not as the answer. Compare their anatomy, states and behaviour, pick or design the right one for each difference, and add what all three missed, often unhappy states and accessibility notes. The spec then leads the extracted build rather than transcribing any one version.
- How do you stop a spec-first document from going stale once code starts?Make the spec the place implementation findings land: an open-questions section, a named owner and a rule that no stable release ships until spec and component match. A changelog after release keeps later changes visible to both designers and engineers.
saying these in an interview costs you the question
- A spec written after the code is just a description of the build.
- Spec-first means the spec is frozen and the code must obey it.
- Code-first is fine because the code is the only real spec.
- The timing does not matter as long as a spec exists eventually.
- Accessibility can wait until the spec is written after launch.