@colixsystems/widget-sdk 0.161.0 → 0.163.0

package/README.md

@@ -73,7 +73,40 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.160.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.163.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.163.0 (contract 1.126.0)
+
+**A themed tab strip: `Tabs`, and the `tabs` theme scope.** `<Tabs items={[{ key, label, icon? }]} value={tab} onChange={setTab} />` draws a strip whose look — a segmented control, pills, or an underline — and whose colours and corners come from **Theme Settings > Tabs** (`themeConfig.components.tabs`). It draws the strip only; render the selected panel yourself. The page Tabs container now renders through the same component on the web Player and in the exported app, so a page's tabs and a widget's tabs match, and the two hosts no longer draw different strips. Unthemed, the strip is the segmented control the exported app always drew.
+
+```jsx
+const [tab, setTab] = useState("open");
+<Tabs items={[{ key: "open", label: "Open" }, { key: "done", label: "Done", icon: "check" }]} value={tab} onChange={setTab} />
+{tab === "open" ? <OpenOrders /> : <DoneOrders />}
+```
+
+Pass `variant` ("segmented" | "pill" | "underline"), `activeColor`, `activeTextColor`, `textColor` or `radius` to override one strip, or declare the style fields `tabsStyle`, `tabsActiveColor`, `tabsActiveTextColor`, `tabsTextColor` and `tabsRadius` so an author can.
+
+The component-token vocabulary gains an **`enum`** type (`{ type: "enum", values }`), first used by `tabs.style`; `CONTRACT.themeComponentTabStyles` lists the styles.
+
+### What's new in 0.162.0 (contract 1.125.0)
+
+**Themed list rows: `List`, `ListRow`, `EmptyState`, and the `list` theme scope.** Each widget that showed records used to hand-roll its rows from `View` + `Pressable`, so two lists in one app disagreed on padding, dividers and corners. `<ListRow>` draws one row whose padding, minimum height, divider, corner radius and background come from **Theme Settings > Lists** (`themeConfig.components.list`), and `<List>` spaces its rows and passes any override down to them. Unthemed, a row is the flush, hairline band the built-in Data List always drew. When the theme sets a `gap`, rows become separate tiles on the surface, outlined by the divider. A selected row carries an accent bar as well as the tint, the last row of a `<List>` has no divider, a pressable row never drops below 44px, and every override passes the same bounds a theme value does. `<EmptyState>` is the matching "nothing here" panel.
+
+```jsx
+<List>
+  {items.map((item) => (
+    <ListRow key={item.id} title={item.name} subtitle={item.email} onPress={() => open(item)} selected={item.id === selectedId} />
+  ))}
+</List>
+{items.length === 0 ? <EmptyState icon="inbox" title="No orders yet" message="New orders appear here." /> : null}
+```
+
+To let an author restyle one widget's rows, declare the style fields `listRowPadding`, `listRowMinHeight`, `listRowGap`, `listRowRadius`, `listRowBackground`, `listDividerColor` and `listDividerWidth`. They follow the theme until set, like the `card*` fields do, and you pass them through as the matching `ListRow` props (`rowPadding`, …).
+
+**`textRoleStyle(role, theme.typography, theme.colors)`** returns the complete style of a semantic text tier (`display`, `title`, `subtitle`, `body`, `caption`, `overline`) — size, absolute line height, weight, tracking, case, the tier's face and its colour. The built-in widgets use the same function, so your text matches theirs.
+
+Additive: a theme without a `list` scope renders exactly as before.
 
 ### What's new in 0.161.0 (contract 1.124.0)
 
@@ -1767,6 +1800,9 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.
 - `parseMarkdown`, `markdownToPlainText`, `parseMarkdownImage`, `formatMarkdownImage`, `stripHtmlToMarkdown`, `MARKDOWN_IMAGE_SIZES` — the same grammar as pure helpers, for content you inspect rather than render: the block list, a marker-free projection (list previews, search, a11y labels), the one-line image form read and written, a legacy-HTML row normalised to markdown on read, and the closed size list (`small` | `medium` | `large` | `full`).
 - `isSafeMarkdownImageSrc`, `isHttpImageSrc`, `normaliseMarkdownImageSize`, `readMarkdownAlt` — the image half of that grammar, for a widget rendering images itself via `renderImage`. `isSafeMarkdownImageSrc` is the same allowlist the parser applies (an `http(s)` URL or a filestore id; a `javascript:` scheme is refused), so the widget and the parser cannot disagree about which src is renderable.
+- `List`, `ListRow`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row from `View` + `Pressable`.
+- `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
+- `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
 ## Design & visual polish

package/dist/contract.cjs

@@ -228,6 +228,9 @@ function isThemeColorTokenRef(value) {
 // Single source for four consumers — the build runner's set_theme coercion, the
 // shared host resolver, the planner prompt, and the SDK docs — so the vocabulary
 // cannot drift between what Mason may emit and what a host actually applies.
+// The looks a `tabs.style` token may name; `<Tabs>` draws each.
+const THEME_TAB_STYLES = Object.freeze(["segmented", "pill", "underline"]);
+
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
 // sc-3857 — the `textTransform` token's closed enum, matching the per-instance
@@ -433,6 +436,28 @@ const DANGER_BUTTON_FIELDS = Object.freeze({
   borderColor: "dangerBorderColor",
 });
 
+// The list-row vocabulary. Bound by name as well as to the Data List, so a
+// custom widget that declares `listRowPadding` follows "Lists" like a built-in.
+const LIST_ROW_FIELDS = Object.freeze({
+  rowPadding: "listRowPadding",
+  rowMinHeight: "listRowMinHeight",
+  gap: "listRowGap",
+  radius: "listRowRadius",
+  background: "listRowBackground",
+  dividerColor: "listDividerColor",
+  dividerWidth: "listDividerWidth",
+});
+
+// The tab-strip vocabulary. Bound by name as well as onto User Management,
+// whose Users / Groups / Invites strip is drawn by the SDK <Tabs>.
+const TABS_FIELDS = Object.freeze({
+  style: "tabsStyle",
+  activeColor: "tabsActiveColor",
+  activeTextColor: "tabsActiveTextColor",
+  textColor: "tabsTextColor",
+  radius: "tabsRadius",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -584,6 +609,40 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
     }),
   }),
+  // Record rows: `<ListRow>` reads this scope directly; the fields bind it
+  // onto widgets. No uiDefault on the height: it has no theme token.
+  list: Object.freeze({
+    label: "Lists",
+    universalFields: LIST_ROW_FIELDS,
+    tokens: Object.freeze({
+      rowPadding: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "spacing.md" }),
+      rowMinHeight: Object.freeze({ type: "size", min: 32, max: 96 }),
+      gap: Object.freeze({ type: "size", min: 0, max: 24 }),
+      radius: Object.freeze({ type: "size", min: 0, max: 32 }),
+      background: Object.freeze({ type: "color" }),
+      dividerColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      dividerWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.data-list": LIST_ROW_FIELDS,
+    }),
+  }),
+  // Tab strips: `<Tabs>` and the page Tabs container read this scope directly;
+  // the fields bind it onto widgets. `style` is the first `enum` token.
+  tabs: Object.freeze({
+    label: "Tabs",
+    universalFields: TABS_FIELDS,
+    tokens: Object.freeze({
+      style: Object.freeze({ type: "enum", values: THEME_TAB_STYLES }),
+      activeColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      activeTextColor: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 24 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.user-management": TABS_FIELDS,
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2173,6 +2232,34 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "List",
+    description:
+      "Themed list container. `<List>{rows.map((r) => <ListRow key={r.id} title={r.name} />)}</List>`. Spaces and insets its `<ListRow>` children the way the app's look says (flush rows with hairlines, or separated rounded rows), and hands any row override you pass (`rowPadding`, `rowMinHeight`, `gap`, `radius`, `background`, `dividerColor`, `dividerWidth`) down to every row. Props: those overrides, `style`, `testID`. Put it inside a `ScrollView` (or bound its height) for long lists.",
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ListRow",
+    description:
+      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block, for a multi-column row), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "EmptyState",
+    description:
+      'Themed empty / zero-data state. `<EmptyState icon="inbox" title="No orders yet" message="New orders appear here." />`. THE way to say "nothing here" — a muted panel with an icon, a title and a caption, centred, in the app\'s own surface and text tiers. Props: `icon` (a lucide icon name, default "inbox"; pass null for none), `title`, `message`, `children` (an action, e.g. a button), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Tabs",
+    description:
+      'Themed tab strip. `<Tabs items={[{ key: "open", label: "Open" }, { key: "done", label: "Done", icon: "check" }]} value={tab} onChange={setTab} />`. THE way to switch between views inside a widget: its look (a segmented control, pills, or an underline — Theme Settings > Tabs) and its colours and corner radius come from the theme, so every tab strip in the app matches, including the page Tabs container. It draws the strip only; render the selected panel yourself below it. Never hand-roll tabs from `Pressable` chips. Props: `items` (`[{ key, label, icon?, disabled?, testID? }]`, icon is a lucide name), `value` (the selected key), `onChange(key)`, `accessibilityLabel`, `style`, `testID`, and the overrides `variant` ("segmented" | "pill" | "underline"), `activeColor`, `activeTextColor`, `textColor`, `radius`. The strip scrolls sideways when the tabs overflow. Declare `tabsStyle` / `tabsActiveColor` / `tabsActiveTextColor` / `tabsTextColor` / `tabsRadius` style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -4357,7 +4444,17 @@ const CONTRACT = deepFreeze({
   // 1.123.0: behaviour (sc-8595) — useDatastoreQuery / useDatastoreRecord
   //    keep their data while a changed query or refetch runs; `loading` only
   //    until the first result for the table/record, new `fetching` flag.
-  version: "1.124.0",
+  // 1.125.0: additive — the `list` component scope (row padding, height, gap,
+  //    radius, background, divider) and the `List` / `ListRow` / `EmptyState`
+  //    primitives that read it, plus `textRoleStyle` and its role helpers.
+  //    Widgets each hand-rolled their rows, so two lists in one app disagreed.
+  //    Additive: a theme without `list` paints the rows exactly as before.
+  // 1.126.0: additive — the `tabs` component scope and the `Tabs` primitive
+  //    that reads it, and the `enum` component-token type (`values`), first
+  //    used by `tabs.style`. The page Tabs container renders through `Tabs` on
+  //    both hosts. Additive: an unthemed strip is the segmented control the
+  //    export always drew.
+  version: "1.126.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4370,6 +4467,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,
+  themeComponentTabStyles: THEME_TAB_STYLES,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,

package/dist/contract.js

@@ -228,6 +228,9 @@ function isThemeColorTokenRef(value) {
 // Single source for four consumers — the build runner's set_theme coercion, the
 // shared host resolver, the planner prompt, and the SDK docs — so the vocabulary
 // cannot drift between what Mason may emit and what a host actually applies.
+// The looks a `tabs.style` token may name; `<Tabs>` draws each.
+const THEME_TAB_STYLES = Object.freeze(["segmented", "pill", "underline"]);
+
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
 // sc-3857 — the `textTransform` token's closed enum, matching the per-instance
@@ -433,6 +436,28 @@ const DANGER_BUTTON_FIELDS = Object.freeze({
   borderColor: "dangerBorderColor",
 });
 
+// The list-row vocabulary. Bound by name as well as to the Data List, so a
+// custom widget that declares `listRowPadding` follows "Lists" like a built-in.
+const LIST_ROW_FIELDS = Object.freeze({
+  rowPadding: "listRowPadding",
+  rowMinHeight: "listRowMinHeight",
+  gap: "listRowGap",
+  radius: "listRowRadius",
+  background: "listRowBackground",
+  dividerColor: "listDividerColor",
+  dividerWidth: "listDividerWidth",
+});
+
+// The tab-strip vocabulary. Bound by name as well as onto User Management,
+// whose Users / Groups / Invites strip is drawn by the SDK <Tabs>.
+const TABS_FIELDS = Object.freeze({
+  style: "tabsStyle",
+  activeColor: "tabsActiveColor",
+  activeTextColor: "tabsActiveTextColor",
+  textColor: "tabsTextColor",
+  radius: "tabsRadius",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -584,6 +609,40 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
     }),
   }),
+  // Record rows: `<ListRow>` reads this scope directly; the fields bind it
+  // onto widgets. No uiDefault on the height: it has no theme token.
+  list: Object.freeze({
+    label: "Lists",
+    universalFields: LIST_ROW_FIELDS,
+    tokens: Object.freeze({
+      rowPadding: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "spacing.md" }),
+      rowMinHeight: Object.freeze({ type: "size", min: 32, max: 96 }),
+      gap: Object.freeze({ type: "size", min: 0, max: 24 }),
+      radius: Object.freeze({ type: "size", min: 0, max: 32 }),
+      background: Object.freeze({ type: "color" }),
+      dividerColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      dividerWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.data-list": LIST_ROW_FIELDS,
+    }),
+  }),
+  // Tab strips: `<Tabs>` and the page Tabs container read this scope directly;
+  // the fields bind it onto widgets. `style` is the first `enum` token.
+  tabs: Object.freeze({
+    label: "Tabs",
+    universalFields: TABS_FIELDS,
+    tokens: Object.freeze({
+      style: Object.freeze({ type: "enum", values: THEME_TAB_STYLES }),
+      activeColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      activeTextColor: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 24 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.user-management": TABS_FIELDS,
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2173,6 +2232,34 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "List",
+    description:
+      "Themed list container. `<List>{rows.map((r) => <ListRow key={r.id} title={r.name} />)}</List>`. Spaces and insets its `<ListRow>` children the way the app's look says (flush rows with hairlines, or separated rounded rows), and hands any row override you pass (`rowPadding`, `rowMinHeight`, `gap`, `radius`, `background`, `dividerColor`, `dividerWidth`) down to every row. Props: those overrides, `style`, `testID`. Put it inside a `ScrollView` (or bound its height) for long lists.",
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ListRow",
+    description:
+      'Themed list row. `<ListRow title={item.name} subtitle={item.email} leading={<Icon name="user" size={20} />} trailing={<Text>…</Text>} onPress={() => open(item)} selected={item.id === selectedId} />`. THE way to draw one row of records: its padding, minimum height, divider, corner radius and background come from the theme\'s Lists settings, so every list in the app matches — never hand-roll a row from `View` + `Pressable`. Props: `title`, `subtitle` (rendered in the subtitle / caption text tiers), `leading` / `trailing` nodes, `children` (replaces the title block, for a multi-column row), `onPress` (makes it a button with a press state), `selected`, `disabled`, `divider` (default true; pass false on the last row), `accessibilityLabel`, `style`, `testID`, plus the same per-row overrides `<List>` takes. Declare `listRowPadding` / `listRowRadius` / … style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "EmptyState",
+    description:
+      'Themed empty / zero-data state. `<EmptyState icon="inbox" title="No orders yet" message="New orders appear here." />`. THE way to say "nothing here" — a muted panel with an icon, a title and a caption, centred, in the app\'s own surface and text tiers. Props: `icon` (a lucide icon name, default "inbox"; pass null for none), `title`, `message`, `children` (an action, e.g. a button), `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Tabs",
+    description:
+      'Themed tab strip. `<Tabs items={[{ key: "open", label: "Open" }, { key: "done", label: "Done", icon: "check" }]} value={tab} onChange={setTab} />`. THE way to switch between views inside a widget: its look (a segmented control, pills, or an underline — Theme Settings > Tabs) and its colours and corner radius come from the theme, so every tab strip in the app matches, including the page Tabs container. It draws the strip only; render the selected panel yourself below it. Never hand-roll tabs from `Pressable` chips. Props: `items` (`[{ key, label, icon?, disabled?, testID? }]`, icon is a lucide name), `value` (the selected key), `onChange(key)`, `accessibilityLabel`, `style`, `testID`, and the overrides `variant` ("segmented" | "pill" | "underline"), `activeColor`, `activeTextColor`, `textColor`, `radius`. The strip scrolls sideways when the tabs overflow. Declare `tabsStyle` / `tabsActiveColor` / `tabsActiveTextColor` / `tabsTextColor` / `tabsRadius` style fields and pass them through to let an author override one widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -4353,7 +4440,17 @@ const CONTRACT = deepFreeze({
   // 1.123.0: behaviour (sc-8595) — useDatastoreQuery / useDatastoreRecord
   //    keep their data while a changed query or refetch runs; `loading` only
   //    until the first result for the table/record, new `fetching` flag.
-  version: "1.124.0",
+  // 1.125.0: additive — the `list` component scope (row padding, height, gap,
+  //    radius, background, divider) and the `List` / `ListRow` / `EmptyState`
+  //    primitives that read it, plus `textRoleStyle` and its role helpers.
+  //    Widgets each hand-rolled their rows, so two lists in one app disagreed.
+  //    Additive: a theme without `list` paints the rows exactly as before.
+  // 1.126.0: additive — the `tabs` component scope and the `Tabs` primitive
+  //    that reads it, and the `enum` component-token type (`values`), first
+  //    used by `tabs.style`. The page Tabs container renders through `Tabs` on
+  //    both hosts. Additive: an unthemed strip is the segmented control the
+  //    export always drew.
+  version: "1.126.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4366,6 +4463,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,
+  themeComponentTabStyles: THEME_TAB_STYLES,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,

package/dist/index.d.ts

@@ -2553,6 +2553,117 @@ export const Overlay: (props: {
   children?: ReactNode;
 }) => any;
 
+/** Per-list row overrides; unset values follow Theme Settings > Lists. */
+export interface ListRowTokens {
+  rowPadding?: number;
+  rowMinHeight?: number;
+  /** Space between rows. Above 0, rows are separate tiles on the muted surface. */
+  gap?: number;
+  radius?: number;
+  background?: string;
+  dividerColor?: string;
+  dividerWidth?: number;
+}
+
+/**
+ * Themed list container. Spaces and insets its `<ListRow>` children the way the
+ * app's look says, and hands its overrides down to every row.
+ */
+export const List: (props: ListRowTokens & {
+  style?: any;
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
+/**
+ * Themed list row. Padding, height, divider, radius and background come from
+ * the theme's `list` scope, so every list in the app matches.
+ *
+ * @example
+ *   <List>
+ *     {items.map((item) => (
+ *       <ListRow key={item.id} title={item.name} subtitle={item.email} onPress={() => open(item)} />
+ *     ))}
+ *   </List>
+ */
+export const ListRow: (props: ListRowTokens & {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  leading?: ReactNode;
+  trailing?: ReactNode;
+  /** Makes the row a button with a press state. */
+  onPress?: () => void;
+  selected?: boolean;
+  disabled?: boolean;
+  /** Defaults to true; pass false on the last row. */
+  divider?: boolean;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+  /** Replaces the title block, e.g. for a multi-column row. */
+  children?: ReactNode;
+}) => any;
+
+/** Themed empty / zero-data state: icon, title and caption on the muted surface. */
+export const EmptyState: (props: {
+  /** A lucide icon name; defaults to "inbox". Pass null for none. */
+  icon?: string | null;
+  title?: ReactNode;
+  message?: ReactNode;
+  style?: any;
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
+export type TabStyle = "segmented" | "pill" | "underline";
+
+/**
+ * Themed tab strip. Its look (segmented, pills or underline), colours and
+ * corners come from the theme's `tabs` scope, so every strip in the app —
+ * including the page Tabs container — matches. Draws the strip only; render
+ * the selected panel yourself.
+ *
+ * @example
+ *   const [tab, setTab] = useState("open");
+ *   <Tabs items={[{ key: "open", label: "Open" }, { key: "done", label: "Done" }]} value={tab} onChange={setTab} />
+ */
+export const Tabs: (props: {
+  items: Array<{ key: string; label: ReactNode; icon?: string; disabled?: boolean; testID?: string }>;
+  value?: string;
+  onChange?: (key: string) => void;
+  /** Overrides the theme's tab style for this strip. */
+  variant?: TabStyle;
+  activeColor?: string;
+  activeTextColor?: string;
+  textColor?: string;
+  radius?: number;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+export type TextRole = "display" | "title" | "subtitle" | "body" | "caption" | "overline";
+export const TEXT_ROLES: readonly TextRole[];
+export const TEXT_TRANSFORMS: readonly string[];
+export const LINE_HEIGHT_RATIO: number;
+export const LEGACY_FONT_ROLE_ALIASES: Readonly<Record<string, TextRole>>;
+export const DEFAULT_TEXT_ROLE: TextRole;
+export const ROLE_FACES: Readonly<Record<TextRole, "heading" | "body">>;
+export function normaliseTextRole(value: unknown): TextRole;
+export function roleTokens(role: string, typography: any): Record<string, any> | null;
+export function roleColor(tokens: any, colors: any): string | undefined;
+/**
+ * The full text style for a semantic tier — size, absolute line height, weight,
+ * tracking, case, the tier's face and its colour — from the theme.
+ *
+ * @example
+ *   const theme = useTheme();
+ *   <Text style={textRoleStyle("caption", theme.typography, theme.colors)}>Updated 2m ago</Text>
+ */
+export function textRoleStyle(role: TextRole | string, typography: any, colors?: any): Record<string, any>;
+
 // ----------------------------------------------------- formatted content
 // sc-6970 — widgets have no HTML path: they render through React Native
 // primitives, which have no `dangerouslySetInnerHTML` on either host. Content

package/dist/index.js

@@ -189,6 +189,23 @@ export {
   applyPendingReactions,
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
+// Themed list building blocks; rows follow the theme's `list` scope.
+export { List, ListRow, EmptyState } from "./list.js";
+// A themed tab strip; follows the theme's `tabs` scope.
+export { Tabs } from "./tabs.js";
+// The semantic text tiers, shared with the built-in widgets.
+export {
+  textRoleStyle,
+  TEXT_ROLES,
+  TEXT_TRANSFORMS,
+  LINE_HEIGHT_RATIO,
+  LEGACY_FONT_ROLE_ALIASES,
+  DEFAULT_TEXT_ROLE,
+  ROLE_FACES,
+  normaliseTextRole,
+  roleTokens,
+  roleColor,
+} from "./text-roles.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.js";
 export { styleGroup } from "./style-group.js";

package/dist/index.native.js

@@ -182,6 +182,23 @@ export {
   applyPendingReactions,
 } from "./emoji-reactions.js";
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
+// Themed list building blocks; rows follow the theme's `list` scope.
+export { List, ListRow, EmptyState } from "./list.native.js";
+// A themed tab strip; follows the theme's `tabs` scope.
+export { Tabs } from "./tabs.native.js";
+// The semantic text tiers, shared with the built-in widgets.
+export {
+  textRoleStyle,
+  TEXT_ROLES,
+  TEXT_TRANSFORMS,
+  LINE_HEIGHT_RATIO,
+  LEGACY_FONT_ROLE_ALIASES,
+  DEFAULT_TEXT_ROLE,
+  ROLE_FACES,
+  normaliseTextRole,
+  roleTokens,
+  roleColor,
+} from "./text-roles.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";
 export { pressableLift } from "./interaction.native.js";
 export { styleGroup } from "./style-group.js";

package/dist/list-tokens.js

@@ -0,0 +1,68 @@
+// The values `<List>` / `<ListRow>` paint with, resolved from the theme's `list`
+// component scope. Platform-free, like overlay-tokens.js, so both hosts render
+// a row from the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { mixHex } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+// A row with no themed height still meets the 44px touch-target floor.
+export const LIST_ROW_MIN_HEIGHT = 44;
+
+// The per-row overrides a widget may pass, named as the theme tokens are.
+export const LIST_TOKEN_NAMES = Object.freeze([
+  "rowPadding",
+  "rowMinHeight",
+  "gap",
+  "radius",
+  "background",
+  "dividerColor",
+  "dividerWidth",
+]);
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pick(overrides, scope, name) {
+  if (overrides && isSet(overrides[name])) return overrides[name];
+  if (scope && isSet(scope[name])) return scope[name];
+  return undefined;
+}
+
+/**
+ * Resolve one list's row values: explicit override, then the theme's `list`
+ * scope, then the theme tokens. Both layers pass the contract's own bounds, so
+ * a hand-edited or planned value cannot reach a native style unvalidated.
+ * Unthemed, a row is the flush band with a 1px hairline the Data List drew;
+ * a `gap` makes separate tiles on the surface, outlined by the divider.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-list values keyed by LIST_TOKEN_NAMES.
+ */
+export function resolveListTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const fallback = DEFAULT_THEME_TOKENS;
+  const colors = base.colors || fallback.colors;
+  const spacing = base.spacing || fallback.spacing;
+  const scope = base.components && base.components.list;
+  const own = normaliseThemeComponents({ list: overrides }).list;
+
+  const gap = pick(own, scope, "gap") ?? 0;
+  const separated = gap > 0;
+  const background = pick(own, scope, "background") ?? (separated ? colors.surface : undefined);
+  return {
+    rowPadding: pick(own, scope, "rowPadding") ?? spacing.md,
+    rowMinHeight: pick(own, scope, "rowMinHeight") ?? LIST_ROW_MIN_HEIGHT,
+    gap,
+    separated,
+    // A flush band has square ends; a divider would curve into round ones.
+    radius: separated ? pick(own, scope, "radius") ?? 0 : 0,
+    background,
+    dividerColor: pick(own, scope, "dividerColor") ?? colors.border,
+    dividerWidth: pick(own, scope, "dividerWidth") ?? 1,
+    selectedBackground: colors.primarySoft || colors.surfaceMuted,
+    selectedAccent: colors.primary,
+    pressedBackground: mixHex(colors.onSurface, background || colors.surface, 0.94),
+  };
+}

package/dist/list-view.js

@@ -0,0 +1,215 @@
+// The ONE implementation behind the `<List>`, `<ListRow>` and `<EmptyState>`
+// SDK primitives. The platform bindings (`list.js` / `list.native.js`) differ
+// only in where the primitives come from, so the hosts cannot drift.
+//
+// Every widget drawing a list of records used to hand-roll its rows, so two
+// widgets in one app disagreed on padding, dividers and radius. These read the
+// theme's `list` scope, which a look sets once for the whole app.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { resolveListTokens, LIST_TOKEN_NAMES } from "./list-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+
+// Outside a widget host (a test, a preview) the defaults still paint a row.
+function useListTheme() {
+  return useHostTheme() || DEFAULT_THEME_TOKENS;
+}
+
+function listOverrides(props) {
+  const out = {};
+  for (const name of LIST_TOKEN_NAMES) {
+    if (props[name] !== undefined && props[name] !== null) out[name] = props[name];
+  }
+  return out;
+}
+
+/**
+ * Bind the shared list components to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeList(rn) {
+  const { View, Text, Pressable } = rn;
+  const ListContext = React.createContext(null);
+
+  function List(props) {
+    const { children, style, testID } = props;
+    const theme = useListTheme();
+    const inherited = React.useContext(ListContext);
+    const overrides = { ...inherited, ...listOverrides(props) };
+    const tokens = resolveListTokens(theme, overrides);
+    // No divider under the last row: the list's own edge ends it.
+    const rows = React.Children.toArray(children);
+    const last = rows.length - 1;
+    const content = rows.map((row, i) =>
+      i === last && React.isValidElement(row) && row.props.divider === undefined
+        ? React.cloneElement(row, { divider: false })
+        : row,
+    );
+    return React.createElement(
+      ListContext.Provider,
+      { value: overrides },
+      React.createElement(View, { style: [{ gap: tokens.gap }, style], testID }, content),
+    );
+  }
+  List.displayName = "List";
+
+  function ListRow(props) {
+    const {
+      title,
+      subtitle,
+      leading,
+      trailing,
+      onPress,
+      selected = false,
+      disabled = false,
+      divider = true,
+      accessibilityLabel,
+      style,
+      testID,
+      children,
+    } = props;
+    const theme = useListTheme();
+    const inherited = React.useContext(ListContext);
+    const tokens = resolveListTokens(theme, {
+      ...inherited,
+      ...listOverrides(props),
+    });
+    const { colors, spacing, typography } = theme;
+
+    const pressable = typeof onPress === "function";
+    // A tile is outlined; a flush band is separated by its bottom divider.
+    const edge = tokens.separated
+      ? tokens.dividerWidth > 0
+        ? { borderWidth: tokens.dividerWidth, borderColor: tokens.dividerColor }
+        : null
+      : divider && tokens.dividerWidth > 0
+        ? { borderBottomWidth: tokens.dividerWidth, borderColor: tokens.dividerColor }
+        : null;
+    const rowStyle = {
+      flexDirection: "row",
+      alignItems: "center",
+      gap: spacing.md,
+      paddingHorizontal: tokens.rowPadding,
+      paddingVertical: tokens.rowPadding,
+      // A dense look may shrink a static row, never a tap target.
+      minHeight: pressable ? Math.max(tokens.rowMinHeight, 44) : tokens.rowMinHeight,
+      borderRadius: tokens.radius,
+      ...(tokens.background ? { backgroundColor: tokens.background } : null),
+      ...edge,
+      // A tint alone is too faint to read as the current row.
+      ...(selected
+        ? {
+            backgroundColor: tokens.selectedBackground,
+            borderLeftWidth: 3,
+            borderLeftColor: tokens.selectedAccent,
+          }
+        : null),
+    };
+
+    const body =
+      children !== undefined
+        ? children
+        : React.createElement(
+            View,
+            { style: { flex: 1, gap: 2 } },
+            title !== undefined && title !== null
+              ? React.createElement(
+                  Text,
+                  {
+                    style: textRoleStyle("subtitle", typography, colors),
+                    numberOfLines: 1,
+                  },
+                  title,
+                )
+              : null,
+            subtitle !== undefined && subtitle !== null
+              ? React.createElement(
+                  Text,
+                  {
+                    style: textRoleStyle("caption", typography, colors),
+                    numberOfLines: 2,
+                  },
+                  subtitle,
+                )
+              : null,
+          );
+    const content = [leading || null, body, trailing || null];
+
+    if (!pressable) {
+      return React.createElement(
+        View,
+        {
+          style: [rowStyle, style],
+          testID,
+          accessibilityLabel,
+          accessible: accessibilityLabel ? true : undefined,
+        },
+        ...content,
+      );
+    }
+    return React.createElement(
+      Pressable,
+      {
+        onPress,
+        disabled,
+        // accessibilityRole + aria-*: the pair that announces on both hosts.
+        accessibilityRole: "button",
+        accessibilityLabel,
+        "aria-selected": selected,
+        "aria-disabled": disabled,
+        testID,
+        style: ({ pressed }) => [
+          rowStyle,
+          pressed ? { backgroundColor: tokens.pressedBackground } : null,
+          disabled ? { opacity: 0.5 } : null,
+          style,
+        ],
+      },
+      ...content,
+    );
+  }
+  ListRow.displayName = "ListRow";
+
+  function EmptyState({ icon = "inbox", title, message, children, style, testID }) {
+    const { colors, spacing, radii, typography } = useListTheme();
+    return React.createElement(
+      View,
+      {
+        style: [
+          {
+            padding: spacing.lg,
+            borderRadius: radii.md,
+            backgroundColor: colors.surfaceMuted,
+            alignItems: "center",
+            gap: spacing.sm,
+          },
+          style,
+        ],
+        testID,
+      },
+      icon ? React.createElement(Icon, { name: icon, size: 20, color: colors.onSurfaceMuted }) : null,
+      title
+        ? React.createElement(
+            Text,
+            { style: { ...textRoleStyle("subtitle", typography, colors), textAlign: "center" } },
+            title,
+          )
+        : null,
+      message
+        ? React.createElement(
+            Text,
+            { style: { ...textRoleStyle("caption", typography, colors), textAlign: "center" } },
+            message,
+          )
+        : null,
+      children || null,
+    );
+  }
+  EmptyState.displayName = "EmptyState";
+
+  return { List, ListRow, EmptyState };
+}

package/dist/list.js

@@ -0,0 +1,7 @@
+// `<List>`, `<ListRow>`, `<EmptyState>` (web). Binds ./list-view.js to
+// react-native-web; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeList } from "./list-view.js";
+
+export const { List, ListRow, EmptyState } = makeList(ReactNative);

package/dist/list.native.js

@@ -0,0 +1,7 @@
+// `<List>`, `<ListRow>`, `<EmptyState>` (native). Binds ./list-view.js to
+// React Native's own primitives; only the import differs from ./list.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeList } from "./list-view.js";
+
+export const { List, ListRow, EmptyState } = makeList({ View, Text, Pressable });

package/dist/tabs-tokens.js

@@ -0,0 +1,75 @@
+// The values `<Tabs>` paints with, resolved from the theme's `tabs` component
+// scope. Platform-free, like list-tokens.js, so both hosts draw one strip from
+// the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT, contrastRatio } from "./contract.js";
+
+export const TAB_STYLES = CONTRACT.themeComponentTabStyles;
+
+// Segmented is the strip the exported app's Tabs container always drew.
+export const DEFAULT_TAB_STYLE = "segmented";
+export const DEFAULT_TAB_RADIUS = 6;
+
+// Per-strip overrides a widget may pass, named as the theme tokens are.
+export const TAB_TOKEN_NAMES = Object.freeze([
+  "style",
+  "activeColor",
+  "activeTextColor",
+  "textColor",
+  "radius",
+]);
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pick(overrides, scope, name) {
+  if (overrides && isSet(overrides[name])) return overrides[name];
+  if (scope && isSet(scope[name])) return scope[name];
+  return undefined;
+}
+
+/**
+ * Resolve one tab strip: explicit override, then the theme's `tabs` scope,
+ * then the widget's `defaultStyle`, then the tokens. The active label is the
+ * accent on the surface styles, and readable on the accent for a pill.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-strip values keyed by TAB_TOKEN_NAMES.
+ */
+export function resolveTabsTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const scope = base.components && base.components.tabs;
+
+  // The widget's own default sits BELOW the theme: a look still wins.
+  const requested =
+    pick(overrides, scope, "style") ?? (overrides && overrides.defaultStyle);
+  const style = TAB_STYLES.includes(requested) ? requested : DEFAULT_TAB_STYLE;
+  const ownAccent = pick(overrides, scope, "activeColor");
+  const activeColor = ownAccent ?? colors.primary;
+  return {
+    style,
+    activeColor,
+    activeTextColor:
+      pick(overrides, scope, "activeTextColor") ??
+      (style === "pill"
+        ? ownAccent
+          ? readableOn(ownAccent, colors)
+          : colors.onPrimary
+        : activeColor),
+    textColor: pick(overrides, scope, "textColor") ?? colors.onSurfaceMuted,
+    radius: pick(overrides, scope, "radius") ?? DEFAULT_TAB_RADIUS,
+    barBackground: colors.surfaceMuted,
+    activeSurface: colors.surface,
+    rule: colors.border,
+  };
+}
+
+// A chosen accent carries the label that reads best on it, dark or light.
+function readableOn(fill, colors) {
+  const dark = colors.onSurface;
+  const light = "#ffffff";
+  return contrastRatio(fill, dark) >= contrastRatio(fill, light) ? dark : light;
+}

package/dist/tabs-view.js

@@ -0,0 +1,169 @@
+// The ONE implementation behind the `<Tabs>` SDK primitive. The platform
+// bindings (`tabs.js` / `tabs.native.js`) differ only in where the primitives
+// come from, so the hosts cannot drift.
+//
+// The page Tabs container, the built-in widgets and custom widgets each drew
+// their own tab strip, so an app's tabs looked different on every screen and
+// between web and native. This strip reads the theme's `tabs` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { resolveTabsTokens } from "./tabs-tokens.js";
+
+const SEGMENT_INSET = 4;
+
+function stripStyles(t, theme) {
+  const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+  const elevation = theme.elevation || DEFAULT_THEME_TOKENS.elevation;
+  if (t.style === "pill") {
+    // An idle chip is outlined: a muted fill vanishes on a white card.
+    return {
+      bar: null,
+      content: { gap: spacing.sm },
+      item: (active) => ({
+        borderRadius: t.radius,
+        borderWidth: 1,
+        borderColor: active ? t.activeColor : t.rule,
+        backgroundColor: active ? t.activeColor : "transparent",
+      }),
+    };
+  }
+  if (t.style === "underline") {
+    // The rule sits on the content, so the scroller cannot clip the accent.
+    return {
+      bar: null,
+      content: { gap: spacing.lg, borderBottomWidth: 1, borderColor: t.rule },
+      item: (active) => ({
+        paddingHorizontal: 4,
+        borderBottomWidth: 2,
+        borderColor: active ? t.activeColor : "transparent",
+      }),
+    };
+  }
+  // A concentric outer radius keeps the inset chip's corners parallel. The
+  // bar hugs its segments, and the active one is outlined as well as lifted
+  // because a shadow alone disappears on a dark theme.
+  return {
+    bar: {
+      backgroundColor: t.barBackground,
+      borderRadius: t.radius + 2,
+      alignSelf: "flex-start",
+      maxWidth: "100%",
+    },
+    content: { padding: SEGMENT_INSET, gap: SEGMENT_INSET },
+    item: (active) => ({
+      borderRadius: t.radius,
+      borderWidth: 1,
+      borderColor: active ? t.rule : "transparent",
+      ...(active
+        ? { backgroundColor: t.activeSurface, ...(elevation.sm || {}) }
+        : null),
+    }),
+  };
+}
+
+/**
+ * Bind the shared tab strip to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, ScrollView: any}} rn
+ */
+export function makeTabs(rn) {
+  const { Text, Pressable, ScrollView } = rn;
+
+  function Tabs({
+    items = [],
+    value,
+    onChange,
+    variant,
+    defaultVariant,
+    activeColor,
+    activeTextColor,
+    textColor,
+    radius,
+    theme: explicitTheme,
+    accessibilityLabel,
+    style,
+    testID,
+  }) {
+    const hostTheme = useHostTheme();
+    // Layout containers render outside a widget context, so they pass theirs.
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const t = resolveTabsTokens(theme, {
+      defaultStyle: defaultVariant,
+      style: variant,
+      activeColor,
+      activeTextColor,
+      textColor,
+      radius,
+    });
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const strip = stripStyles(t, theme);
+
+    return React.createElement(
+      ScrollView,
+      {
+        horizontal: true,
+        showsHorizontalScrollIndicator: false,
+        // A strip never grows into, or shrinks away from, the panel below.
+        style: [{ flexGrow: 0, flexShrink: 0 }, strip.bar, style],
+        contentContainerStyle: [{ flexDirection: "row" }, strip.content],
+        accessibilityRole: "tablist",
+        accessibilityLabel,
+        testID,
+      },
+      ...items.map((item) => {
+        const active = item.key === value;
+        const ink = active ? t.activeTextColor : t.textColor;
+        return React.createElement(
+          Pressable,
+          {
+            key: item.key,
+            onPress: () => {
+              if (!active && typeof onChange === "function") onChange(item.key);
+            },
+            disabled: item.disabled,
+            // accessibilityRole + aria-*: the pair that announces on both hosts.
+            accessibilityRole: "tab",
+            "aria-selected": active,
+            "aria-disabled": !!item.disabled,
+            testID: item.testID,
+            style: [
+              {
+                flexDirection: "row",
+                alignItems: "center",
+                justifyContent: "center",
+                gap: 6,
+                minHeight: 44,
+                paddingHorizontal: 12,
+                paddingVertical: 8,
+              },
+              strip.item(active),
+              item.disabled ? { opacity: 0.5 } : null,
+            ],
+          },
+          item.icon
+            ? React.createElement(Icon, { name: item.icon, size: 16, color: ink })
+            : null,
+          React.createElement(
+            Text,
+            {
+              numberOfLines: 1,
+              style: {
+                fontFamily: typography.fontFamily,
+                fontSize: typography.sizes.sm,
+                fontWeight: active ? "600" : "500",
+                color: ink,
+              },
+            },
+            item.label,
+          ),
+        );
+      }),
+    );
+  }
+
+  Tabs.displayName = "Tabs";
+  return Tabs;
+}

package/dist/tabs.js

@@ -0,0 +1,7 @@
+// `<Tabs>` (web). Binds ./tabs-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeTabs } from "./tabs-view.js";
+
+export const Tabs = makeTabs(ReactNative);

package/dist/tabs.native.js

@@ -0,0 +1,7 @@
+// `<Tabs>` (native). Binds ./tabs-view.js to React Native's own primitives;
+// only the import differs from ./tabs.js.
+
+import { View, Text, Pressable, ScrollView } from "react-native";
+import { makeTabs } from "./tabs-view.js";
+
+export const Tabs = makeTabs({ View, Text, Pressable, ScrollView });

package/dist/text-roles.js

@@ -0,0 +1,102 @@
+// REQ-THEME-ROLE — the semantic text tiers, resolved against a theme.
+//
+// The ONE implementation behind every role-styled text: the built-in widgets
+// (frontend `_shared/textStyle.js` re-exports it), the SDK's own themed
+// components, and any custom widget that calls `textRoleStyle`. Platform-free,
+// so both hosts and the exported app resolve a tier identically.
+
+// Leading is a MULTIPLE of the font size; 1.4 is the platform body ratio.
+export const LINE_HEIGHT_RATIO = 1.4;
+
+export const TEXT_TRANSFORMS = ["none", "uppercase", "capitalize"];
+
+// The role names the TIER; `theme.typography.roles` owns what it looks like.
+export const TEXT_ROLES = [
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "overline",
+];
+
+// sc-3862's `heading` value predates the tiers and must keep resolving.
+export const LEGACY_FONT_ROLE_ALIASES = Object.freeze({ heading: "title" });
+
+export const DEFAULT_TEXT_ROLE = "body";
+
+// Structural, not a token: the tier decides which of the two faces it takes.
+export const ROLE_FACES = Object.freeze({
+  display: "heading",
+  title: "heading",
+  subtitle: "body",
+  body: "body",
+  caption: "body",
+  overline: "body",
+});
+
+export function normaliseTextRole(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  const aliased = LEGACY_FONT_ROLE_ALIASES[raw] || raw;
+  return TEXT_ROLES.includes(aliased) ? aliased : DEFAULT_TEXT_ROLE;
+}
+
+/** The role's token set as the host resolved it, or null. */
+export function roleTokens(role, typography) {
+  const roles = typography && typography.roles;
+  const tokens = roles && roles[normaliseTextRole(role)];
+  return tokens || null;
+}
+
+/**
+ * The colour a role paints in: the theme's explicit override, else the surface
+ * token the role names — resolved per render so a dark surface recolours it.
+ */
+export function roleColor(tokens, colors) {
+  if (!tokens) return undefined;
+  const explicit = typeof tokens.color === "string" ? tokens.color.trim() : "";
+  if (explicit) return explicit;
+  if (!colors || typeof tokens.colorToken !== "string") return undefined;
+  return colors[tokens.colorToken];
+}
+
+/**
+ * The complete text style for a semantic tier: size, absolute line height,
+ * weight, tracking, case, the tier's face and its colour.
+ *
+ * @param {string} role — one of TEXT_ROLES; a legacy `heading` is aliased.
+ * @param {object} typography — the resolved theme's typography tokens.
+ * @param {object} [colors] — the resolved theme's colours, for `colorToken`.
+ */
+export function textRoleStyle(role, typography, colors) {
+  const resolved = normaliseTextRole(role);
+  const tokens = roleTokens(resolved, typography) || {};
+  const size =
+    typeof tokens.fontSize === "number" && Number.isFinite(tokens.fontSize)
+      ? tokens.fontSize
+      : undefined;
+  const ratio =
+    typeof tokens.lineHeight === "number" && Number.isFinite(tokens.lineHeight)
+      ? tokens.lineHeight
+      : LINE_HEIGHT_RATIO;
+  const family = !typography
+    ? undefined
+    : ROLE_FACES[resolved] === "heading"
+      ? typography.headingFontFamily || typography.fontFamily
+      : typography.fontFamily;
+  const color = roleColor(tokens, colors);
+  return {
+    ...(size ? { fontSize: size, lineHeight: Math.round(size * ratio) } : null),
+    ...(tokens.fontWeight ? { fontWeight: tokens.fontWeight } : null),
+    ...(tokens.fontStyle ? { fontStyle: tokens.fontStyle } : null),
+    ...(typeof tokens.letterSpacing === "number" &&
+    Number.isFinite(tokens.letterSpacing)
+      ? { letterSpacing: tokens.letterSpacing }
+      : null),
+    ...(TEXT_TRANSFORMS.includes(tokens.textTransform)
+      ? { textTransform: tokens.textTransform }
+      : null),
+    ...(family ? { fontFamily: family } : null),
+    ...(color ? { color } : null),
+  };
+}

package/dist/theme-components.cjs

@@ -65,6 +65,11 @@ function coerceToken(def, value) {
   if (def.type === "gradient") {
     return normaliseComponentGradient(value) || undefined;
   }
+  if (def.type === "enum") {
+    return Array.isArray(def.values) && def.values.includes(value)
+      ? value
+      : undefined;
+  }
   return undefined;
 }
 

package/dist/theme-components.js

@@ -57,6 +57,11 @@ function coerceToken(def, value) {
   if (def.type === "gradient") {
     return normaliseComponentGradient(value) || undefined;
   }
+  if (def.type === "enum") {
+    return Array.isArray(def.values) && def.values.includes(value)
+      ? value
+      : undefined;
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.161.0",
+  "version": "0.163.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",