Contributing to the Design System Docs

These docs are a living, in-repo design system — they document app/frontend's actual token/component/pattern code, and they must evolve in the same commit as the code they describe. A doc that drifts from the implementation is worse than no doc.

The contract

  1. New tip-* component → add design-system/components/<name>.md (title, selector, API table taken verbatim from input()/output()/<ng-content select>, a short usage example, notes) and add a row to the component index tables in both design-system/README.md and README.md, in the same change that adds the component.
  2. Changed component API (input/output added, removed, renamed, or its default/type changed) → update that component's API table in the same change. Do not let the doc go stale "for now" — a wrong API table is actively misleading.
  3. New composed pattern (a new full-screen or multi-component layout convention, like Settings or Auth) → add design-system/patterns/<name>.md and link it from design-system/README.md's patterns table and README.md.
  4. Token changes (styles/tokens/*.css or the @theme block in styles.css) → update the relevant table(s) in design-system/tokens.md in the same change. If a raw scale value changes, also check the Tailwind @theme mapping in styles.css stays in sync (see conventions.md).
  5. Deleting/renaming a component or pattern → delete/rename its doc file and remove it from both index tables in the same change; don't leave orphaned doc files.

Accuracy over length

Each component doc should stay roughly 30–70 lines. The API table is the part that must be exactly right — copy input/output names, types, and defaults straight from the component source rather than paraphrasing. "Notes" should call out real gotchas (e.g. Menu's submenu overflow requirement, Save Bar's sticky positioning contract) discovered while reading the code — not restate the API table in prose.

Reviewing a PR that touches app/frontend/src/app/ui/ or features/

Before approving, check: did this PR touch a tip-* component's public API, add a new one, introduce a new screen pattern, or change a token? If yes, the matching doc under app/developer-doc/ must be part of the same PR.