# 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 a **9-stop scale** (50 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 9-Stop Scale Structure

| Stop | Name | Primary Role | Text Use |
|------|------|-------------|----------|
| 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.

- **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 |
|------|--------------|---------|
| 50–300 | No requirement | Background 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 9-stop scale based on its brightness and saturation:
- Near-white, very light → 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, 50 to 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.
- **Do not** use 50–400 as text colors, even if they technically pass contrast on a dark background. They are background-only tones in this system.
- **Do not** skip the 600 stop. It is the resting state for primary buttons — the 500 stop is hover (lighter) and 700 is pressed (darker).
- **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 9 stops. A 3-color or 6-color scale is always considered incomplete in this system.

---

## Reference: Existing Scales

Use these as ground truth when evaluating whether a new scale feels consistent.

### Blue
| Stop | Hex |
|------|-----|
| 50 | `#F1FEFF` |
| 100 | `#E0F1F4` |
| 200 | `#BFDFE6` |
| 300 | `#9FCEDB` |
| 400 | `#6BAFC4` |
| 500 | `#047897` |
| 600 | `#025F78` |
| 700 | `#054F6A` |
| 800 | `#044055` |
| 900 | `#03303F` |

### Pink
| Stop | Hex |
|------|-----|
| 50 | `#FFF9FF` |
| 100 | `#FAD0F5` |
| 200 | `#EAC3E4` |
| 300 | `#DC9ED3` |
| 400 | `#CB62BB` |
| 500 | `#A81696` |
| 600 | `#8A1079` |
| 700 | `#6C0B5E` |
| 800 | `#55094B` |
| 900 | `#3E0638` |

### Orange
| Stop | Hex |
|------|-----|
| 50 | `#FFF9F5` |
| 100 | `#FAEADE` |
| 200 | `#EED4BF` |
| 300 | `#D4A482` |
| 400 | `#BF7D4E` |
| 500 | `#7F4308` |
| 600 | `#632F03` |
| 700 | `#451E01` |
| 800 | `#361601` |
| 900 | `#270E00` |

---

## Quick Checklist

Before finalizing any new scale, confirm:

- [ ] All 10 stops are present (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