# Color Scale Generation — Agent Instructions

Guidelines for generating new color scales that are consistent with this design system's existing blue, pink, and orange palettes.

---

## Overview

Every color family in this design system follows an **11-stop scale** (0 through 900) with consistent perceptual spacing, semantic role coverage, and WCAG accessibility compliance. When generating a new color scale from a seed color (or a small set of seed colors), follow the process and rules below exactly.

---

## The 11-Stop Scale Structure

| Stop | Name | Primary Role | Text Use |
|------|------|-------------|----------|
| 0 | Background | Passive, non-interactive reading surface | Never |
| 50 | Surface | Page tint, subtle background | Never |
| 100 | Subtle | Card/panel background | Never |
| 200 | Muted | Hover bg on subtle elements | Never |
| 300 | Soft | Focus rings, selected state bg, borders | Never |
| 400 | Mid | Bridges 300→500; hover on muted components | Large text only (if ≥3:1) |
| 500 | Default | Primary interactive color (buttons, links, icons) | Yes, if ≥4.5:1 on white |
| 600 | Emphasis | Hover state on primary (500) components | Yes |
| 700 | Strong | Active/pressed state; emphasis text | Yes |
| 800 | Deep | Dark-mode surfaces, deep borders, secondary ink | Yes |
| 900 | Ink | Body text, icons, dark-mode surfaces | Yes — must hit AAA |

> **Note:** Stop 800 sits between the active/pressed dark (700) and the ink tone (900). Use it for dark-mode card surfaces, deep borders, or a secondary ink tone where 700 is too light and 900 is too heavy.

---

## Perceptual Spacing Rules

The scale must feel **visually even** when displayed as a row of swatches. This is the most important rule — stops that look too similar or too far apart break the system.

- **0 → 50:** Very subtle but intentional shift from passive background to visible surface.
- **50 → 100:** Very subtle shift. Nearly indistinguishable side by side, but noticeable on different backgrounds.
- **100 → 200:** Soft step. Still light, clearly a background tone.
- **200 → 300:** Moderate step. 300 should read as "tinted" but not saturated.
- **300 → 400:** Noticeable step. 400 is where the hue starts to feel like itself.
- **400 → 500:** The largest perceptual jump is acceptable here — this is the light-to-dark threshold crossing. But it should not look like two unrelated colors.
- **500 → 600:** Small, intentional step. Side by side they should look like siblings.
- **600 → 700:** Same — small step. This is the rest-to-pressed transition on primary buttons — it should feel like a subtle physical press.
- **700 → 800:** Moderate step. 800 is noticeably darker than 700 but still retains hue identity.
- **800 → 900:** Small-to-moderate step. 900 can feel slightly more neutral/cooler but should still read as the same family.

**Red flag:** If any two adjacent stops look identical, or if any gap looks like two unrelated colors, the spacing is wrong.

---

## Contrast Requirements

Use the WCAG 2.1 contrast ratio standards against `#FFFFFF` (white):

| Stop | Minimum Ratio | Standard |
|------|--------------|---------|
| 0–300 | No requirement | Background or surface only |
| 400 | ≥ 3:1 | Large text only (or bg) |
| 500 | ≥ 4.5:1 | AA normal text |
| 600 | ≥ 7:1 | AAA preferred |
| 700 | ≥ 7:1 | AAA |
| 800 | ≥ 10:1 | AAA — between strong and ink |
| 900 | ≥ 12:1 | Strong AAA — aim for 14:1+ |

> **Orange/Yellow exception:** Warm hues in the 400 range often cannot reach 3:1 without becoming muddy. If a 400-stop warm color cannot reach 3:1, document it as background-only and ensure 500 compensates with a stronger ratio.

---

## Saturation & Tone Behavior Across the Scale

Follow these directional rules when moving through the scale:

- **50–200:** Desaturate heavily. These should feel like white with a whisper of the hue — almost neutral.
- **200–400:** Gradually reintroduce saturation. Colors become more recognizable as the hue family.
- **400–500:** Peak or near-peak saturation. This is the "true" color.
- **500–700:** Reduce brightness, maintain or slightly reduce saturation. Avoid muddy brown/gray shifts — keep the hue identity intact.
- **900:** Can shift slightly cooler or more neutral. This is an ink tone, not a vivid color. It should feel like the hue's shadow.

**Avoid:** Letting any stop drift into a neighboring hue family. A blue scale should never produce a stop that reads as purple or teal. A pink scale should never drift into red or lavender. Stay on the hue axis.

---

## Generating From Seed Colors

When given one or more existing colors to anchor the scale, follow this process:

### Step 1 — Identify the Seed's Position
Determine where the seed color belongs on the 11-stop scale based on its brightness and saturation:
- Near-white, passive background → 0
- Near-white, interactive surface → 50 or 100
- Light, clearly tinted → 100 or 200
- Medium light, some saturation → 300
- Saturated, mid-brightness → 400 or 500
- Dark, rich → 600 or 700
- Near-black → 900

### Step 2 — Anchor and Extrapolate
Lock the seed color(s) in place and generate the remaining stops by extrapolating in both directions using the perceptual spacing and saturation rules above.

### Step 3 — Verify Contrast
Check every stop from 400 upward against `#FFFFFF`. Adjust lightness until contrast targets are met. Never adjust hue to fix contrast — only adjust lightness/brightness.

### Step 4 — Name and Document
Assign stop numbers and document the role for each. Flag any stops that are new additions vs. existing colors.

---

## Output Format

When presenting a new scale, always deliver:

1. **Swatch row** — all stops displayed left to right, 0, 50, and 100 through 900, with hex codes labeled.
2. **Issues list** — any problems with the seed colors (gaps, contrast failures, redundancy).
3. **Contrast table** — ratio vs. white for each stop, with AA/AAA pass/fail.
4. **Gap visualization** — a horizontal bar showing where missing stops fall between existing ones.
5. **Semantic token map** — three groups: Surfaces & Backgrounds, Interactive States, Text & Icons.
6. **TL;DR table** — a compact table listing only the new colors being added, with hex, role, and contrast ratio.

---

## Common Mistakes to Avoid

- **Do not** create two stops that are perceptually identical. Consolidate and use the freed slot for a missing mid-tone.
- Select foregrounds using the current theme’s semantic mappings and measured contrast; light-background scale roles do not ban light foregrounds in dark mode.
- **Do not** skip the 600 stop. Primary button states follow the current semantic mapping rather than a fixed scale-stop sequence.
- **Do not** use the 900 stop for anything other than text, icons, or dark-mode surfaces. It is too dark to use as a UI color.
- **Do not** change the hue angle to fix a contrast problem. Only adjust lightness. Hue drift breaks the color family's identity.
- **Do not** generate a scale with fewer than 11 stops. A 3-color or 6-color scale is always considered incomplete in this system.

---

## Reference: Existing scales

Use [the shared primitive palette](../../../../shared/colors/primitives.json) for exact current values, and [the color guide](../color.md) for semantic roles and light/dark mappings. Do not maintain a second palette table here.

Generation thresholds below/above describe new scale construction; they do not override approved theme mappings. Light stops can be foregrounds on dark backgrounds when the semantic map selects them and actual contrast passes. Primary button state mappings come from semantic tokens, not a fixed stop sequence.

---

## Quick Checklist

Before finalizing any new scale, confirm:

- [ ] All 11 stops are present (0, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900)
- [ ] No two adjacent stops look perceptually identical
- [ ] No gap between adjacent stops looks like two unrelated colors
- [ ] 50–300 are clearly background-only (light, low contrast)
- [ ] 500 achieves ≥ 4.5:1 on white
- [ ] 600 achieves ≥ 7:1 on white
- [ ] 700 achieves ≥ 7:1 on white
- [ ] 800 achieves ≥ 10:1 on white
- [ ] 900 achieves ≥ 12:1 on white
- [ ] Hue identity is consistent across all stops — no drift into neighboring hue families
- [ ] Semantic token map covers: surfaces, interactive states, and text/icons
