ui-color-palette-audit-palette

Files (1)

• SKILL.md

SKILL.md (first lines)

# Audit Contrast

Use the **ui-color-palette** MCP tool `get_palette` to generate a palette with contrast data, then analyze the results for WCAG and APCA compliance.

## MCP tool reference

**Tool**: `get_palette`

**Input schema**: see `ui-color-palette-scale-palette` for full `base` and `themes` field definitions. Key requirement: every theme must have `textColorsTheme: { lightColor: "#FFFFFF", darkColor: "#000000" }` for `textContrast` to be populated.

**Always pass `compact: true`** — returns a flat array of shade rows instead of the full nested `PaletteData` tree. Each row already has `theme`, `color`, `shade`, `hex`, `contrast`, and `textContrast` at the top level. All other color space values are omitted server-side.

## Pre-computed contrast data

Each shade includes pre-computed scores. **Do NOT recalculate contrast — just read the values.**

**Do NOT read `shade.contrast`** (shade vs palette background) — this skill only uses `shade.textContrast` (light/dark text on shade).

### `shade.textContrast` — light & dark text on shade (requires `textColorsTheme` set in theme)

| Field | Path | Type | Description |
| ----- | ---- | ---- | ----------- |
| WCAG light ratio | `textContrast.wcag.light.ratio` | number | White text on shade |
| WCAG light score | `textContrast.wcag.light.score` | `"A"` \| `"AA"` \| `"AAA"` | WCAG level |
| WCAG dark ratio | `textContrast.wcag.dark.ratio` | number | Black text on shade |
| WCAG dark score | `textContrast.wcag.dark.score` | `"A"` \| `"AA"` \| `"AAA"` | WCAG level |
| APCA light Lc | `textContrast.apca.light.lc` | number | White text Lc |
| APCA light usage | `textContrast.apca.light.recommendedUsage` | string | Recommended usage |
| APCA dark Lc | `textContrast.apca.dark.lc` | number | Black text Lc |
| APCA dark usage | `textContrast.apca.dark.recommendedUsage` | string | Recommended usage |

## Audit dataset

With `compact: true`, the API already returns a flat array — one object per shade. No transformation needed before Step 3.

### Row schema

Each row in the flat array has these fields:

| Column | Source path | Description |
| ------ | ----------- | ----------- |
| `theme` | Theme label |
| `color` | Color family name |
| `shade` | Shade label |
| `hex` | Display color |
| `textContrast.wcag.light.ratio` | White text WCAG ratio |
| `textContrast.wcag.light.score` | White text WCAG level |
| `textContrast.wcag.dark.ratio` | Black text WCAG ratio |
| `textContrast.wcag.dark.score` | Black text WCAG level |
| `textContrast.apca.light.lc` | White text APCA Lc |
| `textContrast.apca.light.recommendedUsage` | White text recommendation |
| `textContrast.apca.dark.lc` | Black text APCA Lc |
| `textContrast.apca.dark.recommendedUsage` | Black text recommendation |
| `best_text` | derived — `LIGHT` or `DARK` |
| `wcag_pass` | derived — `true` if light or dark passes AA |
| `apca_pass` | derived — `true` if light or dark has `|Lc| >= 60` |
| `global_pass` | derived — `true` if `wcag_pass` and `apca_pass` |

### CSV-like representation

Prefer producing or reasoning from a compact CSV-like block instead of the original nested JSON:

```csv
theme,color,shade,hex,wcag_light_ratio,wcag_light_score,wcag_dark_ratio,wcag_dark_score,apca_light_lc,apca_light_usage,apca_dark_lc,apca_dark_usage,best_text,wcag_pass,apca_pass,global_pass
Light,primary,50,#F8FAFC,1.07,A,17.58,AAA,-4.2,AVOID,106.0,FLUENT_TEXT,DARK,true,true,true
Light,primary,100,#E2E8F0,1.32,A,13.16,AAA,-11.5,AVOID,95.2,FLUENT_TEXT,DARK,true,true,true
```

This flattened representation is the preferred input for audit reasoning, summary statistics, and visualization.

## Standards

- **WCAG 2.1**: Contrast ratios — AA requires 4.5:1 for normal text, 3:1 for large text; AAA requires 7:1 / 4.5:1
- **APCA**: Lightness contrast (Lc) values — minimum Lc 60 for body text, Lc 45 for large text, Lc 30 for non-text

## Workflow

### Step 0 — Check session state (free)

**Before calling any tool**, check whether a `PaletteData` slot is already populated in the conversation context (e.g. produced by `ui-color-palette-scale-palette` in the same session).

- If a compact flat array (from a previous `get_palette` call with `compact: true`) is present → **skip to Step 3**. No API call needed.
- If only `base` + `themes` are present (no palette data) → continue to Step 1.
- If nothing is present → ask the user for the source (palette config, hex colors, or palette ID).

### Step 1 — Scope the audit (before calling the API)

Determine the minimum configuration required. Do not pass more themes than necessary.

Ask (or infer from context):

> Which theme do you want to audit?
> - **Light** (recommended)
> - **Dark**
> - **Both**
> If you do not answer, I will audit **Light** only.

If the user has multiple color families and only cares about a subset, ask which ones — otherwise include all.

**Important**: Pass only the scoped themes in the `themes` array. Removing unused themes significantly reduces the `get_palette` response size.

### Step 2 — Call `get_palette` (targeted)

Call `get_palette` with:
- The full `base` configuration (unchanged)
- Only the **selected theme(s)** in `themes` (not the full list if more exist)
- Ensure every theme has `textColorsTheme` set (e.g. `{ lightColor: "#FFFFFF", darkColor: "#000000" }`) — required for `textContrast` to be populated
- **`compact: true`** — mandatory for this skill; returns a flat array and omits all raw color values

### Step 3 — Python extraction

The `compact: true` response is already a flat array — no traversal needed. Pass it directly to Python to produce the audit CSV.

```python
import json, sys

data = json.load(sys.stdin)  # flat array of shade rows

FIELDS = [

From a-ng-d/claude-ui-color-palette, MIT.

More from a-ng-d/claude-ui-color-palette