Gradient Library Developer Reference

Gradient Library is a static HTML route plus an ESM browser runtime. The page shell declares SEO, structured data, application containers, SVG color-vision filters, tabs, form controls and shared Auric Artisan UI chrome. The runtime fetches a compact index of the generated data, normalizes each gradient, renders the card grid and powers advanced analysis panels.

• Page shell: library/gradient/index.html.
• Runtime: library/gradient/gradient-library.js.
• Data URL: /data/gradient-gen/gradient-index.json, with detail shards at /data/gradient-gen/detail/NN.json.
• Saved key: aa.gradient.saved.
• Share type: gradient.
• Workspace domain: gradient.

• Canonical: https://auricartisan.com/library/gradient/.
• Preload: /data/gradient-gen/gradient-index.json as fetch.
• Structured data: Dataset, CollectionPage, ImageObject and BreadcrumbList.
• Shared styles: main, unified, dark-mode and gradient-library CSS.
• Route inline script: /js/generated-inline/771583026d107068e662.js.
• Chrome: header, time, announcement, custom cursor, scroll rail, loader, eye-rest panel, footer, idle layer and generated scripts.
• Application panels: Library, Inspect, Vision, Accessibility, Pair, Tags, Stats, Export and Saved.

The route also defines SVG filters for deuteranopia, protanopia, tritanopia, achromatopsia and low-vision previews. Those filter ids are referenced from the Vision panel.

loadData() fetches INDEX_URL, /data/gradient-gen/gradient-index.json, with cache: "force-cache". fromIndexRow() rebuilds each row into the shape below, deriving OKLCH from the HEX. Sample count, complexity score, Delta E mean, uniformity and seed are not in the index: fullGradient() fetches them from /data/gradient-gen/detail/NN.json, one shard per 256 gradients, when a gradient is opened.

{
  "angle": 0,
  "type": "linear",
  "stops": [
    {
      "pos": 0,
      "hex": "#723C2D",
      "oklch": [0.4204, 0.08, 36.4]
    },
    {
      "pos": 1,
      "hex": "#7B3600",
      "oklch": [0.4194, 0.1115, 49.6]
    }
  ],
  "name": "Aurora Simple #00001",
  "meta": {
    "scheme": "Aurora",
    "method": "aurora",
    "complexity": "simple",
    "stops": 2,
    "sample_count": 96,
    "interpolation_space": "oklch-short",
    "easing": "linear",
    "score": 0.4045,
    "complexity_score": 0.1005,
    "deltaE_mean": 0.1732,
    "uniformity": 0.0391,
    "banding": "smooth",
    "css_preview": "linear-gradient(0deg, #723c2d 0%, #7b3600 100%)",
    "source": "@auric-artisan/gradient-gen",
    "seed": 20260514
  }
}

normalizeGradient() assigns a one-based _id, stores generated CSS in _css, sorts and clamps stops, uppercases stop HEX values and computes internal search text, stop count, score, complexity score, dominant hue, average lightness, average chroma, minimum white contrast and minimum black contrast.

{
  all: [],
  filtered: [],
  page: 0,
  active: null,
  pairText: "#ffffff",
  panelsRendered: {
    vision: false,
    accessibility: false,
    pair: false,
    tags: false,
    stats: false,
    export: false,
    saved: false
  },
  progress: {
    browse: false,
    inspect: false,
    vision: false,
    pair: false,
    export: false
  }
}

1. Resolve DOM nodes into els.
2. Attach search, filter, back-to-top, card, panel, export and pair listeners.
3. Call setMode("advanced"), a no-op kept for the old mode buttons: every tab is visible.
4. Call loadData().
5. Normalize all gradient records and populate dynamic method, scheme, interpolation and easing filters.
6. Hand the filtered set to the virtual grid, update badges, render Saved and register the gradient share handler.

• parseHex(), rgbToHex() and relLuminance() power sampled color conversion and WCAG-style contrast.
• contrastRatio() computes relative-luminance contrast for pairs.
• textOn() chooses near-black (#111111) or white text at a relative luminance threshold of 0.45.
• sortedStops() and cssFromStops() keep stop order and CSS output deterministic.
• cssGradient() prefers meta.css_preview when available.
• representativeStops() samples a manageable stop strip for dense gradients.
• sampleGradient() linearly interpolates RGB across stops for accessibility and pair checks.
• dominantHue() and averageStopValue() derive search and sort metrics from stop OKLCH values.
• minContrastAgainst() samples 24 positions against a fixed text color.
• adjacentStopContrast() checks contrast between neighboring stored stops.

The runtime does not re-run the generator. It analyzes the generated site-compatible output in the browser.

Search is debounced at 120 ms. Reset clears all filters, restores original sort and re-renders from the top of the grid.

• renderGradientCard() builds a focusable card with preview, name, scheme, interpolation, representative stop strip, score chip, CSS action and Save action.
• handleCardClick() routes card-level CSS copy, Save and selection actions.
• selectGradient() sets state.active, renders Inspect, invalidates derived panels and marks the Inspect flow step complete.
• Keyboard Enter or Space on a focused card opens Inspect.
• Pressing / focuses the main search input unless an input or textarea is active.
• Panel headers toggle a collapsed class on advanced cards for dense technical views.
• setMode() no longer hides anything: every panel is reachable from its tab.

• cleanGradient() returns angle, type, sorted stops, name and metadata for JSON export.
• cssClassFor() writes a slugged .aa-gradient-... background class.
• tailwindTokenFor() writes a quoted Tailwind-friendly token value.
• gradientToSvg() creates a 1440 x 900 SVG with a linearGradient definition.
• exportGradientPng() paints the gradient to a 1600 x 1000 canvas and downloads a PNG blob.
• exportGradient() routes selected CSS copy, CSS file, JSON, SVG, Tailwind, PNG, share and token-dialog actions.
• exportBulk() routes visible-set JSON, minified JSON, CSS, CSV and Tailwind output.
• csvFor() writes id, name, type, angle, stops, scheme, method, complexity, interpolation, easing, score, complexity score, banding and CSS.

{
  "exported_at": "2026-05-26T00:00:00.000Z",
  "source": "Auric Artisan gradient-gen",
  "count": 48,
  "gradients": [
    {
      "angle": 0,
      "type": "linear",
      "stops": [
        {
          "pos": 0,
          "hex": "#723C2D",
          "oklch": [0.4204, 0.08, 36.4]
        }
      ],
      "name": "Aurora Simple #00001",
      "meta": {}
    }
  ]
}

• getSavedIds() reads aa.gradient.saved and returns numeric ids.
• toggleSaved(id) stores up to 240 ids and updates the card, Inspect and Saved panel state.
• mirrorSave() stores domain gradient, asset type gradient, tool id library-gradient, gradient CSS, stops and payload.
• mirrorRemove() removes the mirrored workspace item when a saved gradient is toggled off.
• shareGradientLink() calls shareViaDialog() with type gradient.
• registerShareHandler("gradient", hydrateFromSharedGradient) opens a matching gradient by id from shared payloads.
• openTokensDialog() uses a slugged gradient name and tokensFromGradient() for the selected gradient.

Shared payloads include id, name, CSS, stops and method. Hydration resolves by numeric one-based id against state.all. If the source dataset order changes, old share ids may resolve to different gradients.

• The app container uses role="application".
• Tabs use role="tablist", role="tab", aria-selected and aria-controls.
• Panels use role="tabpanel" with matching labels.
• The toast uses role="status" and aria-live="polite".
• Cards support click plus keyboard activation with Enter and Space.
• Vision filters are visual previews, while Accessibility and Pair provide numeric contrast support.

• The compact index is fetched once with cache: "force-cache" and normalized in memory; a detail shard is fetched only when one of its gradients is opened.
• The virtual grid keeps one screenful of cards in the DOM and recycles rows as you scroll.
• Advanced panels render lazily when their tabs are selected.
• Stats invalidate when filters change because the filtered set changes.
• Accessibility and Pair sample the active gradient instead of every gradient.
• SVG and PNG exports create object URLs and revoke them after download.
• Large visible-set exports depend on the current filtered set; keep page interactions responsive before expanding export scope.

• Keep route metadata, hero count, documentation and data/gradient-gen/index.json aligned when the generated dataset changes, and rerun scripts/generate-gradient-index.mjs to rebuild the index and detail shards.
• Update dynamic filter documentation when methods, interpolation spaces, easing curves, complexity labels or banding labels change.
• Validate share hydration when changing _id, dataset order or share payload shape.
• Check workspace mirroring before changing SAVED_KEY, mirror domain or payload shape.
• Validate CSS, SVG, PNG, JSON, CSV, Tailwind and design-token export paths when changing stop schema.
• After documentation changes, regenerate documentation discovery, feeds, sitemaps, PWA cache and search index.

node scripts/generate-discovery.mjs
node scripts/generate-pwa-cache-manifest.mjs
node search/client/build-index.js

For user-facing workflow details, see the Gradient Library User Guide. For generator internals, see the Gradient Gen Developer Reference.