@adea-ai/ui 0.105.0 → 0.106.0

package/src/lib/appearance-font-settings.ts

@@ -0,0 +1,233 @@
+import { fontOptions, type FontOption } from '#lib/font-catalog'
+import { safeScriptStringLiteral } from '#lib/safe-script'
+
+export const APPEARANCE_EDITOR_FONT_AXES = ['ui', 'content', 'code'] as const
+
+export type AppearanceEditorFontAxis = (typeof APPEARANCE_EDITOR_FONT_AXES)[number]
+export type AppearanceEditorFontFamilyId = FontOption['id']
+
+export type AppearanceEditorFontSetting = Readonly<{
+  /** A stable id from the shared font catalogue, never a CSS family string. */
+  family: AppearanceEditorFontFamilyId
+  /** A pixel size, normalized to the supported range. */
+  size: number
+}>
+
+/** The host-owned choices edited by the shared appearance composition. */
+export type AppearanceEditorFontSettings = Readonly<
+  Record<AppearanceEditorFontAxis, AppearanceEditorFontSetting>
+>
+
+export const APPEARANCE_EDITOR_FONT_SIZE_MIN = 10
+export const APPEARANCE_EDITOR_FONT_SIZE_MAX = 32
+
+/** New preferences use the platform face in each text role. */
+export const DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS: AppearanceEditorFontSettings = Object.freeze({
+  ui: Object.freeze({ family: 'system', size: 14 }),
+  content: Object.freeze({ family: 'system', size: 14 }),
+  code: Object.freeze({ family: 'system', size: 12 }),
+})
+
+export type NormalizedAppearanceEditorFontSettings = Readonly<{
+  settings: AppearanceEditorFontSettings
+  /** Axes whose persisted family or size was unavailable or outside its limits. */
+  recoveredAxes: readonly AppearanceEditorFontAxis[]
+}>
+
+const fontFamilyIds: ReadonlySet<string> = new Set(fontOptions.map((option) => option.id))
+const fontOptionsById = Object.freeze(
+  Object.fromEntries(fontOptions.map((option) => [option.id, option])) as Record<
+    AppearanceEditorFontFamilyId,
+    FontOption
+  >
+)
+const fontProjectionById = Object.freeze(
+  Object.fromEntries(
+    fontOptions.map((option) => [
+      option.id,
+      {
+        familyVariables: option.familyVariables,
+        uiTracking: option.uiTracking,
+        uiWordSpacing: option.uiWordSpacing,
+      },
+    ])
+  ) as Record<
+    AppearanceEditorFontFamilyId,
+    Pick<FontOption, 'familyVariables' | 'uiTracking' | 'uiWordSpacing'>
+  >
+)
+const fontAxisProjection = Object.freeze({
+  ui: Object.freeze({
+    familyAttribute: 'data-ui-font',
+    familyProperty: '--font-ui',
+    sizeProperty: '--font-ui-size',
+    scaleProperty: '--font-ui-scale',
+    defaultSize: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS.ui.size,
+  }),
+  content: Object.freeze({
+    familyAttribute: 'data-content-font',
+    familyProperty: '--font-content',
+    sizeProperty: '--font-content-size',
+    scaleProperty: '--font-content-scale',
+    defaultSize: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS.content.size,
+  }),
+  code: Object.freeze({
+    familyAttribute: 'data-code-font',
+    familyProperty: '--font-code',
+    sizeProperty: '--font-code-size',
+    scaleProperty: '--font-code-scale',
+    defaultSize: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS.code.size,
+  }),
+})
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function normalizeFamily(value: unknown): AppearanceEditorFontFamilyId | undefined {
+  return typeof value === 'string' && fontFamilyIds.has(value)
+    ? (value as AppearanceEditorFontFamilyId)
+    : undefined
+}
+
+function clampFontSize(value: number): number {
+  return Math.min(
+    APPEARANCE_EDITOR_FONT_SIZE_MAX,
+    Math.max(APPEARANCE_EDITOR_FONT_SIZE_MIN, Math.round(value))
+  )
+}
+
+/** Normalize a single number-input value; invalid edits return the current size. */
+export function normalizeAppearanceEditorFontSize(value: unknown, fallback: number): number {
+  const parsed =
+    typeof value === 'number'
+      ? value
+      : typeof value === 'string' && value.trim() !== ''
+        ? Number(value)
+        : Number.NaN
+  return Number.isFinite(parsed) ? clampFontSize(parsed) : clampFontSize(fallback)
+}
+
+/**
+ * Recover persisted font choices against the shared font catalogue.
+ *
+ * `legacyUiFamily` lets a host migrate its previous single font field into the
+ * UI axis. Content and code remain on the new System defaults during that
+ * migration. Missing settings are ordinary defaults; an unknown saved id or an
+ * invalid size is reported through `recoveredAxes` for the host's notice.
+ */
+export function normalizeAppearanceEditorFontSettings(
+  value: unknown,
+  legacyUiFamily?: unknown
+): NormalizedAppearanceEditorFontSettings {
+  const source = isRecord(value) ? value : undefined
+  const malformedRoot = value !== undefined && value !== null && source === undefined
+  const recovered = new Set<AppearanceEditorFontAxis>()
+  const settings = {} as Record<AppearanceEditorFontAxis, AppearanceEditorFontSetting>
+
+  for (const axis of APPEARANCE_EDITOR_FONT_AXES) {
+    const axisPresent = source ? hasOwn(source, axis) : false
+    const axisValue = source?.[axis]
+    const axisSource = isRecord(axisValue) ? axisValue : undefined
+    const fallback = DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS[axis]
+
+    if (malformedRoot || (axisPresent && axisSource === undefined)) recovered.add(axis)
+
+    const hasFamily = axisSource ? hasOwn(axisSource, 'family') : false
+    const familyInput = hasFamily
+      ? axisSource?.['family']
+      : axis === 'ui' && legacyUiFamily !== undefined
+        ? legacyUiFamily
+        : undefined
+    const family = normalizeFamily(familyInput) ?? fallback.family
+    if (
+      (hasFamily || (axis === 'ui' && legacyUiFamily !== undefined)) &&
+      !normalizeFamily(familyInput)
+    ) {
+      recovered.add(axis)
+    }
+
+    const hasSize = axisSource ? hasOwn(axisSource, 'size') : false
+    const sizeInput = axisSource?.['size']
+    const size = hasSize
+      ? normalizeAppearanceEditorFontSize(sizeInput, fallback.size)
+      : fallback.size
+    if (
+      hasSize &&
+      (typeof sizeInput !== 'number' || !Number.isFinite(sizeInput) || sizeInput !== size)
+    ) {
+      recovered.add(axis)
+    }
+
+    settings[axis] = Object.freeze({ family, size })
+  }
+
+  return Object.freeze({
+    settings: Object.freeze(settings),
+    recoveredAxes: Object.freeze(APPEARANCE_EDITOR_FONT_AXES.filter((axis) => recovered.has(axis))),
+  })
+}
+
+/**
+ * Project normalized font preferences onto a document root.
+ *
+ * This is shared by `ThemeProvider` and hosts that own their own appearance
+ * persistence, so UI/content/code use the same catalogue ids, theme tokens,
+ * sizes, and projected CSS variables. The marker activates the optional role
+ * stylesheet and survives CSS import reordering.
+ */
+export function applyAppearanceFontSettings(
+  root: HTMLElement,
+  value: unknown
+): NormalizedAppearanceEditorFontSettings {
+  const normalized = normalizeAppearanceEditorFontSettings(value)
+  const { settings } = normalized
+
+  root.removeAttribute('data-font')
+  root.setAttribute('data-font-settings', '')
+  for (const axis of APPEARANCE_EDITOR_FONT_AXES) {
+    const projection = fontAxisProjection[axis]
+    const setting = settings[axis]
+    const option = fontOptionsById[setting.family]
+    if (setting.family === 'system') root.removeAttribute(projection.familyAttribute)
+    else root.setAttribute(projection.familyAttribute, setting.family)
+    root.style.setProperty(projection.familyProperty, `var(${option.familyVariables[axis]})`)
+    root.style.setProperty(projection.sizeProperty, String(setting.size) + 'px')
+    root.style.setProperty(projection.scaleProperty, String(setting.size / projection.defaultSize))
+    if (axis === 'ui') {
+      root.style.setProperty('--ui-tracking', option.uiTracking)
+      root.style.setProperty('--ui-word-spacing', option.uiWordSpacing)
+    }
+  }
+
+  return normalized
+}
+
+/**
+ * Generate a safe inline prepaint script for a host-owned appearance record.
+ *
+ * The stored object is read from `localStorage[storageKey].fonts`. A legacy
+ * top-level `font` family migrates into UI only; content/code use the shared
+ * defaults. The script applies the same catalogue whitelist, limits, attributes,
+ * and CSS properties as `applyAppearanceFontSettings` before styles paint. When
+ * `persistedVersion` is supplied, only a record with that exact top-level version
+ * is used; absent or mismatched records receive the System defaults.
+ */
+export function fontSettingsBootstrapScript(storageKey: string, persistedVersion?: number): string {
+  if (persistedVersion !== undefined && !Number.isSafeInteger(persistedVersion)) {
+    throw new RangeError('persistedVersion must be a safe integer')
+  }
+  const axisConfig = JSON.stringify(fontAxisProjection)
+  const fontProjection = JSON.stringify(fontProjectionById)
+  const fontIds = `[${fontOptions.map((option) => safeScriptStringLiteral(option.id)).join(',')}]`
+  const persistedVersionGuard =
+    persistedVersion === undefined
+      ? ''
+      : `&&parsed.version===Number(${safeScriptStringLiteral(String(persistedVersion))})`
+
+  return `(function(){var r=document.documentElement;var axes=JSON.parse(${safeScriptStringLiteral(axisConfig)});var projection=JSON.parse(${safeScriptStringLiteral(fontProjection)});var ids=${fontIds};var has=function(v,k){return Object.prototype.hasOwnProperty.call(v,k)};var record=function(v){return typeof v==='object'&&v!==null&&!Array.isArray(v)};var p={};try{var raw=localStorage.getItem(${safeScriptStringLiteral(storageKey)});var parsed=raw?JSON.parse(raw):{};if(record(parsed)${persistedVersionGuard})p=parsed;}catch(e){}var saved=record(p.fonts)?p.fonts:{};var valid=function(v,d){return ids.indexOf(v)!==-1?v:d};var size=function(v,d){var n=typeof v==='number'?v:typeof v==='string'&&v.trim()!==''?Number(v):NaN;return Number.isFinite(n)?Math.min(${APPEARANCE_EDITOR_FONT_SIZE_MAX},Math.max(${APPEARANCE_EDITOR_FONT_SIZE_MIN},Math.round(n))):d};r.setAttribute('data-font-settings','');for(var axis in axes){if(!has(axes,axis))continue;var spec=axes[axis];var candidate=saved[axis];var value=record(candidate)?candidate:{};var legacyUi=axis==='ui'&&!has(value,'family');var family=legacyUi?valid(p.font,'system'):valid(value.family,'system');var font=projection[family];if(family==='system')r.removeAttribute(spec.familyAttribute);else r.setAttribute(spec.familyAttribute,family);r.style.setProperty(spec.familyProperty,'var('+font.familyVariables[axis]+')');var px=size(value.size,spec.defaultSize);r.style.setProperty(spec.sizeProperty,px+'px');r.style.setProperty(spec.scaleProperty,String(px/spec.defaultSize));if(axis==='ui'){r.style.setProperty('--ui-tracking',font.uiTracking);r.style.setProperty('--ui-word-spacing',font.uiWordSpacing);}}r.removeAttribute('data-font');})();`
+}

package/src/lib/font-catalog.ts

@@ -0,0 +1,80 @@
+/**
+ * Stable font-family choices shared by the appearance editor and its host APIs.
+ *
+ * This stays independent of the theme-token manifest so consumers that need
+ * only font settings do not retain the palette catalogue.
+ */
+// Explicit catalogue choices resolve to the same named face in every role.
+// System Code is the exception: it resolves to the platform monospace stack.
+const FONT_OPTIONS = [
+  {
+    id: 'space-grotesk',
+    label: 'Space Grotesk',
+    description: 'The self-hosted Space Grotesk family.',
+    familyVariables: {
+      ui: '--font-family-space-grotesk',
+      content: '--font-family-space-grotesk',
+      code: '--font-family-space-grotesk',
+    },
+    uiTracking: 'normal',
+    uiWordSpacing: 'normal',
+    stack: 'both',
+  },
+  {
+    id: 'system',
+    label: 'System',
+    description: "The platform's own interface family and system monospace counterpart.",
+    familyVariables: {
+      ui: '--font-family-system',
+      content: '--font-family-system',
+      code: '--font-family-system-mono',
+    },
+    uiTracking: 'normal',
+    uiWordSpacing: 'normal',
+    stack: 'both',
+  },
+  {
+    id: 'geist',
+    label: 'Geist',
+    description: 'The face cortana already ships. Neutral and wide.',
+    familyVariables: {
+      ui: '--font-family-geist',
+      content: '--font-family-geist',
+      code: '--font-family-geist',
+    },
+    uiTracking: 'normal',
+    uiWordSpacing: 'normal',
+    stack: 'both',
+  },
+  {
+    id: 'geist-mono',
+    label: 'Geist Mono',
+    description: 'Monospace throughout, for someone who wants a uniform texture.',
+    familyVariables: {
+      ui: '--font-family-geist-mono',
+      content: '--font-family-geist-mono',
+      code: '--font-family-geist-mono',
+    },
+    uiTracking: '-0.03em',
+    uiWordSpacing: '-1.5px',
+    stack: 'both',
+  },
+  {
+    id: 'jetbrains-mono',
+    label: 'JetBrains Mono',
+    description: 'Monospace throughout, with coding ligatures off.',
+    familyVariables: {
+      ui: '--font-family-jetbrains-mono',
+      content: '--font-family-jetbrains-mono',
+      code: '--font-family-jetbrains-mono',
+    },
+    uiTracking: '-0.04em',
+    uiWordSpacing: '-2.5px',
+    stack: 'both',
+  },
+] as const
+
+/** Stable catalogue record type; saved values never contain CSS family strings. */
+export type FontOption = (typeof FONT_OPTIONS)[number]
+
+export const fontOptions: readonly FontOption[] = Object.freeze(FONT_OPTIONS)

package/src/lib/safe-script.ts

@@ -0,0 +1,7 @@
+/** Escape a string literal for an inline script's JavaScript source. */
+export function safeScriptStringLiteral(value: string): string {
+  return JSON.stringify(value).replace(
+    /[<>\u2028\u2029]/g,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`
+  )
+}

package/src/lib/tokens.ts

@@ -18,6 +18,8 @@
  */
 
 import { ACCENTS } from '@adea-ai/themes'
+export { fontOptions } from './font-catalog'
+export type { FontOption } from './font-catalog'
 
 export type TokenKind =
   | 'color'
@@ -388,20 +390,35 @@ export const radiusTokens: TokenDefinition[] = [
 ]
 
 export const typographyTokens: TokenDefinition[] = [
+  {
+    name: 'font-ui',
+    kind: 'font-family',
+    description: 'The selected family for interface controls, labels and headings.',
+  },
+  {
+    name: 'font-content',
+    kind: 'font-family',
+    description: 'The selected family for prose, transcripts and long-form reading.',
+  },
+  {
+    name: 'font-code',
+    kind: 'font-family',
+    description: 'The selected family for code, terminals, keyboard keys, ids and paths.',
+  },
   {
     name: 'font-sans',
     kind: 'font-family',
-    description: 'The selected interface face. Space Grotesk unless the font axis says otherwise.',
+    description: 'Compatibility alias for the selected UI family.',
   },
   {
     name: 'font-mono',
     kind: 'font-family',
-    description: 'The selected monospace face. Code, terminals, ids, paths.',
+    description: 'Compatibility alias for the selected code family.',
   },
   {
     name: 'font-family-space-grotesk',
     kind: 'font-family',
-    description: 'The interface default, and the face the visual language was drawn against.',
+    description: 'The self-hosted Space Grotesk family.',
   },
   {
     name: 'font-family-jetbrains-mono',
@@ -428,6 +445,36 @@ export const typographyTokens: TokenDefinition[] = [
     kind: 'font-family',
     description: "The platform's own monospace face.",
   },
+  {
+    name: 'font-ui-size',
+    kind: 'dimension',
+    description: 'Runtime-projected interface size in pixels; scales the shared UI text ladder.',
+  },
+  {
+    name: 'font-content-size',
+    kind: 'dimension',
+    description: 'Runtime-projected prose and transcript size in pixels.',
+  },
+  {
+    name: 'font-code-size',
+    kind: 'dimension',
+    description: 'Runtime-projected code, terminal and keyboard-key size in pixels.',
+  },
+  {
+    name: 'font-ui-scale',
+    kind: 'number',
+    description: 'The UI size ratio applied to the interface text ladder.',
+  },
+  {
+    name: 'font-content-scale',
+    kind: 'number',
+    description: 'The content size ratio applied to rem-relative prose text.',
+  },
+  {
+    name: 'font-code-scale',
+    kind: 'number',
+    description: 'The code size ratio applied to rem-relative code text.',
+  },
   {
     name: 'ui-tracking',
     kind: 'text',
@@ -443,13 +490,13 @@ export const typographyTokens: TokenDefinition[] = [
   {
     name: 'text-2xs',
     kind: 'text',
-    description: '11px — the smallest label the system permits: kbd keys, status bar.',
+    description: 'The smallest UI-scaled label: status bar and compact metadata.',
   },
-  { name: 'text-xs', kind: 'text', description: '12px — metadata, badges, secondary rows.' },
+  { name: 'text-xs', kind: 'text', description: 'UI-scaled metadata, badges and secondary rows.' },
   {
     name: 'text-sm',
     kind: 'text',
-    description: '14px — the interface default. Body copy, labels, controls.',
+    description: 'The UI-scaled interface default for labels and controls.',
   },
   { name: 'text-base', kind: 'text', description: '16px — card titles and dialog titles.' },
   { name: 'text-lg', kind: 'text', description: '18px — a section heading inside a page.' },
@@ -458,7 +505,17 @@ export const typographyTokens: TokenDefinition[] = [
   {
     name: 'text-3xl',
     kind: 'text',
-    description: '30px — the largest size in the system. Reserved for an empty-state headline.',
+    description: 'The largest UI-scaled rung. Reserved for an empty-state headline.',
+  },
+  {
+    name: 'text-content',
+    kind: 'text',
+    description: 'The selected content size with the prose line-height.',
+  },
+  {
+    name: 'text-code',
+    kind: 'text',
+    description: 'The selected code size with the code line-height.',
   },
 ]
 
@@ -661,58 +718,6 @@ export const accentPresets: readonly AccentPreset[] = Object.freeze([
   ...ACCENTS,
 ])
 
-/**
- * The font axis.
- *
- * The family is a selection, like the accent: `data-font` sits on the same element
- * and each option swaps the interface face. `space-grotesk` is the default because
- * it is the face the visual language was drawn against, and `system` is a
- * first-class option rather than a fallback — an application that wants the
- * platform's own face should be able to say so without losing the rest of the
- * system.
- */
-export type FontOption = {
-  /** The `data-font` value. `space-grotesk` is the default and needs no attribute. */
-  id: string
-  label: string
-  description: string
-  /** Which of the two stacks this option sets. */
-  stack: 'sans' | 'mono' | 'both'
-}
-
-export const fontOptions: readonly FontOption[] = Object.freeze([
-  {
-    id: 'space-grotesk',
-    label: 'Space Grotesk',
-    description: 'The default, and the face the visual language was drawn against.',
-    stack: 'both',
-  },
-  {
-    id: 'system',
-    label: 'System',
-    description: "The platform's own face. What a terminal or editor usually wants.",
-    stack: 'both',
-  },
-  {
-    id: 'geist',
-    label: 'Geist',
-    description: 'The face cortana already ships. Neutral and wide.',
-    stack: 'both',
-  },
-  {
-    id: 'geist-mono',
-    label: 'Geist Mono',
-    description: 'Monospace throughout, for someone who wants a uniform texture.',
-    stack: 'both',
-  },
-  {
-    id: 'jetbrains-mono',
-    label: 'JetBrains Mono',
-    description: 'Monospace throughout, with coding ligatures off.',
-    stack: 'both',
-  },
-])
-
 /** Every token, in gallery order. */
 export const designTokens = {
   color: colorTokens,

package/src/styles/appearance-font-settings.css

@@ -0,0 +1,110 @@
+/* Optional typography roles and Appearance font controls.
+ *
+ * Import after `theme.css` and `base.css` when the host uses the shared font
+ * preference projection. This file defines selectors and utilities only; it
+ * never imports font assets. `fonts.css` remains a separate opt-in for bundled
+ * typefaces.
+ */
+
+/* The marker scopes role defaults and wins over theme.css root tokens even
+   when a bundler hoists this optional sheet before shared globals. Family
+   values come from the validated shared runtime/bootstrap projection. */
+:root[data-font-settings] {
+  --font-ui: var(--font-family-system);
+  --font-content: var(--font-family-system);
+  --font-code: var(--font-family-system-mono);
+  --font-sans: var(--font-ui);
+  --font-mono: var(--font-code);
+  --font-ui-scale: 1;
+  --font-content-scale: 1;
+  --font-code-scale: 1;
+
+  --text-2xs: calc(0.6875rem * var(--font-ui-scale));
+  --text-xs: calc(0.75rem * var(--font-ui-scale));
+  --text-sm: calc(0.875rem * var(--font-ui-scale));
+  --text-base: calc(1rem * var(--font-ui-scale));
+  --text-lg: calc(1.125rem * var(--font-ui-scale));
+  --text-xl: calc(1.25rem * var(--font-ui-scale));
+  --text-2xl: calc(1.5rem * var(--font-ui-scale));
+  --text-3xl: calc(1.875rem * var(--font-ui-scale));
+  --text-content: calc(0.875rem * var(--font-content-scale));
+  --text-content--line-height: var(--text-sm--line-height);
+  --text-code: calc(0.75rem * var(--font-code-scale));
+  --text-code--line-height: var(--text-xs--line-height);
+}
+
+@layer base {
+  code,
+  kbd,
+  pre,
+  samp {
+    font-family: var(--font-code);
+    font-size: var(--text-code);
+  }
+
+  /* Appearance's own controls grow with the UI preference while ordinary
+     controls retain their established density. */
+  .global-appearance-font-settings button,
+  .global-appearance-editor-actions button {
+    min-height: max(var(--control-height-sm), calc(1lh + 2px));
+  }
+
+  /* Text controls keep their density rung but gain room for their projected
+     line box. Icon-only controls use size-control-* and keep fixed targets. */
+  [data-font-settings] .h-control-2xs {
+    --font-control-height: var(--control-height-2xs);
+  }
+  [data-font-settings] .h-control-xs {
+    --font-control-height: var(--control-height-xs);
+  }
+  [data-font-settings] .h-control-sm {
+    --font-control-height: var(--control-height-sm);
+  }
+  [data-font-settings] .h-control-md {
+    --font-control-height: var(--control-height-md);
+  }
+  [data-font-settings] .h-control-lg {
+    --font-control-height: var(--control-height-lg);
+  }
+  [data-font-settings] .h-control-xl {
+    --font-control-height: var(--control-height-xl);
+  }
+  [data-font-settings] .h-control-2xl {
+    --font-control-height: var(--control-height-2xl);
+  }
+  [data-font-settings]
+    :is(
+      .h-control-2xs,
+      .h-control-xs,
+      .h-control-sm,
+      .h-control-md,
+      .h-control-lg,
+      .h-control-xl,
+      .h-control-2xl
+    ) {
+    min-height: max(var(--font-control-height), calc(1lh + 2px));
+  }
+
+  [data-font-settings]
+    input:is(
+      .h-control-2xs,
+      .h-control-xs,
+      .h-control-sm,
+      .h-control-md,
+      .h-control-lg,
+      .h-control-xl,
+      .h-control-2xl
+    ) {
+    min-height: max(var(--font-control-height), calc(1lh + var(--spacing) + var(--spacing) + 2px));
+  }
+
+  .global-appearance-font-settings input[type='number'] {
+    min-height: max(var(--control-height-md), calc(1lh + var(--spacing) + var(--spacing) + 3px));
+  }
+}
+
+/* Keep the numeric font-size value visible beside the native number stepper
+   as the UI font grows; unlayered so this minimum wins over min-w-0. */
+.global-appearance-font-settings input[type='number'] {
+  min-width: calc(3ch + var(--control-padding-md) + var(--control-padding-md) + 1.25rem + 2px);
+}

package/src/styles/fonts.css

@@ -4,15 +4,14 @@
  * a desktop app must not fetch a font at runtime, or the first paint after a cold
  * start shows a fallback face and then reflows.
  *
- *   Space Grotesk   the interface default, and the face the visual language was
- *                   drawn against
+ *   Space Grotesk   a self-hosted proportional family
  *   JetBrains Mono  code, terminals, ids, paths
  *   Geist           an alternative interface face; cortana already ships it
  *   Geist Mono      its monospace counterpart
  *
- * The family is a *selection*, not a constant: `theme.css` exposes a `data-font`
- * axis, so a user can pick a face the way they pick an accent, and the system
- * default (`system`) is always available for someone who wants their OS's own.
+ * These families feed the shared UI, content and code axes. Their stable ids are
+ * projected by `@adea-ai/ui/lib/appearance-font-settings`; System is the default
+ * and needs no font asset.
  *
  * Consumers import this after the theme:
  *

package/src/styles/globals.css

@@ -5,10 +5,13 @@
  * @shadcn/lint discover, so it must stay the file that imports Tailwind.
  *
  *   @import '@adea-ai/ui/globals.css';
+ *   @import '@adea-ai/ui/appearance-font-settings.css'; <- optional role preferences
  *   @import '@adea-ai/ui/fonts.css';   <- optional, self-hosted typefaces
  *
  * A consumer that already imports Tailwind itself should import `theme.css`
- * and `base.css` directly instead, and must not import this file.
+ * and `base.css` directly instead, and must not import this file. The font role
+ * stylesheet stays opt-in so applications that use only the base theme keep
+ * the existing CSS footprint.
  *
  * Tokens live in `theme.css` only. This file must never duplicate them.
  */

package/src/styles/theme.css

@@ -525,6 +525,14 @@
   --font-family-geist-mono: 'Geist Mono Variable', 'Geist Mono', monospace;
   --font-family-system: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
   --font-family-system-mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+  /* Lightweight role defaults keep conversation and code components useful for
+     consumers that have not opted into independent Appearance font settings. */
+  --font-content: var(--font-sans);
+  --font-code: var(--font-mono);
+  --text-content: var(--text-sm);
+  --text-content--line-height: var(--text-sm--line-height);
+  --text-code: 0.75rem;
+  --text-code--line-height: 1.5;
 
   /* Width compensation for the mono UI fonts. `normal` on the proportional face,
      tightened by the `[data-font]` blocks above when the UI font is monospace. */
@@ -776,6 +784,8 @@
 
   --font-sans: var(--font-sans);
   --font-mono: var(--font-mono);
+  --font-content: var(--font-content);
+  --font-code: var(--font-code);
   --font-family-space-grotesk: var(--font-family-space-grotesk);
   --font-family-jetbrains-mono: var(--font-family-jetbrains-mono);
   --font-family-geist: var(--font-family-geist);
@@ -799,6 +809,10 @@
   --text-2xl--line-height: var(--text-2xl--line-height);
   --text-3xl: var(--text-3xl);
   --text-3xl--line-height: var(--text-3xl--line-height);
+  --text-content: var(--text-content);
+  --text-content--line-height: var(--text-content--line-height);
+  --text-code: var(--text-code);
+  --text-code--line-height: var(--text-code--line-height);
 
   --radius-sm: var(--radius-sm);
   --radius-md: var(--radius-md);