Basic Color Tools Developer Reference

• tool/basic-tools/index.html: page shell, SEO metadata, SoftwareApplication schema, BreadcrumbList schema, shared cursor, scroll layer, loader, eye-rest UI, catalog container, and module imports.
• js/tool/basic-tools.js: main ES module. Defines the tool registry, shell rendering, floating panel system, color math helpers, chart drawing, seven mount functions, and window.AABasicTools.restoreState.
• js/tool/basic-tools-views.js: view shell. Renders the Workspace, Catalogue, and Panels views, remembers the choice in aa_bt_lab_view, and hands the Workspace stage to the panel system through window.AABasicTools.setPanelStage.
• js/components/color-picker.js: reusable picker component used when editing a Palette Studio swatch.
• js/library/tool-bindings.js: universal library binding for capture and restore. The Basic Color Tools section maps each focused panel to library asset payloads.
• css/color-science.css, css/analyzer.css, css/color-science-lab.css, css/vision-deficiency.css, css/tool-views.css, css/basic-tools-views.css: shared layout and panel styles used by the workspace, with additional runtime CSS injected by ensureBtCss().

The page is a static HTML document that imports /js/unified.js, /js/tool/basic-tools.js, and /js/tool/basic-tools-views.js as modules. The shell follows the broader Auric Artisan tool pattern with header includes, announcement/time includes, cursor layer, scroll layer, loader, eye-rest panel, shared footer, and the idle canvas.

• Canonical URL: https://auricartisan.com/tool/basic-tools/.
• Structured data: SoftwareApplication describes the tool and BreadcrumbList places it under the tool area.
• Permissions Policy: camera, microphone, and geolocation are disabled because this page does not use device capture.
• Main app node: #bt-app contains search, mode switch, guide, category tabs, grid host, and empty state.
• Module mount: the JS module waits for DOMContentLoaded when needed, then runs init().

• Categories: generate, pick, compose, and convert.
• Special tabs: __all__, __favorites__, and __open__.
• Storage keys: aa_bt_depth_mode, aa_bt_active_category, aa_bt_guide_dismissed, and aa_bt_favorites.
• Panel cap: MAX_PANELS is 5. New panels beyond the cap close the oldest panel before opening.
• Tool registry: the TOOLS array stores slug, display name, category, depth, summary, icon, and tags for each card.
• Runtime state: panels tracks active panel objects, while pendingRestore holds saved library state until a mount function consumes it.

The lifecycle is intentionally direct DOM work. The catalog renderer creates cards, a card click calls openTool(), and the floating panel system handles positioning and interactions.

• openTool(item, opts): reuses an existing panel unless duplicate mode is requested. It enforces the panel cap, ensures #bt-panel-host, creates a panel, and focuses it.
• createPanel(item, host): creates a unique id and prefix, appends the element, builds the panel object, applies default geometry, mounts the tool, and binds title-bar actions.
• buildPanelElement(item, id): returns the dialog-like panel section with title bar, duplicate, minimize, maximize, close, body, and resize handle.
• bindPanelDrag() and bindPanelResize(): use pointer capture and requestAnimationFrame to avoid excess layout churn.
• clampRect(): keeps panel width, height, and position inside the panel stage (the viewport when no stage is set) with an 8px gap.
• mountTool(panel): calls ensureBtCss() and dispatches to the slug-specific mount function.

The module keeps color math local instead of importing a library. These helpers are shared by all sub-tools and should be treated as cross-module infrastructure inside the file.

• Conversion helpers: HEX/RGB, HSL, HSV, OKLCh, XYZ D65, Lab D65, CMYK, and CIE xyY-derived chart values.
• Perceptual difference: deltaE76() and deltaE2000() power comparison and battle scoring.
• Accessibility: relLuminance(), contrastRatio(), and wcagLevel() classify common contrast thresholds.
• CVD simulation: matrix transforms approximate deuteranopia, protanopia, tritanopia, and achromatopsia for palette previews and scoring.
• Interpolation: interp() supports RGB, HSL, Lab, and OKLCh paths for gradient sampling.
• Charts: HiDPI helpers draw line charts, histograms, hue wheels, and CIE 1931 chromaticity diagrams directly on canvas.
• Named colors: a small built-in color list is matched with Delta E 2000 for nearest-name output.

• mountPaletteStudio: generates OKLCh-based palettes, locks swatches, supports drag reorder, image extraction with k-means, CVD preview, contrast matrix, charts, info, and CSS/SCSS/Tailwind/JSON/SVG/PNG/ASE-style exports.
• mountPaletteRemix: turns seed colors into recipe-based variants. Recipes are editorial, analog, contrast, and tonal. It supports count limits, remix energy, copy actions, and "use as seed".
• mountGradientMaker: manages stop state, type, angle, interpolation, easing, presets, curve charts, CSS/SVG/JSON output, Tailwind snippet, and 1600px or 4K PNG export.
• mountColorPicker: owns HSV state, native picker, EyeDropper fallback behavior, format outputs, harmonies, CVD previews, CIE charts, named-color info, and background contrast cards.
• mountColorBattle: normalizes team lists, scores pairwise contrast and perceptual distance, computes CVD resilience, renders team cards and cross contrast matrix, and copies winners or reports.
• mountCollageMaker: stores layout controls, cells, filters, optional title, and a DOM-to-canvas 4K PNG export path.
• mountQuickConverter: parses a single color, renders conversion rows, compares two colors, checks wide-gamut coordinates, and draws visual charts.

• Clipboard: copyText() uses the Clipboard API and falls back to a temporary textarea with document.execCommand("copy").
• Text exports: CSS, SCSS, Tailwind, JSON, HEX lists, and reports are copied to clipboard rather than downloaded.
• SVG exports: Palette Studio and Gradient Maker create Blob URLs and trigger a temporary anchor download.
• PNG exports: palette, gradient, and collage exports draw to canvas and call toBlob(). Collage uses the displayed grid geometry to render a high-resolution output.
• File reads: Palette Studio and Collage Maker read local images with FileReader. Palette Studio extracts colors from image data; Collage Maker stores data URLs in cell state.
• Known limitation: conic gradient CSS and PNG export are supported, but SVG export uses the available SVG gradient primitives and is best treated as an approximate handoff.

The universal library integration treats Basic Color Tools as a workspace of focused panels. Capture is read-only against rendered DOM, while restore calls a public bridge exposed by the tool module.

• Binding: attachTool() matches /tool/basic-tools/ and declares tool id basic-tools.
• Focused panel lookup: focusedPanels("bt-panel-host", "vd-panel-focused") returns the focused panel or visible panels sorted by z-index.
• Capture dispatch: captureBasicToolsPanel() switches on panel.dataset.slug and returns asset payloads for palette, remix, gradient, color, battle, collage, quick converter, or best-canvas fallback.
• Restore dispatch: basicToolsRestoreState() infers which sub-tool should reopen from panel_slug, asset type, gradient fields, color fields, battle role, remix kind, or converter input.
• Public API: window.AABasicTools.restoreState(slug, state) stores state in pendingRestore, closes any existing same-slug panel, opens the tool, and lets the mount function apply the pending state.
• Deep state: the library wrapper also captures input maps, UI state, local storage fragments, runtime state, path, tool id, and capture time under the deep-options-v2 support schema.

1. Add a tool() entry to TOOLS with slug, label, category, depth, summary, icon, and tags.
2. Add a mount function named after the feature, for example mountTokenExporter(panel).
3. Register the slug in the mountTool() dispatch map.
4. Use panel.prefix for every generated ID so duplicate panels do not collide.
5. Reset panel body inline style at the start of the mount function and keep the main scroll container on .vd-panel-body.
6. Use existing color helpers before adding a new conversion path.
7. Add copy/download actions through existing clipboard and Blob URL patterns.
8. Add capture and restore logic in js/library/tool-bindings.js so saved assets reopen correctly.
9. Add user-facing documentation and update data/documentation.json, RSS, sitemaps, cache manifest, and search index with the generator scripts.

• Catalog: verify search, the category dropdown (it drives the hidden category tabs), mode switch, favorites, the card count, Copy link, and the Quick start button that shows and hides the guide.
• Panel controls: open, focus, duplicate, drag, resize, minimize, maximize, restore, close, viewport clamp, and five-panel cap.
• Palette Studio: harmony generation, locked colors, reorder, image extraction, CVD mode, contrast matrix, charts, and every export button.
• Gradient Maker: stop edits, track click, interpolation, easing, presets, radial and conic paths, CSS/SVG/PNG/JSON/Tailwind output.
• Color tools: picker harmonies, EyeDropper unsupported path, Quick Converter parser, CIE charts, wide-gamut status, and contrast classification.
• Battle and collage: team parsing, scoring, report copy, image replacement, per-cell filters, title overlay, and 4K export memory behavior.
• Library: capture each slug, save multiple focused panels, restore each asset type, and verify pendingRestore is consumed exactly once.
• Risk: color science helpers are shared by many panels. Changes to OKLCh, Lab, Delta E, luminance, or CVD math can alter palette generation, scoring, charts, and saved asset previews at the same time.