@owlmeans/web-panel 0.1.18-rc.9 → 0.1.18

package/src/picker/utils/color.ts

@@ -0,0 +1,119 @@
+import type { ColorUtils, DerivedColor, Oklch, Rgb } from './color/types.js'
+
+/** The text-contrast floor every derived ink keeps — above the 3:1 icons and dots need. */
+const TARGET = 4.5
+const WHITE = '#ffffff'
+const BLACK = '#000000'
+
+const toLinear = (c: number): number => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+const fromLinear = (c: number): number => c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055
+
+/** sRGB → OKLCH (Björn Ottosson's matrices). */
+const toOklch = ({ r, g, b }: Rgb): Oklch => {
+  const [lr, lg, lb] = [toLinear(r), toLinear(g), toLinear(b)]
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb)
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb)
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb)
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+
+  return { l: L, c: Math.hypot(A, B), h: Math.atan2(B, A) }
+}
+
+/** OKLCH → linear sRGB channels, unclamped (out-of-gamut values fall outside 0..1). */
+const toLinearRgb = ({ l, c, h }: Oklch): [number, number, number] => {
+  const a = c * Math.cos(h)
+  const b = c * Math.sin(h)
+  const l3 = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const m3 = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const s3 = (l - 0.0894841775 * a - 1.291485548 * b) ** 3
+
+  return [
+    4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+    -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+    -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3,
+  ]
+}
+
+const inGamut = (channels: [number, number, number]): boolean =>
+  channels.every(channel => channel >= -1e-4 && channel <= 1 + 1e-4)
+
+export const createColorUtils = (): ColorUtils => {
+  const parse = (hex: string): Rgb | null => {
+    const match = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex.trim())
+    if (match == null) {
+      return null
+    }
+    const [r, g, b] = match.slice(1).map(part => parseInt(part, 16) / 255)
+
+    return { r, g, b }
+  }
+
+  const hex = ({ r, g, b }: Rgb): string => `#${[r, g, b]
+    .map(channel => Math.round(Math.min(1, Math.max(0, channel)) * 255).toString(16).padStart(2, '0'))
+    .join('')}`
+
+  const luminance = (value: string): number => {
+    const rgb = parse(value) ?? { r: 0, g: 0, b: 0 }
+
+    return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b)
+  }
+
+  const contrast = (a: string, b: string): number => {
+    const [x, y] = [luminance(a), luminance(b)]
+
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05)
+  }
+
+  /** The colour at this lightness and hue with as much of `c` as sRGB can show, as hex. */
+  const fit = (l: number, c: number, h: number): string => {
+    let low = 0
+    let high = c
+    if (!inGamut(toLinearRgb({ l, c, h }))) {
+      for (let step = 0; step < 24; step++) {
+        const mid = (low + high) / 2
+        if (inGamut(toLinearRgb({ l, c: mid, h }))) {
+          low = mid
+        } else {
+          high = mid
+        }
+      }
+    } else {
+      low = c
+    }
+    const [r, g, b] = toLinearRgb({ l, c: low, h }).map(channel => fromLinear(Math.min(1, Math.max(0, channel))))
+
+    return hex({ r, g, b })
+  }
+
+  /** Walk the lightness from `from` by `step` until `ok` holds; the far end (black or white) always does. */
+  const walk = (from: number, step: number, c: number, h: number, ok: (candidate: string) => boolean): string => {
+    for (let l = from; l >= 0 && l <= 1; l += step) {
+      const candidate = fit(l, c, h)
+      if (ok(candidate)) {
+        return candidate
+      }
+    }
+
+    return step < 0 ? BLACK : WHITE
+  }
+
+  const derive = (value: string): DerivedColor => {
+    const base = toOklch(parse(value) ?? { r: 0, g: 0, b: 0 })
+    // A grey has no hue to keep; any angle at zero chroma is the same grey.
+    const h = base.c < 1e-4 ? 0 : base.h
+    const soft = fit(0.965, Math.min(base.c, 0.035), h)
+    const softDark = fit(0.25, Math.min(base.c, 0.06), h)
+    const ink = walk(Math.min(base.l, 0.66), -0.01, base.c, h,
+      candidate => contrast(candidate, WHITE) >= TARGET && contrast(candidate, soft) >= TARGET)
+    const inkDark = walk(Math.max(base.l, 0.72), 0.01, Math.min(base.c, 0.16), h,
+      candidate => contrast(candidate, BLACK) >= TARGET && contrast(candidate, softDark) >= TARGET)
+
+    return { ink, soft, inkDark, softDark }
+  }
+
+  return { parse, hex, contrast, derive }
+}
+
+export const colorUtils = createColorUtils()

package/src/picker/vocabulary/consts.ts

@@ -0,0 +1,347 @@
+import type { PickerColor, PickerIconCategory, PickerIconEntry } from './types.js'
+
+/** The palette's keys in hue order — the order the swatch grid shows them in. */
+export const PICKER_COLOR_KEYS = [
+  'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo',
+  'violet', 'purple', 'fuchsia', 'pink', 'rose', 'maroon', 'brown', 'olive', 'navy', 'slate', 'stone', 'graphite',
+] as const
+
+/**
+ * The 24-colour palette.
+ *
+ * Hues follow one scale: the swatch is the hue's 500, the light ink its 700–800, the light ground
+ * its 100, the dark ink its 300 (200 or 400 where a neighbouring hue's 300 sits too close) and the
+ * dark ground its 900–950. Ten hues keep the exact values the generated targets' look has always
+ * used (slate, blue, sky, teal, green, amber, orange, red, pink, violet). The deep four — maroon,
+ * brown, olive, navy — run on scales of their own: a darker light ink and a mid-tone dark ink, so
+ * they stay apart from red, amber, lime and indigo in both modes. Every ink keeps 4.5:1 on its own
+ * ground and on the page in both modes (`tests/picker-vocabulary.spec.ts`).
+ */
+export const PICKER_COLORS: readonly PickerColor[] = Object.freeze([
+  { key: 'red', label: 'Red', swatch: '#EF4444', ink: '#B91C1C', soft: '#FEE2E2', inkDark: '#FCA5A5', softDark: '#450A0A' },
+  { key: 'orange', label: 'Orange', swatch: '#F97316', ink: '#9A3412', soft: '#FFEDD5', inkDark: '#FDBA74', softDark: '#431407' },
+  { key: 'amber', label: 'Amber', swatch: '#F59E0B', ink: '#92400E', soft: '#FEF3C7', inkDark: '#FCD34D', softDark: '#451A03' },
+  { key: 'yellow', label: 'Yellow', swatch: '#EAB308', ink: '#A16207', soft: '#FEF9C3', inkDark: '#FEF08A', softDark: '#422006' },
+  { key: 'lime', label: 'Lime', swatch: '#84CC16', ink: '#4D7C0F', soft: '#ECFCCB', inkDark: '#BEF264', softDark: '#1A2E05' },
+  { key: 'green', label: 'Green', swatch: '#22C55E', ink: '#166534', soft: '#DCFCE7', inkDark: '#86EFAC', softDark: '#052E16' },
+  { key: 'emerald', label: 'Emerald', swatch: '#10B981', ink: '#047857', soft: '#D1FAE5', inkDark: '#34D399', softDark: '#022C22' },
+  { key: 'teal', label: 'Teal', swatch: '#14B8A6', ink: '#115E59', soft: '#CCFBF1', inkDark: '#5EEAD4', softDark: '#042F2E' },
+  { key: 'cyan', label: 'Cyan', swatch: '#06B6D4', ink: '#0E7490', soft: '#CFFAFE', inkDark: '#A5F3FC', softDark: '#083344' },
+  { key: 'sky', label: 'Sky', swatch: '#0EA5E9', ink: '#0369A1', soft: '#E0F2FE', inkDark: '#7DD3FC', softDark: '#082F49' },
+  { key: 'blue', label: 'Blue', swatch: '#3B82F6', ink: '#1D4ED8', soft: '#DBEAFE', inkDark: '#93C5FD', softDark: '#172554' },
+  { key: 'indigo', label: 'Indigo', swatch: '#6366F1', ink: '#4338CA', soft: '#E0E7FF', inkDark: '#818CF8', softDark: '#1E1B4B' },
+  { key: 'violet', label: 'Violet', swatch: '#8B5CF6', ink: '#6D28D9', soft: '#EDE9FE', inkDark: '#C4B5FD', softDark: '#2E1065' },
+  { key: 'purple', label: 'Purple', swatch: '#A855F7', ink: '#6B21A8', soft: '#F3E8FF', inkDark: '#C084FC', softDark: '#3B0764' },
+  { key: 'fuchsia', label: 'Fuchsia', swatch: '#D946EF', ink: '#A21CAF', soft: '#FAE8FF', inkDark: '#F0ABFC', softDark: '#4A044E' },
+  { key: 'pink', label: 'Pink', swatch: '#EC4899', ink: '#BE185D', soft: '#FCE7F3', inkDark: '#F9A8D4', softDark: '#500724' },
+  { key: 'rose', label: 'Rose', swatch: '#F43F5E', ink: '#9F1239', soft: '#FFE4E6', inkDark: '#FB7185', softDark: '#4C0519' },
+  { key: 'maroon', label: 'Maroon', swatch: '#8C1D30', ink: '#6E1423', soft: '#F6E3E6', inkDark: '#D07A8A', softDark: '#3A0B14' },
+  { key: 'brown', label: 'Brown', swatch: '#8B5E3C', ink: '#6B4226', soft: '#F2E8DF', inkDark: '#D4A373', softDark: '#2B1D12' },
+  { key: 'olive', label: 'Olive', swatch: '#7D7F1F', ink: '#535B16', soft: '#F1F2DE', inkDark: '#C5C77E', softDark: '#1F2208' },
+  { key: 'navy', label: 'Navy', swatch: '#233876', ink: '#1E2A5E', soft: '#E3E7F4', inkDark: '#8EA2E0', softDark: '#0D1530' },
+  { key: 'slate', label: 'Slate', swatch: '#64748B', ink: '#334155', soft: '#F1F5F9', inkDark: '#CBD5E1', softDark: '#1E293B' },
+  { key: 'stone', label: 'Stone', swatch: '#78716C', ink: '#57534E', soft: '#F5F5F4', inkDark: '#A8A29E', softDark: '#1C1917' },
+  { key: 'graphite', label: 'Graphite', swatch: '#404040', ink: '#262626', soft: '#E5E5E5', inkDark: '#F0F0F0', softDark: '#171717' },
+])
+
+/** What an unknown colour value renders as. */
+export const PICKER_FALLBACK_COLOR = 'slate'
+
+/** The icon catalogue's categories, in the order the picker's chips show them. */
+export const PICKER_ICON_CATEGORIES = [
+  'work', 'people', 'communication', 'commerce', 'operations', 'places', 'tech', 'status', 'objects', 'nature',
+] as const
+
+/** What an unknown icon name renders as. */
+export const PICKER_FALLBACK_ICON = 'circle'
+
+/**
+ * The curated icon catalogue by category: a kebab-case lucide name (canonical, never an alias) and
+ * its English search words. Icon names stay English in every language — they are what is stored.
+ * A superset of the icons the planning kits use.
+ */
+const CATALOGUE: Readonly<Record<PickerIconCategory, ReadonlyArray<readonly [string, string]>>> = {
+  work: [
+    ['briefcase', 'job, business, portfolio, case'],
+    ['folder', 'directory, project, files'],
+    ['folder-open', 'directory, browse, project'],
+    ['folder-kanban', 'board, project, tasks'],
+    ['file', 'document, page'],
+    ['file-text', 'document, doc, page, note, text'],
+    ['files', 'documents, copies'],
+    ['clipboard-list', 'checklist, tasks, list, agenda'],
+    ['clipboard-check', 'done, approved, review'],
+    ['list-checks', 'checklist, tasks, todo'],
+    ['list-todo', 'tasks, todo, backlog'],
+    ['square-check', 'done, task, complete, checkbox'],
+    ['kanban', 'board, columns, workflow, tasks'],
+    ['calendar', 'date, schedule, event, day'],
+    ['calendar-check', 'booked, scheduled, appointment, done'],
+    ['calendar-days', 'month, schedule, planner'],
+    ['calendar-clock', 'deadline, due, schedule'],
+    ['clock', 'time, hours, schedule'],
+    ['timer', 'stopwatch, countdown, duration'],
+    ['hourglass', 'waiting, time, pending'],
+    ['target', 'goal, aim, objective, focus'],
+    ['flag', 'milestone, priority, report, mark'],
+    ['milestone', 'roadmap, sign, step'],
+    ['rocket', 'launch, release, start, fast'],
+    ['lightbulb', 'idea, insight, tip, innovation'],
+    ['book-open', 'read, docs, guide, knowledge'],
+    ['notebook-pen', 'notes, journal, write'],
+    ['presentation', 'slides, meeting, demo, board'],
+    ['layers', 'stack, levels, epic'],
+    ['layout-grid', 'dashboard, grid, apps'],
+    ['workflow', 'process, flow, pipeline, automation'],
+    ['goal', 'objective, finish, success'],
+    ['trophy', 'win, award, achievement, prize'],
+    ['award', 'badge, medal, quality, recognition'],
+    ['pen-line', 'edit, sign, write'],
+    ['archive', 'storage, old, history, box'],
+    ['paperclip', 'attachment, attach, clip'],
+  ],
+  people: [
+    ['user', 'person, account, profile, member'],
+    ['user-round', 'person, contact, profile'],
+    ['user-round-check', 'verified, approved, assigned'],
+    ['user-round-plus', 'invite, add, new member'],
+    ['user-check', 'verified, approved'],
+    ['user-plus', 'invite, add, signup'],
+    ['users', 'team, group, people, members'],
+    ['users-round', 'team, community, group'],
+    ['contact', 'address book, card, person, lead'],
+    ['id-card', 'identity, badge, passport, license'],
+    ['handshake', 'deal, agreement, partner, sale'],
+    ['person-standing', 'individual, human, figure'],
+    ['accessibility', 'a11y, disability, inclusive'],
+    ['face-slightly-smiling', 'smile, happy, satisfaction, feedback'],
+    ['heart-handshake', 'support, care, volunteer, charity'],
+    ['graduation-cap', 'education, student, school, course'],
+    ['user-cog', 'admin, settings, profile'],
+    ['crown', 'owner, vip, premium, leader'],
+    ['hand', 'help, raise, stop, volunteer'],
+    ['thumbs-up', 'like, approve, good'],
+  ],
+  communication: [
+    ['mail', 'email, message, letter, inbox'],
+    ['mail-open', 'read, email, letter'],
+    ['inbox', 'incoming, messages, queue, tray'],
+    ['send', 'submit, deliver, outgoing, plane'],
+    ['message-square', 'chat, comment, message, conversation'],
+    ['message-circle', 'chat, bubble, talk'],
+    ['messages-square', 'conversation, chat, thread, discussion'],
+    ['phone', 'call, telephone, contact'],
+    ['phone-call', 'ringing, call, support'],
+    ['megaphone', 'announcement, marketing, campaign, broadcast'],
+    ['bell', 'notification, alert, reminder'],
+    ['bell-ring', 'alarm, notification, ring'],
+    ['at-sign', 'email, mention, address'],
+    ['headset', 'support, help desk, call center, service'],
+    ['video', 'call, meeting, camera, record'],
+    ['mic', 'voice, audio, record, podcast'],
+    ['share-2', 'share, network, social'],
+    ['reply', 'answer, respond, back'],
+    ['languages', 'translate, language, i18n'],
+    ['newspaper', 'news, press, article, blog'],
+  ],
+  commerce: [
+    ['shopping-cart', 'cart, buy, checkout, order'],
+    ['shopping-bag', 'bag, purchase, shop'],
+    ['store', 'shop, retail, storefront'],
+    ['receipt', 'invoice, bill, payment'],
+    ['credit-card', 'card, payment, pay'],
+    ['wallet', 'money, funds, budget'],
+    ['banknote', 'cash, money, bill, payment'],
+    ['coins', 'money, cash, cost, change'],
+    ['piggy-bank', 'savings, budget, money'],
+    ['dollar-sign', 'money, price, revenue, usd'],
+    ['euro', 'money, price, eur'],
+    ['percent', 'discount, rate, tax'],
+    ['tag', 'label, price, category'],
+    ['tags', 'labels, categories'],
+    ['ticket', 'event, pass, admission, support ticket'],
+    ['gift', 'present, reward, bonus'],
+    ['package', 'box, product, parcel, delivery'],
+    ['badge-percent', 'sale, discount, promotion'],
+    ['trending-up', 'growth, increase, sales, up'],
+    ['trending-down', 'decline, decrease, loss'],
+    ['scale', 'balance, legal, compare, law'],
+    ['landmark', 'bank, finance, government, institution'],
+    ['calculator', 'math, accounting, estimate'],
+    ['hand-coins', 'pay, donation, tip, payment'],
+    ['chart-line', 'analytics, graph, metrics, trend'],
+    ['chart-column', 'bar chart, stats, report'],
+    ['chart-pie', 'share, distribution, analytics'],
+  ],
+  operations: [
+    ['wrench', 'maintenance, repair, fix, tool'],
+    ['hammer', 'build, construction, tool'],
+    ['settings', 'configuration, preferences, gear'],
+    ['cog', 'gear, mechanism, setup'],
+    ['sliders-horizontal', 'controls, adjust, filters'],
+    ['funnel', 'filter, pipeline, sales funnel, leads'],
+    ['truck', 'delivery, shipping, logistics, transport'],
+    ['warehouse', 'storage, inventory, stock, depot'],
+    ['factory', 'manufacturing, production, plant'],
+    ['container', 'shipping, freight, cargo'],
+    ['boxes', 'inventory, stock, products'],
+    ['package-check', 'delivered, received, fulfilled'],
+    ['route', 'path, journey, road, trip'],
+    ['gauge', 'performance, speed, meter, kpi'],
+    ['activity', 'pulse, health, monitoring'],
+    ['siren', 'emergency, incident, alarm, urgent'],
+    ['shield', 'security, protection, safety, guard'],
+    ['shield-check', 'secure, verified, compliance'],
+    ['lock', 'secure, private, locked, password'],
+    ['key', 'access, password, credentials'],
+    ['hard-hat', 'safety, construction, worker'],
+    ['construction', 'under construction, roadwork, barrier'],
+    ['recycle', 'reuse, sustainability, waste'],
+    ['stamp', 'approval, certify, seal, official'],
+  ],
+  places: [
+    ['building', 'office, company, organization, business'],
+    ['building-complex', 'offices, campus, enterprise, city'],
+    ['house', 'home, residence, property'],
+    ['hotel', 'hospitality, stay, accommodation'],
+    ['school', 'education, campus, class'],
+    ['hospital', 'health, clinic, medical'],
+    ['map', 'location, region, territory'],
+    ['map-pin', 'location, place, address, marker'],
+    ['map-pinned', 'location, venue, destination'],
+    ['globe', 'world, international, web, global'],
+    ['earth', 'planet, world, environment'],
+    ['compass', 'direction, explore, navigation'],
+    ['navigation', 'direction, gps, arrow'],
+    ['plane', 'travel, flight, airport, trip'],
+    ['car', 'vehicle, drive, auto, fleet'],
+    ['bus', 'transit, transport, travel'],
+    ['train-front', 'rail, transit, travel'],
+    ['ship', 'boat, sea, cruise, shipping'],
+    ['bike', 'bicycle, cycling, ride'],
+    ['mountain', 'outdoors, peak, adventure'],
+  ],
+  tech: [
+    ['code', 'development, programming, source'],
+    ['terminal', 'console, shell, command line, cli'],
+    ['server', 'backend, hosting, infrastructure'],
+    ['database', 'data, storage, records, sql'],
+    ['cloud', 'hosting, saas, online'],
+    ['cpu', 'processor, chip, hardware'],
+    ['monitor', 'screen, desktop, display'],
+    ['laptop', 'computer, notebook, device'],
+    ['smartphone', 'mobile, phone, app, device'],
+    ['tablet', 'ipad, device, touch'],
+    ['wifi', 'internet, wireless, network'],
+    ['bluetooth', 'wireless, device, pairing'],
+    ['plug', 'integration, power, connect, plugin'],
+    ['hard-drive', 'disk, storage, backup'],
+    ['git-branch', 'version control, branch, repository'],
+    ['git-pull-request', 'review, merge, code review'],
+    ['bot', 'robot, automation, ai, assistant'],
+    ['brain', 'ai, intelligence, mind, think'],
+    ['puzzle', 'integration, plugin, extension, piece'],
+    ['blocks', 'modules, components, building blocks'],
+    ['bug', 'defect, issue, error, insect'],
+    ['webhook', 'hook, integration, event, api'],
+    ['link', 'url, connection, chain'],
+    ['qr-code', 'scan, code, mobile'],
+    ['keyboard', 'typing, input, shortcut'],
+    ['printer', 'print, document, office'],
+  ],
+  status: [
+    ['circle', 'dot, default, neutral, generic'],
+    ['circle-check', 'done, success, complete, ok'],
+    ['circle-x', 'cancel, failed, error, close'],
+    ['circle-alert', 'warning, attention, issue'],
+    ['circle-question-mark', 'help, question, unknown, faq'],
+    ['circle-pause', 'paused, hold, on hold'],
+    ['circle-play', 'start, running, in progress'],
+    ['circle-dot', 'active, current, selected, record'],
+    ['circle-dashed', 'draft, pending, not started, todo'],
+    ['triangle-alert', 'warning, caution, risk, danger'],
+    ['octagon-alert', 'stop, critical, error, blocker'],
+    ['info', 'information, about, details'],
+    ['ban', 'blocked, forbidden, cancelled, prohibited'],
+    ['check', 'done, ok, yes, approve'],
+    ['x', 'close, no, reject, cancel'],
+    ['loader', 'loading, progress, spinner, working'],
+    ['refresh-cw', 'sync, retry, recurring, update'],
+    ['eye', 'view, visible, watch, review'],
+    ['eye-off', 'hidden, private, invisible'],
+    ['flame', 'hot, trending, urgent, fire'],
+    ['zap', 'fast, energy, power, quick'],
+    ['sparkles', 'new, magic, ai, highlight'],
+    ['star', 'favorite, rating, featured, priority'],
+    ['heart', 'like, love, favorite, health'],
+    ['thumbs-down', 'dislike, reject, bad'],
+    ['badge-check', 'verified, certified, approved, quality'],
+    ['shield-alert', 'risk, threat, security issue'],
+    ['bookmark', 'save, saved, later, mark'],
+    ['pin', 'pinned, important, fixed'],
+  ],
+  objects: [
+    ['book', 'read, manual, library, guide'],
+    ['pen', 'write, sign, edit'],
+    ['pencil', 'edit, draft, write, sketch'],
+    ['palette', 'design, colors, art, theme'],
+    ['brush', 'paint, design, art'],
+    ['camera', 'photo, picture, photography'],
+    ['image', 'picture, photo, media, gallery'],
+    ['music', 'audio, song, sound'],
+    ['headphones', 'audio, listen, podcast, support'],
+    ['gamepad-2', 'game, gaming, play, controller'],
+    ['umbrella', 'insurance, protection, rain, cover'],
+    ['shirt', 'clothing, apparel, fashion, merch'],
+    ['watch', 'time, wearable, clock'],
+    ['coffee', 'break, cafe, drink, morning'],
+    ['utensils', 'food, restaurant, dining, meal'],
+    ['lamp', 'light, idea, desk'],
+    ['armchair', 'furniture, comfort, lounge, waiting room'],
+    ['bed', 'hotel, sleep, rest, room'],
+    ['scissors', 'cut, trim, craft'],
+    ['ruler', 'measure, size, design'],
+    ['trash', 'delete, bin, remove, waste'],
+    ['box', 'package, storage, container'],
+    ['magnet', 'attract, leads, pull'],
+    ['flask-conical', 'lab, science, experiment, test'],
+    ['microscope', 'research, science, lab'],
+    ['stethoscope', 'medical, doctor, health, care'],
+    ['pill', 'medicine, pharmacy, health'],
+    ['dumbbell', 'fitness, gym, workout, sport'],
+  ],
+  nature: [
+    ['leaf', 'eco, green, plant, organic'],
+    ['tree-pine', 'forest, christmas, outdoors'],
+    ['trees', 'forest, park, nature'],
+    ['flower', 'blossom, spring, garden'],
+    ['flower-2', 'blossom, daisy, garden'],
+    ['sprout', 'growth, seedling, startup, new'],
+    ['sun', 'day, light, summer, weather'],
+    ['moon', 'night, dark, sleep'],
+    ['cloud-rain', 'weather, rain, storm'],
+    ['cloud-sun', 'weather, forecast, partly cloudy'],
+    ['snowflake', 'winter, cold, frozen, freeze'],
+    ['droplet', 'water, liquid, drop'],
+    ['waves-horizontal', 'water, sea, ocean, waves'],
+    ['wind', 'air, breeze, weather'],
+    ['mountain-snow', 'alpine, peak, winter'],
+    ['bird', 'animal, fly, wing'],
+    ['fish', 'animal, sea, food'],
+    ['cat', 'pet, animal'],
+    ['dog', 'pet, animal'],
+    ['paw-print', 'pet, animal, vet'],
+    ['feather', 'light, write, bird'],
+    ['apple', 'fruit, food, health, education'],
+    ['carrot', 'vegetable, food, garden'],
+  ],
+}
+
+/** Every catalogue icon with its category and search words, category by category. */
+export const PICKER_ICON_ENTRIES: readonly PickerIconEntry[] = Object.freeze(PICKER_ICON_CATEGORIES.flatMap(
+  category => CATALOGUE[category].map(([name, keywords]): PickerIconEntry =>
+    Object.freeze({ name, category, keywords: Object.freeze(keywords.split(', ')) }))
+))
+
+/** The catalogue's names, in catalogue order. */
+export const PICKER_ICON_NAMES: readonly string[] = Object.freeze(PICKER_ICON_ENTRIES.map(icon => icon.name))

package/src/picker/vocabulary/types.ts

@@ -0,0 +1,72 @@
+import type { PICKER_COLOR_KEYS, PICKER_ICON_CATEGORIES } from './consts.js'
+
+/**
+ * One colour a picker offers. The palette's own entries carry hex values; an application's palette
+ * may carry any CSS colour — a status palette reads its theme's `var(--tone-<t>)` tokens.
+ */
+export interface PickerColor {
+  /** Palette key (`'blue'`), or any id of an application palette (`'info'`). What is stored. */
+  key: string
+  /** The swatch circle the picker shows for this colour (hex or `var(...)`). */
+  swatch: string
+  /** Icon and dot colour on the light page — at least 3:1 on `soft` and on white. */
+  ink: string
+  /** Tile ground on the light page. */
+  soft: string
+  /** Icon and dot colour on the dark page — at least 3:1 on `softDark` and on black. Defaults to `ink`. */
+  inkDark?: string
+  /** Tile ground on the dark page. Defaults to `soft`. */
+  softDark?: string
+  /** English name; absent, the key humanized. */
+  label?: string
+}
+
+/** A stored colour value read against a palette: every field filled in. */
+export interface ResolvedPickerColor {
+  /** The palette key, or the normalized lowercase `#rrggbb` of a custom colour. */
+  key: string
+  /** `true` for a hex value that is not a palette key. */
+  custom: boolean
+  /** English name — the palette label, or the hex itself for a custom colour. */
+  label: string
+  swatch: string
+  ink: string
+  soft: string
+  inkDark: string
+  softDark: string
+}
+
+/** One of the 24 palette keys. */
+export type PickerColorKey = typeof PICKER_COLOR_KEYS[number]
+
+/** One of the icon catalogue's categories. */
+export type PickerIconCategory = typeof PICKER_ICON_CATEGORIES[number]
+
+/** One icon of the catalogue: a kebab-case lucide name, its category and English search words. */
+export interface PickerIconEntry {
+  name: string
+  category: PickerIconCategory
+  keywords: readonly string[]
+}
+
+/** Reads, validates and renders a stored colour value. React-free. */
+export interface PickerColorHelper {
+  /** `'#abc'` or `'#aabbcc'`, any case — the forms a picker accepts as a custom colour. */
+  isHex: (value: unknown) => value is string
+  /** `'#ABC'`, `'abc'`, `'AABBCC'` → `'#aabbcc'`; anything else → `null`. */
+  normalizeHex: (value: string) => string | null
+  /**
+   * A key of `colors` (default the 24-colour palette) or a hex value, every field filled in — a hex
+   * gets an ink and a ground derived from it that keep 4.5:1 in both modes. Unknown or empty → `null`.
+   */
+  resolve: (value: string | null | undefined, colors?: readonly PickerColor[]) => ResolvedPickerColor | null
+  /**
+   * The CSS custom properties `--pick-swatch`, `--pick-ink`, `--pick-soft`, `--pick-ink-dark` and
+   * `--pick-soft-dark` for a value — what every picker part reads. Unknown → the fallback colour's
+   * (`slate`, or the first entry of an application palette without one). A plain string record, so it
+   * goes straight into a React `style` (and merges with other properties there).
+   */
+  styleOf: (value: string | null | undefined, colors?: readonly PickerColor[]) => Record<string, string>
+  /** The same key for the same seed — a stable colour for a record that has none of its own. */
+  hashKey: (seed: string, keys?: readonly string[]) => string
+}

package/src/picker/vocabulary.ts

@@ -0,0 +1,111 @@
+/**
+ * `@owlmeans/web-panel/picker/vocabulary` — the picker's data and its colour helper, with no React
+ * and no icon set: the palette, the icon catalogue's names, categories and search words, and
+ * `pickerColorHelper`. Safe to import from a server, a seed or a Node build script.
+ */
+
+import { PICKER_COLORS, PICKER_COLOR_KEYS, PICKER_FALLBACK_COLOR } from './vocabulary/consts.js'
+import type { PickerColor, PickerColorHelper, ResolvedPickerColor } from './vocabulary/types.js'
+import { colorUtils } from './utils/color.js'
+
+export * from './vocabulary/consts.js'
+export type * from './vocabulary/types.js'
+
+export const createPickerColorHelper = (): PickerColorHelper => {
+  // Derivation walks lightness in small steps; a page renders the same custom colour many times.
+  const derived = new Map<string, ResolvedPickerColor>()
+
+  const isHex = (value: unknown): value is string =>
+    typeof value === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim())
+
+  const normalizeHex = (value: string): string | null => {
+    const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value.trim())
+    if (match == null) {
+      return null
+    }
+    const digits = match[1].toLowerCase()
+
+    return `#${digits.length === 3 ? [...digits].map(digit => digit + digit).join('') : digits}`
+  }
+
+  const humanize = (key: string): string => {
+    const words = key.replace(/[-_]+/g, ' ').trim()
+
+    return words === '' ? key : words[0].toUpperCase() + words.slice(1)
+  }
+
+  const fill = (color: PickerColor): ResolvedPickerColor => ({
+    key: color.key,
+    custom: false,
+    label: color.label ?? humanize(color.key),
+    swatch: color.swatch,
+    ink: color.ink,
+    soft: color.soft,
+    inkDark: color.inkDark ?? color.ink,
+    softDark: color.softDark ?? color.soft,
+  })
+
+  const custom = (hex: string): ResolvedPickerColor => {
+    const known = derived.get(hex)
+    if (known != null) {
+      return known
+    }
+    const resolved: ResolvedPickerColor = { key: hex, custom: true, label: hex.toUpperCase(), swatch: hex, ...colorUtils.derive(hex) }
+    derived.set(hex, resolved)
+
+    return resolved
+  }
+
+  const resolve = (
+    value: string | null | undefined, colors: readonly PickerColor[] = PICKER_COLORS
+  ): ResolvedPickerColor | null => {
+    if (typeof value !== 'string' || value.trim() === '') {
+      return null
+    }
+    const key = value.trim()
+    const known = colors.find(color => color.key === key) ?? colors.find(color => color.key === key.toLowerCase())
+    if (known != null) {
+      return fill(known)
+    }
+    const hex = normalizeHex(key)
+
+    return hex != null && key.startsWith('#') ? custom(hex) : null
+  }
+
+  const paletteFallback = fill(PICKER_COLORS.find(color => color.key === PICKER_FALLBACK_COLOR) ?? PICKER_COLORS[0])
+
+  const fallbackOf = (colors: readonly PickerColor[]): ResolvedPickerColor => {
+    const fallback = colors.find(color => color.key === PICKER_FALLBACK_COLOR) ?? colors.at(0)
+
+    return fallback != null ? fill(fallback) : paletteFallback
+  }
+
+  const styleOf = (
+    value: string | null | undefined, colors: readonly PickerColor[] = PICKER_COLORS
+  ): Record<string, string> => {
+    const color = resolve(value, colors) ?? fallbackOf(colors)
+
+    return {
+      '--pick-swatch': color.swatch,
+      '--pick-ink': color.ink,
+      '--pick-soft': color.soft,
+      '--pick-ink-dark': color.inkDark,
+      '--pick-soft-dark': color.softDark,
+    }
+  }
+
+  const hashKey = (seed: string, keys: readonly string[] = PICKER_COLOR_KEYS): string => {
+    // FNV-1a: tiny, stable across runtimes, and spreads short ids well enough for a palette.
+    let hash = 0x811c9dc5
+    for (let index = 0; index < seed.length; index++) {
+      hash ^= seed.charCodeAt(index)
+      hash = Math.imul(hash, 0x01000193) >>> 0
+    }
+
+    return keys.length > 0 ? keys[hash % keys.length] : PICKER_FALLBACK_COLOR
+  }
+
+  return { isHex, normalizeHex, resolve, styleOf, hashKey }
+}
+
+export const pickerColorHelper = createPickerColorHelper()

package/src/scheme/consts.ts

@@ -0,0 +1,8 @@
+/** The `localStorage` key the choice lives under. */
+export const COLOR_SCHEME_KEY = 'owlmeans:color-scheme'
+
+/**
+ * The event `applyColorScheme` dispatches on `window` after every change, so every mounted
+ * `useColorScheme` in the document — two toggles, a header and a footer — agrees at once.
+ */
+export const COLOR_SCHEME_EVENT = 'owlmeans:color-scheme'

package/src/scheme/index.ts

@@ -0,0 +1,3 @@
+export { colorSchemeHelper, createColorSchemeHelper, colorSchemeBootstrapScript } from './scheme.js'
+export { COLOR_SCHEME_KEY, COLOR_SCHEME_EVENT } from './consts.js'
+export type { ColorSchemeChoice, ColorSchemeHelper } from './types.js'