# UI/UX Routing Matrix

Names below identify **internal specialist modules** located at `references/modules/<name>/MODULE.md` relative to the `mcp-ui-ux` router. Load the chosen module and only its relevant linked references. External skills named here (`mcp-frontend-performance-debugger`, `mcp-browser-automation`, `mcp-master-orchestrator`) remain top-level and are invoked normally.

| Intent | Primary internal module | Entrypoint | Common secondary |
| --- | --- | --- | --- |
| Research, interviews, usability evidence | `mcp-ux-researcher` | `modules/mcp-ux-researcher/MODULE.md` | `mcp-product-experience-designer` |
| Journey, flow, information architecture | `mcp-product-experience-designer` | `modules/mcp-product-experience-designer/MODULE.md` | `mcp-forms-ux-engineer` |
| Page/component visual implementation | `mcp-ui-design-engineer` | `modules/mcp-ui-design-engineer/MODULE.md` | `mcp-responsive-ui-designer` |
| Broad read-only frontend review | `mcp-ui-ux-reviewer` | `modules/mcp-ui-ux-reviewer/MODULE.md` | module matching the highest-risk finding |
| Design tokens, components and governance | `mcp-design-system-engineer` | `modules/mcp-design-system-engineer/MODULE.md` | `mcp-css-architect` |
| Cascade, stylesheet ownership and CSS architecture | `mcp-css-architect` | `modules/mcp-css-architect/MODULE.md` | `mcp-design-system-engineer` |
| Theme model, light/dark and forced colors | `mcp-ui-theming-engineer` | `modules/mcp-ui-theming-engineer/MODULE.md` | `mcp-accessibility-auditor` |
| Font selection, loading and typography | `mcp-typography-designer` | `modules/mcp-typography-designer/MODULE.md` | `mcp-responsive-ui-designer` |
| Responsive/adaptive behavior and viewport coverage | `mcp-responsive-ui-designer` | `modules/mcp-responsive-ui-designer/MODULE.md` | `mcp-ui-design-engineer` |
| Motion, animation and interaction | `mcp-ui-motion-designer` | `modules/mcp-ui-motion-designer/MODULE.md` | `mcp-accessibility-auditor` |
| Accessibility audit and remediation | `mcp-accessibility-auditor` | `modules/mcp-accessibility-auditor/MODULE.md` | `mcp-forms-ux-engineer` |
| Forms, validation and form-state UX | `mcp-forms-ux-engineer` | `modules/mcp-forms-ux-engineer/MODULE.md` | `mcp-accessibility-auditor` |
| Data tables, grids and large datasets | `mcp-data-table-designer` | `modules/mcp-data-table-designer/MODULE.md` | `mcp-grid-ui-debugger` for runtime defects |
| SVG, icons, raster and visual-asset pipelines | `mcp-visual-assets-designer` | `modules/mcp-visual-assets-designer/MODULE.md` | top-level `svg` for technical SVG execution |
| Internationalization, locale, RTL and Unicode | `mcp-ui-internationalization` | `modules/mcp-ui-internationalization/MODULE.md` | `mcp-typography-designer` |
| Metadata, social cards and structured page metadata | `mcp-web-metadata-auditor` | `modules/mcp-web-metadata-auditor/MODULE.md` | `mcp-ui-internationalization` |
| Loading, Core Web Vitals and delivery audit | `mcp-web-performance-auditor` | `modules/mcp-web-performance-auditor/MODULE.md` | `mcp-frontend-performance-debugger` for runtime traces |
| React/Next static performance review | `mcp-react-performance-reviewer` | `modules/mcp-react-performance-reviewer/MODULE.md` | `mcp-react-ui-diagnostics` |
| React health scan and React Doctor triage | `mcp-react-ui-diagnostics` | `modules/mcp-react-ui-diagnostics/MODULE.md` | `mcp-react-performance-reviewer` |
| Bootstrap implementation or migration | `mcp-bootstrap-ui-engineer` | `modules/mcp-bootstrap-ui-engineer/MODULE.md` | `mcp-legacy-ui-modernizer` |
| shadcn/ui implementation or registry work | `mcp-shadcn-ui-engineer` | `modules/mcp-shadcn-ui-engineer/MODULE.md` | `mcp-design-system-engineer` |
| Legacy UI inventory and modernization | `mcp-legacy-ui-modernizer` | `modules/mcp-legacy-ui-modernizer/MODULE.md` | stack-specific module |
| Browser CLI and Playwright test generation | `mcp-playwright-ui-operator` | `modules/mcp-playwright-ui-operator/MODULE.md` | top-level `mcp-browser-automation` when MCP tools are available |
| UI unit/component tests with Vitest | `mcp-vitest-ui-tester` | `modules/mcp-vitest-ui-tester/MODULE.md` | top-level `mcp-browser-automation` for E2E |

## Disambiguation (overlap-prone clusters)

- **Performance (3-way).** `mcp-web-performance-auditor` = loading/delivery and Core Web Vitals audit (images, fonts, CSS, caching, third-party). `mcp-react-performance-reviewer` = React/Next static code-pattern review (bundle, re-render, hydration, server). `mcp-frontend-performance-debugger` (top-level) = reproducible runtime symptom needing traces, lifecycle ownership, leak analysis, soak.
- **Design pipeline (trio).** `mcp-ux-researcher` = evidence before design. `mcp-product-experience-designer` = pre-visual structure (IA, flows, state model). `mcp-ui-design-engineer` = visual implementation and polish. `mcp-design-system-engineer` = shared tokens/components/governance across surfaces.
- **Tokens/theme.** `mcp-css-architect` = stylesheet ownership and cascade. `mcp-ui-theming-engineer` = color schemes and theme model (light/dark/forced-colors). `mcp-design-system-engineer` = token architecture as shared governance. When two apply, route by whether the change is scoped (theming/CSS) or system-wide (design system).
- **React.** `mcp-react-ui-diagnostics` = run/triage React Doctor. `mcp-react-performance-reviewer` = manual performance rule review.
- **Tables.** `mcp-data-table-designer` = build/model tables and grids. `mcp-grid-ui-debugger` (top-level) = recurring rendering/scroll/flicker/drag/first-load bugs.

## Selection rules

1. Prefer one skill.
2. Use two only when two distinct capabilities are necessary.
3. Use three only for broad review, redesign, or explicitly multi-surface work.
4. Assign one owner for working-tree edits.
5. Use `mcp-master-orchestrator` when the program spans UI plus backend, data, infrastructure, migration, or release coordination.