@12-apps/ui 6.33.1 → 6.34.0

package/src/components/utility/AnimatedIcon/AnimatedIcon.styles.ts

@@ -22,6 +22,7 @@ import {
   wobbleAnimation,
 } from './AnimatedIcon.animations';
 import type { AnimationSize, AnimationVariant } from './AnimatedIcon.types';
+import { neutralTones, shadowInk, sheen } from '../../../tokens/ink';
 
 export const sizeConfigs: Record<AnimationSize, { size: number; fontSize: number }> = {
   xs: { size: 12, fontSize: 10 },
@@ -70,10 +71,10 @@ const animationFor = (
 };
 
 const SHADOWS: Record<string, (theme: Theme) => string> = {
-  soft: (theme) => `0 4px 20px ${alpha(theme.palette.common.black, 0.15)}`,
-  hard: (theme) => `4px 4px 0px ${alpha(theme.palette.common.black, 0.25)}`,
+  soft: (theme) => `0 4px 20px ${shadowInk(theme, 0.15)}`,
+  hard: (theme) => `4px 4px 0px ${shadowInk(theme, 0.25)}`,
   elevated: (theme) =>
-    `0 10px 40px ${alpha(theme.palette.common.black, 0.2)}, 0 2px 10px ${alpha(theme.palette.common.black, 0.1)}`,
+    `0 10px 40px ${shadowInk(theme, 0.2)}, 0 2px 10px ${shadowInk(theme, 0.1)}`,
 };
 
 export interface IconStyleFlags {
@@ -113,20 +114,20 @@ const effectStyles = (
       background: `linear-gradient(135deg, ${alpha(theme.palette.background.paper, 0.2)}, ${alpha(theme.palette.background.paper, 0.1)})`,
       backdropFilter: 'blur(10px)',
       border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
-      boxShadow: `inset 0 1px 1px ${alpha(theme.palette.common.white, 0.3)}, 0 8px 32px ${alpha(theme.palette.common.black, 0.1)}`,
+      boxShadow: `inset 0 1px 1px ${sheen(theme, 0.3)}, 0 8px 32px ${shadowInk(theme, 0.1)}`,
     }),
     ...($metallic && {
       background: `linear-gradient(145deg,
-      ${theme.palette.grey[300]} 0%,
-      ${theme.palette.grey[500]} 25%,
-      ${theme.palette.grey[400]} 50%,
-      ${theme.palette.grey[600]} 75%,
-      ${theme.palette.grey[400]} 100%)`,
+      ${neutralTones(theme).track} 0%,
+      ${neutralTones(theme).muted} 25%,
+      ${neutralTones(theme).subtle} 50%,
+      ${neutralTones(theme).emphasis} 75%,
+      ${neutralTones(theme).subtle} 100%)`,
       backgroundSize: '200% 200%',
       animation: `${animation}, ${breatheAnimation} 4s ease-in-out infinite`,
-      boxShadow: `inset 0 2px 4px ${alpha(theme.palette.common.white, 0.5)},
-                inset 0 -2px 4px ${alpha(theme.palette.common.black, 0.3)},
-                0 4px 8px ${alpha(theme.palette.common.black, 0.2)}`,
+      boxShadow: `inset 0 2px 4px ${sheen(theme, 0.5)},
+                inset 0 -2px 4px ${shadowInk(theme, 0.3)},
+                0 4px 8px ${shadowInk(theme, 0.2)}`,
     }),
     ...($gradient && {
       background: `linear-gradient(135deg,

package/src/components/utility/WorkflowStep/WorkflowStep.helpers.ts

@@ -1,6 +1,7 @@
 import type { Theme } from '@mui/material/styles/index.js';
 
 import type { WorkflowStepItem, WorkflowStepProps } from './WorkflowStep.types';
+import { neutralTones } from '../../../tokens/ink';
 
 type StepColor = NonNullable<WorkflowStepProps['color']>;
 type StepSize = NonNullable<WorkflowStepProps['size']>;
@@ -24,9 +25,10 @@ interface StepPalette {
 /** `neutral` has no MUI palette entry, so its pair is derived from grey. */
 export const stepPalette = (theme: Theme, color?: StepColor): StepPalette => {
   if (color === 'neutral') {
+    const main = neutralTones(theme).emphasis;
     return {
-      main: theme.palette.grey[600],
-      contrastText: theme.palette.getContrastText(theme.palette.grey[600]),
+      main,
+      contrastText: theme.palette.getContrastText(main),
     };
   }
 
@@ -83,8 +85,8 @@ export const stepColors = (
   }
 
   return {
-    backgroundColor: theme.palette.grey[300],
-    borderColor: theme.palette.grey[300],
+    backgroundColor: neutralTones(theme).track,
+    borderColor: neutralTones(theme).track,
     textColor: theme.palette.text.secondary,
   };
 };

package/src/components/utility/WorkflowStep/WorkflowStep.parts.tsx

@@ -11,6 +11,7 @@ import type {
   StepIndicatorProps,
   WorkflowStepProps,
 } from './WorkflowStep.types';
+import { neutralTones } from '../../../tokens/ink';
 
 // `outlined` shows the surface through a coloured rim; the other three fill it and
 // differ only in what border they keep.
@@ -167,9 +168,9 @@ const StepConnector = styled(Box, {
 }>(({ theme, orientation, isCompleted, color, variant }) => {
   const colorKey = color || 'primary';
   const colorValue = colorKey === 'neutral' 
-    ? { main: theme.palette.grey[600] }
+    ? { main: neutralTones(theme).emphasis }
     : theme.palette[colorKey as 'primary' | 'secondary' | 'success' | 'warning' | 'error'];
-  const connectorColor = isCompleted ? colorValue.main : theme.palette.grey[300];
+  const connectorColor = isCompleted ? colorValue.main : neutralTones(theme).track;
 
   return {
     flex: 1,

package/src/social-login-button/social-login-button.tsx

@@ -3,7 +3,7 @@
 import * as React from 'react';
 import Box from '@mui/material/Box/index.js';
 import Stack from '@mui/material/Stack/index.js';
-import type { Theme } from '@mui/material/styles/index.js';
+import { useTheme, type Theme } from '@mui/material/styles/index.js';
 import { Button } from '../components/form/Button';
 import { Card, CardContent } from '../components/layout/Card';
 import { Heading } from '../components/typography/Heading';
@@ -11,41 +11,48 @@ import { Text } from '../components/typography/Text';
 import { Separator } from '../components/layout/Separator';
 import type { SocialLoginCopy } from '../copy/form';
 import { EN_US_SOCIAL_LOGIN_COPY } from '../en-US.form';
+import { uiInk, type UiInk } from '../tokens/ink';
 
 export type SocialProvider = 'google' | 'facebook' | 'apple';
 
 /**
  * SVG Icons for social providers
  */
-const GoogleIcon = (): React.ReactElement => (
-  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
-    <path
-      d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
-      fill="#4285F4"
-    />
-    <path
-      d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
-      fill="#34A853"
-    />
-    <path
-      d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
-      fill="#FBBC05"
-    />
-    <path
-      d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
-      fill="#EA4335"
-    />
-  </svg>
-);
+const GoogleIcon = (): React.ReactElement => {
+  const logo = uiInk(useTheme()).socialBrand.googleLogo;
+  return (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"
+        fill={logo.blue}
+      />
+      <path
+        d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
+        fill={logo.green}
+      />
+      <path
+        d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
+        fill={logo.yellow}
+      />
+      <path
+        d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
+        fill={logo.red}
+      />
+    </svg>
+  );
+};
 
-const FacebookIcon = (): React.ReactElement => (
-  <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
-    <path
-      d="M24 12c0-6.627-5.373-12-12-12S0 5.373 0 12c0 5.99 4.388 10.954 10.125 11.854V15.47H7.078V12h3.047V9.356c0-3.007 1.792-4.668 4.533-4.668 1.312 0 2.686.234 2.686.234v2.953H15.83c-1.491 0-1.956.925-1.956 1.874V12h3.328l-.532 3.469h-2.796v8.385C19.612 22.954 24 17.99 24 12z"
-      fill="#1877F2"
-    />
-  </svg>
-);
+const FacebookIcon = (): React.ReactElement => {
+  const { logo } = uiInk(useTheme()).socialBrand.facebook;
+  return (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path
+        d="M24 12c0-6.627-5.373-12-12-12S0 5.373 0 12c0 5.99 4.388 10.954 10.125 11.854V15.47H7.078V12h3.047V9.356c0-3.007 1.792-4.668 4.533-4.668 1.312 0 2.686.234 2.686.234v2.953H15.83c-1.491 0-1.956.925-1.956 1.874V12h3.328l-.532 3.469h-2.796v8.385C19.612 22.954 24 17.99 24 12z"
+        fill={logo}
+      />
+    </svg>
+  );
+};
 
 const AppleIcon = (): React.ReactElement => (
   <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
@@ -93,6 +100,12 @@ const FACEBOOK_LOGO_IN_BUTTON_COLOUR_SX = {
   '& .MuiButton-startIcon path': { fill: 'currentColor' },
 } as const;
 
+/** A provider's own colour, read from the theme's `uiInk.socialBrand` as an `sx` value. */
+const brand =
+  (pick: (colours: UiInk['socialBrand']) => string) =>
+  (theme: Theme): string =>
+    pick(uiInk(theme).socialBrand);
+
 interface ProviderConfig {
   Icon: () => React.ReactElement;
   variant: 'solid' | 'outline' | 'ghost';
@@ -106,12 +119,12 @@ const providerConfig: Record<SocialProvider, ProviderConfig> = {
     variant: 'outline',
     color: 'neutral',
     sx: {
-      backgroundColor: '#ffffff',
-      color: '#1f1f1f',
-      borderColor: '#dadce0',
+      backgroundColor: brand((c) => c.google.background),
+      color: brand((c) => c.google.text),
+      borderColor: brand((c) => c.google.border),
       '&:hover': {
-        backgroundColor: '#f5f5f5',
-        borderColor: '#dadce0',
+        backgroundColor: brand((c) => c.google.hover),
+        borderColor: brand((c) => c.google.hoverBorder),
       },
       ...GOOGLE_LOGO_WHEN_DISABLED_SX,
     },
@@ -121,10 +134,10 @@ const providerConfig: Record<SocialProvider, ProviderConfig> = {
     variant: 'solid',
     color: 'primary',
     sx: {
-      backgroundColor: '#1877F2',
-      color: '#ffffff',
+      backgroundColor: brand((c) => c.facebook.background),
+      color: brand((c) => c.facebook.text),
       '&:hover': {
-        backgroundColor: '#166fe5',
+        backgroundColor: brand((c) => c.facebook.hover),
       },
       ...FACEBOOK_LOGO_IN_BUTTON_COLOUR_SX,
     },
@@ -134,10 +147,10 @@ const providerConfig: Record<SocialProvider, ProviderConfig> = {
     variant: 'solid',
     color: 'neutral',
     sx: {
-      backgroundColor: '#000000',
-      color: '#ffffff',
+      backgroundColor: brand((c) => c.apple.background),
+      color: brand((c) => c.apple.text),
       '&:hover': {
-        backgroundColor: '#1a1a1a',
+        backgroundColor: brand((c) => c.apple.hover),
       },
     },
   },

package/src/tokens/index.native.ts

@@ -15,3 +15,5 @@ export {
   fieldHeightPx,
   fieldHeightRem,
 } from './field-height.core';
+// The named colour sets a *.metrics.ts table reads (FUT-2593); no MUI behind them.
+export * from './ink.core';

package/src/tokens/ink.core.ts

@@ -0,0 +1,128 @@
+/**
+ * THE COLOURS THAT HAVE NO PALETTE ROLE, NAMED — with no renderer behind them.
+ *
+ * Every colour a component draws comes from the theme (FUT-2593, under
+ * FUT-2585). Most have a palette role — text, divider, a semantic main, a
+ * neutral tone (`./ink.ts`). These do not: a chart's neon series, a map's
+ * terrain, a code editor's syntax chrome, a vendor's brand. They were hex
+ * literals inside components; they are NAMED sets here, which a host can
+ * replace through `theme.uiInk` (`./ink.ts`), and each default is exactly the
+ * value the component drew before, so moving it here changed nothing on screen.
+ *
+ * This file imports nothing: `*.metrics.ts` tables, which the native renderer
+ * reads too, take their colours from it.
+ */
+
+/** The `neon` Chart variant: its series, its ground, its accent (`Chart`). */
+export const DATA_VIZ_NEON = {
+  series: ['#00ffff', '#ff00ff', '#ffff00', '#00ff00', '#ff0080', '#8000ff'],
+  ground: '#000',
+  accent: '#00ffff',
+} as const;
+
+/** The phases a `TimingDiagram` bar is split into, in order. */
+export const TIMING_PHASES = {
+  dns: '#9C27B0',
+  connect: '#2196F3',
+  tls: '#00BCD4',
+  request: '#4CAF50',
+  response: '#FF9800',
+} as const;
+
+/** `MapPreview`'s ground for the terrain and satellite map types. */
+export const MAP_SURFACE = {
+  terrainFrom: '#8BC34A',
+  terrainTo: '#4CAF50',
+  terrainTileFrom: '#7cb342',
+  terrainTileTo: '#558b2f',
+  satelliteTileFrom: '#1a1a1a',
+  satelliteTileTo: '#2a2a2a',
+} as const;
+
+/** `CodeEditor`'s Monaco chrome, per mode — GitHub's own light and dark. */
+export const CODE_EDITOR_CHROME = {
+  light: {
+    background: '#FFFFFF',
+    foreground: '#24292E',
+    lineHighlight: '#F6F8FA',
+    lineNumber: '#959DA5',
+    lineNumberActive: '#24292E',
+    gutterBorder: '#D1D5DA',
+    selection: '#C8E1FF',
+  },
+  dark: {
+    background: '#0D1117',
+    foreground: '#C9D1D9',
+    lineHighlight: '#161B22',
+    lineNumber: '#8B949E',
+    lineNumberActive: '#C9D1D9',
+    gutterBorder: '#21262D',
+    selection: '#3392FF44',
+  },
+} as const;
+
+/**
+ * The social-login providers' OWN colours. Brand rules fix these — a host may
+ * not "theme" Google's button — so the override exists only for a provider that
+ * changes its guideline.
+ */
+export const SOCIAL_BRAND = {
+  googleLogo: { blue: '#4285F4', green: '#34A853', yellow: '#FBBC05', red: '#EA4335' },
+  google: { background: '#ffffff', text: '#1f1f1f', border: '#dadce0', hover: '#f5f5f5', hoverBorder: '#dadce0' },
+  facebook: { background: '#1877F2', text: '#ffffff', hover: '#166fe5', logo: '#1877F2' },
+  apple: { background: '#000000', text: '#ffffff', hover: '#1a1a1a' },
+} as const;
+
+/** The two decorative gradients a completed step and a tutorial's call to action wear. */
+export const CELEBRATION_GRADIENTS = {
+  mint: ['#84fab0', '#8fd3f4'],
+  violet: ['#667eea', '#764ba2'],
+} as const;
+
+/** A count that wants attention before it is read (`NavigationMenu`'s badge). */
+export const ATTENTION_INK = { from: '#ff5252', to: '#ff1744', glow: 'rgb(255, 23, 68)' } as const;
+
+/** A search hit inside a row label (`CategorySelect`). */
+export const HIGHLIGHT_MARK = '#fff2a8';
+
+/** The slate a frosted breadcrumb bar is tinted with in dark mode. */
+export const GLASS_SLATE = 'rgb(17, 24, 39)';
+
+/** The ink of a raised floating panel's shadow (`CategorySelect`). */
+export const PANEL_SHADOW_INK = 'rgb(16, 20, 35)';
+
+/**
+ * Glows that were drawn in a FIXED hue rather than the host's primary: MUI's
+ * default blue (`Checkbox`, `NavigationMenu`) and the platform's default indigo
+ * (`Breadcrumbs`). Kept as they are — moving them onto `palette.primary` would
+ * recolour them for every host — and named so that a host can.
+ */
+export const EFFECT_GLOW = { muiBlue: 'rgb(25, 118, 210)', brandIndigo: 'rgb(99, 102, 241)' } as const;
+
+/**
+ * MUI's own elevation shadows 1, 2, 3 and 8 — what `theme.shadows[n]` holds at
+ * MUI's defaults — for the `*.metrics.ts` tables the native renderer reads.
+ */
+export const ELEVATION_SHADOWS = {
+  1: '0px 2px 1px -1px rgba(0,0,0,0.2),0px 1px 1px 0px rgba(0,0,0,0.14),0px 1px 3px 0px rgba(0,0,0,0.12)',
+  2: '0px 3px 1px -2px rgba(0,0,0,0.2),0px 2px 2px 0px rgba(0,0,0,0.14),0px 1px 5px 0px rgba(0,0,0,0.12)',
+  3: '0px 3px 3px -2px rgba(0,0,0,0.2),0px 3px 4px 0px rgba(0,0,0,0.14),0px 1px 8px 0px rgba(0,0,0,0.12)',
+  8: '0px 5px 5px -3px rgba(0,0,0,0.2),0px 8px 10px 1px rgba(0,0,0,0.14),0px 3px 14px 2px rgba(0,0,0,0.12)',
+} as const;
+
+/** The two absolutes, for a renderer with no palette to read them from. */
+export const ABSOLUTE_INK = { black: '#000', white: '#fff' } as const;
+
+/** The grey ramp's steps the neutral tones are drawn from (MUI's). */
+export const NEUTRAL_RAMP = {
+  50: '#fafafa',
+  100: '#f5f5f5',
+  200: '#eeeeee',
+  300: '#e0e0e0',
+  400: '#bdbdbd',
+  500: '#9e9e9e',
+  600: '#757575',
+  700: '#616161',
+  800: '#424242',
+  900: '#212121',
+} as const;

package/src/tokens/ink.ts

@@ -0,0 +1,170 @@
+import type { Theme } from '@mui/material/styles/index.js';
+
+import { alpha } from './color';
+import {
+  ATTENTION_INK,
+  CELEBRATION_GRADIENTS,
+  CODE_EDITOR_CHROME,
+  DATA_VIZ_NEON,
+  EFFECT_GLOW,
+  GLASS_SLATE,
+  HIGHLIGHT_MARK,
+  MAP_SURFACE,
+  NEUTRAL_RAMP,
+  PANEL_SHADOW_INK,
+  SOCIAL_BRAND,
+  TIMING_PHASES,
+} from './ink.core';
+
+/**
+ * EVERY COLOUR A COMPONENT DRAWS, BY ROLE (FUT-2593, under FUT-2585).
+ *
+ * A component never writes a hex, an `rgba()`, a named colour or a step on the
+ * grey ramp; it asks for a ROLE, and the role reads the theme:
+ *
+ * - the palette's own roles, straight — `text.secondary`, `divider`,
+ *   `action.hover`, a semantic `main` and its `contrastText`;
+ * - the INK roles below, over the palette's two absolutes — a scrim behind a
+ *   modal, a shadow's ink, a glass sheen, the ink on a photo;
+ * - the NEUTRAL tones, over the grey ramp, named by what they do rather than by
+ *   their step, so a host that re-greys the ramp re-greys every one;
+ * - `uiInk(theme)`, the colours with no palette role at all (`./ink.core.ts`),
+ *   which a host can replace through `theme.uiInk`.
+ *
+ * Every default is the value the component drew before, so moving a component
+ * onto these changed nothing on screen. `scripts/ui-tokens-gate.mjs` refuses a
+ * raw colour or a ramp step in a component from here on.
+ */
+
+export interface UiInk {
+  dataVizNeon: { series: readonly string[]; ground: string; accent: string };
+  timingPhases: Record<keyof typeof TIMING_PHASES, string>;
+  mapSurface: Record<keyof typeof MAP_SURFACE, string>;
+  codeEditor: { light: Record<keyof typeof CODE_EDITOR_CHROME.light, string>; dark: Record<keyof typeof CODE_EDITOR_CHROME.dark, string> };
+  socialBrand: typeof SOCIAL_BRAND;
+  celebration: { mint: readonly [string, string]; violet: readonly [string, string] };
+  attention: { from: string; to: string; glow: string };
+  highlightMark: string;
+  glassSlate: string;
+  panelShadowInk: string;
+  effectGlow: { muiBlue: string; brandIndigo: string };
+}
+
+export const DEFAULT_UI_INK: UiInk = {
+  dataVizNeon: DATA_VIZ_NEON,
+  timingPhases: TIMING_PHASES,
+  mapSurface: MAP_SURFACE,
+  codeEditor: CODE_EDITOR_CHROME,
+  socialBrand: SOCIAL_BRAND,
+  celebration: CELEBRATION_GRADIENTS,
+  attention: ATTENTION_INK,
+  highlightMark: HIGHLIGHT_MARK,
+  glassSlate: GLASS_SLATE,
+  panelShadowInk: PANEL_SHADOW_INK,
+  effectGlow: EFFECT_GLOW,
+};
+
+declare module '@mui/material/styles' {
+  interface Theme {
+    /** Colours with no palette role, by name. See `@12-apps/ui/tokens`' `uiInk`. */
+    uiInk?: Partial<UiInk>;
+  }
+  interface ThemeOptions {
+    /**
+     * Replace any of the named colour sets `@12-apps/ui` draws with. Each set is
+     * replaced WHOLE (the merge is one level deep): to change `codeEditor.dark`,
+     * pass `codeEditor` with both `light` and `dark`.
+     */
+    uiInk?: Partial<UiInk>;
+  }
+}
+
+/** The named colour sets, with the host's `theme.uiInk` layered over the defaults. */
+export function uiInk(theme: Theme): UiInk {
+  return { ...DEFAULT_UI_INK, ...theme.uiInk };
+}
+
+/* ── Ink roles over the palette's two absolutes ───────────────────────────── */
+
+/** The dim laid behind a modal, a lightbox, a spotlight. */
+export const scrim = (theme: Theme, opacity: number): string => alpha(theme.palette.common.black, opacity);
+
+/** The colour of a drop shadow or a glow's dark half. */
+export const shadowInk = (theme: Theme, opacity = 1): string => alpha(theme.palette.common.black, opacity);
+
+/** A highlight: a glass edge, a shimmer, a pressed-in light. */
+export const sheen = (theme: Theme, opacity = 1): string => alpha(theme.palette.common.white, opacity);
+
+/** Ink that sits ON a photo, a gradient or a scrim — never on the page. */
+export const onMedia = (theme: Theme): string => theme.palette.common.white;
+
+/**
+ * The palette's two absolutes, for the places the hue must be exactly black or
+ * white: a CSS mask's opaque stop, the black `dark` tooltip.
+ */
+export const absoluteInk = (theme: Theme): { black: string; white: string } => ({
+  black: theme.palette.common.black,
+  white: theme.palette.common.white,
+});
+
+/** The absolute that CONTRASTS with the mode's page: black in light mode, white in dark. */
+export const modeInk = (theme: Theme): string =>
+  theme.palette.mode === 'dark' ? theme.palette.common.white : theme.palette.common.black;
+
+/* ── Neutral tones over the grey ramp ─────────────────────────────────────── */
+
+const step = (theme: Theme, n: keyof typeof NEUTRAL_RAMP): string => theme.palette.grey[n] ?? NEUTRAL_RAMP[n];
+
+/**
+ * The neutral scale by ROLE. The names say what a tone is for, so a component
+ * reads `neutralTones(theme).track` rather than "grey 300", and a host that
+ * re-greys the ramp moves every one of them together.
+ */
+export function neutralTones(theme: Theme) {
+  return {
+    /** A dark chip on a light UI: a tooltip, a context menu, a code block's dark ground. */
+    inverseSurface: step(theme, 900),
+    /** A raised dark panel. */
+    raised: step(theme, 800),
+    /** A neutral control's fill. */
+    strong: step(theme, 700),
+    /** A neutral accent: a badge, a strong scrollbar thumb. */
+    emphasis: step(theme, 600),
+    /** A quiet mark: an offline dot, a secondary icon. */
+    muted: step(theme, 500),
+    /** An idle connector, a light scrollbar thumb. */
+    subtle: step(theme, 400),
+    /** An idle track, a placeholder fill. */
+    track: step(theme, 300),
+    /** A faint track, a light scrollbar channel. */
+    faint: step(theme, 200),
+    /** A light code block, a light card. */
+    surface: step(theme, 100),
+    /** The lightest ground. */
+    canvas: step(theme, 50),
+  };
+}
+
+/** The four-stop accent a component's `neutral` colour resolves to. */
+export interface NeutralAccent {
+  main: string;
+  light: string;
+  dark: string;
+  contrastText: string;
+}
+
+/**
+ * The neutral the CONTROLS draw with — grey 700, pressed 800, soft 500, white
+ * ink — for `Button`, `Toggle`, `RadioGroup`, `Switch`, `Slider`, `Textarea`,
+ * `InputOTP`. Not `accentFor(theme, 'neutral')` (600/400/800, a badge's): the
+ * controls have always been one step darker.
+ */
+export function controlNeutral(theme: Theme): NeutralAccent {
+  return { main: step(theme, 700), dark: step(theme, 800), light: step(theme, 500), contrastText: theme.palette.common.white };
+}
+
+/** The softer neutral a notice or a progress track draws with — 500 on a 300 ground, 700 pressed. */
+export function softNeutral(theme: Theme): NeutralAccent {
+  const main = step(theme, 500);
+  return { main, light: step(theme, 300), dark: step(theme, 700), contrastText: theme.palette.getContrastText(main) };
+}

package/src/tokens/scales.ts

@@ -16,6 +16,9 @@ export * from './theme';
 export * from './color';
 // The relative-size vocabulary every component writes its sizes in (FUT-2585).
 export { rem, rems, remPx, resetRootFontCache, sxRem } from './relative';
+// Every colour by role (FUT-2593): ink roles, neutral tones, the named sets.
+export * from './ink';
+export * from './ink.core';
 export { DEFAULT_FIELD_RADIUS, fieldRadius, fieldRadiusOverrides, fieldRadiusPx, fieldRootStyles } from './field-radius';
 export {
   asFieldSize,