Shade Library User Guide

The Shade Library is a searchable, export-ready browser for generated shade systems. It is available at /library/shades/ and loads /data/shade-gen/shades.json, the public dataset generated by @auric-artisan/shade-gen.

Each shade system is a small design-system candidate: a base color, a generation method, a set of token names and a matching list of colors. The browser enriches those compact records with RGB, CIE Lab, OKLCH, WCAG contrast, average lightness, average chroma, hue spread, quality score, copy tools and export tools.

• Primary route: /library/shades/.
• Main data: /data/shade-gen/shades.json.
• Manifest: /data/shade-gen/index.json.
• Current public count: 8,192 generated shade records.
• Step range: shade systems in the public dataset contain 5 to 21 color tokens; the generator supports 2 to 64.
• Common uses: product themes, Tailwind scales, neutral systems, UI surfaces, data visualization ramps and brand-adjacent color systems.

Open Shade Library. All seven tabs are always available: Library, Inspect, Harmony, Accessibility, Stats, Export and Saved.

1. Use the main search field to find a color, method, token or shade name.
2. Click a card to open the Inspect panel.
3. Use filters to narrow the results by hue, chroma, lightness and method.
4. Open the Harmony, Accessibility, Stats, Export and Saved tabs for analysis, export and saved collections.
5. Copy or download the shade system in the format your project needs.

Press / to focus the search field without leaving the keyboard.

The Library tab uses a card grid. Each card shows a strip of swatches labelled with token and HEX, the shade id, the generation method and Inspect, Copy and Save buttons. Swatches are not just decorative: click any swatch to copy its HEX value.

• Main search: searches across every matching shade in the dataset.
• Result search: filters inside the current library results using the same search terms.
• Shuffle: sets random sort and reorders the visible result set.
• Random: opens a random shade system in Inspect.
• Scrolling: the grid scrolls through every match; the counter below it shows the range in view, and Back to top returns to the start.

Search text is built from shade id, name, base HEX, method, token names and color HEX values. That means a query such as material-like 500, #ff724c, neutral or 950 can find useful matches.

The filter row lets you move from broad exploration to practical design-system selection.

Use Reset when a search or filter stack becomes too narrow. The Library tab badge shows how many shades currently match the active filters.

Inspect is the most important panel for deciding whether a shade scale is useful. It opens when you click a card, press Enter or Space on a focused card, or use Random.

• Shade strip: shows each token with an automatic readable text color.
• Summary cards: show id, index, method, base, token count, average lightness, average chroma, hue span, score, auto-AA token count and minimum adjacent contrast.
• Per-token cards: show HEX, RGB, OKLCH, CIE Lab, WCAG contrast against white and black, plus copy pills.
• Contrast ladder: previews the text color the runtime would choose for each shade token.
• Quick export: gives immediate access to copy, download, save, share and design token actions.

The runtime names colors from OKLCH tone, chroma and hue. These generated names are useful as scan labels, but your exported token names should still follow your product naming system.

Shade Library computes WCAG-style contrast ratios for every token against white and black. It also counts how many tokens can reach AA when the browser chooses the better automatic text color for each token.

• Auto AA tokens: tokens where either white or black text reaches at least 4.5:1 contrast.
• White coverage: tokens where white text reaches at least 4.5:1.
• Black coverage: tokens where black text reaches at least 4.5:1.
• Minimum adjacent contrast: the smallest contrast ratio between neighboring swatches in the shade strip.
• All-token candidates: shade systems where every token has an automatic AA text option.

Accessibility data is a fast triage layer, not a final design approval. Always test your real text size, font weight, component state, overlay, background and brand constraints before shipping.

The Harmony, Accessibility, Stats, Export and Saved tabs turn the Shade Library from a browser into a review workstation.

These panels use every shade that matches the current search and filters, not necessarily the whole dataset. Refine filters first, then use Harmony, Accessibility and Stats to compare a meaningful subset.

The Shade Library supports two export scopes: the active selected shade and the filtered results, every shade system that matches the current search and filters.

CSS variable exports use a slug based on the shade name. For production systems, rename the prefix to match your component or brand namespace before committing.

The Save action pins a shade system in the current browser and mirrors it into the shared Library workspace. The Saved tab is local-first, while the workspace provides a broader library view with previews.

• Local saved ids: stored under aa.shades.saved.
• Workspace domain: shades.
• Workspace tool id: library-shades.
• Share type: shade.
• Shared payload: shade id, name, method, colors and tokens.

Share links are best for returning to an exact generated shade id in the current public dataset. If the public dataset is regenerated with different ids or colors, old shared ids may no longer resolve to the same record.

The page uses generated Shade Gen data rather than creating new shades in the browser. The manifest currently records source: "@auric-artisan/shade-gen", count 8192, seed 20260514, format json, method mixed and steps mixed.

Compact records use short keys such as id, n, b, m, t, c and s. The runtime normalizes those into readable shade objects before rendering.

• Start broad with hue and method filters, then narrow by chroma and lightness.
• Use score as a triage signal, not as the only decision factor.
• Use accessible-ui and neutral-system when interface contrast and surfaces matter more than brand saturation.
• Use tailwind-like or material-like when matching common design system expectations.
• Check both white and black contrast before using a token for foreground text.
• Rename exported variables before shipping so token names describe product purpose, not only color position.
• Save promising systems before changing filters if you are comparing multiple candidates.
• Use SVG or PNG strips for review conversations, and use JSON or CSS for implementation.

For generator internals, see the Shade Gen Developer Reference. For this browser's implementation, see the Shade Library Developer Reference.