@pharos-ds/core 0.1.9

package/dist/theme/expandRadiusScale.js

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file expandRadiusScale.ts
+ * @input Radius scale configuration { base, multiplier }
+ * @output Token overrides for radius tokens
+ * @position Theme utility; consumed by defineTheme.ts
+ *
+ * Computes border-radius values from a base unit and multiplier.
+ * --radius-none and --radius-full are always fixed (never affected by multiplier).
+ * --radius-inner through --radius-page = base * step * multiplier.
+ *
+ * Semantic scale:
+ *   --radius-none      → 0px (fixed)
+ *   --radius-inner     → base × 1 × multiplier (internal corners)
+ *   --radius-element   → base × 2 × multiplier (buttons, inputs)
+ *   --radius-container → base × 3 × multiplier (cards, panels)
+ *   --radius-page      → base × 7 × multiplier (page-level containers)
+ *   --radius-chat      → base × 7 × multiplier (chat surfaces; tracks page)
+ *   --radius-full      → 9999px (fixed, pill shapes)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/expandRadiusScale.test.ts
+ * - /packages/core/src/theme/defineTheme.ts
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Radius scale configuration.
+ *
+ * @example
+ * ```
+ * // Default Pharos radius scale
+ * { base: 4, multiplier: 1 }
+ *
+ * // Sharp/brutalist — all radii become 0
+ * { base: 4, multiplier: 0 }
+ *
+ * // Extra rounded
+ * { base: 4, multiplier: 1.5 }
+ * ```
+ */
+
+/**
+ * Generated radius token overrides.
+ * Keys are CSS custom property names, values are CSS strings.
+ */
+
+// =============================================================================
+// Computation
+// =============================================================================
+
+/**
+ * Expand a radius scale config into token overrides.
+ *
+ * --radius-none and --radius-full are fixed anchors.
+ * --radius-inner through --radius-page scale with base × step × multiplier.
+ *
+ * @example
+ * ```
+ * const tokens = expandRadiusScale({ base: 4, multiplier: 1 });
+ * // tokens['--radius-none'] === '0px'
+ * // tokens['--radius-inner'] === '4px'       (4 × 1 × 1)
+ * // tokens['--radius-element'] === '8px'     (4 × 2 × 1)
+ * // tokens['--radius-container'] === '12px'  (4 × 3 × 1)
+ * // tokens['--radius-page'] === '28px'       (4 × 7 × 1)
+ * // tokens['--radius-chat'] === '28px'       (4 × 7 × 1)
+ * // tokens['--radius-full'] === '9999px'
+ *
+ * const sharp = expandRadiusScale({ base: 4, multiplier: 0 });
+ * // All scalable tokens become '0px', none and full unchanged
+ * ```
+ */
+export function expandRadiusScale(config) {
+  const {
+    base,
+    multiplier
+  } = config;
+  return {
+    '--radius-none': '0px',
+    '--radius-inner': `${Math.round(base * 1 * multiplier)}px`,
+    '--radius-element': `${Math.round(base * 2 * multiplier)}px`,
+    '--radius-container': `${Math.round(base * 3 * multiplier)}px`,
+    '--radius-page': `${Math.round(base * 7 * multiplier)}px`,
+    // Chat surfaces track the page step (× 7) so they scale with the theme
+    // multiplier, but remain a distinct token for independent theming. #2072
+    '--radius-chat': `${Math.round(base * 7 * multiplier)}px`,
+    '--radius-full': '9999px'
+  };
+}

package/dist/theme/expandTypeScale.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @file expandTypeScale.ts
+ * @input Type scale configuration { base, ratio, weights? }
+ * @output Token overrides for raw size tokens and semantic typography tokens
+ * @position Theme utility; consumed by defineTheme.ts
+ *
+ * Computes a complete typography token set from a base size and scaling ratio
+ * using a geometric progression: size = base × ratio^step.
+ *
+ * Two-layer architecture:
+ *   Layer 1: Raw size tokens (--font-size-4xs … --font-size-4xl)
+ *            Geometric progression in rem.
+ *   Layer 2: Semantic tokens (--heading-*, --text-*-size/leading/weight)
+ *            Sizes are var() references to Layer 1.
+ *            Line heights are hardcoded computed values (4px grid snapped).
+ *            Weights are var() references to font-weight tokens.
+ *
+ * The named leading tokens (--leading-tight … --leading-relaxed) are NOT
+ * modified by the type scale — they remain as intent-based ratios for
+ * component use.
+ *
+ * Step mapping:
+ *   step -5 → --font-size-4xs   (sub-scale)
+ *   step -4 → --font-size-3xs   (sub-scale)
+ *   step -3 → --font-size-2xs   (sub-scale)
+ *   step -2 → --font-size-xs   (h6)
+ *   step -1 → --font-size-sm    (h5, supporting)
+ *   step  0 → --font-size-base  (h4, body, label, code)
+ *   step +1 → --font-size-lg    (h3, large)
+ *   step +2 → --font-size-xl    (h2)
+ *   step +3 → --font-size-2xl   (h1)
+ *   step +4 → --font-size-3xl
+ *   step +5 → --font-size-4xl
+ *
+ * Line heights use a tiered target ratio based on font size:
+ *   < 20px  → 1.5   (body text, small UI)
+ *   20–31px → 1.4   (medium headings)
+ *   ≥ 32px  → 1.25  (large display headings)
+ *
+ * Then 4px-grid-snapped with Math.round and a minimum of fontSize + 4.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/expandTypeScale.test.ts
+ * - /packages/core/src/theme/defineTheme.ts
+ */
+/** Font weight value — either a CSS string or a var() reference. */
+export type FontWeightValue = string;
+/**
+ * Weight overrides for heading levels.
+ * Keys are heading levels 1–6, values are CSS font-weight values
+ * (e.g. '600', 'var(--font-weight-bold)').
+ */
+export type HeadingWeightOverrides = Partial<Record<1 | 2 | 3 | 4 | 5 | 6, FontWeightValue>>;
+/**
+ * Weight overrides for text types.
+ * Keys are built-in text type names, values are CSS font-weight values.
+ * Accepts additional string keys for custom theme-defined text types.
+ */
+export type TextWeightOverrides = Partial<Record<'body' | 'large' | 'label' | 'code' | 'supporting' | 'display-1' | 'display-2' | 'display-3' | (string & {}), FontWeightValue>>;
+/**
+ * Type scale configuration.
+ *
+ * @example
+ * ```
+ * // Default Pharos type scale
+ * { base: 14, ratio: 1.2 }
+ *
+ * // With custom weights
+ * {
+ *   base: 14,
+ *   ratio: 1.2,
+ *   weights: {
+ *     heading: { 1: 'var(--font-weight-bold)', 3: 'var(--font-weight-bold)' },
+ *     text: { large: 'var(--font-weight-normal)' },
+ *   },
+ * }
+ *
+ * // Suggested starting points:
+ * //   Dense/functional: { base: 12, ratio: 1.125 }
+ * //   Default:          { base: 14, ratio: 1.2 }
+ * //   Airy/editorial:   { base: 16, ratio: 1.25 }
+ * ```
+ */
+export interface TypeScaleConfig {
+    /** Base font size in px. Anchored to h4 and body text. */
+    base: number;
+    /** Scaling ratio for the geometric progression. */
+    ratio: number;
+    /** Optional weight overrides for headings and text types. */
+    weights?: {
+        /** Per-level heading weight overrides. Unset levels use the defaults. */
+        heading?: HeadingWeightOverrides;
+        /** Per-type text weight overrides. Unset types use the defaults. */
+        text?: TextWeightOverrides;
+    };
+}
+/**
+ * Generated typography token overrides.
+ * Keys are CSS custom property names, values are CSS strings.
+ */
+export type TypeScaleTokens = Record<string, string>;
+/**
+ * Expand a type scale configuration into typography token overrides.
+ *
+ * Generates two layers of tokens:
+ *   - Layer 1: 11 raw size tokens (--font-size-4xs … --font-size-4xl) in rem
+ *   - Layer 2: semantic tokens using var() refs for sizes and
+ *              hardcoded computed values for line heights
+ *
+ * Includes 6 heading levels × 3 + 8 text types × 3 (body, large, label, code, supporting, display-1/2/3).
+ * Font sizes are emitted as rem values (e.g. '1.5rem') based on 16px root.
+ * Line heights are emitted as unitless ratios (e.g. '1.3333').
+ * Font weights are emitted as var() references (e.g. '''var(--font-weight-semibold)'''').
+ *
+ * @example
+ * ```
+ * const tokens = expandTypeScale({ base: 14, ratio: 1.2 });
+ * // Layer 1 — raw sizes
+ * // tokens['--font-size-base'] === '0.875rem'
+ * // tokens['--font-size-2xl'] === '1.5rem'
+ * //
+ * // Layer 2 — semantic
+ * // tokens['--text-heading-1-size'] === 'var(--font-size-2xl)'
+ * // tokens['--text-heading-1-leading'] === '1.3333'
+ * // tokens['--text-body-size'] === 'var(--font-size-base)'
+ * // tokens['--text-body-leading'] === '1.4286'
+ * ```
+ */
+export declare function expandTypeScale(config: TypeScaleConfig): TypeScaleTokens;
+/**
+ * Generate component style overrides for heading and text components.
+ */
+export declare function generateTypeScaleComponents(_config: TypeScaleConfig): Record<string, Record<string, Record<string, string>>>;
+//# sourceMappingURL=expandTypeScale.d.ts.map

package/dist/theme/expandTypeScale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expandTypeScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandTypeScale.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAMH,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC1C,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,CAC/C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,MAAM,CACF,MAAM,GACN,OAAO,GACP,OAAO,GACP,MAAM,GACN,YAAY,GACZ,WAAW,GACX,WAAW,GACX,WAAW,GACX,CAAC,MAAM,GAAG,EAAE,CAAC,EACf,eAAe,CAChB,CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,OAAO,CAAC,EAAE;QACR,yEAAyE;QACzE,OAAO,CAAC,EAAE,sBAAsB,CAAC;QACjC,oEAAoE;QACpE,IAAI,CAAC,EAAE,mBAAmB,CAAC;KAC5B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAwIrD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA+CxE;AAiBD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAkCxD"}

package/dist/theme/expandTypeScale.js

@@ -0,0 +1,346 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file expandTypeScale.ts
+ * @input Type scale configuration { base, ratio, weights? }
+ * @output Token overrides for raw size tokens and semantic typography tokens
+ * @position Theme utility; consumed by defineTheme.ts
+ *
+ * Computes a complete typography token set from a base size and scaling ratio
+ * using a geometric progression: size = base × ratio^step.
+ *
+ * Two-layer architecture:
+ *   Layer 1: Raw size tokens (--font-size-4xs … --font-size-4xl)
+ *            Geometric progression in rem.
+ *   Layer 2: Semantic tokens (--heading-*, --text-*-size/leading/weight)
+ *            Sizes are var() references to Layer 1.
+ *            Line heights are hardcoded computed values (4px grid snapped).
+ *            Weights are var() references to font-weight tokens.
+ *
+ * The named leading tokens (--leading-tight … --leading-relaxed) are NOT
+ * modified by the type scale — they remain as intent-based ratios for
+ * component use.
+ *
+ * Step mapping:
+ *   step -5 → --font-size-4xs   (sub-scale)
+ *   step -4 → --font-size-3xs   (sub-scale)
+ *   step -3 → --font-size-2xs   (sub-scale)
+ *   step -2 → --font-size-xs   (h6)
+ *   step -1 → --font-size-sm    (h5, supporting)
+ *   step  0 → --font-size-base  (h4, body, label, code)
+ *   step +1 → --font-size-lg    (h3, large)
+ *   step +2 → --font-size-xl    (h2)
+ *   step +3 → --font-size-2xl   (h1)
+ *   step +4 → --font-size-3xl
+ *   step +5 → --font-size-4xl
+ *
+ * Line heights use a tiered target ratio based on font size:
+ *   < 20px  → 1.5   (body text, small UI)
+ *   20–31px → 1.4   (medium headings)
+ *   ≥ 32px  → 1.25  (large display headings)
+ *
+ * Then 4px-grid-snapped with Math.round and a minimum of fontSize + 4.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/expandTypeScale.test.ts
+ * - /packages/core/src/theme/defineTheme.ts
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Font weight value — either a CSS string or a var() reference. */
+
+/**
+ * Weight overrides for heading levels.
+ * Keys are heading levels 1–6, values are CSS font-weight values
+ * (e.g. '600', 'var(--font-weight-bold)').
+ */
+
+/**
+ * Weight overrides for text types.
+ * Keys are built-in text type names, values are CSS font-weight values.
+ * Accepts additional string keys for custom theme-defined text types.
+ */
+
+/**
+ * Type scale configuration.
+ *
+ * @example
+ * ```
+ * // Default Pharos type scale
+ * { base: 14, ratio: 1.2 }
+ *
+ * // With custom weights
+ * {
+ *   base: 14,
+ *   ratio: 1.2,
+ *   weights: {
+ *     heading: { 1: 'var(--font-weight-bold)', 3: 'var(--font-weight-bold)' },
+ *     text: { large: 'var(--font-weight-normal)' },
+ *   },
+ * }
+ *
+ * // Suggested starting points:
+ * //   Dense/functional: { base: 12, ratio: 1.125 }
+ * //   Default:          { base: 14, ratio: 1.2 }
+ * //   Airy/editorial:   { base: 16, ratio: 1.25 }
+ * ```
+ */
+
+/**
+ * Generated typography token overrides.
+ * Keys are CSS custom property names, values are CSS strings.
+ */
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Step → raw size token name.
+ * These tokens form the geometric font size scale.
+ *
+ * The full scale spans steps -5 to +5:
+ *   -5 → --font-size-4xs (sub-scale)
+ *   -4 → --font-size-3xs (sub-scale)
+ *   -3 → --font-size-2xs (sub-scale)
+ *   -2 → --font-size-xs
+ *   -1 → --font-size-sm
+ *    0 → --font-size-base (anchor)
+ *   +1 → --font-size-lg
+ *   +2 → --font-size-xl
+ *   +3 → --font-size-2xl
+ *   +4 → --font-size-3xl
+ *   +5 → --font-size-4xl
+ */
+const STEP_TO_SIZE_TOKEN = {
+  [-5]: '--font-size-4xs',
+  [-4]: '--font-size-3xs',
+  [-3]: '--font-size-2xs',
+  [-2]: '--font-size-xs',
+  [-1]: '--font-size-sm',
+  [0]: '--font-size-base',
+  [1]: '--font-size-lg',
+  [2]: '--font-size-xl',
+  [3]: '--font-size-2xl',
+  [4]: '--font-size-3xl',
+  [5]: '--font-size-4xl',
+  [6]: '--font-size-5xl'
+};
+
+/**
+ * Heading level → step offset from base (h4 = 0).
+ * h1 is 3 steps above base, h6 is 2 steps below.
+ */
+const HEADING_STEPS = {
+  1: 3,
+  2: 2,
+  3: 1,
+  4: 0,
+  5: -1,
+  6: -2
+};
+
+/**
+ * Text type → step offset from base.
+ * body/label/code are at base, large is one step up, supporting one step down.
+ */
+const TEXT_STEPS = {
+  body: 0,
+  large: 1,
+  label: 0,
+  code: 0,
+  supporting: -1,
+  'display-1': 6,
+  // largest — continues progression above h1
+  'display-2': 5,
+  'display-3': 4 // closest to h1
+};
+
+/**
+ * Default font weights per heading level.
+ */
+const DEFAULT_HEADING_WEIGHTS = {
+  1: 'var(--font-weight-semibold)',
+  2: 'var(--font-weight-semibold)',
+  3: 'var(--font-weight-semibold)',
+  4: 'var(--font-weight-semibold)',
+  5: 'var(--font-weight-semibold)',
+  6: 'var(--font-weight-semibold)'
+};
+
+/**
+ * Default font weights per text type.
+ */
+const DEFAULT_TEXT_WEIGHTS = {
+  body: 'var(--font-weight-normal)',
+  large: 'var(--font-weight-semibold)',
+  label: 'var(--font-weight-medium)',
+  code: 'var(--font-weight-normal)',
+  supporting: 'var(--font-weight-normal)',
+  'display-1': 'var(--font-weight-normal)',
+  'display-2': 'var(--font-weight-normal)',
+  'display-3': 'var(--font-weight-normal)'
+};
+
+// =============================================================================
+// Computation
+// =============================================================================
+
+/**
+ * Compute a font size from the geometric progression and round to nearest integer.
+ */
+function computeSize(base, ratio, step) {
+  return Math.round(base * Math.pow(ratio, step));
+}
+
+/** Convert px to rem based on the standard 16px root font size. */
+function pxToRem(px) {
+  const rem = Math.round(px / 16 * 10000) / 10000;
+  return `${rem}rem`;
+}
+
+/**
+ * Tiered target line-height ratio based on font size.
+ *
+ *   < 20px  → 1.5   (body text, small UI elements)
+ *   20–31px → 1.4   (medium headings, transitional)
+ *   ≥ 32px  → 1.25  (large display headings)
+ */
+function targetLeadingRatio(fontSize) {
+  return fontSize < 20 ? 1.5 : fontSize < 32 ? 1.4 : 1.25;
+}
+
+/**
+ * Compute a unitless line-height ratio, snapped so the computed px value
+ * aligns to a 4px grid. Ensures a minimum gap of fontSize + 4px.
+ *
+ * Uses a tiered target ratio — see `targetLeadingRatio`.
+ */
+function computeLeading(fontSize) {
+  const target = targetLeadingRatio(fontSize);
+  const rawLh = fontSize * target;
+  const snappedLh = Math.max(Math.round(rawLh / 4) * 4, Math.ceil((fontSize + 4) / 4) * 4);
+  return Math.round(snappedLh / fontSize * 10000) / 10000;
+}
+
+/**
+ * Expand a type scale configuration into typography token overrides.
+ *
+ * Generates two layers of tokens:
+ *   - Layer 1: 11 raw size tokens (--font-size-4xs … --font-size-4xl) in rem
+ *   - Layer 2: semantic tokens using var() refs for sizes and
+ *              hardcoded computed values for line heights
+ *
+ * Includes 6 heading levels × 3 + 8 text types × 3 (body, large, label, code, supporting, display-1/2/3).
+ * Font sizes are emitted as rem values (e.g. '1.5rem') based on 16px root.
+ * Line heights are emitted as unitless ratios (e.g. '1.3333').
+ * Font weights are emitted as var() references (e.g. '''var(--font-weight-semibold)'''').
+ *
+ * @example
+ * ```
+ * const tokens = expandTypeScale({ base: 14, ratio: 1.2 });
+ * // Layer 1 — raw sizes
+ * // tokens['--font-size-base'] === '0.875rem'
+ * // tokens['--font-size-2xl'] === '1.5rem'
+ * //
+ * // Layer 2 — semantic
+ * // tokens['--text-heading-1-size'] === 'var(--font-size-2xl)'
+ * // tokens['--text-heading-1-leading'] === '1.3333'
+ * // tokens['--text-body-size'] === 'var(--font-size-base)'
+ * // tokens['--text-body-leading'] === '1.4286'
+ * ```
+ */
+export function expandTypeScale(config) {
+  const {
+    base,
+    ratio,
+    weights
+  } = config;
+  const tokens = {};
+
+  // Merge weight overrides with defaults
+  const headingWeights = {
+    ...DEFAULT_HEADING_WEIGHTS,
+    ...weights?.heading
+  };
+  const textWeights = {
+    ...DEFAULT_TEXT_WEIGHTS,
+    ...weights?.text
+  };
+
+  // ── Layer 1: Raw size tokens (rem) ────────────────────────────────────────
+  for (let step = -5; step <= 6; step++) {
+    const size = computeSize(base, ratio, step);
+    tokens[STEP_TO_SIZE_TOKEN[step]] = pxToRem(size);
+  }
+
+  // ── Layer 2: Semantic tokens ──────────────────────────────────────────────
+  // Sizes → var() refs to Layer 1
+  // Line heights → hardcoded computed values (4px grid snapped)
+  // Weights → var() refs (unchanged)
+
+  // Heading tokens
+  for (const [levelStr, step] of Object.entries(HEADING_STEPS)) {
+    const level = Number(levelStr);
+    const size = computeSize(base, ratio, step);
+    const leading = computeLeading(size);
+    tokens[`--text-heading-${level}-size`] = `var(${STEP_TO_SIZE_TOKEN[step]})`;
+    tokens[`--text-heading-${level}-weight`] = headingWeights[level];
+    tokens[`--text-heading-${level}-leading`] = `${leading}`;
+  }
+
+  // Text tokens
+  for (const [type, step] of Object.entries(TEXT_STEPS)) {
+    const size = computeSize(base, ratio, step);
+    const leading = computeLeading(size);
+    tokens[`--text-${type}-size`] = `var(${STEP_TO_SIZE_TOKEN[step]})`;
+    tokens[`--text-${type}-weight`] = textWeights[type];
+    tokens[`--text-${type}-leading`] = `${leading}`;
+  }
+  return tokens;
+}
+
+// =============================================================================
+// Component override generation
+// =============================================================================
+
+const TEXT_FONT_FAMILIES = {
+  body: 'var(--font-family-body)',
+  large: 'var(--font-family-body)',
+  label: 'var(--font-family-body)',
+  code: 'var(--font-family-code)',
+  supporting: 'var(--font-family-body)',
+  'display-1': 'var(--font-family-heading)',
+  'display-2': 'var(--font-family-heading)',
+  'display-3': 'var(--font-family-heading)'
+};
+
+/**
+ * Generate component style overrides for heading and text components.
+ */
+export function generateTypeScaleComponents(_config) {
+  const components = {};
+  const headingRules = {};
+  for (const level of [1, 2, 3, 4, 5, 6]) {
+    headingRules[`level:${level}`] = {
+      fontFamily: 'var(--font-family-heading)',
+      fontSize: `var(--text-heading-${level}-size)`,
+      fontWeight: `var(--text-heading-${level}-weight)`,
+      lineHeight: `var(--text-heading-${level}-leading)`
+    };
+  }
+  components.heading = headingRules;
+  const textRules = {};
+  for (const type of ['body', 'large', 'label', 'code', 'supporting', 'display-1', 'display-2', 'display-3']) {
+    textRules[`type:${type}`] = {
+      fontFamily: TEXT_FONT_FAMILIES[type],
+      fontSize: `var(--text-${type}-size)`,
+      lineHeight: `var(--text-${type}-leading)`
+    };
+  }
+  components.text = textRules;
+  return components;
+}

package/dist/theme/generateThemeRules.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file Theme CSS generation utilities
+ *
+ * Shared logic for generating CSS rules from a resolved theme definition.
+ * Used by both the runtime path (Theme injects <style>) and the build
+ * path (`pharos theme build` pre-compiles to CSS files).
+ *
+ * Extracted from defineTheme.ts to reduce cyclomatic complexity and provide
+ * a clear single-responsibility module for CSS generation.
+ *
+ * @input DefinedTheme (resolved theme object from defineTheme)
+ * @output CSS rule strings, split by layer (component vs prose)
+ * @position packages/core/src/theme/generateThemeRules.ts
+ */
+import type { DefinedTheme } from './defineTheme';
+/**
+ * Structured output from generateThemeRulesSplit.
+ * Separates prose element defaults from component/token overrides
+ * so callers can place them in different CSS layers.
+ */
+export interface ThemeRulesSplit {
+    /** Token overrides + component .pharos-* overrides + prop-level color rules */
+    component: string[];
+    /** Prose element defaults (h1-h6, p, small, code, hr) — belongs in reset layer */
+    prose: string[];
+}
+/**
+ * Output from generateThemeCSS — two CSS blocks for different layers.
+ */
+export interface ThemeCSSOutput {
+    /**
+     * Prose element defaults (p, h1-h6, small, code, hr) scoped to the theme.
+     * Should be injected into @layer reset — lowest priority, any class wins.
+     * Empty string if no prose rules.
+     */
+    prose: string;
+    /**
+     * Token overrides + component .pharos-* overrides scoped to the theme.
+     * Should be injected into @layer pharos-theme — above StyleX layers so
+     * theme component overrides take effect. Empty string if no rules.
+     */
+    component: string;
+}
+/**
+ * Generate the intermediary CSS rules for a theme.
+ *
+ * Returns an array of CSS rule strings — the shared format used by both
+ * the runtime path (useInsertionEffect) and the build path (pharos theme build).
+ */
+export declare function generateThemeRules(theme: DefinedTheme): string[];
+/**
+ * Generate theme rules split into component and prose groups.
+ *
+ * Prose element rules (h1-h6, p, small, code, hr) style bare HTML elements
+ * as themed defaults — conceptually the same tier as the CSS reset. They
+ * belong in the reset layer so any class-based style wins.
+ *
+ * Component rules (tokens, .pharos-* overrides) are intentional theme overrides
+ * that need to beat StyleX — they stay in pharos-theme (above StyleX layers).
+ */
+export declare function generateThemeRulesSplit(theme: DefinedTheme): ThemeRulesSplit;
+/**
+ * Generate CSS for on-media token and component overrides.
+ *
+ * Emitted in an unbounded @scope (no `to` limit) so the rules can reach
+ * [data-pharos-media] elements. Parent theme component overrides flow through
+ * to media contexts — only tokens change. Themes can further customize
+ * via onDark.components / onLight.components.
+ */
+export declare function generateOnMediaCSS(theme: DefinedTheme): string;
+/**
+ * Generate layered CSS for a theme — runtime path.
+ *
+ * Returns two CSS blocks for injection into different layers:
+ * - `prose`: @scope'd element defaults → inject into @layer reset
+ * - `component`: @scope'd token + .pharos-* overrides → inject into @layer pharos-theme
+ *
+ * This separation ensures prose defaults (what bare HTML looks like in a theme)
+ * sit at reset-layer priority where any class-based style wins, while component
+ * overrides sit above StyleX so themes can restyle components intentionally.
+ */
+export declare function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput;
+/**
+ * Generate the full CSS string for a theme as a single string.
+ * @deprecated Use generateThemeCSS() which returns { prose, component } for proper layering.
+ * This flat version is kept for backwards compatibility with tests and simple cases.
+ */
+export declare function generateThemeCSSFlat(theme: DefinedTheme): string;
+//# sourceMappingURL=generateThemeRules.d.ts.map

package/dist/theme/generateThemeRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AA+DhD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAgKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAoChE;AAwPD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4E9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA2BpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQhE"}