# Composer UI > Use when building or styling plugin UI with Composer's design system — the `@dxos/react-ui*` packages. Covers theme tokens, primitives (Panel/Card/List/Input/Button/Icon), the standard container layout (Panel + ScrollArea), lists/pickers/stacks, schema-driven forms, toolbar/menu wiring, reactivity (useObject), attention/density, translations, storybook setup, and before/after screenshots. The UI adjunct to the composer-plugins skill; consult it whenever you write a container/component, reach for a Tailwind color class, build a toolbar, render a form or list, add a story, or open a PR that changes what the app renders. - Skill: `dxos/composer-ui` (Agent Skill) - Install (CLI): `npx skillmds@latest add dxos/composer-ui` - Raw SKILL.md: https://api.skillmd.com/api/skills/dxos/composer-ui/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: dxos (https://skillmd.com/u/dxos) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dxos/composer-ui --- # Composer UI How to **consume** Composer's design system (`@dxos/react-ui*`) from a plugin. This is the UI adjunct to [[composer-plugins]] (which owns plugin _structure_: capabilities, surfaces, schema, operations) and [[composite-components]] (which owns _authoring_ new `@dxos/react-ui` primitives). When you're laying out a container, picking a color class, wiring a toolbar, or writing a story, the rules live here. **Golden rule:** If the design system already has a primitive, a token, or a layout for what you need you must use it. Reaching for a raw `
` with custom classes, a native ``, or a guessed color token is almost always a sign you missed an existing piece. Find it (grep an existing themed component) before inventing. Low-level components (plugin/_/src/components, react-ui-_). Must NOT depend on `@dxos/app-framework` or `@dxos/app-toolkit` capabilitiess. Instead aspects that may be derived from capabilites must be passed as properties. Each component lives in its own subdirectory with an `index.ts` barrel. Use named exports; no default exports. ## Package family Import from the most specific package. Common ones: | Package | Provides | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `@dxos/react-ui` | Core primitives: `Panel`, `Card`, `List`, `Input`, `Button`, `IconButton`, `Icon`, `ScrollArea`, `Toolbar`, `Dialog`, `Popover`, `Tooltip`, `Select`, `Tag`, `Avatar`, `Separator`, plus `useTranslation`, `useThemeContext`, `DensityProvider`. | | `@dxos/react-ui-theme` | The theme (`tx` resolver, tokens, Tailwind preset). You rarely import from it directly — tokens are plain Tailwind classes. | | `@dxos/react-ui-form` | `Form.*` — schema-driven forms (the way to edit ECHO objects). | | `@dxos/react-ui-menu` | `Menu.*`, `MenuBuilder`, `useMenuActions` — toolbars and command menus. | | `@dxos/react-ui-attention` | Attention system: `AttentionGlyph`, `useAttention`, attendable wiring. | | `@dxos/react-ui-list` | Navigable lists with `dx-current`/`dx-selected` item states. | | `@dxos/react-ui-mosaic` / `-board` | Layout composition (Mosaic `Stack`, Deck, Board) — usually owned by the shell, not plugins. (`@dxos/react-ui-stack` is **deprecated** — use the Mosaic `Stack`.) | | `@dxos/react-ui-editor` / `-markdown` | Text/markdown editing. | | `@dxos/react-ui-table` / `-data` | Data tables. | Many more exist (`-card`, `-chat`, `-thread`, `-pickers`, `-search`, `-syntax-highlighter`, …). When you need a domain widget, check for a `react-ui-` package before building one. ## Theme tokens Color/spacing tokens are **plain Tailwind classes** generated from CSS custom properties. The source of truth is [`packages/ui/ui-theme/src/css/theme/semantic.css`](../../../packages/ui/ui-theme/src/css/theme/semantic.css) and the per-component files under [`packages/ui/ui-theme/src/css/components/`](../../../packages/ui/ui-theme/src/css/components/). **The rule:** every `--color-` custom property yields the utilities `bg-`, `text-`, `border-`. So `--color-modal-surface` → `bg-modal-surface`. To find a valid token, grep `semantic.css` for `--color-`, or copy classes from an existing themed component — **never guess a name**. Invented tokens (`bg-input`, `text-primary`) aren't in the theme and render wrong (e.g. white-on-white in dark mode), which is the kind of bug that's invisible until someone toggles the theme. Verified common tokens (kebab-case is current; legacy camelCase like `bg-modalSurface` / `text-baseText` is being phased out — prefer the kebab forms): - **Surfaces:** `bg-base-surface`, `bg-card-surface`, `bg-modal-surface`, `bg-toolbar-surface`, `bg-sidebar-surface`, `bg-deck-surface`, `bg-group-surface`, `bg-input-surface`, `bg-hover-surface`, `bg-attention-surface`, `bg-accent-bg` (+ `-hover`). - **Text:** `text-base-fg` (body), `text-description` (muted), `text-subdued` (dimmest), `text-placeholder`, `text-accent-text`. - **Borders:** `border-separator`, `border-subdued-separator`, `border-primary-separator`, `border-active-separator`, `border-focus-ring`. Themed primitives accept overrides via a `classNames` prop (string or array) — never `className`. Pass functional layout hints (`p-4`, `space-y-4`, `@container` queries) freely; pass color/size through tokens. Hand-written `flex`/`grid` class soup is the exception, not the hint — `Flex`/`Grid` cover it (see below). If you're writing more than a layout hint by hand, you're probably missing a primitive. ## Sizing vs logical utilities (post-Tailwind-3) **Sizing is physical.** Use `w-*` / `h-*` / `min-w-*` / `max-h-*` / `size-*` for width and height. The custom `is-*` / `bs-*` (inline-size / block-size) utilities were **dropped** — Tailwind core never shipped logical _size_ utilities and keeps width/height physical, so `is-full` / `bs-[20rem]` are dead classes. Prefer `w-full` / `h-[20rem]`. **Direction-sensitive spacing stays logical** — these Tailwind ships and they flip correctly under RTL, so keep using them: `ps-*` / `pe-*` (padding), `ms-*` / `me-*` (margin), `start-*` / `end-*` (inset), `border-s` / `border-e` (border side), `text-start` / `text-end` (alignment). Do **not** rewrite these to physical (`pl-`, `ml-`, `left-`, `text-left`). **The `tailwindcss-logical` dialect is gone.** Dropped in the Tailwind v4 migration (#10611), so every class it provided now compiles to **nothing** — silently. These are the ones that keep coming back, with what to write instead: | Dead class | Write | | ----------------------- | --------------------- | | `pis-*` / `pie-*` | `ps-*` / `pe-*` | | `pbs-*` / `pbe-*` | `pt-*` / `pb-*` | | `pli-*` / `plb-*` | `px-*` / `py-*` | | `mis-*` / `mie-*` | `ms-*` / `me-*` | | `mbs-*` / `mbe-*` | `mt-*` / `mb-*` | | `mli-*` / `mlb-*` | `mx-*` / `my-*` | | `is-*` / `bs-*` | `w-*` / `h-*` | | `min-is-*` / `min-bs-*` | `min-w-*` / `min-h-*` | | `max-is-*` / `max-bs-*` | `max-w-*` / `max-h-*` | This is the highest-frequency regression in this codebase, and the most expensive kind: nothing errors, nothing lints, the layout is merely wrong — and when the dead class was load-bearing (a `min-bs-*` floor reserving height, a `min-is-0` letting a grid child shrink) the failure surfaces far from its cause. **Grep your diff before committing:** ```bash git diff | grep -nE '\b(p|m)(is|ie|bs|be|li|lb)-|\b(min-|max-)?(is|bs)-' ``` Note the near-misses that ARE real: `ps-*`/`pe-*` and `ms-*`/`me-*` (Tailwind's own logical spacing) and `inset-*`/`start-*`/`end-*`. Only the `-is-`/`-bs-`/`-li-`/`-lb-` infixes above are dead. Rule of thumb: **width/height → physical; margin/padding/inset/border-side/text-align → logical.** ## Icons Icons are Phosphor sprite references named `ph----` (weights: `regular`, `bold`, `fill`, `light`, `duotone`, `thin`). Use the `Icon` primitive or any primitive that takes an `icon` prop: ```tsx import { Icon } from '@dxos/react-ui'; ; ``` `size` is a numeric `Size` (Tailwind scale), or inherit from the `--dx-icon-size` CSS var. See [`packages/ui/react-ui/src/components/Icon/Icon.tsx`](../../../packages/ui/react-ui/src/components/Icon/Icon.tsx). Nothing needs registering to use a new Phosphor icon — name it and it resolves. `dx--*` brand glyphs are `regular`-only. How resolution works (and why an icon might not appear) → [`packages/ui/react-ui/docs/icons.md`](../../../packages/ui/react-ui/docs/icons.md). ## Containers: Panel + ScrollArea `Panel.*` ([`packages/ui/react-ui/src/components/Panel/Panel.tsx`](../../../packages/ui/react-ui/src/components/Panel/Panel.tsx)) is the container shell — a CSS grid with rows `auto 1fr auto` mapped to the `toolbar` / `content` / `statusbar` areas, so the content row absorbs the slack and the toolbar/statusbar hug their content. The canonical article shape: ```tsx {/* Menu.Root toolbar — see below */} {/* List / Stack / Form, or ad-hoc content */} ``` Parts: `Panel.Root` / `Panel.Toolbar` / `Panel.Content` / `Panel.Statusbar`. Add `Panel.Statusbar` (takes a `size`) only when the surface needs a persistent bottom status row — most articles don't. **`role`:** `Panel.Root` defaults `role` to `none`. Only pass a `role` that the surface itself receives (the article/section/companion role threaded in via `AppSurface.*Props`) — don't invent ARIA roles to hang behaviour on. **`asChild` + composable.** Every `Panel.*` part is `slottable`, so `asChild` makes the part _become_ its single child instead of rendering its own `
`. Use `asChild` whenever the child is itself composable (e.g. `ScrollArea.Root`): one fewer DOM node, and the height chain passes straight through. `ScrollArea` provides the themed scrollbar **and** the height chain that lets content scroll — content that should scroll goes in `ScrollArea.Viewport` inside `Panel.Content asChild`. **Let components own their spacing.** `Form`, `List`, and `Stack` each control their own padding and spacing — don't wrap them in a padded viewport or sprinkle `p-*`/`space-*` around them; that double-pads and fights their internal rhythm. Reserve hand-written layout hints (`p-4 space-y-4`, `@container` queries) on `ScrollArea.Viewport` for _ad-hoc_ free-form content that has no owning component. Anything beyond a layout hint means you're probably missing a primitive — clear it with the user first. **Never introduce a wrapper `
` for styling.** Wrappers break the height chain that `ScrollArea` relies on (a wrapper around an input once silently disabled scrolling). If a context-provider component (like `Input.Root`, which renders no DOM) has nowhere to hang a class, rely on parent-level layout rules rather than wrapping — and if there's genuinely no path without a wrapper, discuss it first. See: `plugin-chess/src/containers/ChessArticle/`, `plugin-sample/src/containers/`. ## Layout primitives: Flex, Grid, Column, Container When you do need a box — inside `ScrollArea.Viewport`, between `Panel` parts, anywhere the shell doesn't already give you one — reach for these before writing `
`. All take `asChild`, so the layout can project onto a semantic element (`
`, `
    `) at no extra DOM node. `Flex`/`Grid`/`Container` live in [`packages/ui/react-ui/src/layout/`](../../../packages/ui/react-ui/src/layout) (not `components/`); `Column` is in `components/Column`. - **`Flex`** — `column`, `gap`, `align`, `justify`, `wrap`, `grow`, `center`. `grow` is `flex-1 overflow-hidden` (the height-chain link); `center` centers on both axes. - **`Grid`** — `cols`, `rows`, `gap`, `align`, `center`, `grow`, `contents`. Tracks take a count for equal columns (`cols={3}`) or a list for anything asymmetric (`cols={['min-content', '1fr']}`, `cols={[2, 1]}` for `2fr 1fr`) — the list form replaces `grid-cols-[min-content_1fr]`, which is the least readable class in the corpus. `cols='subgrid'` adopts the parent's tracks and spans them. `overflow-hidden` comes only with `grow`, so a `grow={false}` grid clips no more than the `
    ` it replaced. - **`Column`** — the gutter grid: three tracks (leading gutter / content / trailing gutter) sized by `--gutter`. This is what aligns icons, controls, and scrollbars to the same vertical rules across every surface, so use it instead of hand-padding a content column. - **`Container`** — a bare `dx-expand` box, for when the only job is to fill the parent. Add `overflow-hidden` yourself if a clip is also wanted; it is no longer implied. ```tsx … … {t('empty.message')}
    …
     ``` **`Column` parts.** `Column.Root` (`gutter: sm|md|lg`, `subgrid`, `gap`) defines the tracks and exposes `--dx-col`; `Column.Center` puts plain content in the centre track and is the default choice; `Column.Row` is a 3-track subgrid row for content flanked by gutter items; `Column.Block` is a gutter slot sized to `--dx-rail-item` (`end` for the trailing gutter) so a passive `` and an interactive `IconButton` align to the pixel. For slotted children that can't take a part, the `withColumn` helpers apply placement: `center()`, `placeContent()`, `propagate()`. Reach for `propagate()` — not `center()` — when a descendant must address the gutters, e.g. a `ScrollArea` that should span full width and keep its scrollbar out in the gutter; `Dialog.Body` depends on exactly that, and `center()` there confines the body and pulls the scrollbar inboard. Nest with `subgrid` when a `Column` (or `Card`) sits inside another 3-track grid and must inherit its rules rather than invent new ones. **`gap` takes ramp steps, not Tailwind numbers.** `xs | sm | md | lg | xl | 2xl | form | form-section` ([`layout/layout.ts`](../../../packages/ui/react-ui/src/layout/layout.ts)) — a `gap-2` literal is precisely the drift the prop exists to prevent. `Flex` grows **no** padding or colour props on purpose (components own their spacing); everything else goes through `classNames`. There is no implicit `align`: row-centering is common, but defaulting it would silently restyle consumers relying on CSS `stretch`. **This is a live migration, so match it rather than adding to the backlog.** [`packages/ui/react-ui/AUDIT.md`](../../../packages/ui/react-ui/AUDIT.md) is the wrapper-div census that produced `Flex` and drove the `Grid` extension: of 191 flex/grid wrappers in plugin containers, 145 are converted. A new hand-rolled flex or grid div is new debt in a count someone is actively driving down. ## Lists, pickers, and stacks **Rule: never hand-roll a list.** Any vertical collection of rows — even a read-only display list — is built from a `@dxos/react-ui-list` primitive, never a `map()` over `
    `/`
  • `. A mapped stack of `
    `s in a review is a defect; reach for the primitive below instead. `@dxos/react-ui`'s core `List`/`ListItem` are **deprecated** — do not use them; `Listbox` is their successor. Pick the collection primitive by decision order: 1. **Need a picker / combobox** (choose from a set, typeahead)? **Check for an existing one first** — `Picker` / `Combobox` / `Listbox` in [`@dxos/react-ui-list`](../../../packages/ui/react-ui-list/src/components), or a domain widget like `SearchList` (`@dxos/react-ui-search`). Reuse before building. 2. **A simple flat list** (display rows, selectable rows, or rows with per-row controls)? Use **`Listbox`** from `@dxos/react-ui-list`: `Listbox.Root` (headless; omit `value`/`onValueChange` for a non-selectable `role=list`, pass them for single-select) → `Listbox.Content` (the `
      `) → `Listbox.Item id=… classNames=…` (a row; put arbitrary children — labels via `Listbox.ItemLabel`, buttons, a `Select` — inside). See `plugin-space/src/components/ForeignKeys/ForeignKeys.tsx` for the read-only idiom. For a **reorderable / master-detail** list use `OrderedList`; for hierarchy use `Tree` / `Accordion`. 3. **A reorderable / resizable / tiled collection of surfaces**? Use the **`Stack` from `@dxos/react-ui-mosaic`** (`MosaicStack` / `MosaicVirtualStack`, with `MosaicStackTileComponent` tiles). **Do NOT use `@dxos/react-ui-stack` — it is deprecated.** (Some plugins still import it; don't copy them.) The live Stack is the Mosaic one. **`dx-current` / `dx-selected` are automatic.** `Listbox` and `Stack` drive current-item and selection state themselves (via react-tabster keyboard navigation) — you don't set those classes or wire focus by hand. Like `Form`, both **own their own padding and spacing**, so drop them straight into a `ScrollArea.Viewport` without a padded wrapper. ## Toolbar / menu wiring Container toolbars are **always** built from menu actions, never bare `Toolbar.IconButton` chains. Compose actions with `MenuBuilder` inside an `Atom`, thread them through `useMenuActions`, and render with `Menu.Root` — passing `attendableId` so attention-driven contributions (graph actions, plugin extensions, keyboard shortcuts) target the right surface. Skipping this breaks plugin composition. ```tsx const actionsAtom = useMemo( () => Atom.make((): ActionGraphProps => MenuBuilder.make() .action( 'add', { label: ['add.label', { ns: meta.id }], icon: 'ph--plus--regular', disposition: 'toolbar' }, handleAdd, ) .build(), ), [handleAdd], ); const menuActions = useMenuActions(actionsAtom); return ( ); ``` Encode dynamic state (disabled, busy/idle icon swap) inside the action properties and list that state in the `useMemo` deps — the atom rebuilds and the toolbar updates. Always thread `attendableId` from `AppSurface.ObjectArticleProps`; don't underscore it as unused. See: `plugin-sample/src/containers/SampleArticle.tsx`. ## Reactivity State lives in one of three stores — React state (ephemeral, local), atoms (shared/derived), ECHO objects (persistent, collaborative) — and reading an ECHO object during render does **not** subscribe: subscribe where you read (`useObject` / `useQuery`), as narrowly as you read, and write through the live object, never the snapshot. The house rules and anti-pattern catalog (bare reads, `.target` in render, list-level ref resolution, hook pileups, effect-syncing between stores) live in the [reactivity](../reactivity/SKILL.md) skill — load it for any component that holds or reads state. ## State management Two app-level homes for atom state — don't conflate them (full detail: `packages/ui/react-ui-attention/AUDIT.md`): - **Settings** — a user preference, _set infrequently_, applies globally, shown in the Settings UI. Built with `createKvsStore` (one schema-validated blob per plugin, keyed by `meta.profile.key`); read/write via `useAtomCapabilityState(XCapabilities.Settings)`. Idiom `org.dxos.effect.kvsStore`. - **ViewState** — the _current, sticky UI state that survives navigation_ (selection, scroll, split, view mode). Per-context: keyed by `(aspect, contextId)`. Declare once with `define({ key, backend, schema, defaultValue })`; the `backend` sets durability — `'local'` persists across reloads (best-effort; degrades to memory when storage is blocked), `'memory'` is session-only. Read/write via `useViewState` / `useViewStateActions` (React), or `Capability.get(AttentionCapabilities.ViewState)` (operations / graph-builders). Idiom `org.dxos.react-ui-attention.viewState`. The tell: _configure-once-and-forget_ → Settings; _tracks-what-you're-currently-doing_ → ViewState. Keep at most **one Settings object and one ViewState object per aspect** per plugin — widen an existing schema, don't add a parallel store. Passing state into low-level components (which must not resolve capabilities): prefer a **writable atom** over a `value` + `onChange` pair — simpler, and it needs no provider ancestor, so the component stays generic. **Caveat:** a ViewState `local` atom does _not_ self-persist on a direct set — persistence lives in `manager.set`. To hand ViewState down as one atom (e.g. combined with a settings field), use a writable derived atom whose write calls `manager.set` (see `MessageArticle`'s `optionsAtom`). Consider factoring each state concern into a small **file-local hook** (e.g., `useMessageExpansion`, `useThreadViewActions`) so the container body reads as a sequence of named concerns instead of an inline wall. ## Forms Never hand-roll native `` / `