46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
# UI Change Playbook
|
|
|
|
Use this when an agent changes layout, navigation, shell, buttons, dialogs, inputs, tables, feedback UI, or any `apps/web/app/components/ui` primitive.
|
|
|
|
## First Reads
|
|
|
|
1. `docs/ui-inventory/surface-map.md`
|
|
2. `docs/ui-inventory/surfaces.json`
|
|
3. `docs/ui-inventory/components.json`
|
|
4. `apps/web/app/application/ui/uiRegistry.ts`
|
|
5. `docs/agent-playbooks/ui-adapter-migration.md` if the change touches `packages/ui`
|
|
|
|
## Agent Workflow
|
|
|
|
1. Identify the target by `data-ui-id`, not by visual guesswork.
|
|
2. Find the source file in `docs/ui-inventory/surfaces.json` or `components.json`.
|
|
3. Check whether the change is a surface change, component primitive change, or feature-specific UI change.
|
|
4. Preserve or add stable `data-ui-id` attributes for user-visible surfaces and actions.
|
|
5. Update `docs/ui-inventory/components.json` when adding root UI primitives.
|
|
6. Update `docs/ui-inventory/surfaces.json` when adding or renaming surfaces/actions/navigation IDs.
|
|
7. Add or update DOM tests for important `data-ui-id` behavior.
|
|
|
|
## Rules
|
|
|
|
- Do not add sidebar/nav items without stable IDs.
|
|
- Do not add dynamic UI items without `uiIdPattern` and `uiIdParams`.
|
|
- Do not move app components into `packages/ui` unless the adapter migration playbook says the category is ready.
|
|
- Do not change `packages/ui` exports in a way that imports app runtime or React components unless that migration phase explicitly owns it.
|
|
- Do not rely on visible text alone to locate UI in agent instructions; prefer `data-ui-id`.
|
|
|
|
## Common Requests
|
|
|
|
- "Change the app sidebar": start with `ui.surface.app.sidebar`.
|
|
- "Change admin sidebar settings": start with `ui.nav.admin.settings`.
|
|
- "Change header search": start with `ui.action.shell.search`.
|
|
- "Change header right actions": start with `ui.surface.shell.navActions`.
|
|
- "Change page content shell": start with `ui.surface.shell.main`.
|
|
|
|
## Done Criteria
|
|
|
|
- Target UI ID still exists in rendered DOM.
|
|
- New UI IDs are listed in `surfaces.json` when stable.
|
|
- Root primitives are listed in `components.json`.
|
|
- Tests cover changed registry, inventory, or DOM behavior.
|
|
|