HiveGrid-Wireframes/hivegrid-cloud/docs/agent-playbooks/ui-changes.md

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.