Standards Guide

How Unit modules are built

Six binding standards govern every Unit module. This guide is the practical layer — how each standard applies in daily work, what "done" means, what's forbidden, and what reviewers check.

Engineering Standard
§ 1 · Why standards exist

Each rule maps to a failure mode we've already paid for

Unit standards are not aspirational. They are the corrective response to specific past incidents — and the cheapest way to prevent the next one.

✕
Inconsistent UI across modules
✕
Broken or unrunnable previews
✕
Undocumented implementation decisions
✕
Display values corrupting execution values
✕
Module drift between spec, code, and screen
✕
Engineer interpretation errors
Core principle:
Spec → Screen → Preview → Test → Report → Handoff
§ 2 · The six standards

One library, six binding standards

Every module satisfies all six. Click any card for the practical details and the binding markdown source.

01

Unit Design System

UDSP v1.1
Covers
  • Color tokens, typography, spacing, elevation
  • Component visual discipline
  • No raw hex outside :root
02

Preview System

preview-release-gate
Covers
  • Self-contained preview HTML
  • Deterministic mock states; no async
  • Reproducible screenshots
03

Test System

deterministic test discipline
Covers
  • Pure-logic unit tests
  • Browser smoke + capture pipelines
  • Forbidden-state absence assertions
04

Traceability

authority chain doctrine
Covers
  • Authority chain at the top of binding docs
  • Author history rows on every spec
  • No silent changes
05

State Modeling

closed-set lifecycle doctrine
Covers
  • Closed lifecycle states (no invented states)
  • Validation states disjoint from terminal failures
  • Forbidden post-submit causes named explicitly
06

UI Copy

user-safe language doctrine
Covers
  • No raw backend enums in user UI
  • Safe error language with userFacingReason
  • No technical leakage (extrinsic, GraphQL, OCW)
§ 3 · Implementation flow

One direction. Spec leads. Reports follow.

Each artifact derives from the one to its left. Reversing the flow ("the code says so, update the spec") is a drift signal — fix the spec before the code lands.

01 Module spec Lifecycle, validation, forbidden states, copy boundaries.
02 UI / TSX Pure-render components with explicit props. No async.
03 Preview HTML Self-contained review harness, deterministic mocks.
04 Tests Unit + smoke; invariants asserted explicitly.
05 Screenshots One PNG per reviewable state, captured headlessly.
06 Completion report Validation matrix tying invariants to assertions.
07 Engineer handoff README + STATUS finalized; ready for integration.
§ 4 · What "done" means

Done is a verification, not a feeling

Not done

Common false-done signals

  • "The screen renders without errors."
  • "The happy path works on my machine."
  • "The TSX type-checks."
  • "I tested it manually, the tests are coming next."
  • "Spec is rough, I'll write it after."
Actually done

Done means all of this

  • UI matches the binding spec
  • Preview works end-to-end with zero console errors
  • Tests pass and assert invariants explicitly
  • Screenshots exist for every reviewable state
  • STATUS / completion report carries this pass
  • Forbidden states / patterns asserted absent
  • No unrelated modules touched
§ 5 · Forbidden patterns

The non-negotiable list

These patterns must not appear in any module. If a need arises, the spec changes first — the implementation never leads.

UI-driven logic State transitions never originate in the TSX. The wrapper or backend owns lifecycle decisions.
Silent spec changes If the implementation diverges, the spec is updated first. No back-fits.
Raw backend enums in user UI Use userFacingReason; never surface DepositNotPending, TX_REUSED, etc. to end users.
Display-rounded executable values A value through toFixed() must never be reused as the executable amount.
Arbitrary colors or spacing All visual values come from UDSP tokens. No raw hex; no inline pixel constants outside tokens.
Backend calls inside preview Previews are deterministic, self-contained, offline-capable. No fetch(), no async.
Untested quick-fill / amount logic Every percent-fill or amount derivation has an asserting unit test. No "we'll add tests later".
Copying Deposit rules into Withdraw or vice versa Distinct funding models, distinct invariants. Cross-pollination is a CRITICAL violation.
§ 6 · Reviewer checklist

The nine questions every review must answer

Is the authority chain stated at the top of every binding doc?
Does the preview match the TSX (same state shape, labels, flow)?
Are all states reviewable from the preview sidebar?
Are forbidden states absent (grep + test assertions)?
Are decimals handled correctly (display ≠ executable, asset-precision honored)?
Are tests deterministic (no Date.now, no Math.random, no network)?
Are screenshots current (regenerated this pass)?
Is the completion report updated with the validation matrix?
Is the module ready for main-app integration (wrapper plan + integration notes)?