@ramme-io/ui 4.0.1 → 4.1.1

package/src/wizardManifest.ts

@@ -402,6 +402,25 @@ export const wizardManifest: WizardManifest = {
       "humanLabel": "AIChatThread",
       "humanDescription": "A complete chat surface — message history, streaming indicator, error banner, provider/model attribution, and the composer. Strategic purpose: the presentational half of a chat feature, driven entirely by props from kernel's useRammeAI(). It holds no transport of its own, and takes a `renderMessage` override so products can add markdown or rich rendering without pulling those deps into @ramme-io/ui."
     },
+    {
+      "id": "architecture-reference-card",
+      "name": "ArchitectureReferenceCard",
+      "version": "1.0.0",
+      "description": "AI-generated card summarizing this platform's own data architecture — stack, data model, AI pipelines, and sentinel fleet",
+      "tags": [
+        "ai",
+        "architecture",
+        "reference",
+        "generative-ui"
+      ],
+      "category": "ai",
+      "props": [],
+      "importPath": "./components/ai/ArchitectureReferenceCard/ArchitectureReferenceCard",
+      "filePath": "src/components/ai/ArchitectureReferenceCard/ArchitectureReferenceCard.tsx",
+      "sku": "@molecule/ai/architecture-reference-card",
+      "humanLabel": "ArchitectureReferenceCard",
+      "humanDescription": "AI-generated card summarizing this platform's own data architecture — stack, data model, AI pipelines, and sentinel fleet"
+    },
     {
       "id": "company-profile-card",
       "name": "CompanyProfileCard",
@@ -429,6 +448,77 @@ export const wizardManifest: WizardManifest = {
       "humanLabel": "CompanyProfileCard",
       "humanDescription": "A company summary for a ticker — sector, industry, and description — fetched on demand and cached. Strategic purpose: a generative-UI block an AI tool call can render directly into a chat thread. Surfaces its own provenance, distinguishing a live fetch from a cached or stale answer instead of presenting all three as equally fresh."
     },
+    {
+      "id": "counterparty-graph-card",
+      "name": "CounterpartyGraphCard",
+      "version": "1.0.0",
+      "description": "AI-generated counterparty relationship card showing suppliers, customers, partners, and competitors inferred from alternative signals",
+      "tags": [
+        "ai",
+        "counterparty",
+        "graph",
+        "relationships",
+        "generative-ui"
+      ],
+      "category": "ai",
+      "props": [],
+      "importPath": "./components/ai/CounterpartyGraphCard/CounterpartyGraphCard",
+      "filePath": "src/components/ai/CounterpartyGraphCard/CounterpartyGraphCard.tsx",
+      "sku": "@molecule/ai/counterparty-graph-card",
+      "humanLabel": "CounterpartyGraphCard",
+      "humanDescription": "AI-generated counterparty relationship card showing suppliers, customers, partners, and competitors inferred from alternative signals"
+    },
+    {
+      "id": "divergence-metrics-card",
+      "name": "DivergenceMetricsCard",
+      "version": "1.0.0",
+      "description": "AI-generated card showing operational and customer divergence scores — a signed delta between expected and observed performance",
+      "tags": [
+        "ai",
+        "divergence",
+        "metrics",
+        "generative-ui"
+      ],
+      "category": "ai",
+      "props": [],
+      "importPath": "./components/ai/DivergenceMetricsCard/DivergenceMetricsCard",
+      "filePath": "src/components/ai/DivergenceMetricsCard/DivergenceMetricsCard.tsx",
+      "sku": "@molecule/ai/divergence-metrics-card",
+      "humanLabel": "DivergenceMetricsCard",
+      "humanDescription": "AI-generated card showing operational and customer divergence scores — a signed delta between expected and observed performance"
+    },
+    {
+      "id": "key-injection-overlay",
+      "name": "KeyInjectionOverlay",
+      "version": "1.0.0",
+      "description": "Blocks the app and collects an AI provider key when the gateway reports one is missing or expired. Strategic purpose: the BYOK prompt, in one place, so a key request looks the same everywhere and never becomes an inline form somebody rebuilds per feature. Renders nothing unless status is 'BYOK_REQUIRED' or 'KEY_EXPIRED', so it can stay mounted at the shell level.",
+      "tags": [
+        "ai",
+        "byok",
+        "overlay",
+        "auth",
+        "gateway",
+        "key"
+      ],
+      "category": "ai",
+      "props": [
+        {
+          "name": "status",
+          "type": "string",
+          "description": "Gateway status. The overlay shows only for 'BYOK_REQUIRED' or 'KEY_EXPIRED'."
+        },
+        {
+          "name": "setSessionKey",
+          "type": "function",
+          "description": "Receives the entered key when the form is submitted."
+        }
+      ],
+      "importPath": "./components/ai/KeyInjectionOverlay",
+      "filePath": "src/components/ai/KeyInjectionOverlay.tsx",
+      "sku": "@molecule/ai/key-injection-overlay",
+      "humanLabel": "KeyInjectionOverlay",
+      "humanDescription": "Blocks the app and collects an AI provider key when the gateway reports one is missing or expired. Strategic purpose: the BYOK prompt, in one place, so a key request looks the same everywhere and never becomes an inline form somebody rebuilds per feature. Renders nothing unless status is 'BYOK_REQUIRED' or 'KEY_EXPIRED', so it can stay mounted at the shell level."
+    },
     {
       "id": "live-quote-card",
       "name": "LiveQuoteCard",
@@ -510,7 +600,7 @@ export const wizardManifest: WizardManifest = {
     {
       "id": "login-page",
       "name": "LoginPage",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "description": "The standard sign-in screen — email and password, with inline error and loading states already wired. Strategic purpose: a drop-in credential form so products don't rebuild one; `quickProfiles` adds one-click demo personas, which is what makes a prototype instantly explorable without real accounts.",
       "tags": [
         "auth",
@@ -540,6 +630,21 @@ export const wizardManifest: WizardManifest = {
           "name": "quickProfiles",
           "type": "Array<QuickProfile>",
           "description": "Optional one-click demo identities, each `{ name, email, role }`."
+        },
+        {
+          "name": "signupHref",
+          "type": "string",
+          "description": "Where \"Create one\" points. Pass `null` to hide that line entirely, which is what an invite-only product wants. Defaults to `/auth/signup`."
+        },
+        {
+          "name": "signupLabel",
+          "type": "string",
+          "description": "Text for that link. Defaults to \"Create one\"."
+        },
+        {
+          "name": "forgotHref",
+          "type": "string",
+          "description": "Where \"Forgot?\" points. Pass `null` to hide it — a product with no reset email has nothing to link to. Defaults to `#`."
         }
       ],
       "importPath": "./components/auth/LoginPage",
@@ -755,31 +860,58 @@ export const wizardManifest: WizardManifest = {
     {
       "id": "code-block",
       "name": "CodeBlock",
-      "version": "1.0.0",
-      "description": "A component for displaying formatted and syntax-highlighted code snippets.",
+      "version": "1.0.1",
+      "description": "The one way to show code. Syntax-highlighted, theme-aware, with a copy button that works on touch and outside secure contexts. Use for every snippet in docs and tutorials — do not hand-roll a <pre>. Long lines scroll inside the block so the page never scrolls sideways on a phone.",
       "tags": [
         "ui",
         "data-display",
-        "code"
+        "code",
+        "docs",
+        "tutorial"
       ],
       "category": "ui",
       "props": [
         {
           "name": "code",
           "type": "string",
-          "description": "The string of code to display."
+          "description": "The snippet to display. Outer blank lines are trimmed."
         },
         {
           "name": "language",
           "type": "string",
-          "description": "The programming language for syntax highlighting (e.g., 'tsx', 'css', 'javascript')."
+          "description": "Prism language id — 'tsx', 'bash', 'css', 'json'. Defaults to 'tsx'."
+        },
+        {
+          "name": "filename",
+          "type": "string",
+          "description": "Header label. Prefer a real path like 'src/App.tsx'; falls back to the language."
+        },
+        {
+          "name": "showLineNumbers",
+          "type": "boolean",
+          "description": "Show gutter line numbers. Use when the surrounding prose cites line numbers."
+        },
+        {
+          "name": "highlightLines",
+          "type": "number[]",
+          "description": "1-based lines to emphasise, for \"change this line\" steps."
+        },
+        {
+          "name": "wrap",
+          "type": "boolean",
+          "description": "Wrap long lines instead of scrolling them. Off by default."
+        },
+        {
+          "name": "hideCopy",
+          "type": "boolean",
+          "description": "Hide the copy button, for snippets that are not meant to be run."
         }
       ],
       "importPath": "./components/data-display/CodeBlock",
       "filePath": "src/components/data-display/CodeBlock.tsx",
       "sku": "@atom/primitive/code-block",
       "humanLabel": "CodeBlock",
-      "humanDescription": "A component for displaying formatted and syntax-highlighted code snippets."
+      "humanDescription": "The one way to show code. Syntax-highlighted, theme-aware, with a copy button that works on touch and outside secure contexts. Use for every snippet in docs and tutorials — do not hand-roll a <pre>. Long lines scroll inside the block so the page never scrolls sideways on a phone."
     },
     {
       "id": "data-table",
@@ -1752,8 +1884,8 @@ export const wizardManifest: WizardManifest = {
     {
       "id": "segmented-control",
       "name": "SegmentedControl",
-      "version": "1.0.0",
-      "description": "A theme-aware linear toggle component. Ideal for switching between discrete modes (e.g., \"Map / List\").",
+      "version": "1.0.1",
+      "description": "A theme-aware linear toggle component. Ideal for switching between discrete modes (e.g., \"Map / List\"). Every size clears the 24px WCAG 2.5.8 (AA) target-size minimum — xs 24px, sm ~25px, md ~36px. None reaches the 44px 2.5.5 (AAA) figure, so for a primary control on a touch screen prefer md or give the control its own 44px row; xs and sm are density sizes for pointer-driven toolbars.",
       "tags": [
         "input",
         "toggle",
@@ -1767,7 +1899,7 @@ export const wizardManifest: WizardManifest = {
       "filePath": "src/components/forms/SegmentedControl.tsx",
       "sku": "@atom/form/segmented-control",
       "humanLabel": "SegmentedControl",
-      "humanDescription": "A theme-aware linear toggle component. Ideal for switching between discrete modes (e.g., \"Map / List\")."
+      "humanDescription": "A theme-aware linear toggle component. Ideal for switching between discrete modes (e.g., \"Map / List\"). Every size clears the 24px WCAG 2.5.8 (AA) target-size minimum — xs 24px, sm ~25px, md ~36px. None reaches the 44px 2.5.5 (AAA) figure, so for a primary control on a touch screen prefer md or give the control its own 44px row; xs and sm are density sizes for pointer-driven toolbars."
     },
     {
       "id": "select",
@@ -1848,31 +1980,53 @@ export const wizardManifest: WizardManifest = {
     {
       "id": "textarea",
       "name": "Textarea",
-      "version": "1.0.0",
-      "description": "A theme-aware textarea component for multi-line text input.",
+      "version": "1.0.1",
+      "description": "A theme-aware multi-line text input with label, helper text, and validation state support. Strategic purpose: the multi-line sibling of Input, styled identically so the two are indistinguishable when stacked in one form. Forwards all standard HTML textarea attributes via spread.",
       "tags": [
         "form",
         "input",
-        "ui"
+        "ui",
+        "text",
+        "multiline"
       ],
       "category": "form",
       "props": [
         {
           "name": "label",
           "type": "string",
-          "description": "An optional label to display above the textarea."
+          "description": "Optional label displayed above the textarea."
+        },
+        {
+          "name": "helperText",
+          "type": "string",
+          "description": "Supporting text rendered below the textarea. Appears in destructive color when error is true."
+        },
+        {
+          "name": "error",
+          "type": "boolean",
+          "description": "If true, applies destructive border styling to indicate a validation error. Defaults to false."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "description": "If true, appends a required (*) indicator next to the label. Defaults to false."
+        },
+        {
+          "name": "showOptionalLabel",
+          "type": "boolean",
+          "description": "If true, appends an (optional) label when the field is not required. Defaults to false."
         },
         {
           "name": "containerClassName",
           "type": "string",
-          "description": "Optional additional CSS classes for the container div."
+          "description": "Additional CSS classes applied to the outer container div."
         }
       ],
       "importPath": "./components/forms/Textarea",
       "filePath": "src/components/forms/Textarea.tsx",
       "sku": "@atom/form/textarea",
       "humanLabel": "Textarea",
-      "humanDescription": "A theme-aware textarea component for multi-line text input."
+      "humanDescription": "A theme-aware multi-line text input with label, helper text, and validation state support. Strategic purpose: the multi-line sibling of Input, styled identically so the two are indistinguishable when stacked in one form. Forwards all standard HTML textarea attributes via spread."
     },
     {
       "id": "toggle-switch",
@@ -2242,6 +2396,48 @@ export const wizardManifest: WizardManifest = {
       "humanLabel": "SectionHeader",
       "humanDescription": "A simple, consistent header for organizing sections of content within a page."
     },
+    {
+      "id": "connector-overlay",
+      "name": "ConnectorOverlay",
+      "version": "1.0.0",
+      "description": "Covers a panel while its data source is connecting, and explains itself when the connection fails. Strategic purpose: the standard treatment for a live region that has no data yet — telemetry panels, market feeds, device dashboards — so every product says the same thing about a dead socket instead of inventing a spinner. Renders nothing once status is 'connected', so it can stay mounted.",
+      "tags": [
+        "feedback",
+        "overlay",
+        "connection",
+        "realtime",
+        "loading",
+        "error"
+      ],
+      "category": "feedback",
+      "props": [
+        {
+          "name": "status",
+          "type": "string",
+          "description": "'connecting' | 'connected' | 'error'. Renders null when connected."
+        },
+        {
+          "name": "message",
+          "type": "ReactNode",
+          "description": "Replaces the default copy for the current status."
+        },
+        {
+          "name": "onRetry",
+          "type": "function",
+          "description": "Shows a retry action in the error state when provided."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Additional CSS classes."
+        }
+      ],
+      "importPath": "./components/molecular/ConnectorOverlay",
+      "filePath": "src/components/molecular/ConnectorOverlay.tsx",
+      "sku": "@molecule/feedback/connector-overlay",
+      "humanLabel": "ConnectorOverlay",
+      "humanDescription": "Covers a panel while its data source is connecting, and explains itself when the connection fails. Strategic purpose: the standard treatment for a live region that has no data yet — telemetry panels, market feeds, device dashboards — so every product says the same thing about a dead socket instead of inventing a spinner. Renders nothing once status is 'connected', so it can stay mounted."
+    },
     {
       "id": "data-card",
       "name": "DataCard",
@@ -2464,8 +2660,8 @@ export const wizardManifest: WizardManifest = {
     {
       "id": "mobile-nav",
       "name": "MobileNav",
-      "version": "1.0.0",
-      "description": "A fixed bottom tab bar for mobile screens, providing native-feeling navigation with primary icon+label tabs and a \"More\" drawer for secondary links. Hidden on md: and up via Tailwind. Designed as the mobile counterpart to the desktop Sidebar.",
+      "version": "1.0.3",
+      "description": "Mobile navigation, in two shapes. 'bar' is a fixed bottom tab bar with icon+label tabs and a \"More\" drawer for secondary links. 'sheet' drops the bar entirely and puts every destination in a bottom drawer the host opens from its own trigger — the right choice when a mobile browser's toolbar already owns the bottom edge. Hidden on md: and up via Tailwind. The mobile counterpart to the desktop Sidebar.",
       "tags": [
         "navigation",
         "mobile",
@@ -2514,13 +2710,33 @@ export const wizardManifest: WizardManifest = {
           "name": "className",
           "type": "string",
           "description": "Additional CSS classes on the root nav bar."
+        },
+        {
+          "name": "variant",
+          "type": "string",
+          "description": "'bar' (default) renders the fixed bottom tab bar with a \"More\" Drawer. 'sheet' renders no bar at all and puts every destination in a Sheet — opening at 60% and growing to full as you drag or scroll it up — which the host opens itself — use it when a top header can hold the trigger, since a fixed bar and a mobile browser's own toolbar stack into ~120px of lost screen."
+        },
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "Controlled drawer state. Required by 'sheet', which has no trigger of its own; ignored by 'bar'."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "function",
+          "description": "Fired when the sheet wants to close (backdrop, Escape, or an item tapped)."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "description": "Extra content rendered in the panel body after the destinations, scrolling with them. The mirror of drawerHeader; use it instead of drawerFooter when the content belongs with the list rather than pinned under it."
         }
       ],
       "importPath": "./components/navigation/MobileNav",
       "filePath": "src/components/navigation/MobileNav.tsx",
       "sku": "@molecule/nav/mobile-nav",
       "humanLabel": "MobileNav",
-      "humanDescription": "A fixed bottom tab bar for mobile screens, providing native-feeling navigation with primary icon+label tabs and a \"More\" drawer for secondary links. Hidden on md: and up via Tailwind. Designed as the mobile counterpart to the desktop Sidebar."
+      "humanDescription": "Mobile navigation, in two shapes. 'bar' is a fixed bottom tab bar with icon+label tabs and a \"More\" drawer for secondary links. 'sheet' drops the bar entirely and puts every destination in a bottom drawer the host opens from its own trigger — the right choice when a mobile browser's toolbar already owns the bottom edge. Hidden on md: and up via Tailwind. The mobile counterpart to the desktop Sidebar."
     },
     {
       "id": "pagination",
@@ -2982,6 +3198,26 @@ export const wizardManifest: WizardManifest = {
       "humanLabel": "AuthLayout",
       "humanDescription": "The centred, chrome-free frame for unauthenticated screens, rendering the matched child route via an Outlet. Strategic purpose: sign-in and sign-up must not show the app shell's sidebar or header — wrap those routes in this instead of conditionally hiding chrome inside AppShell."
     },
+    {
+      "id": "about-ramme",
+      "name": "AboutRamme",
+      "version": "1.0.0",
+      "description": "The \"About\" panel for a Settings Console — what the framework is, which packages make it up, and why it is built this way. Strategic purpose: ships the explanation with the framework so every product's about screen stays accurate as the architecture moves, instead of each one carrying a copy that goes stale. Takes no props; drop it into a settings tab.",
+      "tags": [
+        "layout",
+        "settings",
+        "about",
+        "documentation",
+        "panel"
+      ],
+      "category": "layout",
+      "props": [],
+      "importPath": "./components/layout/AboutRamme",
+      "filePath": "src/components/layout/AboutRamme.tsx",
+      "sku": "@chassis/layout/about-ramme",
+      "humanLabel": "AboutRamme",
+      "humanDescription": "The \"About\" panel for a Settings Console — what the framework is, which packages make it up, and why it is built this way. Strategic purpose: ships the explanation with the framework so every product's about screen stays accurate as the architecture moves, instead of each one carrying a copy that goes stale. Takes no props; drop it into a settings tab."
+    },
     {
       "id": "accordion-item",
       "name": "AccordionItem",
@@ -3911,6 +4147,69 @@ export const wizardManifest: WizardManifest = {
       "humanLabel": "SettingsContainer",
       "humanDescription": "The canonical settings page arrangement, with a fixed slot per section so every app's settings read the same way. Strategic purpose: settings sprawl fast — this pins the section order and navigation so General, AI Gateway, Theme Lab, and About always live in the same place."
     },
+    {
+      "id": "sheet",
+      "name": "Sheet",
+      "version": "1.0.0",
+      "description": "A bottom sheet that opens at a partial height and grows to full screen as you drag or scroll it up. Strategic purpose: the native-feeling surface for mobile navigation, settings and pickers — reachable by thumb, dismissed by flicking down. Use instead of Drawer when the surface is primarily touched.",
+      "tags": [
+        "layout",
+        "overlay",
+        "sheet",
+        "mobile",
+        "touch",
+        "drawer",
+        "ui"
+      ],
+      "category": "layout",
+      "props": [
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "Controls the open/closed state. Required."
+        },
+        {
+          "name": "onClose",
+          "type": "function",
+          "description": "Fired when the sheet requests dismissal (flick down, drag below the smallest detent, Escape, overlay tap, or the close button). Required."
+        },
+        {
+          "name": "detents",
+          "type": "Array<number>",
+          "description": "Resting heights as fractions of the viewport, ascending. Defaults to [0.6, 1] — opens at 60%, expands to full."
+        },
+        {
+          "name": "initialDetent",
+          "type": "number",
+          "description": "Index into detents to open at. Defaults to 0."
+        },
+        {
+          "name": "title",
+          "type": "string",
+          "description": "Optional title in the sticky header, beside the close button."
+        },
+        {
+          "name": "footer",
+          "type": "ReactNode",
+          "description": "Optional sticky footer, kept clear of the home indicator."
+        },
+        {
+          "name": "overlayDismiss",
+          "type": "boolean",
+          "description": "Tap the dimmed backdrop to close. Defaults to true."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Extra classes for the sheet panel."
+        }
+      ],
+      "importPath": "./components/layout/Sheet",
+      "filePath": "src/components/layout/Sheet.tsx",
+      "sku": "@chassis/layout/sheet",
+      "humanLabel": "Sheet",
+      "humanDescription": "A bottom sheet that opens at a partial height and grows to full screen as you drag or scroll it up. Strategic purpose: the native-feeling surface for mobile navigation, settings and pickers — reachable by thumb, dismissed by flicking down. Use instead of Drawer when the surface is primarily touched."
+    },
     {
       "id": "sidebar",
       "name": "Sidebar",
@@ -4126,6 +4425,52 @@ export const wizardManifest: WizardManifest = {
       "sku": "@chassis/layout/user-nav",
       "humanLabel": "UserNav",
       "humanDescription": "The signed-in user's avatar menu — identity plus account actions. Strategic purpose: the standard account affordance for the app shell's header, with logout, settings, profile, and an optional theme toggle already wired. Compose extra entries with ButtonItem rather than rebuilding the menu."
+    },
+    {
+      "id": "button-item",
+      "name": "ButtonItem",
+      "version": "1.0.0",
+      "description": "A single row inside a UserNav menu — icon, label, action. Strategic purpose: the sanctioned way to add an entry to the account menu, so extra actions match the built-in ones instead of arriving as a hand-styled button. Use `variant=\"destructive\"` for anything that removes or signs out.",
+      "tags": [
+        "layout",
+        "navigation",
+        "menu",
+        "item",
+        "user-nav"
+      ],
+      "category": "layout",
+      "props": [
+        {
+          "name": "icon",
+          "type": "string",
+          "description": "Lucide icon name shown before the label."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "description": "The menu entry text."
+        },
+        {
+          "name": "onClick",
+          "type": "function",
+          "description": "Called when the entry is activated."
+        },
+        {
+          "name": "variant",
+          "type": "string",
+          "description": "'default' | 'destructive'. Destructive tints the row for sign-out and delete."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Additional CSS classes."
+        }
+      ],
+      "importPath": "./components/layout/UserNav",
+      "filePath": "src/components/layout/UserNav.tsx",
+      "sku": "@chassis/layout/button-item",
+      "humanLabel": "ButtonItem",
+      "humanDescription": "A single row inside a UserNav menu — icon, label, action. Strategic purpose: the sanctioned way to add an entry to the account menu, so extra actions match the built-in ones instead of arriving as a hand-styled button. Use `variant=\"destructive\"` for anything that removes or signs out."
     }
   ],
   "utils": [],

package/tailwind.preset.js

@@ -71,6 +71,14 @@ module.exports = {
         },
 
         // ─── Specialized Sub-Systems ───
+        // Categorical accents for colour-coded content. Distinct from `chart`:
+        // chart series collapse to one hue under a custom theme (see
+        // themeUtils.ts), these stay four hues on all five themes.
+        'accent-1': 'rgb(var(--app-accent-1) / <alpha-value>)',
+        'accent-2': 'rgb(var(--app-accent-2) / <alpha-value>)',
+        'accent-3': 'rgb(var(--app-accent-3) / <alpha-value>)',
+        'accent-4': 'rgb(var(--app-accent-4) / <alpha-value>)',
+
         chart: {
           1: 'rgb(var(--app-chart-1) / <alpha-value>)',
           2: 'rgb(var(--app-chart-2) / <alpha-value>)',
@@ -105,17 +113,97 @@ module.exports = {
         mono: ['var(--app-font-mono)', 'Menlo', 'monospace'],
       },
 
-      // ─── Fluid Typography Scale (clamp) ───────────────
-      // Scales smoothly between 320px and 1280px viewport.
-      // Usage: text-fluid-xs, text-fluid-sm, text-fluid-base, etc.
+      // ─── Fluid Typography Scale ───────────────────────
+      // The values live in framework/ui/src/index.css as --app-step-*, generated
+      // with the Utopia method (utopia.fyi/type/calculator) and fluid between a
+      // 360px and a 1240px viewport. They are referenced here rather than inlined
+      // for the same reason borderRadius is: a CSS variable can be re-pointed per
+      // theme (.dark/.corporate/.midnight/.blueprint) and adjusted at runtime
+      // through useTheme, which a literal in this file cannot.
+      //
+      // These REPLACE Tailwind's static defaults, so every existing text-sm /
+      // text-2xl / … call site becomes fluid with no edit. Each entry is a
+      // [size, { lineHeight, letterSpacing }] tuple — Tailwind's own scale pairs a
+      // line-height with every size, and dropping to a bare string (as the old
+      // fluid-* keys did) silently inherits whatever leading is in scope.
       fontSize: {
-        'fluid-xs':   'clamp(0.625rem, 0.55rem + 0.25vw, 0.75rem)',    // 10px → 12px
-        'fluid-sm':   'clamp(0.75rem, 0.65rem + 0.33vw, 0.875rem)',    // 12px → 14px
-        'fluid-base': 'clamp(0.875rem, 0.75rem + 0.42vw, 1rem)',       // 14px → 16px
-        'fluid-lg':   'clamp(1rem, 0.83rem + 0.56vw, 1.25rem)',        // 16px → 20px
-        'fluid-xl':   'clamp(1.25rem, 1rem + 0.83vw, 1.5rem)',         // 20px → 24px
-        'fluid-2xl':  'clamp(1.5rem, 1.17rem + 1.11vw, 2rem)',         // 24px → 32px
-        'fluid-3xl':  'clamp(2rem, 1.5rem + 1.67vw, 2.75rem)',         // 32px → 44px
+        '2xs':  ['var(--app-step--3)',  { lineHeight: 'var(--app-leading-base)' }],
+        xs:     ['var(--app-step--2)',  { lineHeight: 'var(--app-leading-base)' }],
+        sm:     ['var(--app-step--1)',  { lineHeight: 'var(--app-leading-relaxed)' }],
+        base:   ['var(--app-step-0)',   { lineHeight: 'var(--app-leading-relaxed)' }],
+        lg:     ['var(--app-step-1)',   { lineHeight: 'var(--app-leading-relaxed)' }],
+        xl:     ['var(--app-step-2)',   { lineHeight: 'var(--app-leading-snug)' }],
+        '2xl':  ['var(--app-step-3)',   { lineHeight: 'var(--app-leading-snug)' }],
+        '3xl':  ['var(--app-step-4)',   { lineHeight: 'var(--app-leading-snug)' }],
+        '4xl':  ['var(--app-step-5)',   { lineHeight: 'var(--app-leading-tight)' }],
+        '5xl':  ['var(--app-step-6)',   { lineHeight: 'var(--app-leading-tight)' }],
+        '6xl':  ['var(--app-step-7)',   { lineHeight: 'var(--app-leading-tight)' }],
+        '7xl':  ['var(--app-step-8)',   { lineHeight: 'var(--app-leading-none)' }],
+        '8xl':  ['var(--app-step-9)',   { lineHeight: 'var(--app-leading-none)' }],
+        '9xl':  ['var(--app-step-10)',  { lineHeight: 'var(--app-leading-none)' }],
+
+        // Back-compat aliases. text-fluid-* predates this scale and is still used
+        // in Card, ActivityFeed and MobileNav; they now resolve to the same steps
+        // as their plain counterparts. Prefer the plain names in new code.
+        'fluid-xs':   ['var(--app-step--2)', { lineHeight: 'var(--app-leading-base)' }],
+        'fluid-sm':   ['var(--app-step--1)', { lineHeight: 'var(--app-leading-relaxed)' }],
+        'fluid-base': ['var(--app-step-0)',  { lineHeight: 'var(--app-leading-relaxed)' }],
+        'fluid-lg':   ['var(--app-step-1)',  { lineHeight: 'var(--app-leading-relaxed)' }],
+        'fluid-xl':   ['var(--app-step-2)',  { lineHeight: 'var(--app-leading-snug)' }],
+        'fluid-2xl':  ['var(--app-step-3)',  { lineHeight: 'var(--app-leading-snug)' }],
+        'fluid-3xl':  ['var(--app-step-4)',  { lineHeight: 'var(--app-leading-snug)' }],
+      },
+
+      // ─── Leading ──────────────────────────────────────
+      // Unitless, so they multiply whichever step they land on.
+      lineHeight: {
+        none:    'var(--app-leading-none)',
+        tight:   'var(--app-leading-tight)',
+        snug:    'var(--app-leading-snug)',
+        normal:  'var(--app-leading-base)',
+        relaxed: 'var(--app-leading-relaxed)',
+      },
+
+      // ─── Tracking ─────────────────────────────────────
+      // Replaces the hand-written tracking-[0.12em..0.3em] arbitrary values.
+      letterSpacing: {
+        tighter: 'var(--app-tracking-tighter)',
+        tight:   'var(--app-tracking-tight)',
+        normal:  'var(--app-tracking-normal)',
+        wide:    'var(--app-tracking-wide)',
+        wider:   'var(--app-tracking-wider)',
+        widest:  'var(--app-tracking-widest)',
+      },
+
+      // ─── Readable measure ─────────────────────────────
+      // ch-based, so line length tracks font size. max-w-prose is rem-based and
+      // drifts off a comfortable measure as soon as the base size changes.
+      maxWidth: {
+        measure:          'var(--app-measure)',
+        'measure-narrow': 'var(--app-measure-narrow)',
+      },
+
+      // ─── Layering Scale ───────────────────────────────
+      // One named order for everything that overlays, because "z-50" was the
+      // only overlay layer this framework had: Modal, Drawer, DetailDrawer,
+      // ToastProvider, Menu, UserNav, Sidebar and AIChatPanel all sat on it,
+      // so which one won was decided by portal mount order rather than intent.
+      // A toast confirming what you just did could land behind the modal you
+      // did it in.
+      //
+      // Read it top to bottom — each layer must clear the one above it in this
+      // list. Use the name, never a bare number, so the order stays arguable in
+      // one place instead of in eleven files.
+      zIndex: {
+        raised:  '10',   // lifted within its own pane — cards, in-flow overlays
+        sticky:  '20',   // sticky headers and toolbars inside a scroll region
+        nav:     '30',   // app chrome that outranks sticky page content
+        fab:     '40',   // floating action buttons over the page
+        scrim:   '45',   // a backdrop, under its own panel but over the app
+        drawer:  '50',   // drawers, modals, full-screen surfaces and overlays
+        popover: '60',   // menus, dropdowns, tooltips — must clear a drawer
+                         // they were opened from
+        toast:   '70',   // notifications — must clear everything, always
       },
 
       // ─── Fluid Spacing Scale (clamp) ──────────────────