@lotics/ui 47.6.0 → 47.6.1

package/src/section_heading.tsx

@@ -1,3 +1,4 @@
+import { Children } from "react";
 import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Text, type HeadingLevel, type TextSize } from "./text";
 import { Icon, type IconName } from "./icon";
@@ -143,7 +144,7 @@ export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
         {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
       </View>
       {description ? (
-        <Text color="zinc-500" size="sm">
+        <Text color="muted" size="sm">
           {description}
         </Text>
       ) : null}
@@ -156,10 +157,63 @@ export interface SectionHeadingProps {
   style?: StyleProp<ViewStyle>;
 }
 
+/**
+ * The heading's TRAILING slot — every child after the title, as ONE unit.
+ *
+ * Two things were wrong with laying them out as independent flex items of a
+ * wrapping row. With TWO verbs, one stayed on the title's row and the other
+ * dropped to the next at a different indent, so a single action group rendered
+ * as two unrelated controls; the group must move or stay together, and only the
+ * TITLE should ever break away from it. And a trailing child was centred against
+ * the title COLUMN — title plus description — so its height came from how many
+ * lines that description happened to wrap to, and it landed somewhere different
+ * in each section of one screen. It belongs on the title's FIRST line, which is
+ * the line box of whichever rung the altitude selected.
+ *
+ * One child keeps the old geometry exactly: with nothing to hold together there
+ * is no group, and the single verb still drops below a title too long to share
+ * the row.
+ */
 export function SectionHeading(props: SectionHeadingProps) {
+  const children = Children.toArray(props.children);
+  const [title, ...trailing] = children;
+  const grouped = trailing.length > 1;
+
   return (
-    <View style={[{ flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 12 }, props.style]}>
-      {props.children}
+    <View
+      style={[
+        { flexDirection: "row", flexWrap: "wrap", gap: 12 },
+        // Top-aligned once there is a group, so it rides the title's FIRST line
+        // instead of the centre of a column whose height is however many lines
+        // the description happened to wrap to. With a lone trailing child there
+        // is nothing to hold together and centring is still the right answer.
+        { alignItems: grouped ? "flex-start" : "center" },
+        props.style,
+      ]}
+    >
+      {grouped ? (
+        <>
+          {title}
+          {/* The group wraps INSIDE itself and shrinks; only its relationship to
+              the TITLE is rigid. `flexShrink: 0` here was wrong in the way RN-Web
+              punishes: a View is `flexShrink: 0` already, so a group wider than
+              the heading never shrinks, never wraps, and paints past the right
+              edge — visible to `checkVisibility()`, invisible to an overflow
+              check because the parent clips, and simply absent on a phone. The
+              `flexShrink: 1` + `minWidth: 0` PAIR is what actually lets it wrap;
+              shrink alone floors the box at its min-content width. */}
+          <View
+            style={{
+              flexDirection: "row", alignItems: "center", gap: 12,
+              flexWrap: "wrap", flexShrink: 1, minWidth: 0,
+            }}
+          >
+            {trailing}
+          </View>
+        </>
+      ) : (
+        props.children
+      )}
     </View>
   );
 }
@@ -168,6 +222,20 @@ export interface SectionHeadingTitleProps {
   children: React.ReactNode;
   description?: string;
   icon?: IconName;
+  /**
+   * A MARK for the thing the heading names — an `Avatar` for a company or person,
+   * a logo, a `FileThumbnail`. Rendered inside the title's own column, before the
+   * text, so the pair reads as one subject.
+   *
+   * Distinct from `icon`, which takes an `IconName` and means a CATEGORY: files,
+   * comments, a warning. An identity cannot be an icon name, and passing the mark
+   * as a sibling of this component instead makes it the heading's FIRST child —
+   * which `SectionHeading` reads as the title, so the real title joins the trailing
+   * group and the row stops pushing anything to its right edge. That failure is
+   * silent: everything renders, nothing clips, and the action simply sits in the
+   * middle of the row.
+   */
+  leading?: React.ReactNode;
   /**
    * Heading rank, when the surface's own outline needs one the altitude does not
    * give it. Leave it unset: the default is the rank of whichever rung the
@@ -221,7 +289,7 @@ const SECTION_RUNG = {
  * Optional muted `description` line; grows to push any sibling actions to the
  * right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level, weight = "semibold", info } = props;
+  const { children, description, icon, leading, level, weight = "semibold", info } = props;
   // Hoisted — a hook inside the `info ?` ternary breaks hook ordering the
   // render `info` appears or disappears.
   const words = useLoticsLocale();
@@ -229,6 +297,7 @@ export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
   return (
     <View style={{ flex: 1, minWidth: HEADING_TITLE_MIN_WIDTH, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+        {leading}
         {icon ? <Icon name={icon} size={rung.icon} /> : null}
         <Text level={level ?? rung.level} weight={weight} size={rung.size}>
           {children}
@@ -236,7 +305,7 @@ export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
         {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
       </View>
       {description ? (
-        <Text color="zinc-500" size="sm">
+        <Text color="muted" size="sm">
           {description}
         </Text>
       ) : null}

package/src/segmented_control.tsx

@@ -163,7 +163,7 @@ function Segment<T extends string>(props: SegmentProps<T>) {
           <Text
             size="sm"
             weight={selected ? "medium" : "regular"}
-            color={selected || hovered ? "zinc-900" : "zinc-700"}
+            color={selected || hovered ? "default" : "muted"}
             numberOfLines={1}
             userSelect="none"
           >

package/src/select.tsx

@@ -295,7 +295,7 @@ function SelectTrigger<T extends string, D = unknown>({
           <Text userSelect="none">{selectedItems.map((s) => s.label).join(", ")}</Text>
         )
       ) : (
-        <Text color="zinc-500" userSelect="none">
+        <Text color="muted" userSelect="none">
           {placeholder}
         </Text>
       )}

package/src/shortcut_badge.tsx

@@ -18,7 +18,7 @@ export function ShortcutBadge(props: ShortcutBadgeProps) {
 
   return (
     <View style={styles.badge}>
-      <Text size="xs" color="zinc-500" weight="medium" style={{ color: colors.zinc[400] }}>{label}</Text>
+      <Text size="xs" color="muted" weight="medium" style={{ color: colors.zinc[400] }}>{label}</Text>
     </View>
   );
 }

package/src/stacked_bar_chart.tsx

@@ -6,7 +6,7 @@ import { useLoticsLocale } from "./locale";
 import { SPACE } from "./spacing";
 import { Text } from "./text";
 import { TYPE_LEADING_TIGHT_DESKTOP, TYPE_LEADING_TIGHT_MOBILE } from "./type_ramp";
-import type { TextColor } from "./text_utils";
+import type { TextColor } from "./text_ink";
 
 export interface StackedBarSeries {
   key: string;

package/src/switcher.tsx

@@ -70,7 +70,7 @@ export function Switcher(props: SwitcherProps) {
     <Popover open={open} onOpenChange={setOpen} side={side} align={align}>
       <PopoverTrigger>
         <PressableHighlight focusRing style={[styles.trigger, { maxWidth: maxTriggerWidth }]}>
-          <Text size="sm" weight="medium" color="zinc-700" numberOfLines={1}>
+          <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
             {label}
           </Text>
           <Icon name="chevrons-up-down" size={14} color={colors.zinc["500"]} />

package/src/table.tsx

@@ -14,6 +14,7 @@ import { Animated, StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors, solid, type ColorName } from "./colors";
 import { PressableRow } from "./pressable_row";
+import { CONTROL_HEIGHT } from "./control_surface";
 import { PressDoor } from "./press_door";
 import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
@@ -72,6 +73,7 @@ interface TableCtx {
   /** Width of the ordinal gutter, 0 when the register is not counted. */
   ordinal: number;
   trailing: number;
+  align: "center" | "top";
   visibleKeys: ReadonlySet<string>;
   stacked: boolean;
 }
@@ -182,6 +184,32 @@ export interface TableProps {
   headerFill?: boolean;
   /** Reserve a trailing gutter (px) for rows that render a `trailing` slot (a ⋯ / button). */
   trailing?: number;
+  /**
+   * How a row's cells sit against each other VERTICALLY. Default `center`, which
+   * is right while every cell is one line — and wrong the moment one is not.
+   *
+   * Centring resolves PER CELL, so a cell that grows a second line moves its own
+   * content up relative to its single-line siblings, and the trailing control,
+   * centred against the tallest cell, drops below the field it acts on. The offset
+   * varies with the DATA, so the controls stop forming a column at all — measured
+   * at 10px on one row and 27px on another in the same register.
+   *
+   * `top` puts every cell and both gutters on one top edge. A single-line row is
+   * PIXEL-IDENTICAL either way, because the slack centring would have spent becomes
+   * padding — so this is safe to pass anywhere and shows only once a row is taller
+   * than one line.
+   *
+   * **Pass `top` on a register that has a TRAILING CONTROL beside multi-line cells.**
+   * That is the case it exists for: the control must line up with the field it acts
+   * on, and centring puts it wherever the tallest cell leaves it.
+   *
+   * WITHOUT a trailing control, prefer the default. Centring lets each cell's block
+   * sit in the middle of the row, so a one-line value beside a two-line neighbour
+   * reads as balanced rather than stranded at the top — and with nothing to line up
+   * against, top alignment buys nothing and costs that. Losing the control is a
+   * reason to drop `top` again, which is easy to miss because nothing breaks.
+   */
+  align?: "center" | "top";
   /** The `TableRow`s. */
   children: ReactNode;
 }
@@ -201,7 +229,7 @@ export interface TableProps {
  * keeps its current order). See `computeTableFit`.
  */
 export function Table(props: TableProps) {
-  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, counted, headerFill, trailing = 0, children } = props;
+  const { columns, sort, onSort, sortLabels, selectAll, leading = 0, count, counted, headerFill, trailing = 0, align = "center", children } = props;
   // Either prop reserves the gutter; only `count` puts a number in its header.
   // `LeadGutter` already renders an empty box when it has no number — the same
   // path a group band takes — so nothing new is needed to draw it.
@@ -222,7 +250,7 @@ export function Table(props: TableProps) {
   const visibleColumns = columns.filter((c) => fit.visibleKeys.has(c.key));
 
   return (
-    <TableContext.Provider value={{ columns, leading, ordinal, trailing, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
+    <TableContext.Provider value={{ columns, leading, ordinal, trailing, align, visibleKeys: fit.visibleKeys, stacked: fit.stacked }}>
       {/* ONE layout node: without this wrapper the header band + body land as two
           direct flex children of the app's container, and a parent column `gap`
           (the standard section spacing) opens a hole between the header and rows. */}
@@ -354,7 +382,7 @@ export function TableGroup(props: TableGroupProps) {
           {label}
         </Text>
         {count != null ? (
-          <Text size="sm" color="zinc-500" tabular>
+          <Text size="sm" color="muted" tabular>
             {count}
           </Text>
         ) : null}
@@ -540,7 +568,12 @@ export function TableRow(props: TableRowProps) {
 
   // ONE style for the column row, shared by the pressable and read-only paths
   // below, which render near-identical Views.
-  const cellsStyle = [styles.cells, { minHeight: rowMinHeight }];
+  const topAligned = ctx.align === "top";
+  const alignPad = (ROW_HEIGHT - CONTROL_HEIGHT) / 2;
+  const vAlign = topAligned
+    ? ({ alignItems: "flex-start", paddingVertical: alignPad } as const)
+    : null;
+  const cellsStyle = [styles.cells, { minHeight: rowMinHeight }, vAlign];
 
   const body = ctx.stacked ? (
     <View style={styles.stackedBody}>
@@ -574,11 +607,11 @@ export function TableRow(props: TableRowProps) {
       return <View style={styles.staticStackedRow}>{body}</View>;
     }
     return (
-      <View style={styles.staticRow}>
+      <View style={[styles.staticRow, vAlign]}>
         <LeadGutter ordinal={ordinal}>{leading}</LeadGutter>
         <View style={cellsStyle}>{cells}</View>
         {ctx.trailing > 0 ? (
-          <View style={[styles.trailingSlot, { width: ctx.trailing }]}>
+          <View style={[styles.trailingSlot, { width: ctx.trailing }, vAlign]}>
             {action}
             {trailing}
           </View>
@@ -588,7 +621,12 @@ export function TableRow(props: TableRowProps) {
   }
 
   const rowSurface = (
-    <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked} style={styles.row}>
+    // The ROW must stop centring too, not just its cells: `PressableRow` centres the
+    // cells block and the trailing gutter as WHOLE blocks, so a taller cells block
+    // left the gutter — and the control in it — floating in the middle of the row.
+    // Styling the slot's children could never reach that; the row's own axis had to.
+    <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked}
+      style={topAligned ? [styles.row, { alignItems: "flex-start" as const }] : styles.row}>
       <ArrivalWash on={justArrived === true} />
       {!ctx.stacked ? <LeadGutter ordinal={ordinal}>{leading}</LeadGutter> : null}
       {/* The door hit-tests above in-flow content; the cells/slots lift back above it
@@ -601,7 +639,7 @@ export function TableRow(props: TableRowProps) {
         <>
           <View style={cellsStyle}>{cells}</View>
           {ctx.trailing > 0 ? (
-            <View style={[styles.slot, styles.trailingSlot, { width: ctx.trailing }]}>
+            <View style={[styles.slot, styles.trailingSlot, { width: ctx.trailing }, vAlign]}>
               {action}
               {trailing}
             </View>

package/src/tabs.tsx

@@ -121,13 +121,13 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
       ) : null}
       <Text
         weight={selected ? "medium" : "regular"}
-        color={selected ? "zinc-900" : "zinc-700"}
+        color={selected ? "default" : "muted"}
         userSelect="none"
       >
         {option.label}
       </Text>
       {option.count != null ? (
-        <Text color="zinc-500" tabular userSelect="none">
+        <Text color="muted" tabular userSelect="none">
           {option.count}
         </Text>
       ) : null}

package/src/text.tsx

@@ -3,13 +3,8 @@ import React from "react";
 import { Platform, Text as RNText, TextProps as RNTextProps, StyleSheet, type TextStyle } from "react-native";
 import { fontFamilyDisplay } from "./display_font";
 import { TYPE_LEADING_TIGHT_MOBILE, TYPE_RAMP_MOBILE, trackingPx, type TypeRungName } from "./type_ramp";
-import {
-  fontFamilyMedium,
-  fontFamilyRegular,
-  fontFamilySemiBold,
-  getTextColor,
-  TextColor,
-} from "./text_utils";
+import { fontFamilyMedium, fontFamilyRegular, fontFamilySemiBold } from "./text_utils";
+import { getTextColor, TextColor } from "./text_ink";
 
 export interface TextProps {
   children?: RNTextProps["children"];

package/src/text_ink.ts

@@ -0,0 +1,96 @@
+import { colors } from "./colors";
+
+/**
+ * TEXT INK, AS AN ALIAS TABLE — the semantic layer, addressable.
+ *
+ * Two layers, and only one of them is a decision:
+ *
+ * - The **primitive** layer is the palette (`colors.zinc[600]`). It holds values
+ *   and owns nothing; it is the same Tailwind ramp anyone could paste.
+ * - The **semantic** layer is this table. It holds the actual decisions — "a line
+ *   that supports the thing above it is one step lighter than body" — and every
+ *   component addresses ink through it.
+ *
+ * This used to be a `switch` inside `getTextColor`, which made the semantic layer
+ * real but not REFERENCEABLE: the roles existed as a prop union on `Text` and
+ * nowhere else, so nothing outside a `.tsx` file could name them. That is why the
+ * palette leaked into call sites and into design: a designer picking `zinc-500` in
+ * Figma and an author typing `zinc-500` in code look like one source of truth, but
+ * the thing they agree on is a THIRD-PARTY RAMP. The decision that supporting text
+ * is zinc-600 was written in neither, so it was re-made at every call site — which
+ * is exactly how one role came to render in two inks.
+ *
+ * As a table it serializes: {@link textInkTokens} emits it in the W3C Design
+ * Tokens format with the alias intact (`{color.zinc.600}` rather than a flattened
+ * hex), which is the form Figma Variables import as ALIAS variables pointing at
+ * primitive ones. One file, both tools, and the alias survives the trip — so
+ * re-pointing `muted` moves Figma and the code together instead of starting a
+ * find-and-replace.
+ *
+ * RN-free on purpose, so `@lotics/ui/tokens` stays importable by an app that
+ * hand-rolls plain DOM without pulling react-native-web in behind it.
+ */
+export const TEXT_INK = {
+  /** Body copy and any value the reader is meant to land on. */
+  default: "zinc.900",
+  /** ALL supporting text — under a value, under a heading, anywhere. One role. */
+  muted: "zinc.600",
+  /** A disabled control's label, and a value that is not filled in ("Not set"). */
+  inactive: "zinc.400",
+  /** Requires a dark ground — illegal on the canvas. */
+  onInverse: "white",
+  danger: "red.900",
+  warning: "amber.700",
+  success: "emerald.700",
+} as const satisfies Record<string, string>;
+
+/**
+ * Derived from the table, so anything iterating the vocabulary is exhaustive by
+ * construction. Declaring the union separately would let a new ink ship without
+ * a contrast case and keep every test green.
+ */
+export type TextColor = keyof typeof TEXT_INK;
+
+export const TEXT_COLORS = Object.keys(TEXT_INK) as TextColor[];
+
+/** Resolve a `family.shade` reference against the palette. */
+function resolve(ref: string): string {
+  const [family, shade] = ref.split(".");
+  const table = colors as unknown as Record<string, unknown>;
+  if (shade === undefined) return table[family] as string;
+  return (table[family] as Record<string, string>)[shade];
+}
+
+export function getTextColor(color?: TextColor): string {
+  return resolve(TEXT_INK[color ?? "default"]);
+}
+
+/**
+ * The vocabulary in the W3C Design Tokens Community Group format, primitives and
+ * aliases in one document — the file a Figma Variables import (or Tokens Studio)
+ * reads, so the design tool and the code resolve `muted` from the same place.
+ *
+ * The alias is emitted as a REFERENCE, never a resolved hex. A flattened export
+ * would hand Figma seven unrelated colours and lose the only thing worth syncing:
+ * that `muted` IS `zinc.600`, and moves when it moves.
+ */
+export function textInkTokens(): string {
+  const palette = colors as unknown as Record<string, unknown>;
+  const color: Record<string, unknown> = {};
+  for (const [family, value] of Object.entries(palette)) {
+    if (typeof value === "string") {
+      color[family] = { $type: "color", $value: value };
+    } else if (value && typeof value === "object") {
+      const scale: Record<string, unknown> = {};
+      for (const [shade, hex] of Object.entries(value as Record<string, string>)) {
+        scale[shade] = { $type: "color", $value: hex };
+      }
+      color[family] = scale;
+    }
+  }
+  const text: Record<string, unknown> = {};
+  for (const [role, ref] of Object.entries(TEXT_INK)) {
+    text[role] = { $type: "color", $value: `{color.${ref}}` };
+  }
+  return JSON.stringify({ color, text }, null, 2);
+}

package/src/text_link.tsx

@@ -1,7 +1,7 @@
 import { Text, type TextProps } from "./text";
 import { Icon, type IconName } from "./icon";
 import { colors } from "./colors";
-import { getTextColor } from "./text_utils";
+import { getTextColor } from "./text_ink";
 
 export interface TextLinkProps extends TextProps {
   /** Optional leading icon. */

package/src/text_utils.ts

@@ -1,53 +1,8 @@
 import { Platform, TextStyle } from "react-native";
-import { colors } from "./colors";
+import { getTextColor } from "./text_ink";
 import { multilineInputHeight } from "./input_metrics";
 import { TYPE_RAMP_DESKTOP, TYPE_RAMP_MOBILE } from "./type_ramp";
 
-export type TextColor =
-  | "default"
-  | "muted"
-  | "inverted"
-  | "danger"
-  | "warning"
-  | "success"
-  | "zinc-900"
-  | "zinc-700"
-  | "zinc-500"
-  | "zinc-400";
-
-export function getTextColor(color?: TextColor): string {
-  switch (color) {
-    case "default":
-      return colors.zinc["900"];
-    case "muted":
-      return colors.zinc["600"];
-    case "zinc-900":
-      return colors.zinc["900"];
-    case "zinc-700":
-      return colors.zinc["700"];
-    case "zinc-500":
-      return colors.zinc["500"];
-    // The disabled ink — light enough that a control reads inert at a glance
-    // (muted/600 still reads as body ink on the control's resting surface).
-    case "zinc-400":
-      return colors.zinc["400"];
-    case "inverted":
-      return colors.white;
-    // Valence set — the lightest status weight: a state WORD whose meaning is in
-    // the word, colored for reinforcement (never color-only). Red sits darker at
-    // 900; green/amber use 700 to stay recognizably their hue while clearing AA on
-    // white (600 would fail).
-    case "danger":
-      return colors.red["900"];
-    case "warning":
-      return colors.amber["700"];
-    case "success":
-      return colors.emerald["700"];
-    default:
-      return colors.zinc[900];
-  }
-}
-
 // The three rungs live in their own platform-split module — see `font_family.ts`.
 // Re-exported here so every existing consumer keeps one import.
 export { fontFamilyRegular, fontFamilyMedium, fontFamilySemiBold } from "./font_family";

package/src/thumbnail_stack.tsx

@@ -156,7 +156,7 @@ export function ThumbnailStack(props: ThumbnailStackProps) {
         >
           {/* The rung's own type — a fixed size here is how a stack ends up
               with a 14px count beside 12px marks. */}
-          <Text size={AVATAR_TEXT[size]} weight="medium" color="zinc-700" aria-hidden>
+          <Text size={AVATAR_TEXT[size]} weight="medium" color="muted" aria-hidden>
             {`+${hidden}`}
           </Text>
         </View>

package/src/time_picker.tsx

@@ -105,7 +105,7 @@ export function TimePicker(props: TimePickerProps) {
             {formatTimeOfDay(value, localeTag)}
           </Text>
         ) : (
-          <Text size="sm" color="zinc-500" userSelect="none">
+          <Text size="sm" color="muted" userSelect="none">
             {placeholder}
           </Text>
         )}

package/src/timeline.tsx

@@ -119,7 +119,7 @@ export function Timeline(props: TimelineProps) {
               numberOfLines={expanded ? undefined : 2}
               // The same ink an unfilled field draws (`Not set`, `No date set`),
               // so an unwritten row reads as unwritten everywhere it appears.
-              color={item.placeholder ? "zinc-400" : undefined}
+              color={item.placeholder ? "inactive" : undefined}
               style={{ flex: 1 }}
             >
               {item.label}

package/src/tokens.ts

@@ -20,10 +20,24 @@
  *   colors.background   → var(--lotics-background)
  *   colors.border       → var(--lotics-border)
  *
- * No semantic abstraction (no `--lotics-fg`, `--lotics-danger`) — those
- * names don't exist in the parent's TS code, so introducing them only
- * in the iframe creates two vocabularies the agent + a new developer
- * have to learn separately.
+ * TWO LAYERS, and the second one is where the decisions live. The palette above
+ * is primitives: values, owned by nobody, the same ramp anyone could paste. The
+ * semantic layer is {@link TEXT_INK} — `muted` → `zinc.600` — and it holds the
+ * actual rules ("supporting text is one step lighter than body"). Components
+ * address ink only through it.
+ *
+ * This file used to claim the semantic names "don't exist in the parent's TS
+ * code", and that was wrong about its own codebase: the roles had always existed
+ * as `Text`'s `color` union, used hundreds of times. They were just not
+ * ADDRESSABLE — nothing outside a `.tsx` could name one — so the palette leaked
+ * into call sites and into design, and one role ended up rendering in two inks.
+ *
+ * Emitting only primitives is also what broke the Figma story. A designer picking
+ * `zinc-500` and an author typing `zinc-500` look like one source of truth, but
+ * what they agree on is a THIRD-PARTY RAMP; the decision itself is written in
+ * neither tool. {@link textInkTokens} emits both layers with the alias intact, in
+ * the W3C Design Tokens format Figma Variables import as alias variables — so the
+ * rule has one home and moving it moves both sides.
  *
  * Spacing / type / weight / radius are iframe-side conveniences with no
  * parent equivalent (parent uses bare numeric pixel values inline).
@@ -33,6 +47,8 @@
 
 export { colors } from "./colors";
 import { colors } from "./colors";
+export { TEXT_INK, TEXT_COLORS, getTextColor, textInkTokens, type TextColor } from "./text_ink";
+import { TEXT_INK } from "./text_ink";
 
 /**
  * Spacing scale (4px base unit). Use for padding, margin, gap.
@@ -150,5 +166,13 @@ export function getCssVariables(): string {
     lines.push(`  --lotics-radius-${key}: ${value}px;`);
   }
 
+  // TEXT INK — emitted as a var() pointing at the PRIMITIVE, not as a copied hex,
+  // so `--lotics-text-muted` and `colors.zinc[600]` cannot drift apart and a
+  // hand-rolled DOM surface can address the same role a component does.
+  for (const [role, ref] of Object.entries(TEXT_INK)) {
+    const primitive = ref.replace(".", "-");
+    lines.push(`  --lotics-ink-${role.toLowerCase()}: var(--lotics-${primitive});`);
+  }
+
   return `:root {\n${lines.join("\n")}\n}`;
 }

package/src/tooltip.tsx

@@ -156,7 +156,7 @@ export function TooltipProvider({ children }: { children: React.ReactNode }) {
                   }),
             }}
           >
-            <Text numberOfLines={1} size="sm" color="inverted">
+            <Text numberOfLines={1} size="sm" color="onInverse">
               {tooltip.text}
             </Text>
           </div>,

package/src/uploading_thumbnail.tsx

@@ -172,7 +172,7 @@ function OverlayStack(props: { tone?: "error"; compact: boolean; label: string;
 
 function OverlayLabel({ children }: { children: string }) {
   return (
-    <Text size="xs" weight="medium" color="inverted" numberOfLines={2} style={styles.overlayLabel} userSelect="none">
+    <Text size="xs" weight="medium" color="onInverse" numberOfLines={2} style={styles.overlayLabel} userSelect="none">
       {children}
     </Text>
   );