--- type: Concept title: The Design Loop description: How a PM runs UI/UX design as a first-class, repeatable, product-scoped sub-flow of the Build stage — brief → design → reconcile → build → design-sync — gated by the Review Gate. Presentation-only for redesigns; a new surface downstream of an approved PRD may define its decided views and flows (D60), making the design the reference the build works from. PMOS's own app is one instance. tags: [design, ui, workflow, build, reconciliation, watermelon] timestamp: 2026-07-01 --- # The Design Loop **Situating context:** Any product a PM runs through PMOS may have a user-facing surface that needs UI/UX design. That design was an out-of-band activity — a brief handed to claude.ai/design, an ad-hoc reconciliation, a build, a sync back — never named as a loop, never made a skill, never gated. This concept names that loop **product-agnostically** (PMOS's own `web/` control-plane app is one instance — see [Per-product instances](#per-product-instances-pmos-and-tenants) below), so the [intake checklist](/planning/prd/initiative-intake-checklist.md), the skills, and [AGENTS.md](/AGENTS.md) all refer to one thing. **The load-bearing claim: design is a sub-flow of the [Build stage](/okf/core/concepts/sdlc-loop.md) (stage 3), not a new lifecycle stage.** It informs any initiative that adds or changes a user-facing surface. ## The loop An initiative with a user-facing surface runs four legs *inside* Build: ``` 1. BRIEF ──────► 2. DESIGN ────────► 3. RECONCILE + BUILD ──────► 4. DESIGN-SYNC (design-brief (claude.ai/design, (design-reconcile gate, (/design-sync skill: skill) external) then the design-system export the real web/ build, web-ci) library back) ``` 1. **Brief** — the [design-brief skill](/skills/design-brief.skill) writes the context handoff: what to design and the hard, presentation-only constraints, each surface tied to a real data source. It is to design what the [PRD](/skills/prd.skill) is to build. 2. **Design** — the design is made in an external design surface (PMOS-self uses claude.ai/design; any capable design surface fits — external to this repo). 3. **Reconcile + build** — the [design-reconcile skill](/skills/design-reconcile.skill) classifies every surface against **the product's capability ledger** and the PM signs off before any code; then the design is built into the product's app on its design system, verified by the product's CI. (For PMOS's own app the ledger is [web-capability-ledger.md](/planning/web-capability-ledger.md), the system is D38, and CI is `web-ci`.) 4. **Design-sync** — the external `/design-sync` Claude Code skill exports the now-real component library back to claude.ai/design (for PMOS, see [.design-sync/conventions.md](/.design-sync/conventions.md)), so the next design starts from the product's actual parts. The design surface (legs 2 and 4) is **pluggable and provider-agnostic** — PMOS-self uses claude.ai/design, but the loop is not tied to it; any capable design surface that can consume a brief and export a component library fits (harness-model-agnosticism). Legs 2 and 4 are external tools PMOS *references*; legs 1 and 3 are the PMOS skills that make the loop repeatable. ## Presentation-only is the load-bearing constraint For a **redesign of an existing surface**, design is **behavior-preserving**: no new views, no new data, no changed flows — presentation only. If such a design implies a data or feature change, it is **flagged back as a separate decision**, never smuggled into the build. **Scoped by [D60](/okf/products/pmos/adr/d60-prototype-loop.md) (2026-07-21):** for a **new surface downstream of an approved PRD**, the design *may* define the new views and flows — because the PRD already decided them. The constraint exists to stop design smuggling in features **nobody decided**; a PRD-decided feature is not smuggling. In that case the design produced here is **the reference the build works from** (D60 leg B), carrying the scored designer-grilling bar — not a Build-stage ornament. Anything the design implies **beyond** what its PRD decided is still flagged back, exactly as before. This is what keeps design at [control altitude](/okf/core/concepts/control-plane.md) in both cases: the PM's decisions bound the design; the design never makes them. ## Reconciliation is the watermelon defense for UI Leg 3's classification — **Supported** (maps to a real read/write) / **Cosmetic** (pure presentation, free) / **Available-unsurfaced** (data exists, opt-in) / **Unsupported** (no backend) — is the [watermelon-flag](/okf/core/concepts/watermelon-flag.md) concept applied to a design. A control that *looks* functional with no backend behind it is **watermelon-UI**: green on the surface, hollow underneath. The canonical instance is a Routing screen offering provider connections and API-key fields when PMOS has no connections table and must never hold API keys client-side. Reconciliation catches these before any code; the PM signs off the Unsupported dispositions as an [Acceptance-Gate](/okf/core/concepts/output-eval.md) call. ## Where design meets the three-tier gate Design is judged by the standard [three-tier gate](/okf/core/concepts/output-eval.md), not a bespoke one: - **Quality Gate** — the product's CI (build/lint; `web-ci` for PMOS's own app) and token-hygiene checks (no raw hex where a semantic token exists). - **Review Gate** — the reusable [design-fidelity rubric](/planning/evals/design-fidelity-eval-rubric.md): weighted dimensions led by *capability-honesty / no-watermelon-UI*, then token-adherence, accessibility (not color alone), information density, interaction clarity, behavior-preservation. The rubric *is* the design spec ([eval-driven PM](/okf/core/concepts/eval-driven-pm.md)). - **Acceptance Gate** — the PM confirms visual parity and honors the reconciliation dispositions. Non-delegable. ## Why a sub-flow of Build, not a new stage Design changes no world-state of an initiative independent of building — by its own presentation-only charter it is *how a surface being built looks*. Giving it a board column would imply a parallel lifecycle, force a data-model change to the stage machinery, and contradict the charter. PMOS makes a capability first-class by making it **retrievable, repeatable, and gated** (this concept + the two skills + the rubric), not by adding a swimlane — the same move that self-hosted the eval layer. (If design-approval and build-start ever decouple in time such that the board hides real "designed-but-not-built" state, the lighter first step is a `specs` row of `kind:'design'` in the board drawer — still no new stage. Recorded as the revisit trigger in D48.) ## Per-product instances (PMOS and tenants) The loop is a **method**; PMOS's own app is just its first instance. What is **shared** vs **per-product** (D50): - **Shared, authored once, read by every PM** — this concept, the [design-brief](/skills/design-brief.skill) and [design-reconcile](/skills/design-reconcile.skill) skills, the [design-brief template](/okf/core/templates/design-brief-template.md), and the **generic dimensions** of the [design-fidelity rubric](/planning/evals/design-fidelity-eval-rubric.md). These live in PMOS-self's knowledge and are already reachable by tenants (repo-managed OKF rows are shared-read, D37; the `skills` table is select-all). - **Per-product, authored by each tenant** — its **capability ledger** (reconciliation checks a design against *that* product's real reads/writes), its **design system** (chosen at the product's IRS gate, D46 — not PMOS's D38), and its **brief + fidelity-rubric instance** (the generic dimensions plus the product's own tokens/surfaces). - **Where the build runs** — **leg-3 build executes in the product's own repo** (D46): PMOS creates the shell and holds the spec (brief), the reconcile gate, and the rubric; it does not build the tenant's app ([control plane](/okf/core/concepts/control-plane.md), D01). PMOS's own instance: the `web/` app, the [D38](/okf/products/pmos/adr/d38-design-system.md) design system, and [web-capability-ledger.md](/planning/web-capability-ledger.md). ## Relationship to other concepts - Design is a sub-flow of the [SDLC loop](/okf/core/concepts/sdlc-loop.md)'s Build stage. - It is gated by the [three-tier gate](/okf/core/concepts/output-eval.md) and run in an [eval-driven](/okf/core/concepts/eval-driven-pm.md) style (the fidelity rubric before the build). - Reconciliation is [watermelon-flag](/okf/core/concepts/watermelon-flag.md) applied to UI. - PMOS stays a [control plane](/okf/core/concepts/control-plane.md): it specs and evaluates design; the design itself is made in an external design surface (e.g. claude.ai/design) and built by a build agent. - Formalized by [D48](/okf/products/pmos/adr/d48-design-loop.md); made product-scoped by [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md); composes with the design *system* (D38, PMOS's own instance).