@rafters/shared 0.4.4 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafters/shared",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Shared W3C DTCG schemas, base types, and utilities for Rafters design system",
   "homepage": "https://rafters.studio",
   "license": "MIT",

package/src/types.ts

@@ -70,16 +70,32 @@ export const DTCGTokenBaseSchema = z.object({
 export type DTCGTokenBase = z.infer<typeof DTCGTokenBaseSchema>;
 
 /**
- * W3C DTCG Color Value (OKLCH format)
+ * W3C DTCG Color Value (Design Tokens Color Module 2025.10, section 4.1)
+ * https://www.designtokens.org/TR/2025.10/color/
  */
 export const DTCGColorValueSchema = z.object({
-  colorSpace: z.literal('oklch'),
-  channels: z.tuple([
-    z.number().min(0).max(1), // Lightness
-    z.number().min(0), // Chroma
-    z.number().min(0).max(360), // Hue
+  colorSpace: z.enum([
+    'srgb',
+    'srgb-linear',
+    'hsl',
+    'hwb',
+    'lab',
+    'lch',
+    'oklab',
+    'oklch',
+    'display-p3',
+    'a98-rgb',
+    'prophoto-rgb',
+    'rec2020',
+    'xyz-d65',
+    'xyz-d50',
   ]),
-  alpha: z.number().min(0).max(1).optional().default(1),
+  components: z.array(z.union([z.number(), z.literal('none')])),
+  alpha: z.number().min(0).max(1).optional(),
+  hex: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/)
+    .optional(),
 });
 
 export type DTCGColorValue = z.infer<typeof DTCGColorValueSchema>;
@@ -126,26 +142,27 @@ export const DTCGFileSchema = z.record(z.string(), z.union([DTCGTokenBaseSchema,
 export type DTCGFile = z.infer<typeof DTCGFileSchema>;
 
 /**
- * Helper: Convert OKLCH to DTCG Color Value
+ * Helper: Convert OKLCH to DTCG Color Value.
+ * `alpha` is present only when it is below 1 (Color Module 2025.10 defaults it to 1).
  */
 export function oklchToDTCG(oklch: OKLCH): DTCGColorValue {
-  return {
-    colorSpace: 'oklch',
-    channels: [oklch.l, oklch.c, oklch.h],
-    alpha: oklch.alpha ?? 1,
-  };
+  const value: DTCGColorValue = { colorSpace: 'oklch', components: [oklch.l, oklch.c, oklch.h] };
+  if (oklch.alpha !== undefined && oklch.alpha < 1) value.alpha = oklch.alpha;
+  return value;
 }
 
 /**
- * Helper: Convert DTCG Color Value to OKLCH
+ * Helper: Convert an oklch DTCG Color Value to OKLCH. A `none` component reads as 0.
  */
 export function dtcgToOKLCH(dtcg: DTCGColorValue): OKLCH {
-  return {
-    l: dtcg.channels[0],
-    c: dtcg.channels[1],
-    h: dtcg.channels[2],
-    alpha: dtcg.alpha ?? 1,
+  if (dtcg.colorSpace !== 'oklch') {
+    throw new Error(`dtcgToOKLCH: colorSpace "${dtcg.colorSpace}" is not oklch`);
+  }
+  const component = (i: number): number => {
+    const c = dtcg.components[i];
+    return typeof c === 'number' ? c : 0;
   };
+  return { l: component(0), c: component(1), h: component(2), alpha: dtcg.alpha ?? 1 };
 }
 
 /**
@@ -371,6 +388,25 @@ export type PerceptualWeight = z.infer<typeof PerceptualWeightSchema>;
 export const SEMANTIC_STATUS_ROLES = ['destructive', 'success', 'warning', 'info'] as const;
 export type SemanticStatusRole = (typeof SEMANTIC_STATUS_ROLES)[number];
 
+// Family roles: the semantic tokens a designer assigns a palette to. Every
+// other semantic colour belongs to one of these (its owner), and the CSS
+// exporter emits one 50-950 scale per role so a role change moves everything
+// it owns.
+export const SEMANTIC_FAMILY_ROLES = [
+  'primary',
+  'secondary',
+  'tertiary',
+  'accent',
+  'highlight',
+  'neutral',
+  'muted',
+  'success',
+  'warning',
+  'destructive',
+  'info',
+] as const;
+export type SemanticFamilyRole = (typeof SEMANTIC_FAMILY_ROLES)[number];
+
 // Semantic Color Suggestions Schema.
 // 'danger' is a deprecated mirror of 'destructive', kept while apps/api (which
 // asserts .danger) migrates to platform. Inputs with only the legacy key parse
@@ -416,6 +452,18 @@ export const ColorValueSchema = z.object({
 
   // Unique token ID for quick color lookups (e.g., "color-0.500-0.120-240.0")
   tokenId: z.string().optional(),
+
+  // The gamut each scale step sits in, index-aligned with `scale`. Generated
+  // steps are 'srgb' or 'p3'; only an imported seed pinned as typed can be 'out'.
+  gamut: z.array(z.enum(['srgb', 'p3', 'out'])).optional(),
+  // Present when the family was built from a different seed than requested
+  seedAdjusted: z
+    .object({
+      from: OKLCHSchema,
+      to: OKLCHSchema,
+      reason: z.enum(['lightness-bounds', 'gamut']),
+    })
+    .optional(),
 });
 
 export type ColorValue = z.infer<typeof ColorValueSchema>;

package/src/version.ts

@@ -4,4 +4,4 @@
  * Written by packages/cli/scripts/sync-version.ts from the CLI's own
  * package.json version at build time -- do not edit by hand.
  */
-export const RAFTERS_VERSION = '0.4.4';
+export const RAFTERS_VERSION = '0.4.5';