@cognitap/radiant 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +19 -15
  3. package/dist/library/color/colorFamilies.d.ts +3 -0
  4. package/dist/library/color/colorFamilies.d.ts.map +1 -0
  5. package/dist/library/color/colorFamilies.js +20 -0
  6. package/dist/library/color/colorFamilies.js.map +1 -0
  7. package/dist/library/color/generateColorWall.d.ts +54 -0
  8. package/dist/library/color/generateColorWall.d.ts.map +1 -0
  9. package/dist/library/color/generateColorWall.js +231 -0
  10. package/dist/library/color/generateColorWall.js.map +1 -0
  11. package/dist/library/color/index.d.ts +5 -0
  12. package/dist/library/color/index.d.ts.map +1 -0
  13. package/dist/library/color/index.js +3 -0
  14. package/dist/library/color/index.js.map +1 -0
  15. package/dist/library/color/oklch.d.ts +17 -0
  16. package/dist/library/color/oklch.d.ts.map +1 -0
  17. package/dist/library/color/oklch.js +79 -0
  18. package/dist/library/color/oklch.js.map +1 -0
  19. package/dist/library/color/recommendColorPalette.d.ts +65 -0
  20. package/dist/library/color/recommendColorPalette.d.ts.map +1 -0
  21. package/dist/library/color/recommendColorPalette.js +263 -0
  22. package/dist/library/color/recommendColorPalette.js.map +1 -0
  23. package/dist/library/index.d.ts +8 -2
  24. package/dist/library/index.d.ts.map +1 -1
  25. package/dist/library/index.js +4 -1
  26. package/dist/library/index.js.map +1 -1
  27. package/dist/library/styles.css +1 -1
  28. package/dist/library/themes/index.d.ts +4 -0
  29. package/dist/library/themes/index.d.ts.map +1 -1
  30. package/dist/library/themes/index.js +2 -0
  31. package/dist/library/themes/index.js.map +1 -1
  32. package/dist/library/themes/themeDocument.d.ts +16 -0
  33. package/dist/library/themes/themeDocument.d.ts.map +1 -0
  34. package/dist/library/themes/themeDocument.js +307 -0
  35. package/dist/library/themes/themeDocument.js.map +1 -0
  36. package/dist/library/themes/themeDocumentTypes.d.ts +69 -0
  37. package/dist/library/themes/themeDocumentTypes.d.ts.map +1 -0
  38. package/dist/library/themes/themeDocumentTypes.js +2 -0
  39. package/dist/library/themes/themeDocumentTypes.js.map +1 -0
  40. package/dist/library/themes/updateThemeAppearance.d.ts +29 -0
  41. package/dist/library/themes/updateThemeAppearance.d.ts.map +1 -0
  42. package/dist/library/themes/updateThemeAppearance.js +138 -0
  43. package/dist/library/themes/updateThemeAppearance.js.map +1 -0
  44. package/docs/system.md +13 -0
  45. package/docs/theming.md +412 -0
  46. package/package.json +11 -4
  47. package/src/color/colorFamilies.ts +19 -0
  48. package/src/color/generateColorWall.ts +358 -0
  49. package/src/color/index.ts +11 -0
  50. package/src/color/oklch.ts +95 -0
  51. package/src/color/recommendColorPalette.ts +375 -0
  52. package/src/index.ts +37 -0
  53. package/src/themes/index.ts +24 -0
  54. package/src/themes/themeDocument.ts +340 -0
  55. package/src/themes/themeDocumentTypes.ts +76 -0
  56. package/src/themes/updateThemeAppearance.ts +172 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"updateThemeAppearance.js","sourceRoot":"","sources":["../../../src/themes/updateThemeAppearance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AA6B7E,MAAM,MAAM,GAAG;IACb,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;IACpB,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;IACtB,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;IACtB,kBAAkB,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,kBAAkB,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACjB,eAAe,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC;CACjB,CAAA;AACV,SAAS,MAAM,CAAC,KAAc,EAAE,IAAY;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAA;AACrD,CAAC;AACD,SAAS,IAAI,CAAC,KAAa,EAAE,OAA0B,EAAE,IAAY;IACnE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QAClC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,WAAW,IAAI,IAAI,GAAG,GAAG,CAAC,CAAA;AAC9E,CAAC;AACD,SAAS,QAAQ,CAAC,KAAc,EAAE,IAAY;IAC5C,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACnB,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,EAAE,IAAI,CAAC,CAAA;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,IAAI,IAAI,KAAK,SAAS;YAAE,SAAQ;QAChC,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;YAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAQ;QACxF,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,GAA0B,CAAC,CAAA;YACrD,IACE,OAAO,IAAI,KAAK,QAAQ;gBACxB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACrB,IAAI,IAAI,GAAG;gBACX,IAAI,IAAI,GAAG;gBACX,CAAC,GAAG,KAAK,WAAW,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBAE/C,SAAQ;YACV,MAAM,IAAI,SAAS,CACjB,GAAG,IAAI,IAAI,GAAG,iCAAiC,GAAG,OAAO,GAAG,GAAG,GAAG,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,CAC1G,CAAA;QACH,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,+CAA+C,CAAC,CAAA;IAC7E,CAAC;AACH,CAAC;AACD,MAAM,MAAM,GAAG,CAAC,GAAW,EAAE,MAAc,EAAE,EAAE,CAC7C,GAAG,MAAM,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAEvD,SAAS,cAAc,CAAC,QAA+B,EAAE,IAAsB;IAC7E,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;IAChC,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,MAAM,OAAO,GAA4B,EAAE,CAAA;IAC3C,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YACrD,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;QAChD,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAU;YAC3C,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC9D,CAAC;IACD,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS;QAChC,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,EAAE,CAAC;YACzD,MAAM,OAAO,GAA2B,EAAE,CAAA;YAC1C,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,EAAE,eAAe,CAAU;gBACrE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;YAClE,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;QACzB,CAAC;IACH,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI;QAC1B,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACpB,CAAC,aAAa,EAAE,aAAa,CAAC;KACtB,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,GAAG,EAAE,CAAC,EACjC,CAAC,GAAG,QAAQ,CAAC,UAAU,GAAG,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAA;QAC/C,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAA;IACjD,CAAC;IACD,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS;QACpC,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAA;IAClE,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAA;QAChC,OAAO,CAAC,MAAM;YACZ,KAAK,KAAK,CAAC;gBACT,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,KAAK,KAAK,CAAC;oBACX,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM;oBACrB,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,uBAAuB,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAA;QAC5F,OAAO,CAAC,aAAa;YACnB,KAAK,KAAK,CAAC;gBACT,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,KAAK,KAAK,CAAC;oBACX,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa;oBAC5B,CAAC,CAAC,KAAK,KAAK,GAAG,EAAE,MAAM,KAAK,GAAG,EAAE,wBAAwB,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAA;IAChG,CAAC;IACD,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS;QACxC,OAAO,CAAC,QAAQ,GAAG,eAAe,QAAQ,CAAC,eAAe,GAAG,CAAA;IAC/D,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpD,CAAA;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,qBAAqB,CACnC,QAAuB,EACvB,QAAiC;IAEjC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAC9B,IAAI,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,CAAA;IAChE,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,OAAO,KAAK,CAAC;QAC1D,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAA;IACpE,IAAI,IAAI,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IACxC,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAA;QAC9C,IAAI,QAAQ,CAAC,OAAO,CAAC,OAAO,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAA;QAChG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAA;QAC1D,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,4BAA4B,CAAC,CAAA;QAC9D,IAAI,GAAG,mBAAmB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;QAC9E,IAAI,GAAG,mBAAmB,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACzE,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAClC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACvC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAA;IACvC,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAA;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;QAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAA;IAC1F,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,2BAA2B,CAAC,CAAA;QACnD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,2BAA2B,CAAC,CAAA;IACtE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAU,EAAE,CAAC;QAC9C,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS;YACtC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,6BAA6B,IAAI,EAAE,CAAC,CAAA;QACrE,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAA;QACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACrE,IAAI,KAAK,KAAK,SAAS;gBAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QAClE,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAC3C,IAAI,GAAG,mBAAmB,CACxB,IAAI,EACJ,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CACtF,CACF,CAAA;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["import type { ColorPalette } from '../color/recommendColorPalette.js'\nimport { tokenDefaults, type ThemeTokens } from './tokens.js'\nimport { defineThemeDocument, updateThemeDocument } from './themeDocument.js'\nimport type { ThemeDocument, ThemeSection } from './themeDocumentTypes.js'\n\n/** Bounded workshop controls; dimensions are derived from the neutral baseline, not compounded. */\nexport interface ThemeGeometrySettings {\n /** 0.5–2; scales shared gaps and panel padding, retaining rem units. */\n readonly spacing?: number\n /** 0.75–1.5; scales all three control heights, inline padding and indicators, not fonts. */\n readonly density?: number\n /** Pixels, 0–32. Checkbox still caps its inherited radius; Radio stays circular. */\n readonly controlRadius?: number\n /** Pixels, 0–48. */\n readonly surfaceRadius?: number\n /** Pixels, 0–4. */\n readonly controlBorderWidth?: number\n readonly surfaceBorderWidth?: number\n readonly borderStyle?: 'solid' | 'dashed' | 'dotted'\n /** 0 = none, 1 = baseline, 2 = raised, 3 = floating. Passive and overlay shadows only. */\n readonly elevation?: 0 | 1 | 2 | 3\n /** 0–0.9; black modal backdrop. Panel filtering remains a component exception. */\n readonly backdropOpacity?: number\n}\n\nexport interface ThemeAppearanceSettings {\n readonly version?: 1\n readonly palette?: Pick<ColorPalette, 'version' | 'color' | 'surface'>\n readonly geometry?: ThemeSection<ThemeGeometrySettings>\n}\n\nconst bounds = {\n spacing: [0.5, 2],\n density: [0.75, 1.5],\n controlRadius: [0, 32],\n surfaceRadius: [0, 48],\n controlBorderWidth: [0, 4],\n surfaceBorderWidth: [0, 4],\n elevation: [0, 3],\n backdropOpacity: [0, 0.9]\n} as const\nfunction record(value: unknown, path: string): asserts value is Record<string, unknown> {\n if (!value || typeof value !== 'object' || Array.isArray(value))\n throw new TypeError(`${path} must be an object.`)\n}\nfunction keys(value: object, allowed: readonly string[], path: string) {\n for (const key of Object.keys(value))\n if (!allowed.includes(key)) throw new TypeError(`Unknown ${path}.${key}.`)\n}\nfunction validate(value: unknown, path: string): asserts value is ThemeGeometrySettings {\n record(value, path)\n keys(value, [...Object.keys(bounds), 'borderStyle'], path)\n for (const [key, item] of Object.entries(value)) {\n if (item === undefined) continue\n if (key === 'borderStyle') {\n if (typeof item === 'string' && ['solid', 'dashed', 'dotted'].includes(item)) continue\n } else {\n const [min, max] = bounds[key as keyof typeof bounds]\n if (\n typeof item === 'number' &&\n Number.isFinite(item) &&\n item >= min &&\n item <= max &&\n (key !== 'elevation' || Number.isInteger(item))\n )\n continue\n throw new TypeError(\n `${path}.${key} must be a finite number from ${min} to ${max}${key === 'elevation' ? ' (integer)' : ''}.`\n )\n }\n throw new TypeError(`${path}.borderStyle must be solid, dashed or dotted.`)\n }\n}\nconst scaled = (rem: string, factor: number) =>\n `${Number((parseFloat(rem) * factor).toFixed(6))}rem`\n\nfunction geometryTokens(settings: ThemeGeometrySettings, mode: 'light' | 'dark'): ThemeTokens {\n const base = tokenDefaults[mode]\n const spacing: Record<string, string> = {}\n const control: Record<string, unknown> = {}\n const surface: Record<string, string> = {}\n if (settings.spacing !== undefined) {\n for (const [key, value] of Object.entries(base.spacing))\n spacing[key] = scaled(value, settings.spacing)\n for (const key of ['padding', 'gap'] as const)\n surface[key] = scaled(base.surface[key], settings.spacing)\n }\n if (settings.density !== undefined)\n for (const size of ['small', 'medium', 'large'] as const) {\n const metrics: Record<string, string> = {}\n for (const key of ['height', 'paddingInline', 'indicatorSize'] as const)\n metrics[key] = scaled(base.control[size][key], settings.density)\n control[size] = metrics\n }\n for (const [key, target] of [\n ['Radius', 'radius'],\n ['BorderWidth', 'borderWidth']\n ] as const) {\n const a = settings[`control${key}`],\n b = settings[`surface${key}`]\n if (a !== undefined) control[target] = `${a}px`\n if (b !== undefined) surface[target] = `${b}px`\n }\n if (settings.borderStyle !== undefined)\n control.borderStyle = surface.borderStyle = settings.borderStyle\n if (settings.elevation !== undefined) {\n const level = settings.elevation\n surface.shadow =\n level === 0\n ? 'none'\n : level === 1\n ? base.surface.shadow\n : `0 ${level * 2}px ${level * 6}px -2px rgb(0 0 0 / ${mode === 'light' ? 0.12 : 0.4})`\n surface.overlayShadow =\n level === 0\n ? 'none'\n : level === 1\n ? base.surface.overlayShadow\n : `0 ${level * 12}px ${level * 32}px -16px rgb(0 0 0 / ${mode === 'light' ? 0.3 : 0.6})`\n }\n if (settings.backdropOpacity !== undefined)\n surface.backdrop = `rgb(0 0 0 / ${settings.backdropOpacity})`\n return {\n ...(Object.keys(spacing).length ? { spacing } : {}),\n ...(Object.keys(control).length ? { control } : {}),\n ...(Object.keys(surface).length ? { surface } : {})\n }\n}\n\n/** Apply generated color/canvas atomically and geometry leaves without erasing authored exceptions. */\nexport function updateThemeAppearance(\n document: ThemeDocument,\n settings: ThemeAppearanceSettings\n): ThemeDocument {\n record(settings, 'appearance')\n keys(settings, ['version', 'palette', 'geometry'], 'appearance')\n if (settings.version !== undefined && settings.version !== 1)\n throw new TypeError('Unsupported appearance.version; expected 1.')\n let next = defineThemeDocument(document)\n if (settings.palette !== undefined) {\n record(settings.palette, 'appearance.palette')\n if (settings.palette.version !== 1) throw new TypeError('appearance.palette.version must be 1.')\n record(settings.palette.color, 'appearance.palette.color')\n record(settings.palette.surface, 'appearance.palette.surface')\n next = updateThemeDocument(next, { color: settings.palette.color }, 'replace')\n next = updateThemeDocument(next, { surface: settings.palette.surface })\n }\n const geometry = settings.geometry\n if (geometry === undefined) return next\n record(geometry, 'appearance.geometry')\n keys(geometry, ['values', 'modes'], 'appearance.geometry')\n if (geometry.values !== undefined) validate(geometry.values, 'appearance.geometry.values')\n if (geometry.modes !== undefined) {\n record(geometry.modes, 'appearance.geometry.modes')\n keys(geometry.modes, ['light', 'dark'], 'appearance.geometry.modes')\n }\n for (const mode of ['light', 'dark'] as const) {\n if (geometry.modes?.[mode] !== undefined)\n validate(geometry.modes[mode], `appearance.geometry.modes.${mode}`)\n const values = { ...geometry.values }\n for (const [key, value] of Object.entries(geometry.modes?.[mode] ?? {}))\n if (value !== undefined) Object.assign(values, { [key]: value })\n const tokens = geometryTokens(values, mode)\n next = updateThemeDocument(\n next,\n Object.fromEntries(\n Object.entries(tokens).map(([group, value]) => [group, { modes: { [mode]: value } }])\n )\n )\n }\n return next\n}\n"]}
package/docs/system.md CHANGED
@@ -50,6 +50,19 @@ fonts in your application; choosing a theme never downloads a font. The
50
50
  [theming reference](theming.md#define-and-apply-a-theme) owns the authoring
51
51
  example, token defaults, preset IDs, font families/weights and migration steps.
52
52
 
53
+ For public workshop editing, use the versioned `ThemeDocument` authoring API.
54
+ Its token sections compile through `defineTheme` into the same `ThemeScope`
55
+ contract. Section imports preserve unrelated settings and deliberate component
56
+ exceptions. See [portable documents and import semantics](theming.md#portable-workshop-documents). The pure
57
+ `generateColorWall` interface supplies calibrated sRGB palette metadata through
58
+ `@cognitap/radiant/color`; see [color-wall inputs and output](theming.md#generate-a-color-wall). Use
59
+ `colorCalibrationPresets` for independent wall/ramp treatments (Classic, Balanced,
60
+ Expressive; Balanced by default), and `recommendColorPalette` to select a limited working set, map light/dark color and
61
+ canvas layers, and inspect named contrast pairs before compiling a theme.
62
+ Apply these together with bounded geometry using `updateThemeAppearance`; it
63
+ updates existing spacing, control and surface roles without removing authored
64
+ component exceptions. See [appearance settings](theming.md#apply-palette-spacing-and-surfaces-together).
65
+
53
66
  | Token group | Shared responsibility |
54
67
  | ------------ | ---------------------------------------------------------------------------------- |
55
68
  | `color` | Surface, foreground, borders, focus, invalid/disabled colors and action tone pairs |
package/docs/theming.md CHANGED
@@ -70,6 +70,418 @@ values → that theme's mode values**. Missing dark values use the dark baseline
70
70
  unless a common value already overrides them. Put a common color in `tokens`
71
71
  only when it works in both modes, or supply its dark counterpart explicitly.
72
72
 
73
+ ## Portable workshop documents
74
+
75
+ `ThemeDocument` is the versioned authoring format for the public theme workshop.
76
+ It keeps authored values and editor metadata; `Theme` remains the resolved data
77
+ accepted by `ThemeScope`. Radiant owns validation, section updates and compilation.
78
+ The documentation application owns selection, undo history, persistence and UI.
79
+ These APIs are unreleased until the next package publication.
80
+
81
+ ```tsx
82
+ import {
83
+ ThemeScope,
84
+ themeDocumentFromDefinition,
85
+ updateThemeDocument,
86
+ compileThemeDocument,
87
+ exportThemeSections,
88
+ parseThemeDocument
89
+ } from '@cognitap/radiant'
90
+
91
+ const initial = themeDocumentFromDefinition({
92
+ id: 'garden',
93
+ name: 'Garden',
94
+ tokens: {
95
+ typography: { family: 'system-ui, sans-serif' },
96
+ surface: { radius: '1rem' }
97
+ },
98
+ components: { button: { radius: '2rem' } }
99
+ })
100
+
101
+ const document = updateThemeDocument(initial, {
102
+ color: {
103
+ brand: { value: '#166534', gamut: 'srgb' },
104
+ palettes: [
105
+ {
106
+ id: 'brand',
107
+ name: 'Brand',
108
+ swatches: [{ stop: 500, value: '#166534' }]
109
+ }
110
+ ],
111
+ anchor: { paletteId: 'brand', stop: 500 },
112
+ values: { accent: '#166534', accentForeground: '#ffffff' },
113
+ modes: { dark: { accent: '#86efac', accentForeground: '#052e16' } }
114
+ }
115
+ })
116
+
117
+ const theme = compileThemeDocument(document)
118
+ const scope = (
119
+ <ThemeScope
120
+ theme={theme}
121
+ mode="system"
122
+ >
123
+ Garden
124
+ </ThemeScope>
125
+ )
126
+
127
+ // Full authoring configuration, including font descriptors and component exceptions.
128
+ const fullJSON = JSON.stringify(document)
129
+ // Resolved application output, accepted directly by ThemeScope after JSON round trip.
130
+ const runtimeJSON = JSON.stringify(theme)
131
+ // Only these sections; deliberately excludes identity and component exceptions.
132
+ const colorJSON = JSON.stringify(exportThemeSections(document, ['color']))
133
+
134
+ const imported = parseThemeDocument(JSON.parse(colorJSON))
135
+ const next =
136
+ imported.kind === 'radiant-theme'
137
+ ? imported // Explicit full replacement of the editor's document.
138
+ : updateThemeDocument(initial, imported.sections, 'replace')
139
+ ```
140
+
141
+ `defineThemeDocument` accepts a typed document literal. `parseThemeDocument`
142
+ accepts unknown data, such as `JSON.parse` output, and returns either a full
143
+ `{ kind: 'radiant-theme', version: 1, id, name, sections }` document or a selective
144
+ `{ kind: 'radiant-theme-sections', version: 1, sections }` export. Both are
145
+ validated, detached and deeply frozen. Unsupported versions fail with a migration
146
+ message; unknown fields and invalid values identify their path. No automatic
147
+ version migration or silent dropping of future fields occurs. Parse text with
148
+ `JSON.parse` first so malformed JSON errors remain distinct from schema errors.
149
+
150
+ The section names follow the existing token groups: `color`, `typography`,
151
+ `control`, `surface`, `focus`, `motion`, `spacing`, `state`, plus `components`.
152
+ Each has optional `values` and `modes.light`/`modes.dark`. Values are exactly the
153
+ corresponding partial token group or component override map, retaining its
154
+ existing types and validation. Typography and motion will extend these sections
155
+ when their richer authoring models are defined; arbitrary runtime or engine
156
+ objects are not configuration fields. Editor layout can combine sections: the
157
+ spacing/surfaces editor can update `control`, `surface`, `spacing`, `focus` and
158
+ `state` together as needed.
159
+
160
+ Compilation uses the same **mode defaults → common values → mode values**
161
+ resolution as `defineTheme`, including all component resets. Metadata does not
162
+ change rendered values: a palette or brand input alone never overwrites semantic
163
+ roles. The color engine and semantic mapping stages will populate those values.
164
+ The original `defineTheme` API, presets, CSS routes and scope behavior are unchanged.
165
+ `themeDocumentFromDefinition` imports an authored `ThemeDefinition`, retaining
166
+ only explicit overrides rather than baking in library defaults. It does not
167
+ reverse-engineer a resolved `Theme` or recover authoring metadata from a preset.
168
+
169
+ ### Section editing and import semantics
170
+
171
+ | Operation | Result |
172
+ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
173
+ | `updateThemeDocument(doc, sections)` | Merge supplied leaves recursively; preserve omitted leaves and sections. Arrays replace as a whole. |
174
+ | `updateThemeDocument(doc, sections, 'replace')` | Replace each supplied section, including all its mode layers and metadata. Omitted sections remain intact. |
175
+ | `updateThemeDocument(doc, { color: {} }, 'replace')` | Reset that section to library fallback values by removing its authored values and metadata. |
176
+ | `updateThemeDocument(doc, { color: {} })` | Empty merge is a no-op. |
177
+ | Parse a full document and use it as editor state | Replace identity and every section; no implicit merge. |
178
+ | Parse a selective export, then pass its `sections` to an update | Apply an explicit merge or replacement while retaining the destination identity. |
179
+
180
+ Updates preserve deliberate component exceptions unless `components` is explicitly
181
+ included. A typography change therefore retains a Button-only font; a color
182
+ change retains an Input-only focus color. Select `components` separately to copy
183
+ those exceptions. Resetting `color` does not reset an exception in `components`.
184
+ To delete individual leaves, replace their section with the desired retained
185
+ values. `null` is invalid, and optional object properties set to `undefined` are
186
+ omitted, not deletion markers. Array holes and undefined array elements are invalid.
187
+
188
+ ### Color identity and font boundaries
189
+
190
+ `color.brand` retains the original `value`, declared `gamut` (`srgb` or
191
+ `display-p3`) and optional explicitly labeled `srgbFallback`. Adding a brand
192
+ materialises `fidelity: 'anchored'` unless `unanchored` was explicitly selected.
193
+ `palettes` holds named ramps with unique stops from 50, 100, 200, …, 900, 950.
194
+ Partial ramps can be saved while authoring. An optional `anchor` references a
195
+ palette/stop whose value must exactly equal `brand.value`; a stale anchor fails
196
+ validation with a regeneration/replacement instruction. An unanchored ramp omits
197
+ `anchor`. A fallback cannot stand in for the unchanged original.
198
+
199
+ This schema preserves the exact-anchoring decision; it does not generate ramps,
200
+ parse color syntax, check gamut claims, measure contrast or prove balanced swatches.
201
+ Use the color generator and semantic mapper below for those separate responsibilities. A P3 source
202
+ and labeled fallback can be retained as data without claiming P3 generation support.
203
+ Changing source/fidelity alongside an existing anchor requires a coherent replacement
204
+ or regenerated palette; the compiler never silently adjusts the source.
205
+
206
+ `typography.fonts` contains portable descriptors: unique `id`, `family`, `source`
207
+ (`system`, `catalog` or `local`), optional numeric `weights` (1–1000) and `styles`
208
+ (`normal`/`italic`). These describe requirements; the consuming application loads
209
+ fonts and determines availability. Local font bytes, file paths/handles, URLs,
210
+ DOM objects and runtime functions have no fields in the schema. A local family
211
+ name can travel with the configuration, but the local font itself does not.
212
+ Font metadata does not set `typography.values.family` automatically.
213
+
214
+ Full and selective authoring JSON preserve those descriptors; only selecting
215
+ `typography` exports them. Compiled `Theme` output contains resolved CSS values
216
+ and no palette/source/font metadata. Both formats are data: plain objects,
217
+ arrays, strings, booleans, null and finite numbers, restricted further by their
218
+ field schema. Functions, class/binary instances, cycles, accessors and unsupported
219
+ keys fail before import can silently discard data.
220
+
221
+ ## Generate a color wall
222
+
223
+ ```ts
224
+ import { generateColorWall, colorCalibrationPresets } from '@cognitap/radiant/color'
225
+ import { updateThemeDocument } from '@cognitap/radiant'
226
+
227
+ const wall = generateColorWall({
228
+ brand: '#7C3AED',
229
+ wallPreset: 'expressive',
230
+ rampPreset: 'balanced'
231
+ })
232
+ // Registry entries supply stable IDs, names and descriptions for public controls.
233
+ console.log(colorCalibrationPresets)
234
+ // Optional dials are materialised, so this reproduces every output swatch.
235
+ const replay = generateColorWall(JSON.parse(JSON.stringify(wall.input)))
236
+
237
+ // Retain independently authored semantic values/modes; replace generated metadata
238
+ // so switching to unanchored fidelity also removes the previous anchor.
239
+ const previous = document.sections.color
240
+ const next = updateThemeDocument(
241
+ document,
242
+ {
243
+ color: { values: previous?.values, modes: previous?.modes, ...wall.color }
244
+ },
245
+ 'replace'
246
+ )
247
+ ```
248
+
249
+ The generator is available from the package root and from the React-free
250
+ `@cognitap/radiant/color` entry. It reads no browser globals, loads no fonts and
251
+ uses no randomness or AI. The result is detached, deeply frozen, JSON-safe data.
252
+ This is an unreleased API until the next package publication.
253
+
254
+ `wall.color` fits the existing `ThemeColorSection`: original `brand`, selected
255
+ `fidelity`, 18 `palettes` and an `anchor` only for anchored fidelity. Palette order
256
+ is Brand, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue,
257
+ Indigo, Violet, Purple, Pink, Rose, Neutral. Each has a stable lowercase ID and
258
+ 11 swatches at 50, 100, 200, …, 900, 950. Generated values are opaque six-digit
259
+ sRGB hex; the exact original preserves its supplied spelling/case.
260
+ `wall.neutralInput` reports the low-chroma path. `wall.input` contains all
261
+ materialised controls and algorithm `version: 1` for replay. Persist that input
262
+ as a generator recipe separately; the current version-1 theme document stores
263
+ its color output, not a new untyped generation-settings field.
264
+
265
+ | Input | Default | Supported range / meaning |
266
+ | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
267
+ | `brand` | Required | Opaque six-digit sRGB hex. Alpha, CSS functions, named colors and P3 sources are rejected explicitly. |
268
+ | `version` | `1` | Only the calibrated algorithm version 1 is supported. |
269
+ | `gamut` | `srgb` | Only sRGB output is currently supported. No automatic P3 fallback or source replacement. |
270
+ | `fidelity` | `anchored` | `anchored` preserves the original at its nearest-lightness numbered stop; `unanchored` keeps the regular ramp and separate original. |
271
+ | `wallPreset` | `balanced` | `classic`, `balanced`, `expressive`; selects the supporting wall's curves, automatic vividness, neutral tint and hue alignment. |
272
+ | `rampPreset` | `balanced` | Same three IDs, independently selects brand curves, automatic vividness and anchor reshaping. |
273
+ | `brandVividness` | Source-derived by ramp preset | 0–1 brand-ramp chroma, independent of wall vividness; never changes the exact source. |
274
+ | `vividness` | Source-derived by wall preset | 0–1 supporting-wall chroma; it never changes the brand ramp. |
275
+ | `lightness` | `hue-aware` | `hue-aware` adapts the middle toward each hue's gamut cusp; `shared` uses the common reference curve. |
276
+ | `distribution` | `1` | .75–1.35. Redistributes intermediate shades while retaining endpoints/middle in regular chromatic ramps. |
277
+ | `neutralTint` | Classic `.012`, Balanced `.008`, Expressive `.016` | 0–.035 peak chroma in the Neutral ramp; zero produces untinted grays. |
278
+ | `hueAlignment` | Classic `.6`, Balanced `.25`, Expressive `.5` | 0–1. Rotate the wall so its nearest named family moves toward the brand hue; family order/spacing stays intact. |
279
+ | `neutralHue` | `255` | Any finite degrees, wrapped into [0, 360). Explicit direction when source C < .02; the near-neutral Brand ramp remains neutral apart from its exact source neighborhood. |
280
+
281
+ Classic retains the [accepted DEV-151 calibration](https://github.com/cognitap/radiant/blob/50044fc0d6d66c94b2e3dfb02fc17c0d2828aff6/docs/research/dev-151-calibration-proposal.md).
282
+ It uses the reference lightness curve .985, .965, .93, .87, .79, .70, .61, .52,
283
+ .43, .34, .24, hue-relative gamut fractions and a smooth chroma envelope. Anchored
284
+ fidelity reshapes neighboring lightness and chroma around the unchanged source.
285
+ Balanced and Expressive use monotone cubic lightness reshaping and local gamut-relative
286
+ chroma blending around the anchor; Classic retains linear lightness reshaping.
287
+ For automatic settings, let `m = sqrt(clamp(source C / .28, 0, 1))`. Balanced uses
288
+ wall strength `.45 + .4m` and brand strength `.18 + .65m`; Expressive uses
289
+ `.6 + .3m` and `.28 + .62m`. Classic uses source C / available C, clamped to
290
+ .10–.92 (.35 for low-chroma sources), for both. Hue-aware midpoints, envelope
291
+ limits and distribution curves follow the selected preset independently.
292
+ `distribution` multiplies each preset's exponent (Classic 1, Balanced .95,
293
+ Expressive 1.05); `shared` fixes the midpoint at .7. Explicit dials override
294
+ preset defaults, and every effective input is materialised for exact replay.
295
+ Public editors should clear wall-owned dials (vividness/tint/alignment) when
296
+ selecting a wall preset, and brandVividness when selecting a ramp preset; retain
297
+ independent controls and explicit semantic pins.
298
+
299
+ Nearest-lightness ties prefer the earlier/lighter stop. Black and white can
300
+ occupy the endpoint stops. Metrics and anchor selection use actual quantized
301
+ colors, rather than assuming requested OKLCH values survived mapping unchanged.
302
+
303
+ The mapper reduces chroma at constant lightness/hue until the result fits sRGB,
304
+ then emits 8-bit output. Conversion uses [Ottosson's Oklab matrices](https://bottosson.github.io/posts/oklab/)
305
+ and the [CSS Color 4 transfer functions](https://www.w3.org/TR/css-color-4/#color-conversion-code).
306
+ This deliberate mapper does not claim to duplicate a browser's gamut-mapping
307
+ algorithm. The per-call caches are discarded after generation; past calls cannot
308
+ change subsequent results or retain an unbounded history of user colors.
309
+
310
+ A color wall is palette data. It does not select semantic text/action/state
311
+ roles, guarantee contrast on arbitrary surfaces or certify chart distinctions.
312
+ Use `recommendColorPalette` below for working sets and named role-pair checks.
313
+ `compileThemeDocument` continues to use only
314
+ semantic `values`/`modes`; adding this metadata alone does not change a rendered
315
+ theme. In Storybook, **System → Color Wall → Reference** exposes the accepted
316
+ 12 inputs and controls for visual inspection; the public workshop UI remains
317
+ separate documentation-application work.
318
+
319
+ ## Recommend a working palette and semantic roles
320
+
321
+ ```ts
322
+ import { generateColorWall, recommendColorPalette } from '@cognitap/radiant/color'
323
+ import { updateThemeDocument, compileThemeDocument } from '@cognitap/radiant'
324
+
325
+ const wall = generateColorWall({ brand: '#7C3AED' })
326
+ const palette = recommendColorPalette(wall, {
327
+ working: { support: 'teal' },
328
+ modes: { dark: { focus: '#ABCDEF' } }
329
+ })
330
+
331
+ // Replace the complete color section, preserving the original source and all ramps.
332
+ // Merge the canvas layer to retain surface radius, spacing and other authored values.
333
+ const colored = updateThemeDocument(document, { color: palette.color }, 'replace')
334
+ const themed = updateThemeDocument(colored, { surface: palette.surface })
335
+ const theme = compileThemeDocument(themed)
336
+ const failures = palette.checks.filter(check => check.pass === false)
337
+ ```
338
+
339
+ `recommendColorPalette(wall, options?)` consumes a complete version-1 sRGB wall.
340
+ It returns deeply frozen, detached, JSON-safe recommendations. The original
341
+ brand, fidelity, anchor and all 18 ramps remain unchanged in `palette.color`.
342
+ The result has five parts:
343
+
344
+ - `working`: primary, support, neutral, success, warning and danger, each with a
345
+ wall `paletteId` and independently selected light/dark background/foreground pairs.
346
+ - `color`: the original wall metadata plus complete light/dark maps for the
347
+ existing shared color roles. No common-mode values are needed.
348
+ - `surface`: light/dark `canvas` layers, using the existing surface token group.
349
+ - `checks`: measured pairs with mode, role names, exact colors, unrounded ratio,
350
+ minimum, pass/fail and an actionable failure message.
351
+ - `pass`: whether every listed required pair passes. This is a scoped contrast
352
+ result, not a complete accessibility or arbitrary-theme certification.
353
+
354
+ Defaults use Brand as primary, Neutral for surfaces, Emerald for success, Amber
355
+ for warning and Red for danger. The support family is nearest to primary hue +
356
+ 150°. Low-chroma candidates use the wall's explicit hue direction and nominal
357
+ family geometry rather than numerical hue noise. `working` can replace any of
358
+ these family IDs with another existing wall family. Duplicate families are
359
+ allowed deliberately; color alone does not establish status meaning or chart
360
+ separation. Use labels/icons as appropriate.
361
+
362
+ Light canvas/surface start at Neutral 50/100, dark at 950/900. Foreground,
363
+ secondary text, borders, focus, invalid state and action shades are selected
364
+ against the actual emitted opaque surfaces, independently for each mode. Solid
365
+ pairs require 4.5:1 text contrast. Among eligible primary shades, choose the
366
+ smallest Oklab distance to the original brand, including lightness and both
367
+ chromatic axes. Primary fill also requires 3:1 against both surfaces because it
368
+ identifies checked Checkbox/Radio state. Thus a readable exact source is retained
369
+ when its boundaries also pass; otherwise a nearby readable shade is selected. Exact source identity stays separate: yellow may
370
+ remain the exact Brand 200 while a darker related shade supplies the light action.
371
+ Black/white ink can be selected when it gives the strongest text contrast.
372
+
373
+ `options.version` defaults to 1. `options.modes.light`/`dark` can override any
374
+ existing color role and `canvas`, using opaque six-digit sRGB hex. Provided
375
+ surfaces drive automatic dependent choices; explicit foregrounds and other role
376
+ colors are retained even if they fail. Unsupported fields, palette IDs, versions,
377
+ non-opaque colors and incomplete walls fail with a path or available ID list.
378
+ Recipes remain ordinary serializable options; the existing theme document stores
379
+ mapped values and wall metadata, without adding an untyped recipe field.
380
+
381
+ Contrast uses the [WCAG sRGB luminance formula](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
382
+ on final hex values. Normal text (including secondary text, placeholder and invalid
383
+ text) is checked at 4.5:1 on canvas and surface; solid action/working-palette ink
384
+ is checked at 4.5:1 on its fill. Meaningful border, offset focus ring and primary
385
+ checked-state fill are checked at 3:1 on both surfaces. These are Radiant's
386
+ conservative role policies, not a requirement that every decorative boundary or
387
+ hover/rest color differ by 3:1. See [non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
388
+
389
+ Disabled token pairs have `minimum: null` and `pass: null`, explicitly reflecting
390
+ the inactive-control exception. Their informational ratios exclude component
391
+ opacity/effects. Pending actions remain active and are not exempt. Support/success
392
+ are working-palette pairs; the current component tones remain accent, neutral,
393
+ warning and danger. No new component tones or runtime token roles are introduced.
394
+
395
+ Apply color and canvas together before relying on the report. A color-only import,
396
+ component/local override, gradient/translucent surface or rendered hover/pressed
397
+ effect can change the effective pair. Recheck those contexts in the browser; this
398
+ base-pair report does not silently certify them. **System → Color Palette →
399
+ Reference** reuses the canonical profile form and inspects invalid, disabled,
400
+ checked, pending and keyboard-focus states in both modes. DEV-155 owns the wider
401
+ theme-editor integration is described below; the public editor itself remains in radiant-docs.
402
+
403
+ ## Apply palette, spacing and surfaces together
404
+
405
+ Use `updateThemeAppearance` when the workshop applies generated colors and bounded
406
+ geometry together. It produces an ordinary version-1 `ThemeDocument`; compile it
407
+ through the existing runtime and use either installed CSS route.
408
+
409
+ ```ts
410
+ import {
411
+ themeDocumentFromDefinition,
412
+ updateThemeAppearance,
413
+ compileThemeDocument,
414
+ generateColorWall,
415
+ recommendColorPalette
416
+ } from '@cognitap/radiant'
417
+
418
+ const initial = themeDocumentFromDefinition({
419
+ id: 'brand-workshop',
420
+ name: 'Brand workshop',
421
+ components: { button: { radius: '12px' } } // A deliberate exception survives edits.
422
+ })
423
+ const palette = recommendColorPalette(generateColorWall({ brand: '#7C3AED' }))
424
+ const document = updateThemeAppearance(initial, {
425
+ palette,
426
+ geometry: {
427
+ values: { spacing: 1.25, density: 1.1, controlRadius: 8, surfaceRadius: 16, elevation: 2 },
428
+ modes: { dark: { backdropOpacity: 0.75 } }
429
+ }
430
+ })
431
+ const theme = compileThemeDocument(document)
432
+ // <ThemeScope theme={theme} mode="system">...</ThemeScope>
433
+ ```
434
+
435
+ The optional `palette` is the mapped result of `recommendColorPalette`, not raw
436
+ wall metadata. Its complete color section replaces previous common/mode colors;
437
+ its light/dark canvas leaves merge into surface settings in the same immutable
438
+ operation. Applying a palette never erases radii, padding, elevation or component
439
+ exceptions. A failing deliberate palette choice is retained; inspect its contrast
440
+ report before applying it.
441
+
442
+ `geometry.values` controls both modes; `geometry.modes.light`/`dark` override
443
+ individual controls. Omitted controls retain authored settings. Each provided
444
+ control maps to the existing semantic token leaves in both modes, overriding
445
+ older common or mode values for those leaves. No recipe metadata or new runtime
446
+ token group is added. An empty update changes no values.
447
+
448
+ | Geometry control | Accepted values | Existing responsibilities |
449
+ | ------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
450
+ | `spacing` | 0.5–2 | Multiplies all five `spacing` gaps plus `surface.padding` and `surface.gap`. |
451
+ | `density` | 0.75–1.5 | Multiplies small/medium/large control height, inline padding and indicator size; retains font sizes. |
452
+ | `controlRadius` | 0–32 px | Shared action/input radius; Checkbox caps the inherited radius; Radio remains circular. |
453
+ | `surfaceRadius` | 0–48 px | Card, Dialog and Collapsible shape, including Accordion items. |
454
+ | `controlBorderWidth`, `surfaceBorderWidth` | 0–4 px | Respective shared border widths. |
455
+ | `borderStyle` | `solid`, `dashed`, `dotted` | Both control and surface borders. |
456
+ | `elevation` | Integer 0–3 | 0 removes passive/overlay shadows; 1 uses mode defaults; 2/3 select raised/floating shadows with mode-specific opacity. |
457
+ | `backdropOpacity` | 0–0.9 | Black modal backdrop opacity; panel backdrop filtering stays a Dialog component exception. |
458
+
459
+ Scale controls derive absolute values from the neutral baseline, retaining rem
460
+ units. Reapplying `spacing: 1.25` is idempotent; it never multiplies already-edited
461
+ values. `density: 1` restores baseline metric leaves, while fonts and unrelated
462
+ settings remain authored. Action-local effects/shadows remain component decisions;
463
+ inline Link retains text metrics, and action-shaped Link follows control metrics.
464
+ Values outside the bounds, unknown keys/modes and unsupported `version` (default 1)
465
+ fail with a path instead of being silently clamped. These bounds support workshop
466
+ exploration; border removal, small targets or overrides still need contextual
467
+ accessibility review. Focus behavior, state ownership and forced-colors behavior
468
+ remain the existing families' responsibility.
469
+
470
+ Precedence stays **component exception → shared role → baseline**, followed by
471
+ caller utility/style overrides on the host. Nested mode scopes resolve the same
472
+ compiled theme and retain explicit scope style exceptions; named themes reset
473
+ them. **System → Theme Appearance → Workspace** reuses the canonical ten-family
474
+ workspace, inspects all three control sizes and demonstrates these precedence
475
+ rules. Installed-package checks include the generated theme through compiled CSS
476
+ and Tailwind, with and without a reset.
477
+
478
+ Existing theme definitions, presets, token names, generated baseline CSS and CSS
479
+ imports need no migration. Existing documents can be passed directly; authored
480
+ `ThemeDefinition` inputs use `themeDocumentFromDefinition`. Resolved presets remain
481
+ runtime data and cannot recover their original authoring intent. Advanced CSS
482
+ geometry stays available through typed `updateThemeDocument` token sections and
483
+ component overrides. Public editing and handoff UI follow in DEV-158/DEV-159.
484
+
73
485
  ## Scopes, mode, and overrides
74
486
 
75
487
  `ThemeScope` renders a normal `div` and accepts its native props and ref. It
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cognitap/radiant",
3
- "version": "0.0.3",
3
+ "version": "0.0.4",
4
4
  "description": "React interaction components and presentation primitives",
5
5
  "homepage": "https://github.com/cognitap/radiant#readme",
6
6
  "bugs": {
@@ -37,7 +37,11 @@
37
37
  },
38
38
  "./styles.css": "./dist/library/styles.css",
39
39
  "./reset.css": "./dist/library/reset.css",
40
- "./tailwind.css": "./src/styles.css"
40
+ "./tailwind.css": "./src/styles.css",
41
+ "./color": {
42
+ "types": "./dist/library/color/index.d.ts",
43
+ "default": "./dist/library/color/index.js"
44
+ }
41
45
  },
42
46
  "publishConfig": {
43
47
  "access": "public",
@@ -107,12 +111,15 @@
107
111
  "lint": "oxlint --deny-warnings",
108
112
  "format": "oxfmt",
109
113
  "format:check": "oxfmt --check",
110
- "check": "pnpm theme:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test --styles --compositions && pnpm build:storybook && pnpm test:browser",
114
+ "check:source": "pnpm theme:check && pnpm format:check && pnpm lint && pnpm typecheck",
115
+ "check:ci": "pnpm check:source && pnpm test && pnpm build:storybook && pnpm test:browser:smoke",
116
+ "check": "pnpm check:source && pnpm test --styles --compositions && pnpm build:storybook && pnpm test:browser",
111
117
  "test:compositions": "pnpm build && node scripts/verify-package.mjs --compositions",
112
118
  "release:prepare": "node scripts/prepare-release.mjs",
113
119
  "theme:generate": "node scripts/generate-theme-css.mjs",
114
120
  "theme:check": "node scripts/generate-theme-css.mjs --check",
115
121
  "watch:theme": "node scripts/generate-theme-css.mjs --watch",
116
- "test:browser": "pnpm theme:generate && node scripts/record-browser-environment.mjs && vitest run"
122
+ "test:browser": "pnpm theme:generate && node scripts/record-browser-environment.mjs && vitest run",
123
+ "test:browser:smoke": "pnpm test:browser --project=storybook-radiant-light --project=storybook-radiant-dark --project=browser-platform"
117
124
  }
118
125
  }
@@ -0,0 +1,19 @@
1
+ /** Stable nominal hue geometry shared by generation and semantic recommendations. */
2
+ export const colorFamilies = [
3
+ ['Red', 25],
4
+ ['Orange', 55],
5
+ ['Amber', 80],
6
+ ['Yellow', 100],
7
+ ['Lime', 125],
8
+ ['Green', 145],
9
+ ['Emerald', 165],
10
+ ['Teal', 185],
11
+ ['Cyan', 205],
12
+ ['Sky', 230],
13
+ ['Blue', 255],
14
+ ['Indigo', 275],
15
+ ['Violet', 295],
16
+ ['Purple', 315],
17
+ ['Pink', 340],
18
+ ['Rose', 10]
19
+ ] as const