# Semantic Color Tokens

## Objective

Name colours by the job they do, so changing a theme is one edit rather than a sweep.

A vocabulary of role-named colour tokens — surface, text, border, accent, danger, success — that components reference instead of literal values.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inventory every literal colour value in the codebase and group them by the job they are doing rather than by the shade they happen to be. Two different greys used as card backgrounds are one role; the same grey used as a background and as a border is two.
2. Define the role names once and map each role to a value per theme. A role may resolve to a light grey in one theme and a near-black in another; what must not change is which components reference it.
3. Stop shared components accepting raw colour values. A primitive that takes a hex string as a prop guarantees that some product screen will hardcode a colour the themes never learn about.
4. Separate decorative colour from semantic colour explicitly — a chart series, an avatar fallback, and a category tag are decorative and may cycle freely, while danger and success carry meaning and must never be reassigned for visual variety.
5. Migrate the legacy palette names through an alias layer that maps each old name to its new role, mark the aliases deprecated, and remove them once usage reaches zero. Do not rename in place across the codebase in one commit; anything you miss fails silently as an unresolved variable.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A role must map to a different value in each theme, and the mapping must be complete — a role defined only for light mode leaves components with an unresolved value in dark mode, which usually renders as fully transparent or as the inherited parent colour.
- Shared components must reject raw hex values outright rather than passing them through, because a single accepted literal is invisible to every theme that follows.
- Decorative colour and semantic colour must stay separate. Reusing the danger token as the sixth chart series means a routine chart makes users read failure into ordinary data.
- Legacy palette names have to be migrated through an alias layer with a deprecation window, since a direct rename breaks any reference the search missed and does so without an error.
- Roles proliferate quietly. Without a rule for when a new role is justified, the set drifts into forty near-identical names and the abstraction stops paying for itself.
- Third-party and embedded UI will not honour the tokens; decide whether to theme it through its own configuration or accept that it looks foreign, but do not fork it.
- The underlying colour space and ramp generation belong to OKLCH Theme Tokens — this brief owns only the names and the per-theme mapping, and must not restate the maths.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] No shared component contains a literal colour value.
- [ ] Every role resolves to a defined value in every theme, with no unresolved references.
- [ ] Decorative and semantic colours are separately named and separately governed.
- [ ] Legacy palette names resolve through documented aliases marked as deprecated.
- [ ] A theme change requires editing the role mapping only, not any component.
- [ ] The rule for introducing a new role is written down.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.