Gradient Library User Guide

The Gradient Library is the public browser for the generated Auric Artisan gradient dataset. It lives at /library/gradient/ and loads /data/gradient-gen/gradient-index.json, a compact index of the collection generated from @auric-artisan/gradient-gen; a gradient's full generator metrics load from a detail file when you open it.

The page is built for design-system work, visual exploration and implementation handoff. You can scan the whole collection, inspect individual gradients, test readable text, preview color vision filters, save candidates and export both single gradients and filtered sets.

• Primary route: /library/gradient/.
• Main data: /data/gradient-gen/gradient-index.json.
• Current count: 8,192 generated gradients.
• Methods: analogous, aurora, chaotic, complementary, duotone, golden, monochrome, nebula, prismatic, spectral, terrain and thermal.
• Stop range: 2 to 46 color stops.
• Best use cases: hero backgrounds, product surfaces, visual systems, editorial palettes, wallpaper assets, theme studies and reusable design tokens.

Open Gradient Library. Every tab is available from the start: Library, Inspect, Vision, Accessibility, Pair, Tags, Stats, Export and Saved.

1. Browse the grid or press / to focus search.
2. Use filters when you need a method, complexity level, stop count, interpolation space, easing curve, score band or banding risk.
3. Select a card to inspect its stops, CSS and generator metrics.
4. Open Vision and Accessibility before placing text or UI on top of the gradient.
5. Export a selected gradient, export the visible filtered set or save it to the workspace.

Above the collection, Will your gradient band? takes up to 12 stops of your own, samples the ramp the way a browser paints it and says whether any transition, measured in OKLab, is large enough to read as a step, and where.

The Library tab shows gradient cards in one continuous scroll. Each card is keyboard focusable and opens Inspect with Enter, Space or click.

• Preview: shows the CSS linear gradient using the stored angle and stops.
• Name: includes the generation method, complexity and sequence number, such as Aurora Simple #00001.
• Stop strip: shows representative stops when a gradient has many colors.
• Score chip: shows the generated quality score.
• CSS action: copies the full CSS gradient.
• Save action: pins the gradient locally and mirrors it to the Library workspace.

The counter under the grid shows which cards are in view, and Back to top returns to the start. The Open a random gradient button opens one from the full collection in Inspect. Shuffle changes the visible order by setting sort to random.

Search matches gradient name, type, angle, stop HEX values, scheme, method, complexity, interpolation, easing and banding metadata. The result search field filters within the same dataset, so you can combine broad search with precise filters.

Inspect turns a card into a technical report. It shows the full preview, CSS, stop list, generator metadata and quick exports.

• Quick metrics: type, angle, stop count, method, complexity, score, interpolation space, easing, banding, white text minimum, black text minimum and dominant hue.
• CSS panel: shows the exact linear-gradient() string and copy, CSS download and SVG download actions.
• Color stops: lists every stop with index, swatch, HEX and percent position.
• Generator metrics: exposes scheme, interpolation, easing, sample count, complexity score, Delta E mean, uniformity, banding and seed.
• Quick export: downloads JSON, Tailwind, PNG, share links, design tokens and saved state from the selected gradient.

Use Inspect when a gradient looks promising but needs implementation details. The CSS string is already ordered by stop position and normalized for browser use.

The Vision panel renders the active gradient through SVG filters so you can catch gradients that collapse under common color vision conditions.

• Normal: original gradient.
• Deuteranopia: green-insensitive simulation.
• Protanopia: red-insensitive simulation.
• Tritanopia: blue-yellow simulation.
• Achromatopsia: grayscale simulation.
• Low Vision: blur plus reduced saturation.

These previews are screening tools. They help identify risk before a formal accessibility review, especially when gradients communicate status, direction or category.

The Accessibility panel samples the selected gradient across the ramp and computes WCAG-style contrast against white, black and automatic text choice.

• White text min: weakest contrast sample for white text.
• Black text min: weakest contrast sample for black text.
• Auto text min: contrast after choosing white or black per sample.
• Adjacent stop min: lowest contrast between neighboring stored stops.
• AA-safe samples: count of sampled positions where auto text reaches 4.5:1.
• Sampled stops: 17 evenly spaced samples with HEX and best white/black contrast.

Gradients often pass in one area and fail in another. Treat the weakest sampled region as the design constraint, not the average or the most attractive region.

Pair is a practical typography test. Choose a text color with the color input, HEX input or quick buttons for white, black and gold.

• The preview places real copy over the active gradient.
• The result panel reports minimum contrast, average contrast, text color and a status message.
• A minimum of 4.5:1 means sampled normal text passes AA across the whole ramp.
• A minimum from 3:1 to 4.49:1 means large text may work in weaker regions.
• A minimum below 3:1 usually needs an overlay, shadow, different text color or a different gradient.

Pair is the fastest way to decide whether a gradient can be a real content surface or should remain decorative.

Tags and Stats are exploratory panels for understanding the full dataset or the current filtered result set.

• Tags: counts and clickable filters for methods, schemes, complexity levels, interpolation spaces, easing curves and banding labels.
• Stats: bar charts for methods, complexity, stop counts, interpolation, easing and score bands.
• Tag click: applies the matching filter and returns to Library.
• Filtered statistics: Stats uses the filtered set when filters are active, then falls back to the full collection.

Use these panels when you need to audit coverage, find underused interpolation spaces or prepare a curated export set.

Gradient Library supports selected-gradient exports and visible-set bulk exports.

Save pins a gradient in the current browser and mirrors it into the Auric Artisan Library workspace with a gradient preview and payload.

• Local saved key: aa.gradient.saved.
• Local saved limit: 240 gradient ids.
• Workspace domain: gradient.
• Workspace tool id: library-gradient.
• Share type: gradient.

Saved gradients appear in the Saved panel and in Library workspace. Share links resolve by gradient id against the current generated dataset.

Each gradient stores angle, type, stops, name and meta. Stops use pos, hex and optional oklch arrays. Metadata includes method, complexity, sample count, interpolation space, easing, score, complexity score, Delta E mean, uniformity, banding, CSS preview, source and seed.

• Use search when you know a method, HEX value, interpolation space or name fragment.
• Use score and banding filters together when a gradient is headed for production UI.
• Inspect stop count before using a gradient in environments that simplify CSS.
• Use Vision before encoding meaning with hue transitions.
• Use Pair before placing body copy, labels or buttons over a gradient.
• Use JSON for audits, CSS for implementation, SVG or PNG for review and Tailwind or design tokens for system work.
• Rename exported classes or tokens before shipping them in a public product system.
• Regenerate exports after the source dataset changes; share ids depend on the current collection order.

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