@rebasepro/ui 0.14.2-canary.gf913b76 → 0.15.0

package/dist/src/index.css

@@ -36,26 +36,40 @@ html.dark {
    size goes up. Seven consecutive levels of semibold was a Rubik-era setting,
    and holding 600 all the way down to text-sm made every heading shout equally
    — a heading stops being a headline somewhere, and the scale should say where.
-   600 is display-scale only; the small end carries 500.
+
+   The ladder now spans three weights rather than two. 600 everywhere at the top
+   meant a page title and the section heading inside it were the same voice at
+   two sizes, so a screen had no clear first thing to read. 700 is the *display*
+   tier only — h1 and h2, page titles and stat numbers — and nothing in the UI
+   chrome (nav, labels, buttons, table headers) goes above 600.
+
+   This costs nothing on the wire: both faces are loaded as VARIABLE fonts
+   (@fontsource-variable/inter, @fontsource-variable/instrument-sans), so the
+   whole weight axis is already in the file that ships. The earlier "never above
+   600" rule was written when static weights meant every step was another
+   download; that constraint no longer exists.
 
    With a single face carrying both headings and body, weight and tracking are
    the only things separating a heading from the copy around it — so the tiers
    have to actually differ, rather than all sitting at 600. */
 
 .typography-h1 {
-    @apply text-4xl font-headers font-semibold tracking-display;
+    @apply text-4xl font-headers font-bold tracking-display;
 }
 
 .typography-h2 {
-    @apply text-3xl font-headers font-semibold tracking-display;
+    @apply text-3xl font-headers font-bold tracking-display;
 }
 
 .typography-h3 {
     @apply text-2xl font-headers font-semibold tracking-title;
 }
 
+/* Semibold, not medium: h4 is the section heading inside a page, and at 20px
+   medium sits close enough to body copy that a long page reads as one
+   undifferentiated column. */
 .typography-h4 {
-    @apply text-xl font-headers font-medium tracking-title;
+    @apply text-xl font-headers font-semibold tracking-title;
 }
 
 .typography-h5 {
@@ -98,6 +112,44 @@ html.dark {
     @apply text-sm font-semibold tracking-wide;
 }
 
+/* ---------------------------------------------------------------------------
+ * Three tiers the product kept improvising because the system had no name for
+ * them. Each existed as hand-written utilities in several places before it
+ * existed here, which is the definition of a missing token.
+ * ------------------------------------------------------------------------- */
+
+/* The sentence under a page title. `body2` (12px) was standing in for it, which
+   made the one line explaining what a page is FOR smaller than the page's own
+   table rows. A lead is read once, deliberately, and it gets room to be read. */
+.typography-lead {
+    @apply text-base leading-relaxed;
+}
+
+/* The micro-label above a value: SCANNED, KEPT, TOOK, WHEN. Uppercase and
+   tracked so it reads as a field name rather than as copy, and small enough
+   that it never competes with the value it names.
+
+   This is the one product tier below `text-xs`. It earns the exception by never
+   carrying a sentence — it is always one or two words naming the thing directly
+   underneath it, and at 11px uppercase with this tracking it stays legible
+   where 11px prose would not. */
+.typography-micro {
+    @apply text-2xs font-medium uppercase tracking-[0.08em];
+}
+
+/* A measured value: a count, a duration, a timestamp, an id, a size.
+   `tabular-nums` is the point — proportional digits make a column of numbers
+   ragged and a live-updating counter jitter as its glyphs change width. */
+.typography-mono {
+    @apply font-mono tabular-nums;
+}
+
+/* The headline number on a stat tile. Display weight, display tracking, and
+   tabular figures so a row of tiles shares a baseline grid. */
+.typography-stat {
+    @apply text-3xl font-headers font-bold tracking-display tabular-nums;
+}
+
 :focus-visible {
     @apply outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-0 focus-visible:ring-offset-transparent
 }

package/dist/src/theme.css

@@ -30,11 +30,14 @@
     --tracking-title: -0.018em;   /* 20-24px — section titles */
     --tracking-heading: -0.01em;  /* <= 18px — labels; still a heading, not a headline */
 
-    /* Sub-`xs` type. MARKETING ONLY — product UI must not go below `text-xs`
-       (12px). These exist because the marketing site had ~450 hand-written
-       `text-[10px]` / `text-[11px]` classes: the tier was real, it just wasn't
-       in the system, so every page improvised it. Naming it stops the drift
-       without pretending 10px is acceptable for an admin panel. */
+    /* Sub-`xs` type. These exist because the marketing site had ~450
+       hand-written `text-[10px]` / `text-[11px]` classes: the tier was real, it
+       just wasn't in the system, so every page improvised it.
+
+       In product UI there is exactly ONE sanctioned use — `typography-micro`,
+       the uppercase field label above a value — and it earns the exception by
+       never carrying a sentence. Everything a person actually *reads* stays at
+       `text-xs` (12px) or above. `--text-3xs` remains marketing-only. */
     --text-2xs: 11px;
     --text-2xs--line-height: 1.45;
     --text-3xs: 10px;

package/dist/styles.d.ts

@@ -35,6 +35,34 @@ export declare const fieldBackgroundDisabledMixin = "bg-surface-accent-200/50 da
 export declare const fieldBackgroundHoverMixin = "hover:bg-surface-accent-200/70 hover:dark:bg-white/[0.09]";
 export declare const defaultBorderMixin = "border-surface-200 dark:border-surface-700/60 ";
 export declare const paperMixin = "bg-white rounded-lg dark:bg-surface-900 border border-surface-200 dark:border-surface-700";
-export declare const cardMixin = "bg-white dark:bg-surface-900 rounded-lg border border-surface-200 dark:border-surface-700";
+export declare const cardMixin = "bg-white dark:bg-surface-900 rounded-xl border border-surface-200 dark:border-surface-700/60";
+/**
+ * An inset well: code, a query, a log tail, a connection string.
+ *
+ * It must read as *recessed into* the surface holding it, which means darker
+ * than that surface in dark mode — `surface-950` under a `surface-900` card.
+ * The obvious-looking `surface-800` is a trap: `#111111` is LIGHTER than the
+ * `#0a0a0a` card around it, so the well appears to float above the thing it is
+ * set into. Pair with `font-mono`; this mixin carries the surface only.
+ */
+export declare const codeSurfaceMixin = "bg-surface-100 dark:bg-surface-950 rounded-md";
+/**
+ * The accent, used as TEXT.
+ *
+ * `--color-primary` (#0070F4) is tuned to be a fill — white text on it, it on
+ * white. Read as text on our dark surfaces it lands at **4.36:1 on a
+ * `surface-900` card** (measured), which is below AA for body-sized text, and
+ * every accent link in the product sits on exactly that surface. On the page's
+ * `surface-950` it only reaches 4.62:1, so the margin was never real.
+ *
+ * `--color-primary-light` is the same hue lifted 0.15 in OKLCH lightness and
+ * measures **7.34:1** on the same card. It is indistinguishable as "the blue"
+ * and comfortably legible, so dark mode swaps to it for text.
+ *
+ * Use this for links, accent labels and any accent-coloured type. It is NOT for
+ * fills — a filled button keeps `bg-primary`, where the contrast question runs
+ * the other way and #0070F4 is already correct.
+ */
+export declare const accentTextMixin = "text-primary dark:text-primary-light";
 export declare const cardClickableMixin = "hover:bg-primary/5 dark:hover:bg-primary/5 cursor-pointer transition-colors duration-150";
 export declare const cardSelectedMixin = "bg-primary-bg/30 dark:bg-primary-bg/10 ring-1 ring-primary/75";

package/dist/theme.css

@@ -30,11 +30,14 @@
     --tracking-title: -0.018em;   /* 20-24px — section titles */
     --tracking-heading: -0.01em;  /* <= 18px — labels; still a heading, not a headline */
 
-    /* Sub-`xs` type. MARKETING ONLY — product UI must not go below `text-xs`
-       (12px). These exist because the marketing site had ~450 hand-written
-       `text-[10px]` / `text-[11px]` classes: the tier was real, it just wasn't
-       in the system, so every page improvised it. Naming it stops the drift
-       without pretending 10px is acceptable for an admin panel. */
+    /* Sub-`xs` type. These exist because the marketing site had ~450
+       hand-written `text-[10px]` / `text-[11px]` classes: the tier was real, it
+       just wasn't in the system, so every page improvised it.
+
+       In product UI there is exactly ONE sanctioned use — `typography-micro`,
+       the uppercase field label above a value — and it earns the exception by
+       never carrying a sentence. Everything a person actually *reads* stays at
+       `text-xs` (12px) or above. `--text-3xs` remains marketing-only. */
     --text-2xs: 11px;
     --text-2xs--line-height: 1.45;
     --text-3xs: 10px;

package/dist/util/chip_colors.d.ts

@@ -5,7 +5,21 @@ export type ChipColorScheme = {
     darkColor?: string;
     /** Text color override for dark mode */
     darkText?: string;
+    /**
+     * Ink for the `outlined` variant, which has no fill of its own.
+     *
+     * `text`/`darkText` are the ink ON the chip's own background. An outlined
+     * chip drops that background and sits on the PAGE, so the same value is
+     * being asked to be legible against two different surfaces at once — and
+     * for most hues it cannot be. Splitting the roles is what lets the filled
+     * ink follow its fill (often dark ink on a bright chip) without dragging
+     * the outlined variant down with it.
+     */
+    outlineText?: string;
+    /** Outlined-variant ink in dark mode. */
+    darkOutlineText?: string;
 };
+export declare function contrastRatio(a: string, b: string): number;
 export declare const CHIP_HUES: readonly ["blue", "cyan", "teal", "green", "yellow", "orange", "red", "pink", "purple", "gray", "indigo", "violet", "fuchsia", "rose", "emerald"];
 export type ChipHue = typeof CHIP_HUES[number];
 /**

package/dist/views/CollectionView/CollectionView.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import type { CollectionViewMode, CollectionViewSize, CollectionPropertyConfig, CollectionDataController, CellRendererOverride, CollectionSelectionController, KanbanPropertyOption } from "./CollectionViewTypes";
+import type { CollectionViewMode, CollectionViewSize, CollectionPropertyConfig, CollectionDataController, CellRendererOverride, CollectionCustomViewEntry, CollectionSelectionController, KanbanPropertyOption } from "./CollectionViewTypes";
 /**
  * Props for the headless {@link CollectionView} component.
  *
@@ -76,6 +76,26 @@ export interface CollectionViewProps<T = Record<string, unknown>> {
     cellRenderer?: CellRendererOverride<T>;
     /** Custom empty state component */
     emptyComponent?: React.ReactNode;
+    /**
+     * Additional ways to render these rows, keyed by view mode. A key here can
+     * be named by `viewMode`, `defaultViewMode` and `enabledViews`, and gets
+     * its own entry in the view switcher.
+     *
+     * A custom view is another rendering of the *same* `dataController`, so it
+     * inherits the toolbar's search, the loading state and selection. A
+     * component that fetches its own data does not want to be a view mode —
+     * the toolbar above it would be describing a query it does not render.
+     *
+     * @example
+     * ```tsx
+     * <CollectionView
+     *     customViews={{ map: { name: "Map", Component: MapView } }}
+     *     enabledViews={["table", "map"]}
+     *     defaultViewMode="map"
+     * />
+     * ```
+     */
+    customViews?: Record<string, CollectionCustomViewEntry<T>>;
     /** Actions rendered at the start (left) of the toolbar */
     toolbarActionsStart?: React.ReactNode;
     /** Actions rendered at the end (right) of the toolbar */
@@ -118,4 +138,4 @@ export interface CollectionViewProps<T = Record<string, unknown>> {
  *
  * @group Collection View
  */
-export declare function CollectionView<T extends Record<string, unknown> = Record<string, unknown>>({ dataController, properties, propertiesOrder, displayedColumnIds, idProperty, titleProperty, title, viewMode: viewModeProp, defaultViewMode, enabledViews, onViewModeChange: onViewModeChangeProp, size: sizeProp, defaultSize, onSizeChange: onSizeChangeProp, kanbanProperty: kanbanPropertyProp, kanbanPropertyOptions, onKanbanPropertyChange: onKanbanPropertyChangeProp, onRowClick, onRowCreate, canCreate, selectionEnabled, selectionController, highlightedItems, onMultipleDelete, cellRenderer, emptyComponent, toolbarActionsStart, toolbarActionsEnd, hideToolbar, hoverRow, onColumnResize, onColumnsOrderChange, className }: CollectionViewProps<T>): React.JSX.Element;
+export declare function CollectionView<T extends Record<string, unknown> = Record<string, unknown>>({ dataController, properties, propertiesOrder, displayedColumnIds, idProperty, titleProperty, title, viewMode: viewModeProp, defaultViewMode, enabledViews, onViewModeChange: onViewModeChangeProp, size: sizeProp, defaultSize, onSizeChange: onSizeChangeProp, kanbanProperty: kanbanPropertyProp, kanbanPropertyOptions, onKanbanPropertyChange: onKanbanPropertyChangeProp, onRowClick, onRowCreate, canCreate, selectionEnabled, selectionController, highlightedItems, onMultipleDelete, cellRenderer, emptyComponent, customViews, toolbarActionsStart, toolbarActionsEnd, hideToolbar, hoverRow, onColumnResize, onColumnsOrderChange, className }: CollectionViewProps<T>): React.JSX.Element;

package/dist/views/CollectionView/CollectionViewToolbar.d.ts

@@ -8,6 +8,16 @@ export type CollectionViewToolbarProps = {
     viewMode: CollectionViewMode;
     onViewModeChange?: (mode: CollectionViewMode) => void;
     enabledViews?: CollectionViewMode[];
+    /**
+     * Custom view modes, supplying the label and icon for their switcher
+     * entries. Without these an `enabledViews` key outside the four built-ins
+     * has no label and no icon to draw.
+     */
+    customViews?: {
+        key: string;
+        name: string;
+        icon?: React.ReactNode;
+    }[];
     size?: CollectionViewSize;
     onSizeChange?: (size: CollectionViewSize) => void;
     searchString?: string;
@@ -28,4 +38,4 @@ export type CollectionViewToolbarProps = {
  *
  * @group Collection View
  */
-export declare function CollectionViewToolbar({ viewMode, onViewModeChange, enabledViews, size, onSizeChange, searchString, onSearchChange, loading, actionsStart, actionsEnd, compact, kanbanPropertyOptions, selectedKanbanProperty, onKanbanPropertyChange, }: CollectionViewToolbarProps): React.JSX.Element;
+export declare function CollectionViewToolbar({ viewMode, onViewModeChange, enabledViews, customViews, size, onSizeChange, searchString, onSearchChange, loading, actionsStart, actionsEnd, compact, kanbanPropertyOptions, selectedKanbanProperty, onKanbanPropertyChange, }: CollectionViewToolbarProps): React.JSX.Element;

package/dist/views/CollectionView/CollectionViewTypes.d.ts

@@ -1,7 +1,12 @@
 import React from "react";
 import type { VirtualTableSortKey } from "../../components/VirtualTable/VirtualTableProps";
-/** Supported view modes */
-export type CollectionViewMode = "table" | "cards" | "kanban" | "list";
+/**
+ * Supported view modes.
+ *
+ * Any other string is a key into the `customViews` prop. The `(string & {})`
+ * arm keeps the four built-ins in autocomplete while admitting those keys.
+ */
+export type CollectionViewMode = "table" | "cards" | "kanban" | "list" | (string & {});
 /** Supported collection sizes */
 export type CollectionViewSize = "xs" | "s" | "m" | "l" | "xl";
 /**
@@ -106,3 +111,36 @@ export interface KanbanPropertyOption {
     key: string;
     label: string;
 }
+/**
+ * What a custom view's component receives — the same set the built-in table,
+ * card, list and kanban views are given, so a custom view starts at parity
+ * with them and inherits the toolbar's search, the empty state and selection.
+ */
+export interface CollectionCustomViewProps<T = Record<string, unknown>> {
+    dataController: CollectionDataController<T>;
+    properties: Record<string, CollectionPropertyConfig>;
+    propertiesOrder?: string[];
+    idProperty?: string;
+    titleProperty?: string;
+    onRowClick?: (row: T) => void;
+    onRowCreate?: (defaults?: Record<string, unknown>) => void;
+    canCreate?: boolean;
+    cellRenderer?: CellRendererOverride<T>;
+    selectionEnabled?: boolean;
+    selectionController?: CollectionSelectionController<T>;
+    highlightedItems?: T[];
+    emptyComponent?: React.ReactNode;
+    size?: CollectionViewSize;
+}
+/**
+ * A custom view registration. Either the component on its own, or the
+ * component with the label and icon its switcher entry should carry.
+ *
+ * Without a `name` the switcher falls back to the key, which is legible but
+ * rarely what you want on screen.
+ */
+export type CollectionCustomViewEntry<T = Record<string, unknown>> = React.ComponentType<CollectionCustomViewProps<T>> | {
+    name?: string;
+    icon?: React.ReactNode;
+    Component: React.ComponentType<CollectionCustomViewProps<T>>;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/ui",
   "type": "module",
-  "version": "0.14.2-canary.gf913b76",
+  "version": "0.15.0",
   "description": "Rebase design system — React components and design tokens built on Radix UI, Tailwind CSS and lucide-react",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/components/Chip.tsx

@@ -82,6 +82,16 @@ export function Chip({
 
     if (hasScheme) {
         if (outlined) {
+            // An outlined chip has no fill, so it needs the ink meant for the
+            // PAGE, not the ink meant for the fill it just dropped. Those are
+            // different colours for most hues — a bright `solid` chip carries
+            // dark ink, which on a near-black page would be invisible.
+            if (!error && usedColorScheme) {
+                const outlineInk = dark
+                    ? usedColorScheme.darkOutlineText ?? usedColorScheme.darkText
+                    : usedColorScheme.outlineText;
+                if (outlineInk) textColor = outlineInk;
+            }
             bgColor = getRgba(textColor, dark ? 0.1 : 0.06);
             border = `1px solid ${getRgba(textColor, dark ? 0.2 : 0.14)}`;
         } else if (error) {

package/src/components/Typography.tsx

@@ -31,7 +31,11 @@ const typographyVariants = {
     body2: "p",
     inherit: "p",
     caption: "p",
-    button: "span"
+    button: "span",
+    lead: "p",
+    micro: "span",
+    mono: "span",
+    stat: "span"
 };
 
 const colorToClasses = {
@@ -57,7 +61,11 @@ const gutterBottomClasses = {
     inherit: "mb-3",
     caption: "mb-2",
     button: "mb-2",
-    label: "mb-2"
+    label: "mb-2",
+    lead: "mb-4",
+    micro: "mb-1",
+    mono: "mb-2",
+    stat: "mb-1"
 };
 
 const variantToClasses = {
@@ -74,7 +82,11 @@ const variantToClasses = {
     label: "typography-label",
     inherit: "typography-inherit",
     caption: "typography-caption",
-    button: "typography-button"
+    button: "typography-button",
+    lead: "typography-lead",
+    micro: "typography-micro",
+    mono: "typography-mono",
+    stat: "typography-stat"
 };
 
 export function Typography<C extends React.ElementType = "span">(

package/src/index.css

@@ -36,26 +36,40 @@ html.dark {
    size goes up. Seven consecutive levels of semibold was a Rubik-era setting,
    and holding 600 all the way down to text-sm made every heading shout equally
    — a heading stops being a headline somewhere, and the scale should say where.
-   600 is display-scale only; the small end carries 500.
+
+   The ladder now spans three weights rather than two. 600 everywhere at the top
+   meant a page title and the section heading inside it were the same voice at
+   two sizes, so a screen had no clear first thing to read. 700 is the *display*
+   tier only — h1 and h2, page titles and stat numbers — and nothing in the UI
+   chrome (nav, labels, buttons, table headers) goes above 600.
+
+   This costs nothing on the wire: both faces are loaded as VARIABLE fonts
+   (@fontsource-variable/inter, @fontsource-variable/instrument-sans), so the
+   whole weight axis is already in the file that ships. The earlier "never above
+   600" rule was written when static weights meant every step was another
+   download; that constraint no longer exists.
 
    With a single face carrying both headings and body, weight and tracking are
    the only things separating a heading from the copy around it — so the tiers
    have to actually differ, rather than all sitting at 600. */
 
 .typography-h1 {
-    @apply text-4xl font-headers font-semibold tracking-display;
+    @apply text-4xl font-headers font-bold tracking-display;
 }
 
 .typography-h2 {
-    @apply text-3xl font-headers font-semibold tracking-display;
+    @apply text-3xl font-headers font-bold tracking-display;
 }
 
 .typography-h3 {
     @apply text-2xl font-headers font-semibold tracking-title;
 }
 
+/* Semibold, not medium: h4 is the section heading inside a page, and at 20px
+   medium sits close enough to body copy that a long page reads as one
+   undifferentiated column. */
 .typography-h4 {
-    @apply text-xl font-headers font-medium tracking-title;
+    @apply text-xl font-headers font-semibold tracking-title;
 }
 
 .typography-h5 {
@@ -98,6 +112,44 @@ html.dark {
     @apply text-sm font-semibold tracking-wide;
 }
 
+/* ---------------------------------------------------------------------------
+ * Three tiers the product kept improvising because the system had no name for
+ * them. Each existed as hand-written utilities in several places before it
+ * existed here, which is the definition of a missing token.
+ * ------------------------------------------------------------------------- */
+
+/* The sentence under a page title. `body2` (12px) was standing in for it, which
+   made the one line explaining what a page is FOR smaller than the page's own
+   table rows. A lead is read once, deliberately, and it gets room to be read. */
+.typography-lead {
+    @apply text-base leading-relaxed;
+}
+
+/* The micro-label above a value: SCANNED, KEPT, TOOK, WHEN. Uppercase and
+   tracked so it reads as a field name rather than as copy, and small enough
+   that it never competes with the value it names.
+
+   This is the one product tier below `text-xs`. It earns the exception by never
+   carrying a sentence — it is always one or two words naming the thing directly
+   underneath it, and at 11px uppercase with this tracking it stays legible
+   where 11px prose would not. */
+.typography-micro {
+    @apply text-2xs font-medium uppercase tracking-[0.08em];
+}
+
+/* A measured value: a count, a duration, a timestamp, an id, a size.
+   `tabular-nums` is the point — proportional digits make a column of numbers
+   ragged and a live-updating counter jitter as its glyphs change width. */
+.typography-mono {
+    @apply font-mono tabular-nums;
+}
+
+/* The headline number on a stat tile. Display weight, display tracking, and
+   tabular figures so a row of tiles shares a baseline grid. */
+.typography-stat {
+    @apply text-3xl font-headers font-bold tracking-display tabular-nums;
+}
+
 :focus-visible {
     @apply outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-0 focus-visible:ring-offset-transparent
 }

package/src/styles.ts

@@ -53,7 +53,53 @@ export const fieldBackgroundInvisibleMixin = "bg-surface-accent-200/0 dark:bg-wh
 export const fieldBackgroundDisabledMixin = "bg-surface-accent-200/50 dark:bg-white/[0.03]";
 export const fieldBackgroundHoverMixin = "hover:bg-surface-accent-200/70 hover:dark:bg-white/[0.09]";
 export const defaultBorderMixin = "border-surface-200 dark:border-surface-700/60 ";
+
+// ---------------------------------------------------------------------------
+// Surfaces: two kinds, and the difference is what the border is for.
+//
+// A **floating** surface — a menu, a dialog, a popover — sits OVER the page. It
+// has to be legible against whatever happens to be underneath it, so its edge
+// is definite: solid `surface-700`. That is `paperMixin`.
+//
+// A **page** surface — a card in the document flow — sits ON the page, and the
+// page is already `surface-950`/`surface-900`. A solid edge there reads as a
+// box drawn around content rather than as the content having a surface, which
+// is why every serious caller was overriding it: 53 `<Card>` sites in the SaaS
+// console alone re-declared this border at `/60`, the same value
+// `defaultBorderMixin` above has always used. The component was wrong and the
+// callers were right, so the component now says what they meant.
+// ---------------------------------------------------------------------------
 export const paperMixin = "bg-white rounded-lg dark:bg-surface-900 border border-surface-200 dark:border-surface-700";
-export const cardMixin = "bg-white dark:bg-surface-900 rounded-lg border border-surface-200 dark:border-surface-700";
+export const cardMixin = "bg-white dark:bg-surface-900 rounded-xl border border-surface-200 dark:border-surface-700/60";
+
+/**
+ * An inset well: code, a query, a log tail, a connection string.
+ *
+ * It must read as *recessed into* the surface holding it, which means darker
+ * than that surface in dark mode — `surface-950` under a `surface-900` card.
+ * The obvious-looking `surface-800` is a trap: `#111111` is LIGHTER than the
+ * `#0a0a0a` card around it, so the well appears to float above the thing it is
+ * set into. Pair with `font-mono`; this mixin carries the surface only.
+ */
+export const codeSurfaceMixin = "bg-surface-100 dark:bg-surface-950 rounded-md";
+
+/**
+ * The accent, used as TEXT.
+ *
+ * `--color-primary` (#0070F4) is tuned to be a fill — white text on it, it on
+ * white. Read as text on our dark surfaces it lands at **4.36:1 on a
+ * `surface-900` card** (measured), which is below AA for body-sized text, and
+ * every accent link in the product sits on exactly that surface. On the page's
+ * `surface-950` it only reaches 4.62:1, so the margin was never real.
+ *
+ * `--color-primary-light` is the same hue lifted 0.15 in OKLCH lightness and
+ * measures **7.34:1** on the same card. It is indistinguishable as "the blue"
+ * and comfortably legible, so dark mode swaps to it for text.
+ *
+ * Use this for links, accent labels and any accent-coloured type. It is NOT for
+ * fills — a filled button keeps `bg-primary`, where the contrast question runs
+ * the other way and #0070F4 is already correct.
+ */
+export const accentTextMixin = "text-primary dark:text-primary-light";
 export const cardClickableMixin = "hover:bg-primary/5 dark:hover:bg-primary/5 cursor-pointer transition-colors duration-150";
 export const cardSelectedMixin = "bg-primary-bg/30 dark:bg-primary-bg/10 ring-1 ring-primary/75";

package/src/theme.css

@@ -30,11 +30,14 @@
     --tracking-title: -0.018em;   /* 20-24px — section titles */
     --tracking-heading: -0.01em;  /* <= 18px — labels; still a heading, not a headline */
 
-    /* Sub-`xs` type. MARKETING ONLY — product UI must not go below `text-xs`
-       (12px). These exist because the marketing site had ~450 hand-written
-       `text-[10px]` / `text-[11px]` classes: the tier was real, it just wasn't
-       in the system, so every page improvised it. Naming it stops the drift
-       without pretending 10px is acceptable for an admin panel. */
+    /* Sub-`xs` type. These exist because the marketing site had ~450
+       hand-written `text-[10px]` / `text-[11px]` classes: the tier was real, it
+       just wasn't in the system, so every page improvised it.
+
+       In product UI there is exactly ONE sanctioned use — `typography-micro`,
+       the uppercase field label above a value — and it earns the exception by
+       never carrying a sentence. Everything a person actually *reads* stays at
+       `text-xs` (12px) or above. `--text-3xs` remains marketing-only. */
     --text-2xs: 11px;
     --text-2xs--line-height: 1.45;
     --text-3xs: 10px;