Bind palette roles to stable colors and export semantic tokens

[Artsen]

Summary

• Bind active role assignments to stable palette color IDs so duplicate HEX colors can own different roles and assignments survive reorder, rename, and value edits.
• Upgrade saved palettes and portable ColorCraft JSON to schema version 3 with deterministic legacy migration.
• Add semantic CSS and Tailwind role tokens plus accessible SVG role annotations.
• Extend unit, migration, browser, axe, and deterministic screenshot coverage for identity-safe role workflows.

Contract effects

Internal workspace

• RoleAssignments changes from role-to-HEX references to role-to-PaletteColor.id references.
• Role selectors use stable IDs while showing name-, HEX-, and position-aware labels.
• Contrast and previews resolve current colors by ID; missing IDs are pruned deliberately.

Internal persistence

• Saved-palette schema version 2 becomes version 3.
• Version 2 and older records remain readable and migrate to ID-based role assignments.
• Legacy duplicate-HEX roles map deterministically to the first matching color in palette order; roles with no match are discarded.
• Duplicating a saved palette creates all-new color IDs and remaps every copied role to the corresponding duplicate.

Portable JSON

• New exports use schema version 3 and format: "colorcraft-palette".
• Colors gain deterministic document-local keys (color-1 through color-10), and roleAssignments references those keys.
• Internal workspace IDs, storage metadata, and source-image bytes remain excluded.
• Versions 1 and 2 remain importable. Their HEX-based duplicate-color roles use the documented first-match compatibility rule.

Generated exports

• CSS retains base --color-* values and adds assigned --role-* aliases that reference the correct deduplicated base token.
• Tailwind retains palette keys and adds assigned role-* semantic keys in canonical role order.
• SVG rows retain escaped name/HEX labels and measured black-or-white text while adding role annotations and useful group labels.

Backend API

• No endpoint, request, response, schema, port, or analysis algorithm changes.
• Analysis and suggestion requests continue to send only HEX, RGB, and HSL values; IDs, names, portable keys, and roles stay browser-side.

Validation

• python check.py: passed
  • frontend: 21 files, 114 tests passed
  • frontend coverage: 92.10% statements/lines, 85.23% branches, 74.44% functions
  • backend: 78 tests passed
  • backend coverage: 86%
  • Playwright: 6 workflows passed, including the duplicate-color identity round trip
  • axe: no serious or critical violations in the covered representative states
  • Prettier, ESLint (zero warnings), TypeScript, production build, Ruff, and mypy passed
• pnpm review:screenshots: passed; 16 deterministic screenshots generated
• git diff --check: passed

Remaining compatibility limitation

Portable versions 1 and 2 and saved schema version 2 identify roles by HEX. If those older records contain duplicate HEX colors, the original owner cannot be recovered; import/migration therefore binds the role to the first matching color in palette order.