@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/theme/hairline.ts

@@ -0,0 +1,101 @@
+/**
+ * OPTICS hairline (Axiom 15): a divider means "one device pixel", not "one
+ * CSS pixel". On high-DPI web screens a 1px CSS divider paints 2–3 device
+ * pixels and reads heavy; 0.5px paints a single device pixel on 2x displays.
+ *
+ * Engine notes (probed against Chromium 147 / WebKit / Gecko):
+ * - Blink floors sub-1px BORDER widths up to 1 CSS px, but honors fractional
+ *   HEIGHT/WIDTH — so standalone rules use the filled `line`/`vline`
+ *   treatments (crisp everywhere), while container-owned edge borders
+ *   (`bottom`/`top`/`right`/`left`) render true hairlines on WebKit/Gecko
+ *   and gracefully stay 1px on Blink.
+ * - Low-DPI screens (1dppx) get a 1px fallback via the resolution media
+ *   query below, so hairlines never fade or vanish there.
+ *
+ * Scope: DIVIDERS ONLY — separators between rows/sections, menu separators,
+ * table head rules, full-bleed panel rules. Control borders (inputs,
+ * buttons, control groups) keep the knob-driven `borderWidth` semantics
+ * from `resolveKnobs` and MUST NOT use this token.
+ *
+ * Native twin: `hairline.native.ts` (react-native StyleSheet.hairlineWidth,
+ * no CSS classes).
+ */
+
+/** Divider line width: half a CSS pixel = one device pixel on 2x displays. */
+export const hairlineWidth: number = 0.5;
+
+/**
+ * Spreadable divider treatments. Each entry pairs the 0.5px style with the
+ * fallback class the low-DPI media query targets:
+ *
+ *   <Separator {...hairline.line} />            // horizontal rule element
+ *   <Separator vertical {...hairline.vline} />  // vertical rule element
+ *   <View {...hairline.height} />               // already-filled 1px line
+ *   <YStack {...hairline.bottom} />             // container-owned edge rule
+ */
+export const hairline = {
+  /**
+   * Standalone horizontal rule as a FILLED line (tamagui Separator draws a
+   * border, which Blink cannot paint below 1 CSS px — flip it to a filled
+   * fractional-height line, crisp in every engine). Consumers may override
+   * `backgroundColor` after the spread for non-default divider colors.
+   */
+  line: {
+    height: hairlineWidth,
+    maxHeight: hairlineWidth,
+    // Separator is a `flex: 1` item, so in a stack the main-axis size comes
+    // from flex-basis (height alone is ignored):
+    flexBasis: hairlineWidth,
+    borderBottomWidth: 0,
+    backgroundColor: "$borderColor",
+    className: "mp-hairline-h",
+  },
+  /** Standalone vertical rule as a filled line (see `line`). */
+  vline: {
+    width: hairlineWidth,
+    maxWidth: hairlineWidth,
+    flexBasis: hairlineWidth,
+    borderRightWidth: 0,
+    backgroundColor: "$borderColor",
+    className: "mp-hairline-w",
+  },
+  /** Already-filled 1px line elements (e.g. menu separator views). */
+  height: { height: hairlineWidth, className: "mp-hairline-h" },
+  // Container-owned edge rules. True hairline on WebKit/Gecko; Blink rounds
+  // sub-1px borders up to 1 CSS px (the pre-hairline status quo there).
+  bottom: { borderBottomWidth: hairlineWidth, className: "mp-hairline-b" },
+  top: { borderTopWidth: hairlineWidth, className: "mp-hairline-t" },
+  right: { borderRightWidth: hairlineWidth, className: "mp-hairline-r" },
+  left: { borderLeftWidth: hairlineWidth, className: "mp-hairline-l" },
+} as const;
+
+const STYLE_TAG_ID = "mp-hairline-styles";
+
+/**
+ * 1px fallback for screens where 0.5px cannot map to a whole device pixel.
+ * (`-webkit-max-device-pixel-ratio` covers Safari versions without
+ * `resolution` media-query support.) Exported for unit tests.
+ */
+export const hairlineFallbackCss = `@media (max-resolution: 1.49dppx), (-webkit-max-device-pixel-ratio: 1.49) {
+  .mp-hairline-b { border-bottom-width: 1px !important; }
+  .mp-hairline-t { border-top-width: 1px !important; }
+  .mp-hairline-r { border-right-width: 1px !important; }
+  .mp-hairline-l { border-left-width: 1px !important; }
+  .mp-hairline-h { height: 1px !important; max-height: 1px !important; flex-basis: 1px !important; }
+  .mp-hairline-w { width: 1px !important; max-width: 1px !important; flex-basis: 1px !important; }
+  .mp-hairline-ie { border-inline-end-width: 1px !important; }
+}`;
+
+/** Idempotently mount the low-DPI fallback stylesheet (no-op off-DOM). */
+export function ensureHairlineFallback(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_TAG_ID)) return;
+  const tag = document.createElement("style");
+  tag.id = STYLE_TAG_ID;
+  tag.textContent = hairlineFallbackCss;
+  document.head.appendChild(tag);
+}
+
+// The fallback is static CSS (no knob/theme dependency), so mount it as soon
+// as the module loads in a DOM environment.
+ensureHairlineFallback();

package/src/theme/index.ts

@@ -1,16 +1,24 @@
 export * from "./animations/index";
+export * from "./chartPalette";
 export * from "./colorRules";
 export * from "./cookies";
+export * from "./cornerSmoothing";
 export * from "./createDefaultThemeConfig";
 export * from "./createThemes";
+export * from "./defaults/index";
 export * from "./devtools/ThemeDevtoolsPanel";
+export * from "./focusState";
+export * from "./FontKnobStyles";
+export * from "./hairline";
 export * from "./Intent";
 export * from "./intents";
 export * from "./knobs";
+export * from "./layoutTokens";
 export * from "./Preset";
 export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
 export * from "./PresetContext";
 export * from "./presets";
+export * from "./readableColor";
 export * from "./recipes";
 export * from "./resolveKnobs";
 export * from "./shared";

package/src/theme/intent.spec.tsx

@@ -269,8 +269,8 @@ describe("useResolvedKnobs with Intent", () => {
 
     renderToHtml(wrapWithPreset(makePreset(), createElement(capture.Probe)));
 
-    // Default knobs: elevation "none" → resolved to undefined
-    expect(capture.result.knobProps.elevation).toBeUndefined();
+    // Default knobs: elevation "small" → resolved to "$1"
+    expect(capture.result.knobProps.elevation).toBe("$1");
     expect(capture.result.knobProps.textAccent).toBe("high");
   });
 });

package/src/theme/intents.ts

@@ -1,5 +1,8 @@
 import type { IntentOverride } from "./preset.types";
 
+// One emphasis system (SB-E-01): every intent Button renders SOLID like
+// accent — fillStyle "filled" so the solid _Button sub-theme surface applies
+// even under outlined presets.
 export const defaultIntents: Record<string, IntentOverride> = {
   accent: {
     fillStyle: "outlined",
@@ -8,15 +11,16 @@ export const defaultIntents: Record<string, IntentOverride> = {
   },
   error: {
     textAccent: "high",
-    Button: { elevation: "small" },
+    Button: { fillStyle: "filled", elevation: "small" },
     Input: { borderWidth: "medium" },
   },
   warning: {
     textAccent: "high",
+    Button: { fillStyle: "filled" },
     Input: { borderWidth: "small" },
   },
   success: {
     textAccent: "high",
-    Button: { elevation: "none" },
+    Button: { fillStyle: "filled", elevation: "none" },
   },
 };

package/src/theme/knobs.ts

@@ -12,6 +12,22 @@ export const BorderRadius = {
 } as const;
 export type BorderRadius = (typeof BorderRadius)[keyof typeof BorderRadius];
 
+/**
+ * Corner curvature continuity (Axiom 15 OPTICS). `smooth` renders
+ * continuous-curvature (superellipse/squircle) corners where the platform
+ * can (web: Chromium 139+ via `corner-shape`, others fall back to the plain
+ * arc); `round` is today's circular-arc border-radius everywhere.
+ * Two values, not a numeric dial: every shipped smoothing system converges
+ * on one blessed curve (Apple ≈ Figma 0.6 ≈ superellipse K=2), and a free
+ * number invites per-screen drift (Axiom 5). `none` is not needed —
+ * `borderRadius: "none"` already covers square corners.
+ */
+export const CornerSmoothing = {
+  Round: "round",
+  Smooth: "smooth",
+} as const;
+export type CornerSmoothing = (typeof CornerSmoothing)[keyof typeof CornerSmoothing];
+
 export const BorderWidth = {
   None: "none",
   Small: "small",
@@ -42,6 +58,89 @@ export const Size = {
 } as const;
 export type Size = (typeof Size)[keyof typeof Size];
 
+/** Global density mode — compact steps size+space down one level. */
+export const Density = {
+  Comfortable: "comfortable",
+  Compact: "compact",
+} as const;
+export type Density = (typeof Density)[keyof typeof Density];
+
+// ── House decisions (design-guidelines.md) ─────────────────
+// Behavioral knobs with recommended defaults — not hard constraints.
+
+/** Field label placement relative to the control. Default: top. */
+export const FieldLabelPlacement = {
+  Top: "top",
+  Side: "side",
+  Floating: "floating",
+} as const;
+export type FieldLabelPlacement = (typeof FieldLabelPlacement)[keyof typeof FieldLabelPlacement];
+
+/**
+ * How required/optional fields are marked.
+ * `minority` marks whichever is less common in the form (compute from schema).
+ */
+export const RequiredMarking = {
+  Asterisk: "asterisk",
+  Optional: "optional",
+  Minority: "minority",
+} as const;
+export type RequiredMarking = (typeof RequiredMarking)[keyof typeof RequiredMarking];
+
+/** Alternating table row backgrounds. Default: off. */
+export const TableZebra = {
+  On: "on",
+  Off: "off",
+} as const;
+export type TableZebra = (typeof TableZebra)[keyof typeof TableZebra];
+
+/** Bulk-action bar placement for multi-select tables. Default: top (sticky). */
+export const BulkBarPlacement = {
+  Top: "top",
+  Bottom: "bottom",
+} as const;
+export type BulkBarPlacement = (typeof BulkBarPlacement)[keyof typeof BulkBarPlacement];
+
+/**
+ * Timestamp display style.
+ * Recommended: absolute in data tables; relative in feeds. Default: absolute.
+ */
+export const TimestampStyle = {
+  Absolute: "absolute",
+  Relative: "relative",
+} as const;
+export type TimestampStyle = (typeof TimestampStyle)[keyof typeof TimestampStyle];
+
+/**
+ * Table select-all scope (DG-TBL-03): header checkbox selects the current
+ * page or all filtered/matching rows. Default: page.
+ */
+export const SelectAllScope = {
+  Page: "page",
+  Filtered: "filtered",
+} as const;
+export type SelectAllScope = (typeof SelectAllScope)[keyof typeof SelectAllScope];
+
+/**
+ * Disabled control treatment (LC-40 DISABLED-VISIBLE / DG-ST-05). Both
+ * values render a VISIBLE treatment via the resolved `disabledState` recipe:
+ * `keepLabel` (default, Fluent model) washes the control chrome while
+ * label/value text stays ≥ AA; `dimWhole` (Material model) dims the whole
+ * assembly, label included. Read-only is a different state and never dims.
+ */
+export const DisabledStyle = {
+  DimWhole: "dimWhole",
+  KeepLabel: "keepLabel",
+} as const;
+export type DisabledStyle = (typeof DisabledStyle)[keyof typeof DisabledStyle];
+
+/** Autofocus first field on form mount. Default: off (a11y). */
+export const FormAutofocus = {
+  On: "on",
+  Off: "off",
+} as const;
+export type FormAutofocus = (typeof FormAutofocus)[keyof typeof FormAutofocus];
+
 // ── Emphasis ───────────────────────────────────────────────
 
 export const TextAccent = {
@@ -109,15 +208,38 @@ export type InteractionState = (typeof interactionStates)[number];
 export interface Knobs {
   fillStyle: FillStyle;
   borderRadius: BorderRadius;
+  /**
+   * Corner curvature continuity (Axiom 15 OPTICS). Optional so existing
+   * preset/knob constructions stay valid; resolveKnobs defaults to `round`.
+   */
+  cornerSmoothing?: CornerSmoothing;
   borderWidth: BorderWidth;
   elevation: Elevation;
   space: Space;
   size: Size;
+  /** Propagating density mode. Default comfortable; compact steps size+space. */
+  density: Density;
   textAccent: TextAccent;
   headingFont: HeadingFont;
   bodyFont: BodyFont;
   fontWeight: FontWeight;
   animation: Animation;
+  /** House: field label placement. Default top. */
+  fieldLabelPlacement: FieldLabelPlacement;
+  /** House: required/optional marking. Default minority. */
+  requiredMarking: RequiredMarking;
+  /** House: zebra table rows. Default off. */
+  tableZebra: TableZebra;
+  /** House: bulk bar placement. Default top. */
+  bulkBarPlacement: BulkBarPlacement;
+  /** House: table select-all scope. Default page. */
+  selectAllScope: SelectAllScope;
+  /** House: timestamp style. Default absolute. */
+  timestampStyle: TimestampStyle;
+  /** House: disabled treatment. Default keepLabel. */
+  disabledStyle: DisabledStyle;
+  /** House: form autofocus. Default off. */
+  formAutofocus: FormAutofocus;
   hover: StateKnobs;
   press: StateKnobs;
   focus: StateKnobs;
@@ -131,15 +253,25 @@ export const emptyStateKnobs: StateKnobs = {};
 export const defaultKnobs: Knobs = {
   fillStyle: "filled",
   borderRadius: "medium",
-  borderWidth: "small",
-  elevation: "none",
+  cornerSmoothing: "round",
+  borderWidth: "medium",
+  elevation: "small",
   space: "medium",
   size: "medium",
+  density: "comfortable",
   textAccent: "high",
   headingFont: "sans-serif",
   bodyFont: "sans-serif",
   fontWeight: "regular",
   animation: "quick",
+  fieldLabelPlacement: "top",
+  requiredMarking: "minority",
+  tableZebra: "off",
+  bulkBarPlacement: "top",
+  selectAllScope: "page",
+  timestampStyle: "absolute",
+  disabledStyle: "keepLabel",
+  formAutofocus: "off",
   hover: emptyStateKnobs,
   press: emptyStateKnobs,
   focus: emptyStateKnobs,

package/src/theme/layoutTokens.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  MIN_PRESS_TARGET,
+  NARROW_BREAKPOINT,
+  OVERLAY_BREAKPOINT,
+  READING_WIDTH_CH,
+  READING_WIDTH_MAX_CH,
+  READING_WIDTH_MIN_CH,
+  defaultMaxPanes,
+  getLayoutSizeClass,
+  layoutBreakpoints,
+  layoutSizeClassAtLeast,
+  pressTargetHitSlop,
+  pressTargetStyle,
+  readingWidthStyle,
+} from "./layoutTokens";
+
+describe("layoutBreakpoints (DG-LAY-01)", () => {
+  it("documents FloatingPanel 860 as expanded / overlay", () => {
+    expect(layoutBreakpoints.expanded).toBe(860);
+    expect(OVERLAY_BREAKPOINT).toBe(860);
+  });
+
+  it("documents DeskShell narrow as medium 640", () => {
+    expect(layoutBreakpoints.medium).toBe(640);
+    expect(NARROW_BREAKPOINT).toBe(640);
+  });
+
+  it("maps widths to size classes", () => {
+    expect(getLayoutSizeClass(360)).toBe("compact");
+    expect(getLayoutSizeClass(640)).toBe("medium");
+    expect(getLayoutSizeClass(859)).toBe("medium");
+    expect(getLayoutSizeClass(860)).toBe("expanded");
+    expect(getLayoutSizeClass(1024)).toBe("large");
+    expect(getLayoutSizeClass(1280)).toBe("xl");
+  });
+
+  it("defaults to 1 pane below expanded, 2 at expanded+", () => {
+    expect(defaultMaxPanes("compact")).toBe(1);
+    expect(defaultMaxPanes("medium")).toBe(1);
+    expect(defaultMaxPanes("expanded")).toBe(2);
+    expect(defaultMaxPanes("large")).toBe(2);
+    expect(defaultMaxPanes("xl")).toBe(2);
+  });
+
+  it("compares size classes ordinally", () => {
+    expect(layoutSizeClassAtLeast("expanded", "expanded")).toBe(true);
+    expect(layoutSizeClassAtLeast("medium", "expanded")).toBe(false);
+    expect(layoutSizeClassAtLeast("xl", "large")).toBe(true);
+  });
+});
+
+describe("readingWidthStyle (DG-LAY-05)", () => {
+  it("defaults to ~70ch within 65–75", () => {
+    expect(READING_WIDTH_CH).toBeGreaterThanOrEqual(READING_WIDTH_MIN_CH);
+    expect(READING_WIDTH_CH).toBeLessThanOrEqual(READING_WIDTH_MAX_CH);
+    expect(readingWidthStyle()).toEqual({ maxWidth: "70ch", width: "100%" });
+  });
+
+  it("clamps and supports eject", () => {
+    expect(readingWidthStyle(40)).toEqual({ maxWidth: "65ch", width: "100%" });
+    expect(readingWidthStyle(90)).toEqual({ maxWidth: "75ch", width: "100%" });
+    expect(readingWidthStyle("none")).toEqual({});
+    expect(readingWidthStyle(null)).toEqual({});
+  });
+});
+
+describe("press target (DG-LAY-04)", () => {
+  it("exports 44px floor + hitSlop expansion", () => {
+    expect(MIN_PRESS_TARGET).toBe(44);
+    expect(pressTargetStyle()).toEqual({ minWidth: 44, minHeight: 44 });
+    expect(pressTargetHitSlop(24)).toEqual({ top: 10, bottom: 10, left: 10, right: 10 });
+    expect(pressTargetHitSlop(44)).toEqual({ top: 0, bottom: 0, left: 0, right: 0 });
+  });
+});

package/src/theme/layoutTokens.ts

@@ -0,0 +1,213 @@
+/**
+ * Layout tokens — DG-LAY-01..05 (W11).
+ *
+ * Canonical size classes for layout decisions (pane count, nav mode, overlay
+ * sheet vs float). Primitives consume these classes / helpers — not raw px in
+ * call sites.
+ *
+ * ## Canonical choice (2026-08-12)
+ *
+ * Hybrid of shipped MP1 behavior + Material window-size naming:
+ * - **Names** follow Material (compact → xl).
+ * - **Numbers** prefer already-shipped thresholds:
+ *   - `medium` @ 640 = Tamagui `$sm` / DeskShell narrow (Fluent sm).
+ *   - `expanded` @ 860 = FloatingPanel sheet↔float pivot (~Material 840).
+ *   - `large` / `xl` = Tamagui `$lg` / `$xl`.
+ *
+ * Fluent (480/640/1024/1366/1920) and Material (600/840/1200/1600) stay in the
+ * compat table below for mapping — they are not second sources of truth.
+ *
+ * | Class     | Min px | Max panes (default) | Tamagui media | Notes                          |
+ * |-----------|--------|---------------------|---------------|--------------------------------|
+ * | compact   | 0      | 1                   | < `$sm`       | phones; drawer nav             |
+ * | medium    | 640    | 1                   | `$sm`         | DeskShell rail; still 1 pane   |
+ * | expanded  | 860    | 2                   | — (custom)    | FloatingPanel float; 2 panes   |
+ * | large     | 1024   | 2                   | `$lg`         |                                |
+ * | xl        | 1280   | 2                   | `$xl`         |                                |
+ *
+ * Compat: Material compact≈our compact (600→640), expanded≈our expanded
+ * (840→860). Fluent sm=640 matches medium; Fluent lg=1024 matches large.
+ */
+
+import { useEffect, useState } from "react";
+import { isWeb, useWindowDimensions } from "tamagui";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+// ── Breakpoint tokens (DG-LAY-01) ─────────────────────────────────────────
+
+export type LayoutSizeClass = "compact" | "medium" | "expanded" | "large" | "xl";
+
+/** Named min-widths. Prefer these over literals in layout code. */
+export const layoutBreakpoints = {
+  /** End of compact / DeskShell narrow drawer threshold (Tamagui `$sm`). */
+  medium: 640,
+  /** Two-pane + FloatingPanel float threshold (~M3 expanded 840). */
+  expanded: 860,
+  /** Tamagui `$lg`. */
+  large: 1024,
+  /** Tamagui `$xl`. */
+  xl: 1280,
+} as const;
+
+export type LayoutBreakpointName = keyof typeof layoutBreakpoints;
+
+/**
+ * Alias kept for FloatingPanel / overlay consumers — same value as
+ * `layoutBreakpoints.expanded`.
+ */
+export const OVERLAY_BREAKPOINT = layoutBreakpoints.expanded;
+
+/** DeskShell sidebar collapse — same value as `layoutBreakpoints.medium`. */
+export const NARROW_BREAKPOINT = layoutBreakpoints.medium;
+
+export const LAYOUT_SIZE_CLASS_ORDER: readonly LayoutSizeClass[] = [
+  "compact",
+  "medium",
+  "expanded",
+  "large",
+  "xl",
+] as const;
+
+/** Resolve a viewport width to the canonical layout size class. */
+export function getLayoutSizeClass(width: number): LayoutSizeClass {
+  if (width >= layoutBreakpoints.xl) return "xl";
+  if (width >= layoutBreakpoints.large) return "large";
+  if (width >= layoutBreakpoints.expanded) return "expanded";
+  if (width >= layoutBreakpoints.medium) return "medium";
+  return "compact";
+}
+
+/** Default horizontal pane budget by size class (Material PaneScaffoldDirective). */
+export function defaultMaxPanes(sizeClass: LayoutSizeClass): 1 | 2 {
+  return sizeClass === "compact" || sizeClass === "medium" ? 1 : 2;
+}
+
+export function layoutSizeClassAtLeast(
+  current: LayoutSizeClass,
+  minimum: LayoutSizeClass,
+): boolean {
+  return LAYOUT_SIZE_CLASS_ORDER.indexOf(current) >= LAYOUT_SIZE_CLASS_ORDER.indexOf(minimum);
+}
+
+/** Web viewport width with an SSR fallback (`medium`). Web-only callers. */
+function readViewportWidth(): number {
+  if (typeof window === "undefined") return layoutBreakpoints.medium;
+  return window.innerWidth;
+}
+
+/**
+ * Live layout size class from viewport width — cross-platform:
+ * - Web: matchMedia listeners on the class thresholds (re-renders only when
+ *   the class flips, not per resize pixel). SSR first paint → `medium`.
+ * - Native: react-native window dimensions (rotation / split-screen), so
+ *   phones report `compact` instead of the former pinned `medium`.
+ */
+export function useLayoutSizeClass(): LayoutSizeClass {
+  // Hook order is unconditional; on web the value is ignored in favor of the
+  // matchMedia path below (threshold-only updates).
+  const nativeWidth = useWindowDimensions().width;
+  const [sizeClass, setSizeClass] = useState<LayoutSizeClass>(() =>
+    getLayoutSizeClass(isWeb ? readViewportWidth() : nativeWidth),
+  );
+
+  useEffect(() => {
+    if (!isWeb || typeof window === "undefined") return;
+
+    const queries = [
+      window.matchMedia(`(min-width: ${layoutBreakpoints.xl}px)`),
+      window.matchMedia(`(min-width: ${layoutBreakpoints.large}px)`),
+      window.matchMedia(`(min-width: ${layoutBreakpoints.expanded}px)`),
+      window.matchMedia(`(min-width: ${layoutBreakpoints.medium}px)`),
+    ];
+
+    const sync = () => setSizeClass(getLayoutSizeClass(window.innerWidth));
+    sync();
+    for (const mq of queries) mq.addEventListener("change", sync);
+    return () => {
+      for (const mq of queries) mq.removeEventListener("change", sync);
+    };
+  }, []);
+
+  // Native: derive from the live dimensions; setState bails when unchanged.
+  useEffect(() => {
+    if (isWeb) return;
+    setSizeClass(getLayoutSizeClass(nativeWidth));
+  }, [nativeWidth]);
+
+  return sizeClass;
+}
+
+/** True when the viewport may show two side-by-side panes. */
+export function useMultiPane(maxPanes?: 1 | 2): boolean {
+  const sizeClass = useLayoutSizeClass();
+  const budget = maxPanes ?? defaultMaxPanes(sizeClass);
+  return budget >= 2 && defaultMaxPanes(sizeClass) >= 2;
+}
+
+// ── Reading width (DG-LAY-05) ─────────────────────────────────────────────
+
+/** Ideal prose measure (mid of GOV.UK ≤75 / USWDS ~66). */
+export const READING_WIDTH_CH = 70;
+export const READING_WIDTH_MIN_CH = 65;
+export const READING_WIDTH_MAX_CH = 75;
+
+export type ReadingWidthStyle = {
+  maxWidth: string;
+  width: "100%";
+};
+
+/** Style props for prose / long-form columns. Pass `null`/`"none"` to eject. */
+export function readingWidthStyle(
+  measure: number | "none" | null = READING_WIDTH_CH,
+): ReadingWidthStyle | Record<string, never> {
+  if (measure === "none" || measure === null) return {};
+  const ch = Math.min(READING_WIDTH_MAX_CH, Math.max(READING_WIDTH_MIN_CH, measure));
+  return { maxWidth: `${ch}ch`, width: "100%" };
+}
+
+// ── Min press target (DG-LAY-04) ──────────────────────────────────────────
+
+/** Platform floor for interactive targets (Fluent/HIG web+iOS 44; M3 48 on Android). */
+export const MIN_PRESS_TARGET = 44;
+
+export type PressTargetStyle = {
+  minWidth: number;
+  minHeight: number;
+};
+
+export function pressTargetStyle(size: number = MIN_PRESS_TARGET): PressTargetStyle {
+  return { minWidth: size, minHeight: size };
+}
+
+export type HitSlopInsets = {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+
+/** Expand hit area when the visual control is smaller than the floor. */
+export function pressTargetHitSlop(
+  visualSize: number,
+  min: number = MIN_PRESS_TARGET,
+): HitSlopInsets {
+  const pad = Math.max(0, Math.ceil((min - visualSize) / 2));
+  return { top: pad, bottom: pad, left: pad, right: pad };
+}
+
+// ── Semantic gaps (DG-LAY-03) ─────────────────────────────────────────────
+
+/**
+ * Semantic spacing roles map onto the space-knob recipes:
+ * `within-group` → `knobProps.gap`, `between-groups` → `knobProps.gapLg`.
+ */
+export function useSemanticGaps(): {
+  withinGroup: { gap: string };
+  betweenGroups: { gap: string };
+} {
+  const { knobProps } = useResolvedKnobs();
+  return {
+    withinGroup: knobProps.gap,
+    betweenGroups: knobProps.gapLg,
+  };
+}