@12-apps/ui 6.17.0 → 6.18.0

package/dist/types-native/tokens/vocabulary.d.ts

@@ -0,0 +1,117 @@
+/**
+ * THE TWO VOCABULARIES EVERY COMPONENT SPEAKS.
+ *
+ * Before this file the package had both halves of every argument at once: 26
+ * components sized themselves `xs|sm|md|lg|xl` and four used MUI's
+ * `small|medium|large`; 14 coloured themselves `danger|neutral` and 15 used
+ * MUI's `error`. Nothing enforced either, because most of these props were
+ * spelled out as inline unions and a couple were plain `string`.
+ *
+ * That is not a tidiness problem. A caller learns the vocabulary from whichever
+ * component they used first, and the wrong half is not rejected — it reaches MUI
+ * as an unknown value and silently falls back. `Chip` shipped with `color?:
+ * string` and MUI's `small|medium`, so `color="danger"` rendered grey and
+ * `size="sm"` rendered medium; twelve live call sites were doing exactly that,
+ * and every test passed because they all asserted on text.
+ *
+ * So the vocabulary is declared once, here, and components derive from it.
+ *
+ * DERIVE, DON'T COPY — AND TAKE THE WHOLE VOCABULARY. Every size prop is
+ * `SizeValue` and every colour prop is `ColorValue`, with no `Extract` and no
+ * `Exclude`. Handing a component a slice was tried and undone: it is the same
+ * fragmentation wearing the canonical type's name, and it leaves a caller having
+ * to remember which components accept `xs` and which accept `info`. Where the
+ * underlying widget draws fewer steps than five, that is a rendering detail and
+ * belongs at the MUI boundary below — not in the prop's type.
+ *
+ * A component whose size or colour is not this concept at all keeps its own type
+ * — `Scrollbar`'s `thin|medium|thick` is a track width, `Sheet`'s `full` is a
+ * viewport fraction, `LazyImage`'s size is pixels. Forcing those into the scale
+ * would be consistency for its own sake.
+ */
+/**
+ * The house size scale.
+ *
+ * Abbreviated, because that is what 26 of the 30 components with a real size
+ * already used and what every caller has been taught to write.
+ *
+ * Declared as the array and the type together so the two cannot disagree. The
+ * runtime list is what Storybook `argTypes.options` and the demo grids iterate;
+ * spelled by hand in each story it drifts, and it had — twelve colour lists
+ * omitted `info`, so the control that documents the vocabulary offered a
+ * component less than the component accepted.
+ */
+/**
+ * The type scale is the THIRD vocabulary, and it lives in `./typography.ts`
+ * because it is metrics rather than a prop union. Re-exported here so
+ * `@12-apps/ui/tokens` stays the one import path for "what words does this
+ * package speak" — a second entry point is how a vocabulary gets missed.
+ */
+export { HEADING_LEVELS, HEADING_SCALE, type HeadingLevel, type HeadingMetrics, type HeadingScaleOverrides, } from './heading-scale';
+export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export declare const SIZE_VALUES: readonly ["xs", "sm", "md", "lg", "xl"];
+/**
+ * The house colour vocabulary.
+ *
+ * `danger` and `neutral` are OURS; the rest are MUI's own names already. That
+ * sentence started life in `Button.tsx`, which is the component most callers
+ * meet first and therefore the one that taught the vocabulary — so it is the one
+ * the rest of the package follows.
+ *
+ * Components that hand these to MUI translate at the boundary (`danger` →
+ * `error`, `neutral` → `default` or `inherit` depending on what the underlying
+ * component calls its unaccented state). The translation must be a real mapping
+ * and never a cast: a cast is precisely what let `danger` through untouched and
+ * had MUI fall back to grey.
+ *
+ * Array and type declared together, for the reason given on {@link SIZE_VALUES}.
+ */
+export type ColorValue = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'danger' | 'neutral';
+export declare const COLOR_VALUES: readonly ["primary", "secondary", "success", "warning", "info", "danger", "neutral"];
+/** What MUI calls a size. Three entries against our five. */
+export type MuiSize = 'small' | 'medium' | 'large';
+/**
+ * The house scale collapsed onto MUI's three.
+ *
+ * Five onto three loses information, and it loses it at the ends on purpose:
+ * `xs`/`sm` both draw small and `lg`/`xl` both draw large, because MUI has no
+ * fourth and fifth step to give them. A component that genuinely needs five
+ * distinct sizes styles them itself rather than routing through here — this is
+ * for the ones that just forward the prop.
+ */
+export declare const muiSize: (size: SizeValue) => MuiSize;
+/** What MUI calls a semantic colour on most components. */
+export type MuiColor = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'error';
+/**
+ * The house vocabulary translated for MUI, with the caller naming its neutral.
+ *
+ * `neutral` is the awkward one: MUI spells the unaccented state `default` on a
+ * chip, `inherit` on a button and an icon button, and `grey` in the palette. So
+ * the caller passes the word its own MUI component uses rather than this
+ * pretending there is one answer.
+ *
+ * A MAPPING, NEVER A CAST. The cast is what let `danger` reach MUI untouched and
+ * silently fall back to grey.
+ */
+export declare function muiColor<N extends string>(color: ColorValue, neutralAs: N): MuiColor | N;
+/**
+ * The house vocabulary as a `theme.palette` key.
+ *
+ * Separate from {@link muiColor} because the palette has no `default` and no
+ * `inherit` — an unaccented colour there is `grey`.
+ */
+export type PaletteKey = MuiColor | 'grey';
+export declare const paletteKey: (color: ColorValue) => PaletteKey;
+/**
+ * A `ColorValue` resolved to a four-stop accent from the theme.
+ *
+ * `paletteKey` is not enough on its own for anything that reads `.main`: MUI's
+ * palette has no neutral `PaletteColor`, and `palette.grey` is a 50–900 ramp
+ * with no `main`, `light`, `dark` or `contrastText` on it at all. So `neutral`
+ * is resolved from the ramp here, once, instead of every component discovering
+ * the same hole and branching around it.
+ *
+ * Typed against the theme structurally so this file does not drag in MUI's
+ * `Theme` and become a dependency of everything that imports a token.
+ */
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/types-native/tokens/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../../src/tokens/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;GAWG;AACH;;;;;GAKG;AACH,OAAO,EACL,cAAc,EACd,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD,eAAO,MAAM,WAAW,yCAAyE,CAAC;AAElG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,eAAO,MAAM,YAAY,sFAQiB,CAAC;AAmC3C,6DAA6D;AAC7D,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,SAAS,KAAG,OAGzC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1F;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,GAAG,QAAQ,GAAG,CAAC,CAGxF;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C,eAAO,MAAM,UAAU,GAAI,OAAO,UAAU,KAAG,UACsB,CAAC;AAEtE;;;;;;;;;;;GAWG"}

package/dist/typography/Heading.js

@@ -1,9 +1,10 @@
 import "../chunk-6GP2DOOO.js";
 import {
   Heading
-} from "../chunk-HQJ75HHI.js";
-import "../chunk-QCIWROKG.js";
-import "../chunk-7CA6GVBO.js";
+} from "../chunk-NYLXHOMR.js";
+import "../chunk-CGQI4XE5.js";
+import "../chunk-PT6TCWIW.js";
+import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";
 export {
   Heading

package/dist/typography/Text.js

@@ -1,7 +1,13 @@
 import "../chunk-VUHLNYAE.js";
 import {
   Text
-} from "../chunk-VRHBJXZ7.js";
+} from "../chunk-2PCOC3PT.js";
+import "../chunk-V3PLFYKO.js";
+import "../chunk-QLWBQQW7.js";
+import "../chunk-NQN5Z36J.js";
+import "../chunk-AG66JBNH.js";
+import "../chunk-6JAIFIPW.js";
+import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";
 export {
   Text

package/dist/user-avatar.js

@@ -1,7 +1,7 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-DQIQKIEA.js";
+} from "./chunk-L5ZZJ4XE.js";
 import "./chunk-UDQSIRAP.js";
 import "./chunk-QIV73V2X.js";
 import "./chunk-LYNJJV2X.js";
@@ -12,10 +12,17 @@ import "./chunk-D2IASECY.js";
 import "./chunk-VMF3UXM4.js";
 import "./chunk-RI5JZLZL.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-IAQFQNBL.js";
-import "./chunk-AUYC5K5K.js";
-import "./chunk-NYUGX76C.js";
-import "./chunk-VRHBJXZ7.js";
+import "./chunk-24BUCMQA.js";
+import "./chunk-JT6TERQL.js";
+import "./chunk-ITGG5OKP.js";
+import "./chunk-TAMIZE4Q.js";
+import "./chunk-2PCOC3PT.js";
+import "./chunk-V3PLFYKO.js";
+import "./chunk-QLWBQQW7.js";
+import "./chunk-NQN5Z36J.js";
+import "./chunk-AG66JBNH.js";
+import "./chunk-6JAIFIPW.js";
+import "./chunk-FZXKH2ZT.js";
 import "./chunk-PZ5AY32C.js";
 export {
   UserAvatar,

package/dist/utility/InstallPrompt.js

@@ -1,11 +1,11 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-5ZOJLYD2.js";
-import "../chunk-GY62N32G.js";
+} from "../chunk-JE6RZ5L6.js";
 import {
   usePwaInstall
 } from "../chunk-5GMHJ7Y5.js";
+import "../chunk-GY62N32G.js";
 import "../chunk-WXYLH3QZ.js";
 import {
   PWA_INSTALL_AVAILABLE_EVENT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.17.0",
+  "version": "6.18.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -41,6 +41,10 @@
       "default": "./dist/utils.js"
     },
     "./tokens": {
+      "react-native": {
+        "types": "./dist/types-native/tokens/index.native.d.ts",
+        "default": "./dist/native/tokens.js"
+      },
       "types": "./dist/types/tokens/scales.d.ts",
       "default": "./dist/tokens.js"
     },
@@ -48,6 +52,22 @@
       "types": "./dist/types/tokens/layers.d.ts",
       "default": "./dist/tokens/layers.js"
     },
+    "./provider": {
+      "react-native": {
+        "types": "./dist/types-native/provider/index.native.d.ts",
+        "default": "./dist/native/provider.js"
+      },
+      "types": "./dist/types/provider/index.d.ts",
+      "default": "./dist/provider.js"
+    },
+    "./icons": {
+      "react-native": {
+        "types": "./dist/types-native/icons/index.native.d.ts",
+        "default": "./dist/native/icons.js"
+      },
+      "types": "./dist/types/icons/index.d.ts",
+      "default": "./dist/icons.js"
+    },
     "./mui/Box": {
       "types": "./dist/types/mui/Box.d.ts",
       "default": "./dist/mui/Box.js"
@@ -273,6 +293,10 @@
       "default": "./dist/form/Autocomplete.js"
     },
     "./form/Button": {
+      "react-native": {
+        "types": "./dist/types-native/components/form/Button/index.native.d.ts",
+        "default": "./dist/native/form/Button.js"
+      },
       "types": "./dist/types/components/form/Button/index.d.ts",
       "default": "./dist/form/Button.js"
     },
@@ -392,6 +416,14 @@
       "types": "./dist/types/components/layout/Accordion/index.d.ts",
       "default": "./dist/layout/Accordion.js"
     },
+    "./layout/Box": {
+      "react-native": {
+        "types": "./dist/types-native/components/layout/Box/index.native.d.ts",
+        "default": "./dist/native/layout/Box.js"
+      },
+      "types": "./dist/types/components/layout/Box/index.d.ts",
+      "default": "./dist/layout/Box.js"
+    },
     "./layout/Card": {
       "types": "./dist/types/components/layout/Card/index.d.ts",
       "default": "./dist/layout/Card.js"
@@ -448,6 +480,14 @@
       "types": "./dist/types/components/layout/Spacer/index.d.ts",
       "default": "./dist/layout/Spacer.js"
     },
+    "./layout/Stack": {
+      "react-native": {
+        "types": "./dist/types-native/components/layout/Stack/index.native.d.ts",
+        "default": "./dist/native/layout/Stack.js"
+      },
+      "types": "./dist/types/components/layout/Stack/index.d.ts",
+      "default": "./dist/layout/Stack.js"
+    },
     "./layout/TableFilter": {
       "types": "./dist/types/components/layout/TableFilter/index.d.ts",
       "default": "./dist/layout/TableFilter.js"
@@ -501,6 +541,10 @@
       "default": "./dist/typography/Paragraph.js"
     },
     "./typography/Text": {
+      "react-native": {
+        "types": "./dist/types-native/components/typography/Text/index.native.d.ts",
+        "default": "./dist/native/typography/Text.js"
+      },
       "types": "./dist/types/components/typography/Text/index.d.ts",
       "default": "./dist/typography/Text.js"
     },
@@ -595,11 +639,11 @@
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "dev": "storybook dev -p 6006",
-    "build": "tsup && pnpm build:types && pnpm exports:check",
+    "build": "tsup && tsup --config tsup.native.config.ts && pnpm build:types && pnpm build:types:native && pnpm exports:check",
     "build:types": "tsc --emitDeclarationOnly --outDir dist/types",
     "exports:sync": "node scripts/sync-exports.mjs",
     "exports:check": "node scripts/sync-exports.mjs --check",
-    "clean": "rm -rf dist storybook-static",
+    "clean": "rm -rf dist storybook-static storybook-native-static coverage-native",
     "storybook:build": "storybook build",
     "storybook:serve": "http-server storybook-static -p 6008 --silent",
     "storybook:test": "test-storybook --maxWorkers=4 --url http://localhost:6008",
@@ -611,12 +655,27 @@
     "lint:files": "bash -c 'eslint \"${@:-.}\" --max-warnings 0' _",
     "lint": "pnpm run lint:files .",
     "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
-    "typecheck": "tsc --noEmit",
-    "check-types": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.native.json --noEmit && tsc -p tsconfig.native.test.json",
+    "check-types": "tsc --noEmit && tsc -p tsconfig.native.json --noEmit && tsc -p tsconfig.native.test.json",
+    "build:types:native": "tsc -p tsconfig.native.json",
+    "build:native": "tsup --config tsup.native.config.ts && pnpm build:types:native",
+    "test:native": "node ../../scripts/vitest-with-teardown.mjs run --config vitest.native.config.ts",
+    "test:native:watch": "vitest --config vitest.native.config.ts",
+    "storybook:native": "storybook dev -p 6007 -c .storybook-native",
+    "storybook:native:build": "storybook build -c .storybook-native -o storybook-native-static",
+    "storybook:native:serve": "http-server storybook-native-static -p 6009 --silent",
+    "storybook:native:test": "test-storybook --maxWorkers=4 --url http://localhost:6009 --config-dir .storybook-native",
+    "test:native:ci": "pnpm storybook:native:build && (concurrently -k -s first -n 'serve,test' -c 'bgBlue.bold,bgGreen.bold' 'pnpm storybook:native:serve' 'pnpm storybook:native:test')",
+    "icons:generate": "node scripts/generate-icon-paths.mjs",
+    "icons:check": "node scripts/generate-icon-paths.mjs --check",
+    "native:ledger": "node scripts/native-parity.mjs",
+    "native:check": "node scripts/native-parity.mjs --check && pnpm icons:check"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-native": ">=0.79.0",
+    "react-native-svg": ">=15.0.0"
   },
   "dependencies": {
     "@12-apps/forms-core": "^1.21.0",
@@ -641,6 +700,7 @@
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",
     "@storybook/builder-vite": "^9.1.10",
+    "@storybook/react-native-web-vite": "9.1.20",
     "@storybook/react-vite": "^9.1.10",
     "@storybook/test-runner": "^0.23.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -661,6 +721,9 @@
     "playwright": "^1.56.1",
     "react": "19.2.0",
     "react-dom": "19.2.0",
+    "react-native": "0.83.1",
+    "react-native-svg": "15.15.5",
+    "react-native-web": "0.20.0",
     "start-server-and-test": "^2.1.2",
     "storybook": "^9.1.10",
     "tsup": "^8.0.0",
@@ -686,6 +749,7 @@
     "*.mjs",
     "*.md",
     "!eslint.config.js",
+    "!test-runner-jest.config.cjs",
     "!**/__tests__/**",
     "!**/tests/**",
     "!**/*.test.*",
@@ -693,5 +757,13 @@
     "!**/*.stories.*",
     "!**/*.test-story.*",
     "!**/test-helpers.*"
-  ]
+  ],
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  }
 }

package/src/components/form/Button/Button.base.ts

@@ -0,0 +1,80 @@
+import type * as React from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * This file imports no MUI and no react-native, on purpose: it is in BOTH
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against.
+ */
+export type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'text' | 'glass' | 'gradient';
+
+/**
+ * The contract both renderers honour. Handlers are NOT here: their names are
+ * the same on both sides (`onClick`, `onFocus`, `onBlur`) but their event types
+ * are the renderer's own, so each side declares them beside its own extras.
+ */
+export interface ButtonBaseProps {
+  /**
+   * The variant of the button
+   */
+  variant?: ButtonVariant;
+
+  /**
+   * The color of the button
+   */
+  color?: ColorValue;
+
+  /**
+   * The size of the button
+   */
+  size?: SizeValue;
+
+  /**
+   * Whether the button is in loading state
+   */
+  loading?: boolean;
+
+  /**
+   * Icon to display in the button
+   */
+  icon?: React.ReactNode;
+
+  /**
+   * Position of the icon
+   */
+  iconPosition?: 'left' | 'right';
+
+  /**
+   * Whether the button should have a glow effect
+   */
+  glow?: boolean;
+
+  /**
+   * Whether the button should have a pulse animation
+   */
+  pulse?: boolean;
+
+  /**
+   * Whether to show ripple effect on click
+   */
+  ripple?: boolean;
+
+  /**
+   * Whether the button is in active state
+   */
+  active?: boolean;
+
+  disabled?: boolean;
+
+  children?: React.ReactNode;
+
+  /**
+   * Test ID for testing purposes
+   */
+  dataTestId?: string;
+
+  testID?: string;
+}

package/src/components/form/Button/Button.helpers.ts

@@ -1,4 +1,4 @@
-import type { ButtonProps } from './Button.types';
+import type { ButtonBaseProps } from './Button.base';
 
 type ButtonDefaultedKeys =
   | 'variant'
@@ -11,9 +11,14 @@ type ButtonDefaultedKeys =
   | 'ripple'
   | 'active';
 
-type ResolvedButtonProps = ButtonProps & Required<Pick<ButtonProps, ButtonDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props: the web and the native `Button` pass
+ * different handler types through, and both come back out untouched.
+ */
+type ResolvedButtonProps<P extends ButtonBaseProps> = P &
+  Required<Pick<ButtonBaseProps, ButtonDefaultedKeys>>;
 
-const BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {
+const BUTTON_DEFAULTS: Required<Pick<ButtonBaseProps, ButtonDefaultedKeys>> = {
   variant: 'solid',
   color: 'primary',
   size: 'md',
@@ -27,10 +32,10 @@ const BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {
 
 // Strips explicitly-undefined props before the merge, so `size={undefined}` still
 // falls back to the default exactly as a destructuring default would.
-const definedProps = (props: ButtonProps): Partial<ButtonProps> =>
+const definedProps = <P extends ButtonBaseProps>(props: P): Partial<P> =>
   Object.fromEntries(
     Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<ButtonProps>;
+  ) as Partial<P>;
 
-export const resolveButtonProps = (props: ButtonProps): ResolvedButtonProps =>
-  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps;
+export const resolveButtonProps = <P extends ButtonBaseProps>(props: P): ResolvedButtonProps<P> =>
+  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps<P>;

package/src/components/form/Button/Button.metrics.ts

@@ -0,0 +1,101 @@
+import { darken, lighten } from '../../../tokens/color';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `Button` RENDERERS DRAW WITH.
+ *
+ * `Button.styles.ts` (web, emotion) and `Button.native.tsx` (React Native)
+ * read this one table. The web turns the px into rem and the padding into a
+ * shorthand string; native uses the numbers as they are. Neither restates a
+ * value, which is what keeps a native `md` button 16px tall of padding and
+ * 16px of type exactly like the web one.
+ */
+export interface ButtonSizeMetrics {
+  paddingVertical: number;
+  paddingHorizontal: number;
+  fontSize: number;
+}
+
+export const BUTTON_SIZES: Record<SizeValue, ButtonSizeMetrics> = {
+  xs: { paddingVertical: 2, paddingHorizontal: 8, fontSize: 12 },
+  sm: { paddingVertical: 6, paddingHorizontal: 12, fontSize: 14 },
+  md: { paddingVertical: 8, paddingHorizontal: 16, fontSize: 16 },
+  lg: { paddingVertical: 10, paddingHorizontal: 20, fontSize: 18 },
+  xl: { paddingVertical: 12, paddingHorizontal: 24, fontSize: 20 },
+};
+
+/** A button that is only an icon is square: uniform padding, no min-width. */
+export const ICON_ONLY_PADDING: Record<SizeValue, number> = {
+  xs: 2,
+  sm: 5,
+  md: 7,
+  lg: 9,
+  xl: 11,
+};
+
+export const BUTTON_FONT_WEIGHT = 500;
+/** `theme.spacing(1)`. */
+export const BUTTON_RADIUS_UNITS = 1;
+/** Between the icon and the label: `theme.spacing(0.5)`. */
+export const BUTTON_ICON_GAP_UNITS = 0.5;
+export const BUTTON_SPINNER_SIZE = 16;
+/** MUI's `line-height` for button text. */
+export const BUTTON_LINE_HEIGHT = 1.75;
+
+/** The wash behind an outline, ghost or text button while it is hovered or pressed. */
+export const BUTTON_WASH_ALPHA = 0.1;
+export const GLASS_BACKGROUND_ALPHA = 0.1;
+export const GLASS_BACKGROUND_ALPHA_PRESSED = 0.2;
+export const GLASS_BORDER_ALPHA = 0.2;
+export const GLOW_INNER_ALPHA = 0.6;
+export const GLOW_OUTER_ALPHA = 0.3;
+export const GLOW_RADIUS = 20;
+export const PULSE_ALPHA = 0.3;
+export const PULSE_DURATION_MS = 2000;
+export const PULSE_SPREAD = 15;
+
+/**
+ * `neutral` has no palette slot of its own in MUI, so `Button.styles.ts` has
+ * always drawn it from three greys. Same three greys here.
+ */
+export function buttonPalette(theme: UiTheme, color: ColorValue): UiPaletteColor {
+  if (color === 'neutral') {
+    return {
+      main: theme.palette.grey[700],
+      dark: theme.palette.grey[800],
+      light: theme.palette.grey[500],
+      contrastText: '#fff',
+    };
+  }
+  return theme.palette[color];
+}
+
+/**
+ * The label colour for `ghost` and `text`: one step darker than `main` in
+ * light mode (lighter in dark), because `main` is chosen to sit UNDER white and
+ * is not legible AS text on a tinted surface. See the web `quietInk`.
+ */
+export const quietInk = (theme: UiTheme, palette: UiPaletteColor): string =>
+  theme.mode === 'dark' ? lighten(palette.main, 0.35) : darken(palette.main, 0.3);
+
+/** Gradients run between two related hues; the named colours pick a specific pair. */
+export function gradientStops(
+  theme: UiTheme,
+  color: ColorValue,
+  palette: UiPaletteColor,
+): [string, string] {
+  switch (color) {
+    case 'primary':
+      return [theme.palette.primary.main, theme.palette.secondary.main];
+    case 'secondary':
+      return [theme.palette.secondary.main, theme.palette.primary.main];
+    case 'success':
+    case 'warning':
+      return [theme.palette[color].light, theme.palette[color].dark];
+    case 'danger':
+      return [theme.palette.danger.light, theme.palette.danger.dark];
+    default:
+      return [palette.main, palette.dark];
+  }
+}