Tints & Shades Generator Developer Reference

• Tool shell: tool/general/gamut-and-rendering/tonal-steps-tints-shades/index.html contains page metadata, hero content, controls, the six tab panels, canvases, hidden action buttons, fullscreen chart overlay and script includes.
• Tool engine: js/tool/tonal-steps.js contains the standalone IIFE for color math, generation, rendering, exports, state and API. It also exposes window.AATonalEngine, which js/tool/tonal-steps-views.js reads to render the Lab, Ramps, Contrast, Data, Export and Reference views; js/tool/ts/ts-sources.js holds the dataset register as window.AATonalSources.
• Library binding: js/library/tool-bindings.js registers /tool/general/gamut-and-rendering/tonal-steps-tints-shades/ as tool id tonal-steps, name Tints & Shades Generator, category Gamut & Rendering and asset type palette.
• Shared runtime capture: js/library/tool-bindings.js maps tonalSteps to window.AATonalSteps.getState and restore to window.AATonalSteps.restoreState.
• Discovery outputs: documentation additions must flow into data/documentation.json, RSS, feed, sitemaps, PWA cache manifest and search index.

• App root: ts-app wraps the tool and the main workspace is main with the label Tints & Shades Generator workspace.
• Tabs: tab buttons use data-ts-tab and panels p-ts-lab, p-ts-ramps, p-ts-contrast, p-ts-data, p-ts-export and p-ts-reference.
• Primary controls: the runtime reads ts-base-picker, ts-base-hex, ts-engine, ts-mix-mode, ts-steps, ts-gamma, ts-scale-type and ts-vis-toggles.
• Output nodes: generated UI writes to ts-base-info, ts-schemes, ts-scale-output, ts-uniformity-stats and ts-contrast-body.
• Canvas ids: ts-ramp-canvas, ts-lightness-canvas, ts-uniformity-canvas, ts-contrast-canvas, ts-gamut-canvas and ts-cie-canvas.
• Action ids: ts-copy-hex, ts-copy-css, ts-copy-scss, ts-copy-json, ts-copy-csv, ts-copy-tailwind, ts-export-png, ts-export-lightness, ts-draw-uniformity, ts-draw-contrast, ts-draw-gamut, ts-draw-cie, ts-batch-run and ts-batch-csv.
• Share id note: the runtime writes the link to the read-only ts-share-url field in the Export tab and binds the hidden ts-copy-link button; the visible path is Export, A link to this view, Copy the link. Test this path before changing share behavior.

The runtime state is produced by readState().

• hex: validated six-digit base HEX, fallback #2563EB, the page default.
• engine: hsl, luminance or contrast.
• steps: integer step count, page range 3 through 21, default 11.
• gamma: gamma bias, page range 0.4 through 2.6, default 1.0.
• mode: mixing mode, one of oklab, lab, srgb (what the sRGB linear button sends; srgb-linear is accepted too) or hsl.
• scaleType: tailwind (page default) or material; custom is the fallback when the field is missing.
• vis: object keyed by ramp, tints, shades, tones and neutrals.

updateAll() generates ramp data, tints, shades, tones and neutrals, updates HTML outputs, draws the primary canvases, stores the latest data on window.__tsData and dispatches a ts:updated event, which the views refresh on.

• sRGB transfer: srgbToLinear() and linearToSrgb() implement the IEC sRGB piecewise transfer functions.
• HEX and RGB: hexToRgb() parses six-digit colors and rgbToHex() serializes clipped 8-bit RGB.
• XYZ and Lab: M_S2X, M_X2S, rgbToXyz(), xyzToRgb(), xyzToLab() and labToXyz() use D65 reference white.
• LCh: labToLch() derives chroma and hue angle from CIELAB a/b values for export diagnostics.
• OKLab: rgbToOklab() and oklabToRgb() implement the OKLab transform used by the recommended mixing path and uniformity charts.
• Relative luminance: relativeLuminance() uses BT.709/sRGB coefficients from linearized RGB.
• WCAG: contrastRatio(), wcagLabel() and bestTextColor() power the contrast table and swatch labels.
• APCA: apcaLc() implements APCA-W3 0.1.9 and returns signed, polarity-aware Lc values for text on white and black backgrounds; apcaLcLegacy() keeps the superseded approximation so the Contrast view can show the difference.
• HSL: rgbToHsl() and hslToRgb() support the HSL ramp engine and HSL mixing mode.

• Mixing functions: mixLinear(), mixLab(), mixOklab() and mixHslEngine() are selected by mixColors().
• Swatch object: buildSwatch() returns index, ratio, RGB, HEX, HSL, Lab, LCh, OKLab L, luminance, WCAG contrast, APCA contrast, text color and label.
• Tints: generateTints() mixes the base color toward white.
• Shades: generateShades() mixes the base color toward black.
• Tones: generateTones() mixes the base color toward middle gray.
• Neutrals: generateNeutrals() builds a grayscale ladder using step count and gamma.
• Scales: tailwindScale() and materialScale() generate named scale stops anchored at 500.
• Full ramp: generateRamp() handles the HSL lightness, Equal luminance and Equal contrast engines. The contrast engine lands on the same colors as the luminance engine, so the Lab view offers two and contrast is kept for saved links.
• Luminance solve: solveForLuminance() binary-searches HSL lightness for a target relative luminance.

• Base info: updateBaseInfo() writes the base chip and colorimetric metrics.
• Swatch HTML: renderSwatchSet() renders chips for the visible ramp, tint, shade, tone and neutral sets.
• Contrast table: the Contrast view in tonal-steps-views.js fills ts-contrast-body with each step's WCAG ratio, rating and APCA Lc against white, black or the base; the engine's old updateContrastTable() was removed.
• Scale output: updateScaleOutput() renders Tailwind or Material scale chips.
• Uniformity stats: updateUniformityStats() computes mean Delta L, standard deviation and max deviation from OKLab L steps.
• Primary canvases: drawSwatchStrip() draws the ramp preview and drawLightnessChart() draws OKLab L distribution.
• Research canvases: drawUniformityChart(), drawContrastChart(), drawGamutScatter() and drawCIEChromaticityDiagram() render deeper diagnostics when the Ramps, Contrast and Reference tabs open.
• Device pixel ratio: canvas functions scale backing stores by window.devicePixelRatio for sharper exports.

• PNG export: exportPNG() serializes a canvas through toDataURL("image/png") and downloads it through an anchor.
• Clipboard helper: copyText() writes to navigator.clipboard and displays the toast on success.
• CSS variables: the Export tab uses EXPORTERS (exportRampCSS(), exportRampSCSS(), exportRampJSON(), exportRampCSV()), which write --tonal-0 and later properties, a $tonal map, JSON and CSV under a provenance header. The older buildCssVars() behind the hidden ts-copy-css button outputs --color-0, --color-100 and later stops from the main ramp.
• SCSS map: buildScssMap() outputs a named Sass map.
• JSON: buildJSON() exports full ramp diagnostics.
• CSV: buildCSV() exports index, HEX, HSL, Lab, LCh, OKLab L, luminance, WCAG and APCA columns.
• Tailwind CSS: buildTailwindCSS() exports 50-950 custom properties from tailwindScale().
• Batch: runBatch() parses HEX input, generates tints and shades, and returns Lab, OKLab L, luminance and count data.
• URL encode: stateToURL() stores hex, engine, steps, gamma and mode.
• URL decode: loadFromURL() restores those fields before initial event binding and render.
• URL limitation: scaleType, visible-set toggles and batch input are preserved by full Library state, not by the current share URL.

• API: window.AATonalSteps = { getState, restoreState }.
• getState(): returns { state, data, batchInput }, where state is readState(), data is a deep copy of window.__tsData when available and batchInput is the batch textarea value.
• restoreState(saved): accepts either the full object or a bare state, applies known controls, restores visible-set toggles, restores batch input and schedules an update.
• Simple Library capture: the route binding scans a host node for HEX colors and saves a palette preview when at least two colors are found.
• Capture data: simple capture stores preview_data.colors and asset_data.colors. Full runtime capture can preserve the richer AATonalSteps state.
• Simple restore note: the generic binding still references older ids such as ts-base, tonal-base, ts-generate, tonal-generate and ts-render. Prefer window.AATonalSteps.restoreState() for exact restore on this page.
• Storage boundary: the tool itself does not create persistent local palettes. Persistence is handled by Auric Library capture or by exported token data.

1. When adding a ramp engine, update generateRamp(), the ENGINES list that builds the engine buttons, keyboard shortcuts, standards copy, formulas, docs and tests.
2. When adding a mixing mode, update mixColors(), the MIX_MODES list, export interpretation and uniformity expectations.
3. When changing the swatch schema, update buildJSON(), buildCSV(), contrast table rendering, Library state expectations and docs.
4. When adding scale conventions, create a generator like tailwindScale(), update updateScaleOutput(), add export support and document stop naming.
5. When changing URL state, update stateToURL(), loadFromURL(), share UI, Library docs and smoke tests.
6. When changing control ids, update readState(), restoreState(), event binding, generated inline click targets, Library simple binding and tests.
7. When changing canvas dimensions, test DPR scaling, fullscreen copy behavior, PNG export and mobile layout.
8. When changing APCA or WCAG logic, update labels and docs because exported accessibility values become different compatibility data.
9. Regenerate discovery outputs after documentation changes with scripts/generate-discovery.mjs, scripts/generate-pwa-cache-manifest.mjs and search/client/build-index.js.
10. Keep user-facing text clear that WCAG and APCA values are guidance metrics, not final legal accessibility certification.

• Boot: verify the Lab tab appears, the default base color renders, the ramp and lightness canvases draw, and the contrast table fills.
• Inputs: test valid and invalid HEX, color picker sync, random color, both offered engines plus contrast by URL, all four mixing modes, step extremes and gamma extremes.
• Visible sets: toggle ramp, tints, shades, tones and neutrals independently.
• Scales: test the 50–950 and 50–900 key sets and verify 500 remains the anchor stop for named scales.
• Actions: test every Export tab selection (the ramp, the key set, the contrast table, a link) in each offered format, and share URL restore.
• Research: open the Ramps, Contrast and Reference tabs and check the uniformity, gamut, contrast and CIE charts draw; then run batch analysis and batch CSV.
• Keyboard: test 1, 2, 3 and R outside form controls.
• Library: save a palette, confirm preview colors, restore full runtime state and verify visible toggles and batch input return.
• Numerical risk: changes to sRGB transfer, matrices, OKLab constants, luminance coefficients, APCA exponents or gamma handling will alter charts and exports.
• UX risk: very high step counts can crowd swatches and canvas labels on small screens. Verify mobile layout after changing chip sizes or text labels.