@ankhorage/zora 0.12.1 → 0.12.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.12.2
+
+### Patch Changes
+
+- da31347: Adds internal hue-role assignment for future ZORA theme generation work.
+
 ## 0.12.1
 
 ### Patch Changes

package/dist/internal/color/index.d.ts

@@ -1,6 +1,7 @@
 export { computeZoraHarmony, type ZoraComputedHarmony, type ZoraHarmonySlot, type ZoraHarmonySlotId, } from './harmony';
 export { parseHexToOklch } from './oklch';
 export { resolveModePrimaryColor } from './primary';
+export { assignZoraHarmonyRoleHues, getZoraHueRoleAssignment, type ZoraComputedHueRoles, type ZoraHueRoleAssignment, type ZoraHueRoleId, } from './roleHues';
 export { createZoraColorScale, type CreateZoraColorScaleOptions, createZoraNeutralScale, createZoraPrimaryScale, } from './scales';
 export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/internal/color/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/internal/color/index.js

@@ -1,6 +1,7 @@
 export { computeZoraHarmony, } from './harmony';
 export { parseHexToOklch } from './oklch';
 export { resolveModePrimaryColor } from './primary';
+export { assignZoraHarmonyRoleHues, getZoraHueRoleAssignment, } from './roleHues';
 export { createZoraColorScale, createZoraNeutralScale, createZoraPrimaryScale, } from './scales';
 export { ZORA_COLOR_SCALE_STEPS } from './types';
 //# sourceMappingURL=index.js.map

package/dist/internal/color/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,oBAAoB,EAEpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAgD,MAAM,SAAS,CAAC","sourcesContent":["export {\n  computeZoraHarmony,\n  type ZoraComputedHarmony,\n  type ZoraHarmonySlot,\n  type ZoraHarmonySlotId,\n} from './harmony';\nexport { parseHexToOklch } from './oklch';\nexport { resolveModePrimaryColor } from './primary';\nexport {\n  createZoraColorScale,\n  type CreateZoraColorScaleOptions,\n  createZoraNeutralScale,\n  createZoraPrimaryScale,\n} from './scales';\nexport { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/color/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,wBAAwB,GAIzB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EAEpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAgD,MAAM,SAAS,CAAC","sourcesContent":["export {\n  computeZoraHarmony,\n  type ZoraComputedHarmony,\n  type ZoraHarmonySlot,\n  type ZoraHarmonySlotId,\n} from './harmony';\nexport { parseHexToOklch } from './oklch';\nexport { resolveModePrimaryColor } from './primary';\nexport {\n  assignZoraHarmonyRoleHues,\n  getZoraHueRoleAssignment,\n  type ZoraComputedHueRoles,\n  type ZoraHueRoleAssignment,\n  type ZoraHueRoleId,\n} from './roleHues';\nexport {\n  createZoraColorScale,\n  type CreateZoraColorScaleOptions,\n  createZoraNeutralScale,\n  createZoraPrimaryScale,\n} from './scales';\nexport { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';\n"]}

package/dist/internal/color/roleHues.d.ts

@@ -0,0 +1,15 @@
+import type { ZoraColorHarmony } from '../../theme/types';
+import type { ZoraComputedHarmony, ZoraHarmonySlotId } from './harmony';
+export type ZoraHueRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';
+export interface ZoraHueRoleAssignment {
+    role: ZoraHueRoleId;
+    hue: number;
+    sourceSlotId: ZoraHarmonySlotId;
+}
+export interface ZoraComputedHueRoles {
+    harmony: ZoraColorHarmony;
+    assignments: readonly ZoraHueRoleAssignment[];
+}
+export declare function assignZoraHarmonyRoleHues(harmony: ZoraComputedHarmony): ZoraComputedHueRoles;
+export declare function getZoraHueRoleAssignment(roles: ZoraComputedHueRoles, role: ZoraHueRoleId): ZoraHueRoleAssignment;
+//# sourceMappingURL=roleHues.d.ts.map

package/dist/internal/color/roleHues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roleHues.d.ts","sourceRoot":"","sources":["../../../src/internal/color/roleHues.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAmB,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGzF,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;AAE7F,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC/C;AAmCD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,GAAG,oBAAoB,CA8E5F;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,aAAa,GAClB,qBAAqB,CAQvB"}

package/dist/internal/color/roleHues.js

@@ -0,0 +1,103 @@
+import { normalizeHueDegrees } from './hue';
+function findSlot(harmony, id) {
+    return harmony.orderedSlots.find((slot) => slot.id === id);
+}
+function requireBaseSlot(harmony) {
+    const base = findSlot(harmony, 'base');
+    if (!base) {
+        throw new Error(`[zora] Expected harmony to include a base slot (kind: ${harmony.kind}).`);
+    }
+    return base;
+}
+function assignRole(role, harmony, preferred, fallback = 'base') {
+    const base = requireBaseSlot(harmony);
+    const preferredSlot = findSlot(harmony, preferred);
+    const fallbackSlot = findSlot(harmony, fallback);
+    const chosenSlot = preferredSlot ?? fallbackSlot ?? base;
+    return {
+        role,
+        hue: normalizeHueDegrees(chosenSlot.hue),
+        sourceSlotId: chosenSlot.id,
+    };
+}
+export function assignZoraHarmonyRoleHues(harmony) {
+    const { kind } = harmony;
+    if (kind === 'monochromatic') {
+        return {
+            harmony: kind,
+            assignments: [
+                assignRole('primary', harmony, 'base'),
+                assignRole('secondary', harmony, 'base'),
+                assignRole('accent', harmony, 'base'),
+                assignRole('highlight', harmony, 'base'),
+                assignRole('surfaceTint', harmony, 'base'),
+            ],
+        };
+    }
+    if (kind === 'complementary') {
+        return {
+            harmony: kind,
+            assignments: [
+                assignRole('primary', harmony, 'base'),
+                assignRole('secondary', harmony, 'base'),
+                assignRole('accent', harmony, 'a'),
+                assignRole('highlight', harmony, 'a'),
+                assignRole('surfaceTint', harmony, 'base'),
+            ],
+        };
+    }
+    if (kind === 'analogous') {
+        return {
+            harmony: kind,
+            assignments: [
+                assignRole('primary', harmony, 'base'),
+                assignRole('secondary', harmony, 'a'),
+                assignRole('accent', harmony, 'b', 'a'),
+                assignRole('highlight', harmony, 'b', 'a'),
+                assignRole('surfaceTint', harmony, 'a'),
+            ],
+        };
+    }
+    if (kind === 'splitComplementary') {
+        return {
+            harmony: kind,
+            assignments: [
+                assignRole('primary', harmony, 'base'),
+                assignRole('secondary', harmony, 'a'),
+                assignRole('accent', harmony, 'b', 'a'),
+                assignRole('highlight', harmony, 'b', 'a'),
+                assignRole('surfaceTint', harmony, 'base'),
+            ],
+        };
+    }
+    if (kind === 'triadic') {
+        return {
+            harmony: kind,
+            assignments: [
+                assignRole('primary', harmony, 'base'),
+                assignRole('secondary', harmony, 'a'),
+                assignRole('accent', harmony, 'b', 'a'),
+                assignRole('highlight', harmony, 'b', 'a'),
+                assignRole('surfaceTint', harmony, 'base'),
+            ],
+        };
+    }
+    return {
+        harmony: kind,
+        assignments: [
+            assignRole('primary', harmony, 'base'),
+            assignRole('secondary', harmony, 'a'),
+            assignRole('accent', harmony, 'b', 'a'),
+            assignRole('highlight', harmony, 'c', 'b'),
+            assignRole('surfaceTint', harmony, 'base'),
+        ],
+    };
+}
+export function getZoraHueRoleAssignment(roles, role) {
+    const found = roles.assignments.find((assignment) => assignment.role === role);
+    if (!found) {
+        throw new Error(`[zora] Expected a hue-role assignment for "${role}" (harmony: ${roles.harmony}).`);
+    }
+    return found;
+}
+//# sourceMappingURL=roleHues.js.map

package/dist/internal/color/roleHues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roleHues.js","sourceRoot":"","sources":["../../../src/internal/color/roleHues.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAe5C,SAAS,QAAQ,CACf,OAA4B,EAC5B,EAAqB;IAErB,OAAO,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,eAAe,CAAC,OAA4B;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,yDAAyD,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CACjB,IAAmB,EACnB,OAA4B,EAC5B,SAA4B,EAC5B,WAA8B,MAAM;IAEpC,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACnD,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,aAAa,IAAI,YAAY,IAAI,IAAI,CAAC;IAEzD,OAAO;QACL,IAAI;QACJ,GAAG,EAAE,mBAAmB,CAAC,UAAU,CAAC,GAAG,CAAC;QACxC,YAAY,EAAE,UAAU,CAAC,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,OAA4B;IACpE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAEzB,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;gBACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC;gBACxC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC;gBACrC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC;gBACxC,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;aAC3C;SACF,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QAC7B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;gBACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC;gBACxC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC;gBAClC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC;gBACrC,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;aAC3C;SACF,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;gBACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC;gBACrC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBACvC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBAC1C,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,GAAG,CAAC;aACxC;SACF,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,oBAAoB,EAAE,CAAC;QAClC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;gBACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC;gBACrC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBACvC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBAC1C,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;aAC3C;SACF,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,WAAW,EAAE;gBACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;gBACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC;gBACrC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBACvC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;gBAC1C,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;aAC3C;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,WAAW,EAAE;YACX,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;YACtC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC;YACrC,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;YACvC,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC;YAC1C,UAAU,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC;SAC3C;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,KAA2B,EAC3B,IAAmB;IAEnB,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC/E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,eAAe,KAAK,CAAC,OAAO,IAAI,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { ZoraColorHarmony } from '../../theme/types';\nimport type { ZoraComputedHarmony, ZoraHarmonySlot, ZoraHarmonySlotId } from './harmony';\nimport { normalizeHueDegrees } from './hue';\n\nexport type ZoraHueRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';\n\nexport interface ZoraHueRoleAssignment {\n  role: ZoraHueRoleId;\n  hue: number;\n  sourceSlotId: ZoraHarmonySlotId;\n}\n\nexport interface ZoraComputedHueRoles {\n  harmony: ZoraColorHarmony;\n  assignments: readonly ZoraHueRoleAssignment[];\n}\n\nfunction findSlot(\n  harmony: ZoraComputedHarmony,\n  id: ZoraHarmonySlotId,\n): ZoraHarmonySlot | undefined {\n  return harmony.orderedSlots.find((slot) => slot.id === id);\n}\n\nfunction requireBaseSlot(harmony: ZoraComputedHarmony): ZoraHarmonySlot {\n  const base = findSlot(harmony, 'base');\n  if (!base) {\n    throw new Error(`[zora] Expected harmony to include a base slot (kind: ${harmony.kind}).`);\n  }\n  return base;\n}\n\nfunction assignRole(\n  role: ZoraHueRoleId,\n  harmony: ZoraComputedHarmony,\n  preferred: ZoraHarmonySlotId,\n  fallback: ZoraHarmonySlotId = 'base',\n): ZoraHueRoleAssignment {\n  const base = requireBaseSlot(harmony);\n  const preferredSlot = findSlot(harmony, preferred);\n  const fallbackSlot = findSlot(harmony, fallback);\n  const chosenSlot = preferredSlot ?? fallbackSlot ?? base;\n\n  return {\n    role,\n    hue: normalizeHueDegrees(chosenSlot.hue),\n    sourceSlotId: chosenSlot.id,\n  };\n}\n\nexport function assignZoraHarmonyRoleHues(harmony: ZoraComputedHarmony): ZoraComputedHueRoles {\n  const { kind } = harmony;\n\n  if (kind === 'monochromatic') {\n    return {\n      harmony: kind,\n      assignments: [\n        assignRole('primary', harmony, 'base'),\n        assignRole('secondary', harmony, 'base'),\n        assignRole('accent', harmony, 'base'),\n        assignRole('highlight', harmony, 'base'),\n        assignRole('surfaceTint', harmony, 'base'),\n      ],\n    };\n  }\n\n  if (kind === 'complementary') {\n    return {\n      harmony: kind,\n      assignments: [\n        assignRole('primary', harmony, 'base'),\n        assignRole('secondary', harmony, 'base'),\n        assignRole('accent', harmony, 'a'),\n        assignRole('highlight', harmony, 'a'),\n        assignRole('surfaceTint', harmony, 'base'),\n      ],\n    };\n  }\n\n  if (kind === 'analogous') {\n    return {\n      harmony: kind,\n      assignments: [\n        assignRole('primary', harmony, 'base'),\n        assignRole('secondary', harmony, 'a'),\n        assignRole('accent', harmony, 'b', 'a'),\n        assignRole('highlight', harmony, 'b', 'a'),\n        assignRole('surfaceTint', harmony, 'a'),\n      ],\n    };\n  }\n\n  if (kind === 'splitComplementary') {\n    return {\n      harmony: kind,\n      assignments: [\n        assignRole('primary', harmony, 'base'),\n        assignRole('secondary', harmony, 'a'),\n        assignRole('accent', harmony, 'b', 'a'),\n        assignRole('highlight', harmony, 'b', 'a'),\n        assignRole('surfaceTint', harmony, 'base'),\n      ],\n    };\n  }\n\n  if (kind === 'triadic') {\n    return {\n      harmony: kind,\n      assignments: [\n        assignRole('primary', harmony, 'base'),\n        assignRole('secondary', harmony, 'a'),\n        assignRole('accent', harmony, 'b', 'a'),\n        assignRole('highlight', harmony, 'b', 'a'),\n        assignRole('surfaceTint', harmony, 'base'),\n      ],\n    };\n  }\n\n  return {\n    harmony: kind,\n    assignments: [\n      assignRole('primary', harmony, 'base'),\n      assignRole('secondary', harmony, 'a'),\n      assignRole('accent', harmony, 'b', 'a'),\n      assignRole('highlight', harmony, 'c', 'b'),\n      assignRole('surfaceTint', harmony, 'base'),\n    ],\n  };\n}\n\nexport function getZoraHueRoleAssignment(\n  roles: ZoraComputedHueRoles,\n  role: ZoraHueRoleId,\n): ZoraHueRoleAssignment {\n  const found = roles.assignments.find((assignment) => assignment.role === role);\n  if (!found) {\n    throw new Error(\n      `[zora] Expected a hue-role assignment for \"${role}\" (harmony: ${roles.harmony}).`,\n    );\n  }\n  return found;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {

package/src/internal/color/index.ts

@@ -6,6 +6,13 @@ export {
 } from './harmony';
 export { parseHexToOklch } from './oklch';
 export { resolveModePrimaryColor } from './primary';
+export {
+  assignZoraHarmonyRoleHues,
+  getZoraHueRoleAssignment,
+  type ZoraComputedHueRoles,
+  type ZoraHueRoleAssignment,
+  type ZoraHueRoleId,
+} from './roleHues';
 export {
   createZoraColorScale,
   type CreateZoraColorScaleOptions,

package/src/internal/color/roleHues.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  assignZoraHarmonyRoleHues,
+  getZoraHueRoleAssignment,
+  type ZoraComputedHarmony,
+  type ZoraComputedHueRoles,
+  type ZoraHueRoleAssignment,
+  type ZoraHueRoleId,
+} from './index';
+
+function expectNormalizedHue(hue: number) {
+  expect(Number.isFinite(hue)).toBe(true);
+  expect(hue).toBeGreaterThanOrEqual(0);
+  expect(hue).toBeLessThan(360);
+}
+
+const ROLE_ORDER: readonly ZoraHueRoleId[] = [
+  'primary',
+  'secondary',
+  'accent',
+  'highlight',
+  'surfaceTint',
+];
+
+function expectEveryRoleOnce(roles: ReturnType<typeof assignZoraHarmonyRoleHues>) {
+  expect(roles.assignments).toHaveLength(ROLE_ORDER.length);
+  expect(roles.assignments.map((assignment) => assignment.role)).toEqual(ROLE_ORDER);
+}
+
+describe('assignZoraHarmonyRoleHues', () => {
+  test('monochromatic assigns every role to base', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'monochromatic',
+      orderedSlots: [{ id: 'base', hue: 100 }],
+    };
+
+    const roles: ZoraComputedHueRoles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    for (const assignment of roles.assignments) {
+      expect(assignment.sourceSlotId).toBe('base');
+      expect(assignment.hue).toBe(100);
+      expectNormalizedHue(assignment.hue);
+    }
+  });
+
+  test('complementary assigns accent/highlight to a', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 280 },
+      ],
+    };
+
+    const roles: ZoraComputedHueRoles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    const accent: ZoraHueRoleAssignment = getZoraHueRoleAssignment(roles, 'accent');
+    const highlight: ZoraHueRoleAssignment = getZoraHueRoleAssignment(roles, 'highlight');
+
+    expect(accent.sourceSlotId).toBe('a');
+    expect(highlight.sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+  });
+
+  test('analogous assigns secondary/surfaceTint to a and accent/highlight to b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+        { id: 'b', hue: 130 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'secondary').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('b');
+  });
+
+  test('splitComplementary assigns primary/surfaceTint to base and accent/highlight to b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'splitComplementary',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 250 },
+        { id: 'b', hue: 310 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('b');
+  });
+
+  test('triadic assigns primary/surfaceTint to base and secondary/accent across a/b', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'triadic',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 220 },
+        { id: 'b', hue: 340 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'primary').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'surfaceTint').sourceSlotId).toBe('base');
+    expect(getZoraHueRoleAssignment(roles, 'secondary').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('b');
+  });
+
+  test('tetradic assigns highlight to c', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'tetradic',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 190 },
+        { id: 'b', hue: 280 },
+        { id: 'c', hue: 10 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('c');
+  });
+
+  test('every assignment hue is normalized to [0, 360)', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [
+        { id: 'base', hue: -10 },
+        { id: 'a', hue: 370 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    for (const assignment of roles.assignments) {
+      expectNormalizedHue(assignment.hue);
+    }
+  });
+
+  test('is deterministic for the same computed harmony', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+        { id: 'b', hue: 130 },
+      ],
+    };
+
+    expect(assignZoraHarmonyRoleHues(harmony)).toEqual(assignZoraHarmonyRoleHues(harmony));
+  });
+
+  test('falls back when a preferred non-base slot is missing', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'analogous',
+      orderedSlots: [
+        { id: 'base', hue: 100 },
+        { id: 'a', hue: 70 },
+      ],
+    };
+
+    const roles = assignZoraHarmonyRoleHues(harmony);
+
+    expectEveryRoleOnce(roles);
+    expect(getZoraHueRoleAssignment(roles, 'accent').sourceSlotId).toBe('a');
+    expect(getZoraHueRoleAssignment(roles, 'highlight').sourceSlotId).toBe('a');
+  });
+
+  test('throws a clear error when the base slot is missing', () => {
+    const harmony: ZoraComputedHarmony = {
+      kind: 'complementary',
+      orderedSlots: [{ id: 'a', hue: 200 }],
+    };
+
+    expect(() => assignZoraHarmonyRoleHues(harmony)).toThrow('base');
+  });
+});

package/src/internal/color/roleHues.ts

@@ -0,0 +1,142 @@
+import type { ZoraColorHarmony } from '../../theme/types';
+import type { ZoraComputedHarmony, ZoraHarmonySlot, ZoraHarmonySlotId } from './harmony';
+import { normalizeHueDegrees } from './hue';
+
+export type ZoraHueRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';
+
+export interface ZoraHueRoleAssignment {
+  role: ZoraHueRoleId;
+  hue: number;
+  sourceSlotId: ZoraHarmonySlotId;
+}
+
+export interface ZoraComputedHueRoles {
+  harmony: ZoraColorHarmony;
+  assignments: readonly ZoraHueRoleAssignment[];
+}
+
+function findSlot(
+  harmony: ZoraComputedHarmony,
+  id: ZoraHarmonySlotId,
+): ZoraHarmonySlot | undefined {
+  return harmony.orderedSlots.find((slot) => slot.id === id);
+}
+
+function requireBaseSlot(harmony: ZoraComputedHarmony): ZoraHarmonySlot {
+  const base = findSlot(harmony, 'base');
+  if (!base) {
+    throw new Error(`[zora] Expected harmony to include a base slot (kind: ${harmony.kind}).`);
+  }
+  return base;
+}
+
+function assignRole(
+  role: ZoraHueRoleId,
+  harmony: ZoraComputedHarmony,
+  preferred: ZoraHarmonySlotId,
+  fallback: ZoraHarmonySlotId = 'base',
+): ZoraHueRoleAssignment {
+  const base = requireBaseSlot(harmony);
+  const preferredSlot = findSlot(harmony, preferred);
+  const fallbackSlot = findSlot(harmony, fallback);
+  const chosenSlot = preferredSlot ?? fallbackSlot ?? base;
+
+  return {
+    role,
+    hue: normalizeHueDegrees(chosenSlot.hue),
+    sourceSlotId: chosenSlot.id,
+  };
+}
+
+export function assignZoraHarmonyRoleHues(harmony: ZoraComputedHarmony): ZoraComputedHueRoles {
+  const { kind } = harmony;
+
+  if (kind === 'monochromatic') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'base'),
+        assignRole('accent', harmony, 'base'),
+        assignRole('highlight', harmony, 'base'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'complementary') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'base'),
+        assignRole('accent', harmony, 'a'),
+        assignRole('highlight', harmony, 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'analogous') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'a'),
+      ],
+    };
+  }
+
+  if (kind === 'splitComplementary') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  if (kind === 'triadic') {
+    return {
+      harmony: kind,
+      assignments: [
+        assignRole('primary', harmony, 'base'),
+        assignRole('secondary', harmony, 'a'),
+        assignRole('accent', harmony, 'b', 'a'),
+        assignRole('highlight', harmony, 'b', 'a'),
+        assignRole('surfaceTint', harmony, 'base'),
+      ],
+    };
+  }
+
+  return {
+    harmony: kind,
+    assignments: [
+      assignRole('primary', harmony, 'base'),
+      assignRole('secondary', harmony, 'a'),
+      assignRole('accent', harmony, 'b', 'a'),
+      assignRole('highlight', harmony, 'c', 'b'),
+      assignRole('surfaceTint', harmony, 'base'),
+    ],
+  };
+}
+
+export function getZoraHueRoleAssignment(
+  roles: ZoraComputedHueRoles,
+  role: ZoraHueRoleId,
+): ZoraHueRoleAssignment {
+  const found = roles.assignments.find((assignment) => assignment.role === role);
+  if (!found) {
+    throw new Error(
+      `[zora] Expected a hue-role assignment for "${role}" (harmony: ${roles.harmony}).`,
+    );
+  }
+  return found;
+}