ui-implementation
Use when implementing UI behavior, state, loading/error handling, actions, or accessibility behavior.
Procedure
- Read
docs/adr/0010-interface-governance.md,docs/ui/README.md,docs/adr/0017-discoverability-and-meta-code-routing.md,docs/ui/visible-surfaces.inventory.json, and the relevant pattern manifest. - Declare the mutation class. Non-authorized agents may proceed only for
functional-uior governance/tooling work. - Declare the UI governance evidence before editing:
- mutation class,
- pattern IDs or debt/protected/exception mapping,
- touched files and visible surfaces,
- required interactive states,
- accessibility governance evidence,
- public checks to run.
- Keep visual shape stable. Do not change colors, spacing, typography, icons, layout, hierarchy, animations, or visible copy unless explicitly authorized.
- For accessibility-impacting UI, read
docs/adr/0029-accessibility-governance.mdand declare affected axes, surface mapping, generated UI status, and private/manual evidence aliases. - If a guard reports out-of-scope visual debt, list it as pending. Do not fix it in the current change.
- For visual/copy/layout work without authorization, fill
docs/ui/visual-change-proposal.template.mdas a conceptual proposal and stop before editing presentation. - Register any new durable UI governance artifact, guard, harness, docs router,
or skill in
docs/discoverability.registry.jsonso future agents can reach it within two hops. - At task closure, validate against the task's starting commit by setting
CLAWIX_UI_GUARD_DIFF_BASE=<task-base>. Useorigin/mainonly when the task is explicitly PR, release, or historical-audit scope; classify those findings separately from local closure. - Run
node scripts/ui_governance_guard.mjs,node scripts/accessibility_governance_guard.mjs, the relevant UI governance checks, and the focused functional tests.
Constraints
- No opportunistic visual cleanup.
- No protected-surface edits without explicit permission.
- Mechanical extraction requires before/after equivalence evidence.
- UI comments are not canonical; durable UI decisions must point to ADRs, docs, registries, manifests, or tests.
- Do not finish a UI task without reporting the pattern/debt/protected mapping and state coverage that were validated.