Table of Contents
Design handoff rules
Written after the v0.6.8x admin redesign, where the same failure repeated across several pages. Recorded here so it outlives any one session.
The failure
A mockup was being treated as input to a design process rather than as the specification. The pattern each time:
- Read the mockup.
- Re-derive the design from first principles, reasoning about what the data supports and what reads better.
- Ship something adjacent to the mockup.
- Write a persuasive explanation for each deviation.
Step 4 is what made this hard to catch. The explanations were often individually reasonable, which made the output look considered rather than off-spec. A good justification for an unrequested change is still an unrequested change, and it discards the hours already spent making that decision.
Concrete instances, all from one page (admin → Deleted files):
- The subtitle was rewritten shorter.
- The toggle's polarity was inverted: the mockup's "Delete automatically" became "Never delete automatically", so on meant off.
- The two rows were reordered, putting the dependent row above the control it depends on.
- The mockup's conditional hiding (the duration row disappears when automatic deletion is off) was dropped.
- The mockup's in-row description was replaced with a warning banner, which then only looked right in the dark themes.
None of these were flagged as changes. They were simply what got built.
The rules
1. Transcribe copy verbatim. Every string in the mockup is the string that ships. Do not shorten, sharpen, or improve it. Copy has usually been argued over already; rewriting it silently discards that.
2. Preserve control polarity, element order and conditional behaviour exactly. If a toggle reads "Delete automatically", it is not built as "Never delete automatically". If a row is second, it stays second. If a row hides under a condition, it hides.
3. Inventory before implementing. Before writing code, list every element in the mockup, in order, with its exact text, marked buildable / needs data / impossible. That list is the checklist the implementation is verified against, not a summary written afterwards.
4. Deviate only for impossibility, and ask first. If something cannot be built — no endpoint, no data, no way for the server to know — raise it before implementing and let the operator decide. Do not build a substitute and explain it afterwards. "I have not read this" and "this does not exist" are different claims; do not file the first as the second.
Corollary
Where a value genuinely cannot be served, the row comes out, and it is recorded. A plausible-looking wrong value is worse than an absent one, especially on compliance surfaces (retention, holds, quotas) where an operator may rely on it.
Related
- Deferred items and their reasons: issue #311
- The webcheck guard catches dead selectors and undefined i18n keys, but cannot catch a faithful-looking design that does not match the handoff. That check is human.