rafters 0.0.41 → 0.0.42

package/dist/index.js

@@ -45078,6 +45078,228 @@ var DEFAULT_FONT_WEIGHTS = {
   extrabold: { value: 800, meaning: "Extra bold weight", contexts: ["display", "hero"] },
   black: { value: 900, meaning: "Black weight", contexts: ["display", "impact"] }
 };
+var TYPOGRAPHY_ROLE_CONSUMERS = {
+  "display-large": ["hero"],
+  "display-medium": ["h1"],
+  "title-large": ["h2"],
+  "title-medium": [
+    "h3",
+    "card-title",
+    "dialog-title",
+    "sheet-title",
+    "drawer-title",
+    "empty-title",
+    "alert-dialog-title"
+  ],
+  "title-small": ["h4", "alert-title", "accordion-trigger"],
+  "body-large": ["lead"],
+  "body-medium": ["p", "list-item", "blockquote", "accordion-content"],
+  "body-small": [
+    "card-description",
+    "dialog-description",
+    "sheet-description",
+    "alert-description",
+    "field-description",
+    "tooltip",
+    "menu-item",
+    "table-cell",
+    "input",
+    "select",
+    "textarea"
+  ],
+  "label-large": ["button", "tab-trigger", "nav-trigger", "toggle", "pagination-link"],
+  "label-medium": ["label", "breadcrumb", "button-sm", "sidebar-item"],
+  "label-small": ["badge", "sidebar-label", "caption", "command-group-heading"],
+  "code-large": ["code-block"],
+  "code-small": ["code-inline", "kbd"],
+  shortcut: ["keyboard-shortcut"]
+};
+var DEFAULT_TYPOGRAPHY_COMPOSITE_MAPPINGS = {
+  "display-large": {
+    fontFamily: "heading",
+    fontSize: "5xl",
+    fontWeight: "bold",
+    lineHeight: "5xl",
+    letterSpacing: "5xl",
+    responsive: { lg: { fontSize: "6xl" } },
+    meaning: "Largest display text for hero sections and landing pages",
+    contexts: ["hero-heading", "landing-page"],
+    do: ["Use sparingly for maximum visual impact", "Pair with ample whitespace"],
+    never: ["Use more than once per page", "Use in constrained containers like cards"],
+    trustLevel: "high",
+    consequence: "reversible"
+  },
+  "display-medium": {
+    fontFamily: "heading",
+    fontSize: "4xl",
+    fontWeight: "bold",
+    lineHeight: "4xl",
+    letterSpacing: "4xl",
+    responsive: { lg: { fontSize: "5xl" } },
+    meaning: "Primary page heading -- one per page",
+    contexts: ["page-title", "h1"],
+    do: ["Use once per page for the main title", "Place at the top of the content area"],
+    never: ["Use multiple times on a single page", "Use inside cards or dialogs"],
+    trustLevel: "high",
+    consequence: "reversible"
+  },
+  "title-large": {
+    fontFamily: "heading",
+    fontSize: "3xl",
+    fontWeight: "semibold",
+    lineHeight: "3xl",
+    letterSpacing: "3xl",
+    meaning: "Major section heading",
+    contexts: ["section-title", "h2"],
+    do: ["Use to divide major content sections", "Maintain heading hierarchy (h1 > h2 > h3)"],
+    never: ["Skip heading levels (h1 then h3)", "Use for decorative emphasis"],
+    trustLevel: "medium",
+    consequence: "reversible"
+  },
+  "title-medium": {
+    fontFamily: "heading",
+    fontSize: "lg",
+    fontWeight: "semibold",
+    lineHeight: "lg",
+    letterSpacing: "lg",
+    meaning: "Component and subsection title -- shared by card, dialog, sheet, drawer, empty state",
+    contexts: ["h3", "card-title", "dialog-title", "sheet-title", "drawer-title", "empty-title"],
+    do: ["Use for component-level headings", "Use consistently across all overlay and card titles"],
+    never: ["Mix with other title sizes in the same component", "Override without why-gate"],
+    trustLevel: "medium",
+    consequence: "reversible"
+  },
+  "title-small": {
+    fontFamily: "heading",
+    fontSize: "base",
+    fontWeight: "semibold",
+    lineHeight: "base",
+    letterSpacing: "base",
+    meaning: "Minor heading and alert title",
+    contexts: ["h4", "alert-title", "accordion-trigger"],
+    do: ["Use for subsections within a card or panel", "Use for alert and accordion headings"],
+    never: ["Use as the primary heading on a page"],
+    trustLevel: "medium",
+    consequence: "reversible"
+  },
+  "body-large": {
+    fontFamily: "body",
+    fontSize: "xl",
+    fontWeight: "normal",
+    lineHeight: "xl",
+    letterSpacing: "xl",
+    meaning: "Lead paragraph and introductory text",
+    contexts: ["lead", "introduction", "hero-body"],
+    do: ["Use for the first paragraph of a section", "Use for hero body copy"],
+    never: ["Use for all body text", "Use in compact UI like sidebars"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "body-medium": {
+    fontFamily: "body",
+    fontSize: "base",
+    fontWeight: "normal",
+    lineHeight: "base",
+    letterSpacing: "base",
+    meaning: "Default body text for paragraphs and content",
+    contexts: ["paragraph", "body-text", "list-item", "blockquote", "accordion-content"],
+    do: ["Use for all standard body content", "Ensure sufficient contrast against background"],
+    never: ["Use for labels or UI chrome", "Set below 1rem"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "body-small": {
+    fontFamily: "body",
+    fontSize: "sm",
+    fontWeight: "normal",
+    lineHeight: "sm",
+    letterSpacing: "sm",
+    meaning: "Secondary text -- descriptions, tooltips, menu items, table cells",
+    contexts: ["description", "tooltip", "menu-item", "table-cell", "input-text", "helper-text"],
+    do: ["Use for supplementary information", "Use for compact UI elements like menus and tables"],
+    never: ["Use for primary content that users must read", "Set below 0.875rem for body text"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "label-large": {
+    fontFamily: "body",
+    fontSize: "base",
+    fontWeight: "medium",
+    lineHeight: "base",
+    letterSpacing: "base",
+    meaning: "Interactive element text -- buttons, tabs, nav triggers, toggles",
+    contexts: ["button", "tab-trigger", "nav-trigger", "toggle", "pagination"],
+    do: ["Use for primary interactive controls", "Ensure touch target meets 24px minimum"],
+    never: ["Use for passive content", "Mix with body text styling"],
+    trustLevel: "medium",
+    consequence: "reversible"
+  },
+  "label-medium": {
+    fontFamily: "body",
+    fontSize: "sm",
+    fontWeight: "medium",
+    lineHeight: "sm",
+    letterSpacing: "sm",
+    meaning: "Form labels, breadcrumbs, small buttons, sidebar items",
+    contexts: ["label", "breadcrumb", "small-button", "sidebar-item"],
+    do: ["Use for form field labels", "Use for secondary navigation"],
+    never: ["Use for headings", "Use for primary call-to-action buttons"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "label-small": {
+    fontFamily: "body",
+    fontSize: "xs",
+    fontWeight: "medium",
+    lineHeight: "xs",
+    letterSpacing: "xs",
+    meaning: "Smallest label text -- badges, sidebar labels, captions",
+    contexts: ["badge", "sidebar-label", "caption", "command-group-heading"],
+    do: ["Use only for tertiary UI information", "Ensure adequate contrast at small size"],
+    never: ["Use for content users must read to complete a task", "Set below 0.75rem"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "code-large": {
+    fontFamily: "code",
+    fontSize: "base",
+    fontWeight: "normal",
+    lineHeight: "base",
+    letterSpacing: "base",
+    meaning: "Code blocks and pre-formatted text",
+    contexts: ["code-block", "pre", "terminal-output"],
+    do: ["Use for multi-line code content", "Pair with syntax highlighting"],
+    never: ["Use for inline code snippets", "Use for non-code content"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  "code-small": {
+    fontFamily: "code",
+    fontSize: "sm",
+    fontWeight: "normal",
+    lineHeight: "sm",
+    letterSpacing: "sm",
+    meaning: "Inline code and keyboard key indicators",
+    contexts: ["code-inline", "kbd", "technical-term"],
+    do: ["Use for code references within prose", "Use for keyboard shortcut labels"],
+    never: ["Use for multi-line code blocks", "Use for body text"],
+    trustLevel: "low",
+    consequence: "reversible"
+  },
+  shortcut: {
+    fontFamily: "code",
+    fontSize: "xs",
+    fontWeight: "normal",
+    lineHeight: "xs",
+    letterSpacing: "widest",
+    meaning: "Keyboard shortcut indicators in menus",
+    contexts: ["keyboard-shortcut", "command-shortcut", "menu-shortcut"],
+    do: ["Use for keyboard shortcut text in menus and command palettes"],
+    never: ["Use for regular text content", "Use outside of menu/command contexts"],
+    trustLevel: "low",
+    consequence: "reversible"
+  }
+};
 var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // ============================================================================
   // CORE SURFACE TOKENS (shadcn compatible)
@@ -46839,6 +47061,7 @@ function groupTokens(tokens) {
     breakpoint: [],
     elevation: [],
     focus: [],
+    "typography-composite": [],
     other: []
   };
   for (const token of tokens) {
@@ -46876,6 +47099,9 @@ function groupTokens(tokens) {
       case "focus":
         groups.focus.push(token);
         break;
+      case "typography-composite":
+        groups["typography-composite"].push(token);
+        break;
       default:
         groups.other.push(token);
     }
@@ -47157,7 +47383,95 @@ function generateAnimationTokens(motionTokens) {
   }
   return lines.join("\n");
 }
-function tokensToTailwind(tokens, options = {}) {
+function generateTypographyCompositeUtilities(compositeTokens) {
+  if (compositeTokens.length === 0) {
+    return "";
+  }
+  const lines = [];
+  const mappings = compositeTokens.map((t2) => {
+    try {
+      const parsed = JSON.parse(t2.value);
+      return { name: t2.name, ...parsed };
+    } catch {
+      return null;
+    }
+  }).filter((m3) => m3 !== null);
+  for (const mapping of mappings) {
+    lines.push(`@utility text-${mapping.name} {`);
+    lines.push(`  font-family: var(--font-${mapping.fontFamily});`);
+    lines.push(`  font-size: var(--font-size-${mapping.fontSize});`);
+    lines.push(`  font-weight: var(--font-weight-${mapping.fontWeight});`);
+    lines.push(`  line-height: var(--line-height-${mapping.lineHeight});`);
+    const namedTrackingValues = {
+      tighter: "-0.05em",
+      tight: "-0.025em",
+      normal: "0em",
+      wide: "0.025em",
+      wider: "0.05em",
+      widest: "0.1em"
+    };
+    if (mapping.letterSpacing in namedTrackingValues) {
+      lines.push(`  letter-spacing: ${namedTrackingValues[mapping.letterSpacing]};`);
+    } else {
+      lines.push(`  letter-spacing: var(--letter-spacing-${mapping.letterSpacing});`);
+    }
+    if (mapping.responsive) {
+      for (const [breakpoint, overrides] of Object.entries(mapping.responsive)) {
+        if (overrides.fontSize) {
+          const bpWidth = breakpoint === "sm" ? "480px" : breakpoint === "md" ? "640px" : "1024px";
+          lines.push(`  @container (min-width: ${bpWidth}) {`);
+          lines.push(`    font-size: var(--font-size-${overrides.fontSize});`);
+          lines.push(`    line-height: var(--line-height-${overrides.fontSize});`);
+          lines.push("  }");
+        }
+      }
+    }
+    lines.push("}");
+  }
+  return lines.join("\n");
+}
+function overridePropertyToUtility(property, value2) {
+  switch (property) {
+    case "fontFamily":
+      return `font-${value2}`;
+    case "fontWeight":
+      return `font-${value2}`;
+    case "fontSize":
+      return `text-${value2}`;
+    case "lineHeight":
+      return `leading-${value2}`;
+    case "letterSpacing":
+      return `tracking-${value2}`;
+    default:
+      return "";
+  }
+}
+function generateTypographyOverrideCSS(overrides) {
+  if (overrides.length === 0) {
+    return "";
+  }
+  const lines = [];
+  lines.push("/* -- Typography Element Overrides -- */");
+  for (const override of overrides) {
+    const overrideUtilities = [];
+    for (const [prop, val] of Object.entries(override.overrides)) {
+      if (val) {
+        const utility = overridePropertyToUtility(prop, val);
+        if (utility) {
+          overrideUtilities.push(utility);
+        }
+      }
+    }
+    if (overrideUtilities.length > 0) {
+      lines.push(`/* ${override.element}: diverges from ${override.role} (${override.why}) */`);
+      lines.push(`${override.element} {`);
+      lines.push(`  @apply text-${override.role} ${overrideUtilities.join(" ")};`);
+      lines.push("}");
+    }
+  }
+  return lines.join("\n");
+}
+function tokensToTailwind(tokens, options = {}, typographyOverrides = []) {
   const { includeImport = true } = options;
   if (tokens.length === 0) {
     throw new Error("Registry is empty");
@@ -47181,13 +47495,24 @@ function tokensToTailwind(tokens, options = {}) {
   if (keyframes) {
     sections.push(keyframes);
   }
+  const typographyUtilities = generateTypographyCompositeUtilities(groups["typography-composite"]);
+  if (typographyUtilities) {
+    sections.push("");
+    sections.push(typographyUtilities);
+  }
+  const overrideCSS = generateTypographyOverrideCSS(typographyOverrides);
+  if (overrideCSS) {
+    sections.push("");
+    sections.push(overrideCSS);
+  }
   sections.push("");
   sections.push(generateArticleBaseLayer());
   return sections.join("\n");
 }
 function registryToTailwind(registry2, options) {
   const tokens = registry2.list();
-  return tokensToTailwind(tokens, options);
+  const typographyOverrides = registry2.getTypographyOverrides();
+  return tokensToTailwind(tokens, options, typographyOverrides);
 }
 function generateVarsRootBlock(groups) {
   const lines = [];
@@ -47204,7 +47529,7 @@ function generateVarsRootBlock(groups) {
     for (const token of groups.spacing) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
-      lines.push(`  --rafters-spacing-${token.name}: ${value2};`);
+      lines.push(`  --rafters-${token.name}: ${value2};`);
     }
     lines.push("");
   }
@@ -47223,7 +47548,7 @@ function generateVarsRootBlock(groups) {
     for (const token of groups.radius) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
-      lines.push(`  --rafters-radius-${token.name}: ${value2};`);
+      lines.push(`  --rafters-${token.name}: ${value2};`);
     }
     lines.push("");
   }
@@ -48448,6 +48773,26 @@ var TokenSchema = external_exports.object({
   requiresConfirmation: external_exports.boolean().optional()
   // UI pattern requirement for destructive actions
 });
+var TypographyElementOverrideSchema = external_exports.object({
+  /** CSS element selector, e.g. 'h3' */
+  element: external_exports.string().min(1),
+  /** Base role this element uses, e.g. 'title-medium' */
+  role: external_exports.string().min(1),
+  /** Only the properties that differ from the role */
+  overrides: external_exports.object({
+    fontFamily: external_exports.string().optional(),
+    fontWeight: external_exports.string().optional(),
+    fontSize: external_exports.string().optional(),
+    lineHeight: external_exports.string().optional(),
+    letterSpacing: external_exports.string().optional()
+  }),
+  /** Why-gate: reason for the override (required, non-empty) */
+  why: external_exports.string().min(1, "Why-gate required: provide a reason for this override"),
+  /** Who made the override */
+  who: external_exports.string().min(1),
+  /** When the override was made (ISO timestamp) */
+  when: external_exports.string()
+});
 var NamespaceFileSchema = external_exports.object({
   $schema: external_exports.string(),
   namespace: external_exports.string(),
@@ -48456,6 +48801,121 @@ var NamespaceFileSchema = external_exports.object({
   tokens: external_exports.array(TokenSchema)
 });
 
+// ../design-tokens/src/validators/typography-a11y.ts
+var SIZE_ORDER = [
+  "xs",
+  "sm",
+  "base",
+  "lg",
+  "xl",
+  "2xl",
+  "3xl",
+  "4xl",
+  "5xl",
+  "6xl",
+  "7xl",
+  "8xl",
+  "9xl"
+];
+function sizeIndex(size) {
+  return SIZE_ORDER.indexOf(size);
+}
+var WEIGHT_VALUES = {
+  thin: 100,
+  extralight: 200,
+  light: 300,
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+  extrabold: 800,
+  black: 900
+};
+function weightValue(weight) {
+  return WEIGHT_VALUES[weight] ?? 400;
+}
+function validateTypographyComposite(mapping, role) {
+  const violations = [];
+  const sizeIdx = sizeIndex(mapping.fontSize);
+  const weight = weightValue(mapping.fontWeight);
+  const isBody = role.startsWith("body-");
+  const isLabel = role.startsWith("label-");
+  const isHeading = role.startsWith("title-") || role.startsWith("display-");
+  if (isBody && sizeIdx < sizeIndex("sm")) {
+    violations.push({
+      rule: "min-body-font-size",
+      severity: "error",
+      message: `Body role "${role}" uses font-size "${mapping.fontSize}" which is below minimum 'sm' (14px)`,
+      wcagCriterion: "1.4.4 Resize Text",
+      property: "fontSize",
+      currentValue: mapping.fontSize,
+      requiredValue: "sm or larger"
+    });
+  }
+  if (isLabel && sizeIdx < sizeIndex("xs")) {
+    violations.push({
+      rule: "min-label-font-size",
+      severity: "error",
+      message: `Label role "${role}" uses font-size "${mapping.fontSize}" which is below minimum 'xs' (12px)`,
+      wcagCriterion: "1.4.4 Resize Text",
+      property: "fontSize",
+      currentValue: mapping.fontSize,
+      requiredValue: "xs or larger"
+    });
+  }
+  if (isBody) {
+    const lhIdx = sizeIndex(mapping.lineHeight);
+    if (lhIdx >= sizeIndex("xl")) {
+      violations.push({
+        rule: "body-line-height",
+        severity: "warning",
+        message: `Body role "${role}" line-height "${mapping.lineHeight}" may be below 1.5 (WCAG 1.4.12 recommends >= 1.5 for body text)`,
+        wcagCriterion: "1.4.12 Text Spacing",
+        property: "lineHeight",
+        currentValue: mapping.lineHeight,
+        requiredValue: "Scale key with line-height >= 1.5 (xs, sm, base, lg)"
+      });
+    }
+  }
+  if (isHeading) {
+    const lhIdx = sizeIndex(mapping.lineHeight);
+    if (lhIdx >= sizeIndex("7xl")) {
+      violations.push({
+        rule: "heading-line-height",
+        severity: "warning",
+        message: `Heading role "${role}" line-height "${mapping.lineHeight}" may be below 1.2`,
+        wcagCriterion: "1.4.12 Text Spacing",
+        property: "lineHeight",
+        currentValue: mapping.lineHeight,
+        requiredValue: "Scale key with line-height >= 1.2"
+      });
+    }
+  }
+  if (weight <= 300 && sizeIdx <= sizeIndex("sm")) {
+    violations.push({
+      rule: "weight-contrast-coupling",
+      severity: "warning",
+      message: `Role "${role}" uses thin weight (${mapping.fontWeight}) at small size (${mapping.fontSize}). This may have insufficient readability. Consider using weight >= medium for small text.`,
+      wcagCriterion: "1.4.3 Contrast (Minimum)",
+      property: "fontWeight",
+      currentValue: mapping.fontWeight,
+      requiredValue: "medium or heavier for small text"
+    });
+  }
+  return violations;
+}
+function validateTypographyOverride(override, baseMapping) {
+  const merged = {
+    ...baseMapping,
+    fontFamily: override.overrides.fontFamily ? override.overrides.fontFamily : baseMapping.fontFamily,
+    fontSize: override.overrides.fontSize ?? baseMapping.fontSize,
+    fontWeight: override.overrides.fontWeight ?? baseMapping.fontWeight,
+    lineHeight: override.overrides.lineHeight ?? baseMapping.lineHeight,
+    letterSpacing: override.overrides.letterSpacing ?? baseMapping.letterSpacing
+  };
+  return validateTypographyComposite(merged, override.role);
+}
+
 // ../design-tokens/src/registry.ts
 var TokenRegistry = class {
   tokens = /* @__PURE__ */ new Map();
@@ -48465,6 +48925,7 @@ var TokenRegistry = class {
   changeCallback;
   adapter;
   dirtyNamespaces = /* @__PURE__ */ new Set();
+  typographyOverrides = /* @__PURE__ */ new Map();
   constructor(initialTokens) {
     if (initialTokens) {
       for (const token of initialTokens) {
@@ -49000,6 +49461,49 @@ var TokenRegistry = class {
   parseRuleDependencies(rule) {
     return this.dependencyGraph.parseRuleDependencies(rule);
   }
+  // ===========================================================================
+  // Typography Element Overrides
+  // ===========================================================================
+  /**
+   * Add a typography element override with why-gate enforcement.
+   * Stores an override for a specific HTML element that diverges from its
+   * assigned typography role.
+   *
+   * @throws If why field is empty (why-gate enforcement)
+   * @throws If role references a non-existent typography composite token
+   */
+  addTypographyOverride(override) {
+    const parsed = TypographyElementOverrideSchema.parse(override);
+    const roleToken = this.get(parsed.role);
+    if (!roleToken || roleToken.namespace !== "typography-composite") {
+      throw new Error(
+        `Typography override for "${parsed.element}" references unknown role "${parsed.role}". Role must be an existing typography-composite token.`
+      );
+    }
+    const baseMapping = DEFAULT_TYPOGRAPHY_COMPOSITE_MAPPINGS[parsed.role];
+    if (baseMapping) {
+      const violations = validateTypographyOverride(parsed, baseMapping);
+      const errors = violations.filter((v) => v.severity === "error");
+      if (errors.length > 0) {
+        throw new Error(
+          `Typography override for "${parsed.element}" violates accessibility: ${errors.map((e) => e.message).join("; ")}`
+        );
+      }
+    }
+    this.typographyOverrides.set(parsed.element, parsed);
+  }
+  /**
+   * Get all typography element overrides.
+   */
+  getTypographyOverrides() {
+    return Array.from(this.typographyOverrides.values());
+  }
+  /**
+   * Remove a typography element override.
+   */
+  removeTypographyOverride(element) {
+    return this.typographyOverrides.delete(element);
+  }
   /**
    * Enhanced validation that includes both registry and rule validation
    */
@@ -58168,6 +58672,54 @@ function generateTypographyTokens(config3, typographyScale, fontWeights) {
       never: ["Use for body text", "Use for UI elements"]
     }
   });
+  tokens.push({
+    name: "font-heading",
+    value: `var(--font-sans)`,
+    category: "typography",
+    namespace: "typography",
+    semanticMeaning: "Font family for headings and display text",
+    usageContext: ["headings", "display-text", "titles"],
+    dependsOn: ["font-sans"],
+    description: "Heading font family. Defaults to sans-serif. Override to change all headings to serif or another family.",
+    generatedAt: timestamp,
+    containerQueryAware: false,
+    usagePatterns: {
+      do: ["Override to set all headings to a different typeface"],
+      never: ["Reference directly in components -- use typography role utilities instead"]
+    }
+  });
+  tokens.push({
+    name: "font-body",
+    value: `var(--font-sans)`,
+    category: "typography",
+    namespace: "typography",
+    semanticMeaning: "Font family for body text and UI elements",
+    usageContext: ["body-text", "labels", "descriptions", "ui-elements"],
+    dependsOn: ["font-sans"],
+    description: "Body font family. Defaults to sans-serif. Override to change all body and UI text.",
+    generatedAt: timestamp,
+    containerQueryAware: false,
+    usagePatterns: {
+      do: ["Override to set all body text to a different typeface"],
+      never: ["Reference directly in components -- use typography role utilities instead"]
+    }
+  });
+  tokens.push({
+    name: "font-code",
+    value: `var(--font-mono)`,
+    category: "typography",
+    namespace: "typography",
+    semanticMeaning: "Font family for code, keyboard shortcuts, and technical content",
+    usageContext: ["code-blocks", "inline-code", "kbd", "shortcuts"],
+    dependsOn: ["font-mono"],
+    description: "Code font family. Defaults to monospace. Override for a custom code typeface.",
+    generatedAt: timestamp,
+    containerQueryAware: false,
+    usagePatterns: {
+      do: ["Override to set all code content to a custom monospace font"],
+      never: ["Reference directly in components -- use typography role utilities instead"]
+    }
+  });
   const baseFontSizeRem = baseFontSize / 16;
   tokens.push({
     name: "font-size-base",
@@ -58284,6 +58836,72 @@ function generateTypographyTokens(config3, typographyScale, fontWeights) {
   };
 }
 
+// ../design-tokens/src/generators/typography-composite.ts
+function familyRoleToDependency(role) {
+  switch (role) {
+    case "heading":
+      return "font-heading";
+    case "body":
+      return "font-body";
+    case "code":
+      return "font-code";
+  }
+}
+function generateTypographyCompositeTokens(_config) {
+  const tokens = [];
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  for (const [name2, mapping] of Object.entries(DEFAULT_TYPOGRAPHY_COMPOSITE_MAPPINGS)) {
+    const violations = validateTypographyComposite(mapping, name2);
+    const errors = violations.filter((v) => v.severity === "error");
+    if (errors.length > 0) {
+      throw new Error(
+        `Typography role "${name2}" violates accessibility: ${errors.map((e) => e.message).join("; ")}`
+      );
+    }
+    const familyDep = familyRoleToDependency(mapping.fontFamily);
+    const dependsOn = [
+      familyDep,
+      `font-size-${mapping.fontSize}`,
+      `font-weight-${mapping.fontWeight}`,
+      `line-height-${mapping.lineHeight}`,
+      `letter-spacing-${mapping.letterSpacing}`
+    ];
+    const compositeValue = JSON.stringify({
+      fontFamily: mapping.fontFamily,
+      fontSize: mapping.fontSize,
+      fontWeight: mapping.fontWeight,
+      lineHeight: mapping.lineHeight,
+      letterSpacing: mapping.letterSpacing,
+      ...mapping.responsive ? { responsive: mapping.responsive } : {}
+    });
+    const consumers = TYPOGRAPHY_ROLE_CONSUMERS[name2] ?? [];
+    tokens.push({
+      name: name2,
+      value: compositeValue,
+      category: "typography",
+      namespace: "typography-composite",
+      semanticMeaning: mapping.meaning,
+      usageContext: mapping.contexts,
+      trustLevel: mapping.trustLevel,
+      consequence: mapping.consequence,
+      dependsOn,
+      applicableComponents: consumers,
+      containerQueryAware: true,
+      generateUtilityClass: true,
+      description: `Typography composite: font-${mapping.fontFamily} text-${mapping.fontSize} font-${mapping.fontWeight}. ${mapping.meaning}`,
+      generatedAt: timestamp,
+      usagePatterns: {
+        do: mapping.do,
+        never: mapping.never
+      }
+    });
+  }
+  return {
+    namespace: "typography-composite",
+    tokens
+  };
+}
+
 // ../design-tokens/src/generators/index.ts
 function buildAllColorScales(customBases) {
   const bases = customBases ?? DEFAULT_SEMANTIC_COLOR_BASES;
@@ -58313,6 +58931,11 @@ function createGeneratorDefs(colorPaletteBases) {
     },
     // Semantic tokens (depend on color)
     { name: "semantic", generate: (config3) => generateSemanticTokens(config3) },
+    // Typography composites (depend on typography)
+    {
+      name: "typography-composite",
+      generate: (config3) => generateTypographyCompositeTokens(config3)
+    },
     // Derived tokens (depend on spacing/foundation)
     {
       name: "radius",
@@ -58833,13 +59456,13 @@ Container and Grid handle ALL layout. You do not write layout code.
 
 | Instead of | Use |
 |---|---|
-| \`<p className="text-sm text-muted-foreground">\` | \`<Muted>\` |
+| \`<p className="text-sm text-muted-foreground">\` | \`<P size="sm" color="muted">\` |
 | \`<p>\` | \`<P>\` |
 | \`<h1 className="text-4xl font-bold">\` | \`<H1>\` |
 | \`<h2>\` | \`<H2>\` |
 | \`<h3>\` | \`<H3>\` |
 | \`<span className="text-xs">\` | \`<Small>\` |
-| \`<span className="text-lg font-semibold">\` | \`<Large>\` |
+| \`<span className="text-lg font-semibold">\` | \`<P size="lg" weight="semibold">\` |
 
 ## Color -- Tokens, Not Values
 
@@ -58850,7 +59473,7 @@ Never use hex, HSL, or palette internals.
 
 \`\`\`tsx
 import { Container, Grid } from "@rafters/ui"
-import { H1, Lead } from "@rafters/ui/components/ui/typography"
+import { H1, P } from "@rafters/ui/components/ui/typography"
 import { Card } from "@rafters/ui/components/ui/card"
 import { Button } from "@rafters/ui/components/ui/button"
 
@@ -58858,7 +59481,7 @@ export default function Page() {
   return (
     <Container>
       <H1>Title</H1>
-      <Lead>Description.</Lead>
+      <P size="xl" color="muted">Description.</P>
       <Grid preset="cards">
         <Card>...</Card>
         <Card>...</Card>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rafters",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "CLI for Rafters design system - scaffold tokens and add components",
   "license": "MIT",
   "type": "module",