` or ``) + English unpack + line-cited link to the model | **Rule:** Don't paraphrase the API engineer's notes — quote them verbatim in German with a translation underneath. The German is the contract; the English is the explanation. Both languages help reduce drift between API team and implementer team. **Rule:** Every type in the table must match the actual Kotlin model declaration. Cite the line number (`CompositionModels.kt:116`). If the engineer's description and the model disagree, choose one of: - A **"usage rule"** — the field exists on the wire but this specific component ignores it (example: `CompositionButton.backgroundColor` exists but HeroCard_Video uses Design Tokens). - A **"rendering condition"** — the field is consumed but only under specific conditions (example: badge rendered only when `badge != null`). - A **deferred clarification** — flag for the API engineer to resolve before contract freeze. Don't silently pick one. **Rule:** The current Android implementation is not the API contract. If the contract says "hide progress bar at 0 and 100" but the code currently hides only at 0, document the **contract**, then add an "implementer alignment notes" footer that flags the gap. ## Verbatim German for API contract content The product is German-first. When quoting the API engineer's annotations, the German text is the source of truth — keep it verbatim. Pattern: ```html"Falls User nicht eingeloggt / keine Infos zu diesem User vorliegen, wird das Property→ If the user is logged out, or there's no per-user data for this item,user=null(aber vorhanden) sein. Wenn der Wert 0 oder 100 ist, gibt es keine Leiste."useris sent asnull. Bar hidden at0and100. ``` The English line starts with `→` and unpacks the German. Don't translate the German away. ## "Drift" vs "usage rule" vs "implementation gap" Three different things, three different doc treatments: | What you found | Treatment | |---|---| | Wire model has fields, but a specific component chooses not to use them | **Usage rule** — document the choice in the field row ("HeroCard_Video uses Design Tokens, ignores payload colors"). | | API engineer's verbal description and the model don't agree (e.g. "optional" vs declared non-null) | **Drift** — flag for the API engineer to resolve. State both versions. | | Documented contract and current code don't agree (e.g. contract says hide at 100, code renders at 100) | **Implementation gap** — footer note flagging the code line that needs to change. Doc still documents the contract. | Don't conflate them. Each has a different owner and a different remediation path. ## Section structure — keep the order Every component section follows the same structure. Don't reorder, don't skip: 1. **Heading** + brief description (1–2 sentences, platform-neutral) 2. **Anatomy** — wireframe(s) + callout key(s) 3. **Composition API contract** (if data-driven) — screenshot figure + field table 4. **Dimensions** — token-cited values table 5. **States** — `` with one entry per state 6. **Behavior** — `
` per behavior 7. **Accessibility** — bullet list (semantic role, label, contrast, keyboard) 8. **Motion** — duration/easing tokens (or "static" if none) 9. **Audit notes** — what's been verified, what's flagged for follow-up 10. **Implementation reference** — file paths, key composables 11. **Component navigation** — prev/next links Use the existing components in the doc as templates. ButtonGroupSection and HeroVideoCard are the most complete; copy their shape. ## Out-of-scope content is removed, not commented out If a feature is in the code but not in the iteration scope: - ✅ Remove it from the doc entirely. - ❌ Don't leave it commented in HTML. - ❌ Don't write "deferred for v2" — that's noise the agency doesn't need. Example: the MenuDrawer prototype-toggle rows exist in `MenuDrawerOverlay.kt` but won't ship to the external agency. They were removed from the doc completely — states, behaviors, accessibility entries, wireframe rows, token references — even though the code retains them. ## When in doubt, discuss before editing Some changes (renaming sections, removing existing wireframes, restructuring the TOC, bulk-replacing a class of content) are easy to over-shoot. Pattern: state the proposed delta as a bulleted plan, name the lines or sections affected, ask once, then execute. The doc has been over-deleted twice (greedy section-stripping scripts ate too much) — slow is faster than redo. ## Change-control summary Every commit that touches the doc should be: - **Small** — one component or one concern at a time. - **Source-cited** — commit message references the `.kt:line` that drove the change, or the API engineer note that drove the change. - **No invented values** — if you didn't find it in the code, you don't write it. ## Build + deploy Source: `specs/080-create-a-plan/docs/handover.html` + sibling files. Package: `packages/handover-doc/` (nginx static-site image, deployed via Coolify). Trigger: push to the current handover branch → Coolify rebuilds → live URL updates. To preview locally: ```bash cd specs/080-create-a-plan/docs python3 -m http.server 8080 # open http://localhost:8080/handover.html ``` To preview the full image: ```bash docker build -f packages/handover-doc/Dockerfile -t handover-doc . docker run --rm -p 8080:80 handover-doc # open http://localhost:8080 ```