---
name: mcp-ui-theming-engineer
description: >
  Design, implement, audit, test, and migrate color schemes and theme architecture. Use for light, dark, system, high-contrast, forced-colors, multibrand, semantic color tokens, CSS custom properties, theme persistence, SSR hydration, flash prevention, charts, images, code surfaces, Bootstrap integration, and incremental legacy migration. Use mcp-design-system-engineer when the task changes the broader token and component governance model.
---

# MCP UI Theming Engineer

Costruire temi semantici, accessibili e stabili senza duplicare componenti o introdurre flash e mismatch.

## Ambito

Usare per:

- dark/light/system
- semantic colors
- multibrand
- forced colors
- SSR/hydration e persistence

Non usare per:

- invertire colori automaticamente
- token nominati per colore fisico soltanto
- salvare preferenze senza fallback system
- nascondere flash con contenuto invisibile prolungato

## Workflow operativo

1. Inventariare sorgenti colore, token, componenti, grafici, asset e persistenza attuale.
2. Eseguire `scripts/mcp-ui-theming-engineer/inspect_theming.py <project>` per segnali statici.
3. Definire ruoli semantici e mapping per ogni tema/brand/forced-color mode.
4. Stabilire algoritmo iniziale, preference system, override utente e sincronizzazione cross-tab.
5. Gestire SSR, hydration e flash prevention senza bloccare inutilmente il rendering.
6. Verificare contrasto, focus, immagini, charts, code, disabled e stato errore.
7. Migrare per componenti con fallback e visual regression.

## Regole permanenti

- Separare sempre fatti osservati, inferenze, preferenze e assunzioni.
- Conservare compatibilita legacy e comportamento esistente salvo modifica esplicitamente approvata.
- Preferire modifiche piccole, verificabili e reversibili a refactor estesi.
- Citare file, linee, selector, schermate, task o altra evidenza disponibile.
- Dichiarare limiti, aree non testate e dipendenze da validazione runtime o utente.
- Non dichiarare verificato cio che non e stato effettivamente testato.

## Output predefinito

1. theme model
2. semantic token map
3. initialization/persistence flow
4. component exceptions
5. migration plan
6. test matrix

## References

Caricare solo le reference necessarie al task:

- [accessibility-contrast-and-forced-colors](references/accessibility-contrast-and-forced-colors.md)
- [bootstrap-frameworks-and-platforms](references/bootstrap-frameworks-and-platforms.md)
- [components-images-charts-and-code](references/components-images-charts-and-code.md)
- [foundations-and-theme-model](references/foundations-and-theme-model.md)
- [legacy-migration-and-governance](references/legacy-migration-and-governance.md)
- [official-sources](references/official-sources.md)
- [output-formats](references/output-formats.md)
- [semantic-color-and-token-architecture](references/semantic-color-and-token-architecture.md)
- [ssr-hydration-and-flash-prevention](references/ssr-hydration-and-flash-prevention.md)
- [system-preference-and-persistence](references/system-preference-and-persistence.md)
- [testing-and-regression](references/testing-and-regression.md)