Personalization Generator Developer Reference

• tool/personalization-gen/index.html: static tool shell, SEO metadata, SoftwareApplication schema, BreadcrumbList schema, shared cursor, scroll layer, loader, eye-rest UI, SVG CVD filters, header controls, guided flow, tabs, and panel containers.
• js/tool/personalization-gen.js: main ES module. Defines state, the chunked runner, pool tools, result derivation, renderers, Studio mockups, export helpers, Library saves, event binding, persistence, and initialization. Registry constants, profile logic, candidate generation, and scoring are imported from js/tool/personalization/engine-core.js, which the /v1/personalize/* API also runs; the Tokens tab system comes from js/tool/personalization/token-engine.js.
• css/personalization-gen.css: specific visual layer for status pills, progress, pool grids, result cards, palette strips, gradient previews, type previews, UI pair previews, poster templates, Studio mockups, and responsive layout.
• js/tool/color-tools/utils/color-math.js: imported color math dependency for HEX parsing, RGB/HSL/Lab/OKLCH conversion, OKLCH mixing, contrast, relative luminance, Delta E 2000, and CVD simulation.
• js/library/page-mirror.js: imported Library bridge used by result save buttons through mirrorSave() and duplicate detection through isMirrored().
• js/library/tool-bindings.js: holds a dedicated attachTool() binding for /tool/personalization-gen/: the universal Library save FAB captures the top palette (or the pool) and the top gradient through window.AAPersonalization.getState(), and restoring an asset seeds the color pool through restoreState(). Per-result saves are handled inside the tool module.

The page uses the platform shell and then mounts a single tabbed application under #pg-app. The shell imports /js/unified.js, the Personalization Generator module, and /js/tool/personalization-views.js as ES modules; the views module moves the header controls into a three-column workbench (the brief, the results, the run).

• Canonical URL: https://auricartisan.com/tool/personalization-gen/.
• Security: the page disables camera, microphone, and geolocation through Permissions Policy.
• CVD filters: inline SVG filters define deuteranopia, protanopia, and tritanopia matrices for visual simulation support in the shell.
• App regions: header prompt, advanced options, mode switch, guide, start panel, flow rail, result search toolbar, progress strip, tab list, and tab panel root. css/personalization-shell.css hides the emptied header, the guide, the start panel, and the flow rail in the live layout.
• Initialization: init() loads persisted state, applies mode, binds events, refreshes pool caches, renders all tabs, and starts a small first sweep if no palettes exist.

• Tool id: PG_TOOL has the id personalization-gen and is passed to Library mirror saves.
• Storage key: aa_personalization_gen_v3 stores user preferences and UI state. Guide dismissal uses pg_guide_dismissed.
• Limits: MAX_RESULTS is 96, MAX_POOL is 240, and CHUNK_SIZE is 24.
• Registry constants: STYLE_PROFILES, RELATIONSHIPS, HUMAN_PALETTE_SEEDS, TYPE_SYSTEMS, PRESETS, POSTER_TEMPLATES, and GRADIENT_VARIANTS drive the generator.
• State: the central state object contains pool, styles, intent, note, pool target, palette size, depth, diversity, accessibility, warmth, keep count, CVD, contrast, uniqueness, seed, active tab, mode, Studio controls, running job, generation count, counters, result arrays, and search term.
• Cache: RGB, Lab, OKLCH, pool Lab, and pool OKLCH caches reduce repeated color conversion during large sweeps.
• Persistence: saveState() and loadState() persist preferences, active tab, mode, Studio options, and overrides, but generated results are not persisted in localStorage.

• Profile: getProfile() averages active style profiles, then blends profile warmth with the user warmth slider.
• Seed matching: curatedMatches() weights human palette seeds by style overlap, intent match, and preference note words.
• Candidate generation: makeCandidate() selects a relationship, memory seed, anchor color, lightness pattern, OKLCH hue offsets, pool-nearest colors, mutation, final fitting, scoring, naming, and perceptual signature.
• Pool expansion: buildColorPool() and randomPool() create broader source pools from curated seeds, current colors, and random OKLCH movement.
• Chunking: runGeneration() samples candidates in slices of CHUNK_SIZE, updates progress, and yields through requestIdleCallback or requestAnimationFrame.
• Cancellation: cancelGeneration() marks the active job as cancelled, and finalizeRun() still sorts and keeps available candidates.
• Endless mode: toggleEndless() repeatedly runs append sweeps and deduplicates by palette signature.

scorePalette() returns a total score plus component scores. Each component is scaled to 0-100 for the UI, while the weighted total uses normalized 0-1 values internally.

• Preference: compares candidate Lab values to pool Lab values with Delta E 2000, rewarding closeness without exact copying.
• Harmony: compares OKLCH hue deltas to the chosen relationship offsets and adds lightness/chroma rhythm.
• Diversity: scores pairwise Delta E separation and avoids both collapse and excessive scatter.
• Contrast: checks relative luminance range and best contrast pair.
• Style: tests HSL saturation, OKLCH lightness, and OKLCH chroma against the active profile ranges.
• Accessibility: applies protanopia, deuteranopia, and tritanopia transforms, rescoring diversity under each simulation, then blends that with UI contrast targets.
• Weights: diversity and accessibility sliders alter how much those score components influence the total.

• Derivation: deriveOutputs() maps kept palettes into gradients, type combinations, UI pairs, and posters. Current caps are 28 gradients, 24 type systems, 28 UI pairs, and 28 posters.
• Gradients: makeGradient() uses sorted hues and GRADIENT_VARIANTS to create CSS gradient strings and stop metadata.
• Typography: makeTypeCombo() and pickTypeSystem() combine palette roles with predefined font stacks.
• UI pairs: makeUiPair() selects background, text, surface, accent, accent ink, contrast ratio, CVD status, and score.
• Posters: makePoster() and renderPosterTemplate() create named poster compositions from palette roles and template variants.
• Render flow: renderAll() refreshes caches, renders every tab, updates badges, syncs tabs, and syncs the guided flow.
• Delegated actions: handleResultActions() handles copy, add to pool, open in Studio, and save actions for result cards.

Brand Studio is a live renderer rather than a static screenshot. A selected palette is converted into design tokens, then all mockups read those tokens from CSS custom properties.

• System builder: brandSystemFrom() finds readable background and foreground roles, theme-adjusts them, applies token overrides, chooses accent roles, creates surface/muted/subtle tokens, and selects semantic success, warning, danger, and info colors.
• Toolbar: renderStudio() binds palette switcher, theme, density, inspect, test panel, shuffle, and save brand system actions.
• Test panel: renderStudioTestPanel() lets users remap background, text, accent, accent 2, and surface tokens from palette swatches.
• Inspect mode: inspect() adds token metadata attributes to mockup elements when inspection is enabled.
• Mockups: Studio renders brand identity, dashboard, landing, components, type scale, chart deck, pricing, auth, chat, mobile, calendar, music, magazine, banner, email, and product sections.
• Risk: any token name change affects all mockup renderers, Studio save payloads, CSS variables, inspect metadata, and documentation.

• CSS export: cssTokenExport() creates :root variables for the top palette, top gradient, and top typography system, then appends the semantic token system (roles plus light, dark, and high-contrast themes).
• JSON snapshot: snapshot() emits schema aa.personalization-generator.v3 with preferences, search settings, and current result arrays.
• Download: exportJson() writes auric-personalization-generator.json through a Blob URL.
• Save domains: result saves use domains pg-palette, pg-gradient, pg-type, pg-pair, pg-poster, and pg-studio.
• Duplicate guard: pgSweepKey() and isMirrored() prevent duplicate saves for the same generation/index item.
• Preview generation: page-mirror.js creates palette, gradient, or pair preview images when the save call does not pass an explicit image.
• Restore note: Personalization result saves are workspace assets with payloads and source metadata. The module exposes window.AAPersonalization with useColors(), getState(), and restoreState(); restoring seeds the color pool from a saved palette, gradient, color, or shade, while generated results themselves are not restored.

1. Add new style behavior through STYLE_PROFILES and verify ranges for chroma, lightness, saturation, warmth, and contrast.
2. Add new harmony behavior through RELATIONSHIPS with stable id, label, hue offsets, and weight.
3. Add curated inspiration through HUMAN_PALETTE_SEEDS with clean HEX colors, style tags, and intents.
4. Add type behavior through TYPE_SYSTEMS and ensure CSS font-family strings are safe to export.
5. Add presets through PRESETS with colors, styles, and intent.
6. Add a new derived asset by extending deriveOutputs(), adding a maker function, adding a renderer, adding result actions, adding copy/export behavior, and adding Library save behavior.
7. Add a new Studio mockup by creating a renderer, including it in renderStudio(), using token helpers, testing inspect mode, and updating Studio save documentation.
8. If generated results should restore into the tool, extend window.AAPersonalization.restoreState() and the attachTool() binding in js/library/tool-bindings.js, which today only seed the color pool.
9. Update user and developer documentation, then regenerate documentation JSON, RSS, sitemaps, PWA cache manifest, and search index.

• Shell: verify title, canonical, structured data, shared includes, the three-column layout that js/tool/personalization-views.js builds (brief rail, results, run rail), mode switch, tabs, result search, and responsive layout. The guide and the flow rail are hidden in the live layout, so there is nothing to test there.
• Pool: test valid/invalid HEX input, add, remove, build, random, clear, quick seeds, grayscale, jitter, statistics, hue distribution, and lightness ladder.
• Tune: test style chips, intent, note, all ranges, CVD-safe, contrast, unique, reset defaults, and Advanced-only header controls.
• Generation: run low depth, high depth, cancel, Endless mode, append sweeps, strict uniqueness, no-pool fallback, and first-run auto sweep.
• Outputs: verify palette scores, gradient filters, typography CSS, UI pair contrast labels, poster filters, copy buttons, add-to-pool buttons, and Studio handoff.
• Studio: test palette switcher, theme, density, inspect mode, test panel token swaps, reset overrides, shuffle, and every mockup at desktop and mobile widths.
• Exports: validate copied CSS, downloaded JSON schema, and truncated preview display in the Export tab.
• Library: save each asset domain, verify duplicate guard, verify generated previews, and confirm assets include expected tool id, name, colors, payload, and source URL.
• Risk: color math, scoring weights, and state shape affect every generated output. A small helper change can alter ranking, exports, Library payloads, and docs examples.