# 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.