@structuralists/scaffolding 0.0.1

package/src/index.ts

@@ -0,0 +1,87 @@
+export { Text, type TextProps } from './components/Content/Text';
+export { Heading, type HeadingProps } from './components/Content/Heading';
+export { Link, type LinkProps } from './components/Content/Link';
+export { Stack, type StackProps } from './components/Layout/Stack';
+export { Grid, type GridProps } from './components/Layout/Grid';
+export { Button, type ButtonProps } from './components/Forms/Button';
+export {
+  IconButton,
+  type IconButtonProps,
+  type IconButtonVariant,
+  type IconButtonSize,
+} from './components/Forms/IconButton';
+export {
+  Tooltip,
+  type TooltipProps,
+  type TooltipPlacement,
+} from './components/Overlays/Tooltip';
+export { Input, type InputProps } from './components/Forms/Input';
+export { SearchInput, type SearchInputProps } from './components/Forms/SearchInput';
+export { ColorInput, type ColorInputProps } from './components/Forms/ColorInput';
+export { Textarea, type TextareaProps } from './components/Forms/Textarea';
+export { SingleSelect, type SingleSelectProps } from './components/Forms/Select';
+export { MultiSelect, type MultiSelectProps } from './components/Forms/Select';
+export type { SelectOption, SelectSize } from './components/Forms/Select';
+export { Field, type FieldProps } from './components/Forms/Field';
+export { MediumModal, LargeModal, ConfirmModal } from './components/Modals';
+export type { MediumModalProps, LargeModalProps, ConfirmModalProps } from './components/Modals';
+export { Divider } from './components/Layout/Divider';
+export { Debug } from './components/Layout/Debug';
+export { Panels, type PanelsProps } from './components/Layout/Panels';
+export { Bar, type BarProps } from './components/Layout/Bar';
+export { Card, type CardProps } from './components/Content/Card';
+export { Badge, type BadgeProps } from './components/Content/Badge';
+export { Markdown, type MarkdownProps } from './components/Content/Markdown';
+export { EditableMarkdown, type EditableMarkdownProps } from './components/Content/EditableMarkdown';
+export { LoadingContainer, type LoadingContainerProps } from './components/Content/LoadingContainer';
+export { Menu, type MenuProps } from './components/Content/Menu';
+export type { MenuItem, MenuLeaf, MenuBranch } from './components/Content/Menu/types';
+export { Popover, type PopoverProps, type PopoverPlacement } from './components/Overlays/Popover';
+export { List, ListItem, type ListProps, type ListItemProps } from './components/Content/List';
+export { TabBar, type TabBarProps, type TabBarItem } from './components/Navigation/TabBar';
+export { VerticalNav, type VerticalNavProps, type VerticalNavItem } from './components/Navigation/VerticalNav';
+export { Json, type JsonProps } from './components/Json/Json';
+export {
+  QuickTable,
+  QuickTableRow,
+  QuickTableCell,
+  QuickTableHeaderRow,
+  QuickTableHeaderCell,
+  type QuickTableProps,
+  type QuickTableRowProps,
+  type QuickTableCellProps,
+  type QuickTableHeaderRowProps,
+  type QuickTableHeaderCellProps,
+  type QuickTableCellAlign,
+} from './components/Tables/QuickTable';
+export {
+  BigTable,
+  textColumn,
+  numberColumn,
+  currencyColumn,
+  dateColumn,
+  relativeDateColumn,
+  badgeColumn,
+  booleanColumn,
+  linkColumn,
+  idColumn,
+  type BigTableProps,
+  type ColumnDef,
+  type ColumnAlign,
+} from './components/Tables/BigTable';
+export { ChatMessage, ChatShell, ChatComposer, PillCombobox } from './components/Chat';
+export type {
+  ChatMessageProps,
+  ChatMessageRole,
+  ChatShellProps,
+  ChatComposerProps,
+  PillComboboxOption,
+  PillComboboxProps,
+} from './components/Chat';
+export { EmptyValue } from './components/Primitives/EmptyValue';
+export { Num, type NumProps, type NumVariant } from './components/Primitives/Num';
+export { Percent, type PercentProps } from './components/Primitives/Percent';
+export { RelativeTime, type RelativeTimeProps } from './components/Primitives/RelativeTime';
+export { LinedStack, type LinedStackProps } from './components/Primitives/LinedStack';
+export { LongText, type LongTextProps } from './components/Primitives/LongText';
+export { type BackgroundToken } from './tokens';

package/src/storybook/CLAUDE.md

@@ -0,0 +1,35 @@
+# _StoryUtils — dev-only helpers for stories
+
+**These are not product primitives. They exist only to make story files shorter and clearer.** Do not add them to the root `src/index.ts` barrel. Consuming apps should not import from here.
+
+## What lives here
+
+- **`Lorem`** — deterministic text filler. `<Lorem paragraphs={3} />`, `<Lorem sentences={2} />`, `<Lorem words={20} />`. Same corpus every render (no hydration flicker, no jitter between renders). `as` takes either an intrinsic tag (`'p'`/`'span'`/`'div'`) or a component reference — `<Lorem paragraphs={20} as={Text} />` renders 20 `<Text>` paragraphs in one call, no `Repeat` needed. Defaults: `p` for paragraphs, `span` for sentences/words.
+- **`Placeholder`** — sized rectangle with an optional label. `<Placeholder width={200} height={120} label="Sidebar" />`. Dashed border + subtle fill. For showing "something goes here" in layout stories when the content itself doesn't matter.
+- **`Toggle`** — render-prop cheap boolean. `<Toggle>{({ isOn, on, off, toggle }) => …}</Toggle>`. Collapses the `useState(false)` + button + onClose preamble that every modal / menu / popover story repeats.
+- **`Repeat`** — `<Repeat count={20}>{(i) => <Row />}</Repeat>`. Each child wrapped in a keyed `Fragment`. Sugar for `Array.from({length: n}, (_, i) => …)`.
+
+## Relaxed rules
+
+Real primitives follow strict rules in `plan.md` (no `className`, no HTML pass-through, no `aria-*` at call sites, `is*`/`can*`/`has*` booleans, CSS modules only, tokens only). These story utils **intentionally relax the rules** where it helps:
+
+- **Render-prop children are fine** (`Toggle`, `Repeat`). Real primitives favor explicit props; these favor terse story code.
+- **`as` prop is fine** (`Lorem`). Real primitives pick their semantic tag; story utils can defer.
+- **Inline styles for dynamic sizing are fine** (`Placeholder`). Same rule as library code, just used more liberally here.
+
+What still applies: CSS modules, `--ui-*` tokens, no HTML attribute pass-through, no `className` escape hatch. The relaxed rules are about *shape of the API*, not styling discipline.
+
+## Don't graduate these into the public barrel
+
+If a story util starts getting reached for by app code, that's a signal to build a real primitive, not to promote the story util. A real `Placeholder` for empty states would be a different primitive with proper typography, icon support, and action slots — not this dashed box. Keep the lanes separate.
+
+## Adding a new util
+
+- New folder under `src/_StoryUtils/<Name>/` with `index.tsx`.
+- Export from `src/_StoryUtils/index.ts`.
+- No story file for the util itself unless it's actually tricky to use. These are trivial by design.
+- Document the use case in this CLAUDE.md.
+
+## Where they're used
+
+Stories under `src/**/*.stories.tsx` import from `'../_StoryUtils'` (relative) or the folder-local barrel. The ESLint boundary rule treats `_StoryUtils/` as a primitive; external imports go through `src/_StoryUtils/index.ts`. Stories and tests are the "dogfood" element type and are allowed to reach into their own primitive's index as usual.

package/src/storybook/Composition.stories.tsx

@@ -0,0 +1,269 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useRef, useState } from 'react';
+import { Button } from '../components/Forms/Button';
+import { Field } from '../components/Forms/Field';
+import { Input } from '../components/Forms/Input';
+import { MediumModal } from '../components/Modals/MediumModal';
+import { Menu } from '../components/Content/Menu';
+import { Popover } from '../components/Overlays/Popover';
+import { SingleSelect } from '../components/Forms/Select/SingleSelect';
+import { Stack } from '../components/Layout/Stack';
+import { Text } from '../components/Content/Text';
+import { Tooltip } from '../components/Overlays/Tooltip';
+import { Toggle } from '.';
+
+const meta: Meta = {
+  title: 'Composition/Layered overlays',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const PERIOD_OPTIONS = [
+  { value: 'weekly', label: 'Weekly' },
+  { value: 'monthly', label: 'Monthly' },
+  { value: 'quarterly', label: 'Quarterly' },
+  { value: 'annual', label: 'Annual' },
+];
+
+const log = (label: string) => () => console.log('selected:', label);
+
+const MENU_ITEMS = [
+  { label: 'Refresh', onSelect: log('Refresh') },
+  { label: 'Duplicate', onSelect: log('Duplicate') },
+  {
+    label: 'Export',
+    items: [
+      { label: 'CSV', onSelect: log('CSV') },
+      { label: 'JSON', onSelect: log('JSON') },
+    ],
+  },
+  { label: 'Delete', onSelect: log('Delete') },
+];
+
+// Every layer kind opened from inside a modal. Confirms that Popover, Menu,
+// and Tooltip all paint above the modal's backdrop+content because each is
+// portaled to <body> later in mount order than the modal.
+export const ModalContainsEverything: Story = {
+  render: () => {
+    const [period, setPeriod] = useState<string>('monthly');
+
+    return (
+      <Toggle defaultOn>
+        {({ isOn, on, off }) => (
+          <>
+            <Button onClick={on}>Open modal</Button>
+            <MediumModal
+              isOpen={isOn}
+              onClose={off}
+              title="Layer composition test"
+              footer={
+                <>
+                  <Button onClick={off}>Cancel</Button>
+                  <Button variant="primary" onClick={off}>Save</Button>
+                </>
+              }
+            >
+              <Stack gap={3}>
+                <Text size="small" isMuted>
+                  Each row is a different layer kind opened from inside the
+                  modal. They should all sit above the modal's backdrop.
+                </Text>
+
+                <Field label="Popover-based select">
+                  <SingleSelect
+                    options={PERIOD_OPTIONS}
+                    value={period}
+                    onChange={setPeriod}
+                  />
+                </Field>
+
+                <Field label="Inline-edit popover">
+                  <PopoverDemo />
+                </Field>
+
+                <Field label="Menu">
+                  <Menu trigger="Actions ⋯" ariaLabel="Actions" items={MENU_ITEMS} />
+                </Field>
+
+                <Field label="Tooltip">
+                  <Tooltip label="Tooltips also escape the modal stacking context">
+                    <Button>Hover me</Button>
+                  </Tooltip>
+                </Field>
+              </Stack>
+            </MediumModal>
+          </>
+        )}
+      </Toggle>
+    );
+  },
+};
+
+const PopoverDemo = () => {
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [value, setValue] = useState('150');
+  const [draft, setDraft] = useState(value);
+  return (
+    <>
+      <Button
+        ref={anchorRef}
+        size="small"
+        onClick={() => {
+          setDraft(value);
+          setIsOpen(true);
+        }}
+      >
+        Edit ${value}…
+      </Button>
+      <Popover
+        anchorRef={anchorRef}
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Edit amount"
+        actions={
+          <>
+            <Button variant="ghost" size="small" onClick={() => setIsOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              variant="primary"
+              size="small"
+              onClick={() => {
+                setValue(draft);
+                setIsOpen(false);
+              }}
+            >
+              Save
+            </Button>
+          </>
+        }
+      >
+        <Field label="Amount">
+          <Input value={draft} onChange={(e) => setDraft(e.currentTarget.value)} autoFocus />
+        </Field>
+      </Popover>
+    </>
+  );
+};
+
+// Each layer is opened on top of the previous one. Mount order alone should
+// guarantee correct stacking: modal < first popover < menu < tooltip.
+export const StackedDeep: Story = {
+  render: () => {
+    const popoverAnchorRef = useRef<HTMLButtonElement>(null);
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+
+    return (
+      <Toggle defaultOn>
+        {({ isOn, on, off }) => (
+          <>
+            <Button onClick={on}>Open</Button>
+            <MediumModal
+              isOpen={isOn}
+              onClose={off}
+              title="Modal → Popover → Menu → Tooltip"
+              footer={<Button onClick={off}>Close</Button>}
+            >
+              <Stack gap={3}>
+                <Text>
+                  Each layer is anchored inside the previous one. Open them in
+                  order to confirm each new layer paints above its parent.
+                </Text>
+                <div>
+                  <Button
+                    ref={popoverAnchorRef}
+                    onClick={() => setIsPopoverOpen(true)}
+                  >
+                    1. Open popover
+                  </Button>
+                </div>
+                <Popover
+                  anchorRef={popoverAnchorRef}
+                  isOpen={isPopoverOpen}
+                  onClose={() => setIsPopoverOpen(false)}
+                  title="A popover"
+                >
+                  <Stack gap={2}>
+                    <Text size="small">
+                      2. Open the menu (a layer above this popover):
+                    </Text>
+                    <Menu
+                      trigger="Actions ⋯"
+                      ariaLabel="Actions"
+                      items={MENU_ITEMS}
+                    />
+                    <Text size="small">3. Hover for a tooltip:</Text>
+                    <Tooltip label="Tooltip lives above everything">
+                      <Button size="small">Hover me</Button>
+                    </Tooltip>
+                  </Stack>
+                </Popover>
+              </Stack>
+            </MediumModal>
+          </>
+        )}
+      </Toggle>
+    );
+  },
+};
+
+// Hostile container: overflow:hidden + transform on an ancestor. Inline-rendered
+// floaters would clip or land in the wrong containing block. Portaled layers
+// escape both.
+export const InsideClippedTransformedContainer: Story = {
+  render: () => {
+    const [period, setPeriod] = useState<string>('monthly');
+    const popoverAnchorRef = useRef<HTMLButtonElement>(null);
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+
+    return (
+      <div
+        style={{
+          width: 360,
+          height: 240,
+          padding: 16,
+          overflow: 'hidden',
+          transform: 'translateZ(0)',
+          border: '1px dashed var(--ui-border)',
+          borderRadius: 8,
+        }}
+      >
+        <Stack gap={2}>
+          <Text size="small" isMuted>
+            This box has overflow:hidden and a transform. Layers should still
+            escape.
+          </Text>
+          <SingleSelect
+            options={PERIOD_OPTIONS}
+            value={period}
+            onChange={setPeriod}
+          />
+          <Menu trigger="Actions ⋯" ariaLabel="Actions" items={MENU_ITEMS} />
+          <Tooltip label="Escapes the clipped, transformed parent">
+            <Button size="small">Hover me</Button>
+          </Tooltip>
+          <Button
+            ref={popoverAnchorRef}
+            size="small"
+            onClick={() => setIsPopoverOpen(true)}
+          >
+            Open popover
+          </Button>
+          <Popover
+            anchorRef={popoverAnchorRef}
+            isOpen={isPopoverOpen}
+            onClose={() => setIsPopoverOpen(false)}
+            title="Escaped"
+          >
+            <Text size="small">
+              Rendered via portal-to-body, positioned in viewport coords.
+            </Text>
+          </Popover>
+        </Stack>
+      </div>
+    );
+  },
+};

package/src/storybook/Lorem/index.tsx

@@ -0,0 +1,54 @@
+import type { ElementType, ReactNode } from 'react';
+
+export type LoremProps = {
+  paragraphs?: number;
+  sentences?: number;
+  words?: number;
+  /**
+   * Element (or component) to render into. Accepts intrinsic tags like `'p'`
+   * / `'span'` / `'div'`, or a component reference (e.g. `Text`) so paragraph
+   * output inherits the library's typography without a wrapping `Repeat`.
+   * Defaults: `'p'` for paragraphs, `'span'` for sentences/words.
+   */
+  as?: ElementType;
+};
+
+const CORPUS = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Curabitur pretium tincidunt lacus. Nulla gravida orci a odio. Nullam varius, turpis et commodo pharetra, est eros bibendum elit, nec luctus magna felis sollicitudin mauris. Integer in mauris eu nibh euismod gravida. Duis ac tellus et risus vulputate vehicula. Donec lobortis risus a elit. Etiam tempor. Ut ullamcorper, ligula eu tempor congue, eros est euismod turpis, id tincidunt sapien risus a quam. Maecenas fermentum consequat mi. Donec fermentum. Pellentesque malesuada nulla a mi. Duis sapien sem, aliquet nec, commodo eget, consequat quis, neque. Aliquam faucibus, elit ut dictum aliquet, felis nisl adipiscing sapien, sed malesuada diam lacus eget erat. Cras mollis scelerisque nunc. Nullam arcu.`;
+
+const WORDS = CORPUS.replace(/[.,]/g, '').split(/\s+/);
+const SENTENCES = CORPUS.match(/[^.]+\./g)?.map((s) => s.trim()) ?? [];
+
+const makeParagraph = (index: number, sentencesPer: number): string => {
+  const start = (index * sentencesPer) % SENTENCES.length;
+  const out: string[] = [];
+  for (let i = 0; i < sentencesPer; i += 1) {
+    out.push(SENTENCES[(start + i) % SENTENCES.length]!);
+  }
+  return out.join(' ');
+};
+
+export const Lorem = (props: LoremProps): ReactNode => {
+  const { paragraphs, sentences, words, as } = props;
+
+  if (words != null) {
+    const Tag = as ?? 'span';
+    const picked = WORDS.slice(0, words).join(' ');
+    return <Tag>{picked.charAt(0).toUpperCase() + picked.slice(1) + '.'}</Tag>;
+  }
+
+  if (sentences != null) {
+    const Tag = as ?? 'span';
+    const picked = SENTENCES.slice(0, sentences).join(' ');
+    return <Tag>{picked}</Tag>;
+  }
+
+  const count = paragraphs ?? 1;
+  const Tag = as ?? 'p';
+  return (
+    <>
+      {Array.from({ length: count }, (_, i) => (
+        <Tag key={i}>{makeParagraph(i, 4)}</Tag>
+      ))}
+    </>
+  );
+};

package/src/storybook/Placeholder/index.tsx

@@ -0,0 +1,27 @@
+import type { CSSProperties, ReactNode } from 'react';
+import styles from './styles.module.css';
+
+export type PlaceholderProps = {
+  width?: string | number;
+  height?: string | number;
+  label?: ReactNode;
+};
+
+const toLength = (value: string | number | undefined): string | undefined => {
+  if (value == null) return undefined;
+  return typeof value === 'number' ? `${value}px` : value;
+};
+
+export const Placeholder = (props: PlaceholderProps) => {
+  const { width, height, label } = props;
+
+  const style: CSSProperties = {
+    width: toLength(width),
+    height: toLength(height),
+  };
+  return (
+    <div className={styles.placeholder} style={style}>
+      {label ? <span className={styles.label}>{label}</span> : null}
+    </div>
+  );
+};

package/src/storybook/Placeholder/styles.module.css

@@ -0,0 +1,20 @@
+.placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 48px;
+  min-height: 32px;
+  background-color: var(--ui-background-3);
+  border: 1px dashed var(--ui-border);
+  border-radius: var(--ui-radius);
+  color: var(--ui-muted);
+  font-family: var(--ui-font-mono);
+  font-size: var(--ui-text-xsmall);
+  text-align: center;
+  padding: var(--ui-space-1) var(--ui-space-2);
+  box-sizing: border-box;
+}
+
+.label {
+  opacity: 0.85;
+}

package/src/storybook/Repeat/index.tsx

@@ -0,0 +1,23 @@
+import { Fragment, type ReactNode } from 'react';
+
+export type RepeatProps = {
+  count: number;
+  children: (index: number) => ReactNode;
+};
+
+/**
+ * Sugar for `Array.from({ length: n }, (_, i) => …)` in stories.
+ * Each child is wrapped in a keyed `Fragment`, so callers don't need to
+ * thread keys through.
+ */
+export const Repeat = (props: RepeatProps) => {
+  const { count, children } = props;
+
+  return (
+    <>
+      {Array.from({ length: count }, (_, i) => (
+        <Fragment key={i}>{children(i)}</Fragment>
+      ))}
+    </>
+  );
+};

package/src/storybook/Toggle/index.tsx

@@ -0,0 +1,29 @@
+import { useCallback, useState, type ReactNode } from 'react';
+
+export type ToggleChildArgs = {
+  isOn: boolean;
+  on: () => void;
+  off: () => void;
+  toggle: () => void;
+  setOn: (next: boolean) => void;
+};
+
+export type ToggleProps = {
+  defaultOn?: boolean;
+  children: (args: ToggleChildArgs) => ReactNode;
+};
+
+/**
+ * Render-prop boolean state for stories. Collapses the
+ * `useState(false)` + open button + onClose wiring that every modal,
+ * menu, or popover story would otherwise repeat.
+ */
+export const Toggle = (props: ToggleProps) => {
+  const { defaultOn = false, children } = props;
+
+  const [isOn, setOn] = useState(defaultOn);
+  const on = useCallback(() => setOn(true), []);
+  const off = useCallback(() => setOn(false), []);
+  const toggle = useCallback(() => setOn((prev) => !prev), []);
+  return <>{children({ isOn, on, off, toggle, setOn })}</>;
+};

package/src/storybook/_StoryUtils.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Lorem, Placeholder, Toggle, Repeat } from './index';
+import { Button } from '../components/Forms/Button';
+import { Stack } from '../components/Layout/Stack';
+import { Text } from '../components/Content/Text';
+import { MediumModal } from '../components/Modals';
+
+const meta: Meta = { title: 'StoryUtils/Showcase' };
+export default meta;
+type Story = StoryObj;
+
+export const LoremSamples: Story = {
+  render: () => (
+    <Stack gap={4}>
+      <Text size="small" isMuted>paragraphs=3 (default as="p")</Text>
+      <Lorem paragraphs={3} />
+      <Text size="small" isMuted>sentences=2</Text>
+      <Lorem sentences={2} />
+      <Text size="small" isMuted>words=12</Text>
+      <Lorem words={12} />
+    </Stack>
+  ),
+};
+
+export const PlaceholderSamples: Story = {
+  render: () => (
+    <Stack direction="row" gap={2}>
+      <Placeholder width={120} height={80} label="Sidebar" />
+      <Placeholder width={240} height={80} label="Main" />
+      <Placeholder width={80} height={80} label="Aside" />
+    </Stack>
+  ),
+};
+
+export const ToggleWithModal: Story = {
+  render: () => (
+    <Toggle>
+      {({ isOn, on, off }) => (
+        <>
+          <Button onClick={on}>Open modal</Button>
+          <MediumModal isOpen={isOn} onClose={off} title="From a Toggle">
+            <Lorem paragraphs={2} />
+          </MediumModal>
+        </>
+      )}
+    </Toggle>
+  ),
+};
+
+export const RepeatWithPlaceholder: Story = {
+  render: () => (
+    <Stack gap={1}>
+      <Repeat count={6}>
+        {(i) => <Placeholder height={32} label={`row ${i + 1}`} />}
+      </Repeat>
+    </Stack>
+  ),
+};

package/src/storybook/index.ts

@@ -0,0 +1,4 @@
+export { Lorem, type LoremProps } from './Lorem';
+export { Placeholder, type PlaceholderProps } from './Placeholder';
+export { Toggle, type ToggleProps, type ToggleChildArgs } from './Toggle';
+export { Repeat, type RepeatProps } from './Repeat';

package/src/tokens.ts

@@ -0,0 +1,31 @@
+import type { CSSProperties } from 'react';
+
+/**
+ * Background ramp level. Maps 1:1 to the `--ui-background-{0..3}` tokens
+ * defined in `tokens.css`. Each level is role-semantic, not brightness-ordered:
+ *   0 — primary interactive surface (content, inputs, modal)
+ *   1 — sidebar
+ *   2 — body / header / footer wall
+ *   3 — recessed or raised highlight (hover fills, badges)
+ * Each theme assigns a tone to each level. Brightness ordering between the
+ * four levels may differ between light and dark themes (e.g. in dark-warm,
+ * level 3 is lighter than level 0 because hover "lifts" on dark backgrounds).
+ */
+export type BackgroundToken = '0' | '1' | '2' | '3';
+
+/**
+ * Build an inline style that sets a named CSS custom property to the
+ * corresponding background token. Components consume the custom property
+ * in their stylesheet with a fallback to their default, e.g.
+ *   background-color: var(--ui-bar-bg, transparent);
+ *
+ * `varName` is scoped per-component (e.g. `--ui-bar-bg`) so nested
+ * components don't inherit each other's overrides via the cascade.
+ */
+export const backgroundStyle = (
+  varName: string,
+  token: BackgroundToken | undefined,
+): CSSProperties | undefined => {
+  if (token == null) return undefined;
+  return { [varName]: `var(--ui-background-${token})` } as CSSProperties;
+};

package/src/utils.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from 'bun:test';
+import { cx } from './utils';
+
+describe('cx', () => {
+  test('joins truthy strings with spaces', () => {
+    expect(cx('a', 'b', 'c')).toBe('a b c');
+  });
+
+  test('filters out false, null, and undefined', () => {
+    expect(cx('a', false, 'b', null, undefined, 'c')).toBe('a b c');
+  });
+
+  test('returns empty string when all inputs are falsy', () => {
+    expect(cx(false, null, undefined)).toBe('');
+  });
+
+  test('conditional class pattern', () => {
+    const active = true;
+    const disabled = false;
+    expect(
+      cx('btn', active && 'btn-active', disabled && 'btn-disabled'),
+    ).toBe('btn btn-active');
+  });
+});

package/src/utils.ts

@@ -0,0 +1,2 @@
+export const cx = (...parts: (string | false | null | undefined)[]) =>
+  parts.filter(Boolean).join(' ');