@rafters/shared 0.4.4 → 0.5.0

package/README.md

@@ -24,7 +24,7 @@ import {
   DTCGColorTokenSchema,
   oklchToDTCG,
   parseJSDocIntelligence,
-  parseFillSignature,
+  FillValueSchema,
   ImportPendingSchema,
   RAFTERS_VERSION,
 } from '@rafters/shared';
@@ -54,6 +54,14 @@ validate against.
 - `ComponentIntelligenceSchema`, `ColorIntelligenceSchema`, `IntelligenceSchema`
   and friends — the shapes the MCP and Studio read when they describe a
   component or a color.
+- `FillValueSchema` / `FillValue` — a fill recipe, the value of a token in the
+  `fill` namespace: background, gradient, mask, backdrop, blend, foreground
+  and border, with an optional `dark` block and `hover`, `active`, `focus`
+  and `disabled` state blocks. `foreground` is required. Every colour in a
+  recipe is a registry reference (`{ family, position }` or
+  `TokenReferenceSchema`'s `{ token }`), never a literal colour.
+- `FILL_NAME_EXCLUDES` — the names a fill cannot take: Tailwind's own `bg-*`
+  utility names and keywords, without the `bg-` prefix.
 - `COMPUTED` — a sentinel symbol. Set a token to it and the system reverts that
   token to its computed value instead of a hardcoded override.
 
@@ -73,19 +81,6 @@ it back out.
   for what's missing or malformed.
 - `toDisplayName(name)` — turn a component id into its display name.
 
-### Fill signatures (`fill-signature.ts`)
-
-`fill=` is a compact color vocabulary, not a styling grammar. `fill="muted/50"`
-is the muted color at 50% alpha; `fill="barbie-pink-to-ken-brown"` is a two-stop
-gradient. `to`, `via`, and `from` are reserved segments.
-
-- `parseFillSignature(input)` — parse a fill string into stops and alpha.
-- `validateFillSignature(signature, hasWord)` — check every stop word against a
-  vocabulary predicate; returns the first unresolvable word, or `null`.
-- `expandFillSignature(signature, context, hasWord?)` — expand a signature into
-  the classes it sets, for the given context (`surface` or `text`).
-- `foregroundWordFor(...)` — pick the readable foreground word for a surface fill.
-
 ### Import pending (`import-pending.ts`)
 
 The schema for tokens found during `rafters init` detection and left awaiting

package/package.json

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

package/src/index.ts

@@ -1,5 +1,4 @@
 export * from './component-intelligence';
-export * from './fill-signature';
 export * from './import-pending';
 export * from './types';
 export * from './version';

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>;
@@ -428,6 +476,169 @@ export const ColorReferenceSchema = z.object({
 
 export type ColorReference = z.infer<typeof ColorReferenceSchema>;
 
+// Token reference: names a role or semantic colour token ("card", "primary")
+// and follows that token through the cascade and the mode (FR-RAF-FILL-001).
+export const TokenReferenceSchema = z.object({ token: z.string().min(1) }).strict();
+
+export type TokenReference = z.infer<typeof TokenReferenceSchema>;
+
+// Fills (FR-RAF-FILL-001): a designer-authored recipe of stock Tailwind parts.
+// Every colour is a registry reference, never a literal.
+const FillColourSchema = z.union([ColorReferenceSchema.strict(), TokenReferenceSchema], {
+  error: 'must be a registry reference ({family, position} or {token}), not a literal colour',
+});
+const PercentSchema = z.number().min(0).max(100);
+const FillStopSchema = z
+  .object({
+    color: FillColourSchema,
+    alpha: PercentSchema.optional(),
+    position: PercentSchema.optional(),
+  })
+  .strict();
+const FillPartsSchema = z
+  .object({
+    background: z
+      .object({ color: FillColourSchema, alpha: PercentSchema.optional() })
+      .strict()
+      .optional(),
+    gradient: z
+      .object({
+        type: z.enum(['linear', 'radial', 'conic']),
+        direction: z
+          .enum(['to-t', 'to-tr', 'to-r', 'to-br', 'to-b', 'to-bl', 'to-l', 'to-tl'])
+          .optional(),
+        angle: z.number().optional(),
+        from: FillStopSchema.optional(),
+        via: FillStopSchema.optional(),
+        to: FillStopSchema.optional(),
+        interpolation: z
+          .enum(['srgb', 'hsl', 'oklab', 'oklch', 'longer', 'shorter', 'increasing', 'decreasing'])
+          .optional(),
+      })
+      .strict()
+      .optional(),
+    mask: z
+      .object({
+        type: z.enum(['linear', 'radial', 'conic', 't', 'r', 'b', 'l', 'x', 'y']),
+        from: PercentSchema.optional(),
+        to: PercentSchema.optional(),
+      })
+      .strict()
+      .optional(),
+    backdrop: z
+      .object({
+        blur: z.enum(['none', 'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl']).optional(),
+        brightness: z.number().min(0).optional(),
+        contrast: z.number().min(0).optional(),
+        saturate: z.number().min(0).optional(),
+        grayscale: PercentSchema.optional(),
+        opacity: PercentSchema.optional(),
+      })
+      .strict()
+      .optional(),
+    blend: z
+      .enum([
+        'normal',
+        'multiply',
+        'screen',
+        'overlay',
+        'darken',
+        'lighten',
+        'color-dodge',
+        'color-burn',
+        'hard-light',
+        'soft-light',
+        'difference',
+        'exclusion',
+        'hue',
+        'saturation',
+        'color',
+        'luminosity',
+      ])
+      .optional(),
+    foreground: FillColourSchema.optional(),
+    border: FillColourSchema.optional(),
+  })
+  .strict();
+const FillStateSchema = FillPartsSchema.extend({ dark: FillPartsSchema.optional() }).strict();
+
+export const FillValueSchema = FillPartsSchema.extend({
+  foreground: FillColourSchema,
+  dark: FillPartsSchema.optional(),
+  hover: FillStateSchema.optional(),
+  active: FillStateSchema.optional(),
+  focus: FillStateSchema.optional(),
+  disabled: FillStateSchema.optional(),
+}).strict();
+
+export type FillValue = z.infer<typeof FillValueSchema>;
+
+// Names a fill cannot take (FR-RAF-FILL-001): Tailwind's static bg-* utilities
+// (45), the legacy ones it still emits (12) and the bg- keywords, each without
+// its `bg-` prefix. Studio keeps the designer-facing list.
+export const FILL_NAME_EXCLUDES: readonly string[] = [
+  'auto',
+  'blend-color',
+  'blend-color-burn',
+  'blend-color-dodge',
+  'blend-darken',
+  'blend-difference',
+  'blend-exclusion',
+  'blend-hard-light',
+  'blend-hue',
+  'blend-lighten',
+  'blend-luminosity',
+  'blend-multiply',
+  'blend-normal',
+  'blend-overlay',
+  'blend-saturation',
+  'blend-screen',
+  'blend-soft-light',
+  'bottom',
+  'bottom-left',
+  'bottom-right',
+  'center',
+  'clip-border',
+  'clip-content',
+  'clip-padding',
+  'clip-text',
+  'contain',
+  'cover',
+  'fixed',
+  'left',
+  'local',
+  'no-repeat',
+  'none',
+  'origin-border',
+  'origin-content',
+  'origin-padding',
+  'repeat',
+  'repeat-round',
+  'repeat-space',
+  'repeat-x',
+  'repeat-y',
+  'right',
+  'scroll',
+  'top',
+  'top-left',
+  'top-right',
+  'left-top',
+  'right-top',
+  'left-bottom',
+  'right-bottom',
+  'gradient-to-t',
+  'gradient-to-tr',
+  'gradient-to-r',
+  'gradient-to-br',
+  'gradient-to-b',
+  'gradient-to-bl',
+  'gradient-to-l',
+  'gradient-to-tl',
+  'inherit',
+  'current',
+  'transparent',
+];
+
 // Progression system labels stamped on tokens to record which math system
 // produced them. Used only by TokenSchema below; the math-utils package
 // carries the actual ratio definitions in DEFAULT_RATIOS. This array will be
@@ -469,7 +680,7 @@ export type OverrideKind = z.infer<typeof OverrideKindSchema>;
 export const TokenSchema = z.object({
   // Core token data
   name: z.string(),
-  value: z.union([z.string(), ColorValueSchema, ColorReferenceSchema]), // String, ColorValue for families, or ColorReference for semantic
+  value: z.union([z.string(), ColorValueSchema, ColorReferenceSchema, FillValueSchema]), // String, ColorValue for families, ColorReference for semantic, FillValue for fills
   category: z.string(),
   namespace: z.string(),
   binding: BindingSchema.optional(), // Plugin binding for cascade-driven values
@@ -502,7 +713,7 @@ export const TokenSchema = z.object({
   userOverride: z
     .object({
       // Value before override (for undo)
-      previousValue: z.union([z.string(), ColorValueSchema, ColorReferenceSchema]),
+      previousValue: z.union([z.string(), ColorValueSchema, ColorReferenceSchema, FillValueSchema]),
       // Why was this overridden
       reason: z.string(),
       // Additional context (e.g. "Q1 marketing campaign", "accessibility audit")
@@ -518,7 +729,9 @@ export const TokenSchema = z.object({
 
   // Computed value from generation rule (before any override)
   // Stored so agents can see what the system WOULD produce vs what human chose
-  computedValue: z.union([z.string(), ColorValueSchema, ColorReferenceSchema]).optional(),
+  computedValue: z
+    .union([z.string(), ColorValueSchema, ColorReferenceSchema, FillValueSchema])
+    .optional(),
 
   // Dependency tracking for automatic regeneration
   dependsOn: z.array(z.string()).optional(), // Parent token(s) - empty = root token

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.5.0';

package/src/fill-signature.ts

@@ -1,217 +0,0 @@
-/**
- * Fill signature (#1637).
- *
- * A fill is a SIGNATURE: a compact form that sets namespaced classes and
- * existing Tailwind utilities on things. Not a grammar, not an adjective
- * system. The phrase is color vocabulary only:
- *
- *   word            solid          fill="barbie-pink"
- *   word/alpha      with opacity   fill="muted/50"        (Tailwind's slash, verbatim)
- *   word-to-word    2-stop gradient  fill="barbie-pink-to-ken-brown"
- *
- * '-to-' is RESERVED in the color namer (generated names can never contain
- * it), so splitting at the first '-to-' is deterministic without vocabulary.
- * With a vocabulary present, every word must resolve or the signature is
- * rejected naming the unresolvable word (the #1632 lesson: hyphens are
- * overloaded in generated names; split only at reserved separators and
- * validate every side).
- *
- * Everything else -- blur, blend, direction -- is already Tailwind's
- * namespace; our tokens set the VALUES behind those words (what
- * backdrop-blur-sm ends up as). Those words are spoken as plain utilities
- * where class lists are legitimate. Not fill's job.
- *
- * Dark contract: falls out of which utility is emitted. Semantic words
- * compile to utilities over flipping vars (bg-primary follows .dark);
- * family words compile to literal scale utilities (never flip).
- */
-
-export interface FillStop {
-  /** A vocabulary word: semantic role, family, or family-position. */
-  word: string;
-  /** Tailwind slash-opacity, integer 0-100. Absent = opaque. */
-  alpha?: number;
-}
-
-export interface FillSignature {
-  /** One stop = solid; two stops = linear gradient (to-b). */
-  stops: [FillStop] | [FillStop, FillStop];
-}
-
-export type FillParseResult =
-  | { ok: true; signature: FillSignature }
-  | { ok: false; word: string; reason: string };
-
-export type FillContext = 'surface' | 'text';
-
-/**
- * Hyphen segments reserved across the system (#1637). The fill parser
- * splits at '-to-'; 'via' and 'from' are Tailwind's other gradient
- * connectors and are reserved alongside so they can join the signature
- * without a namer migration. The color namer's bank invariant test
- * imports this list -- one copy of the reservation.
- */
-export const RESERVED_FILL_SEGMENTS = ['to', 'via', 'from'] as const;
-
-const SEPARATOR = `-${RESERVED_FILL_SEGMENTS[0]}-`;
-const ALPHA_PATTERN = /^(100|[1-9]?[0-9])$/;
-const WORD_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-
-function parseStop(term: string): FillStop | { word: string; reason: string } {
-  const slash = term.indexOf('/');
-  const word = slash === -1 ? term : term.slice(0, slash);
-  if (!WORD_PATTERN.test(word)) {
-    return { word: word || term, reason: 'not a vocabulary word' };
-  }
-  if (slash === -1) return { word };
-  const alphaRaw = term.slice(slash + 1);
-  if (!ALPHA_PATTERN.test(alphaRaw)) {
-    return { word, reason: `invalid opacity "/${alphaRaw}" (integer 0-100)` };
-  }
-  return { word, alpha: Number(alphaRaw) };
-}
-
-/**
- * Parse a fill signature. Syntax only -- vocabulary validation is the
- * caller's job via `validateFillSignature` wherever a registry exists
- * (build, tests, MCP). Runtime components expand optimistically; the
- * build-time safelist pass is the strict gate.
- */
-export function parseFillSignature(input: string): FillParseResult {
-  const trimmed = input.trim();
-  if (trimmed.length === 0) {
-    return { ok: false, word: input, reason: 'empty fill' };
-  }
-  if (trimmed.includes(' ')) {
-    return {
-      ok: false,
-      word: trimmed,
-      reason:
-        'fill is a single signature -- other utilities are plain Tailwind words in the class list',
-    };
-  }
-
-  const split = trimmed.indexOf(SEPARATOR);
-  if (split === -1) {
-    const stop = parseStop(trimmed);
-    if ('reason' in stop) return { ok: false, ...stop };
-    return { ok: true, signature: { stops: [stop] } };
-  }
-
-  const left = trimmed.slice(0, split);
-  const right = trimmed.slice(split + SEPARATOR.length);
-  if (right.includes(SEPARATOR)) {
-    return {
-      ok: false,
-      word: trimmed,
-      reason: 'three-stop gradients are not supported (two stops only)',
-    };
-  }
-  const from = parseStop(left);
-  if ('reason' in from) return { ok: false, ...from };
-  const to = parseStop(right);
-  if ('reason' in to) return { ok: false, ...to };
-  return { ok: true, signature: { stops: [from, to] } };
-}
-
-/**
- * Validate every word in a parsed signature against a vocabulary.
- * Returns null when valid, else the first unresolvable word.
- */
-export function validateFillSignature(
-  signature: FillSignature,
-  hasWord: (word: string) => boolean,
-): string | null {
-  for (const stop of signature.stops) {
-    if (!hasWord(stop.word)) return stop.word;
-  }
-  return null;
-}
-
-/**
- * The surface roles whose `{word}-foreground` pair is guaranteed by the
- * frozen contract (shadcn drop-in names plus rafters role extensions --
- * doctrine: contract names are frozen interface). Pairing is membership
- * here, never spelling: family words (barbie-pink, blue-300) and unknown
- * words never pair, so no phantom text-*-foreground class ever ships.
- */
-const PAIRED_SURFACE_ROLES = new Set([
-  'background',
-  'card',
-  'panel',
-  'popover',
-  'surface',
-  'primary',
-  'secondary',
-  'muted',
-  'accent',
-  'destructive',
-  'success',
-  'warning',
-  'info',
-  'alert',
-  'highlight',
-  'selection',
-  'sidebar',
-  'nav',
-  'tooltip',
-  'overlay',
-  'table',
-  'table-header',
-  'code',
-  'badge',
-  'avatar',
-  'input',
-]);
-
-/**
- * The paired foreground word for a surface word, or null when pairing
- * does not apply. `background` pairs irregularly with `foreground`.
- * With a vocabulary present (`hasWord`), any word whose `-foreground`
- * pair resolves may pair; without one, only the frozen role set does.
- */
-export function foregroundWordFor(
-  word: string,
-  hasWord?: (word: string) => boolean,
-): string | null {
-  const pair = word === 'background' ? 'foreground' : `${word}-foreground`;
-  if (hasWord) return hasWord(pair) ? pair : null;
-  return PAIRED_SURFACE_ROLES.has(word) ? pair : null;
-}
-
-function stopClass(prefix: string, stop: FillStop): string {
-  return stop.alpha === undefined
-    ? `${prefix}-${stop.word}`
-    : `${prefix}-${stop.word}/${stop.alpha}`;
-}
-
-/**
- * Expand a signature to its class words. Surface context emits the
- * background (and the paired foreground when one exists in the
- * vocabulary); text context emits text color, or gradient text via
- * bg-clip-text. Gradients emit Tailwind v4 utilities (bg-linear-to-b --
- * bg-gradient-to-* is a deprecated v3 alias and is never emitted).
- */
-export function expandFillSignature(
-  signature: FillSignature,
-  context: FillContext,
-  hasWord?: (word: string) => boolean,
-): string {
-  const [first, second] = signature.stops;
-
-  if (!second) {
-    if (context === 'text') return stopClass('text', first);
-    const parts = [stopClass('bg', first)];
-    const fg = foregroundWordFor(first.word, hasWord);
-    if (fg) parts.push(`text-${fg}`);
-    return parts.join(' ');
-  }
-
-  const gradient = ['bg-linear-to-b', stopClass('from', first), stopClass('to', second)];
-  if (context === 'text') {
-    return [...gradient, 'bg-clip-text', 'text-transparent'].join(' ');
-  }
-  const fg = foregroundWordFor(first.word, hasWord);
-  if (fg) gradient.push(`text-${fg}`);
-  return gradient.join(' ');
-}