# 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, and storybook setup. 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, or add a story. - Skill: `dxos/composer-ui-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add dxos/composer-ui-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/dxos/composer-ui-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: dxos (https://skillmd.com/u/dxos) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/dxos/composer-ui-2 --- # 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 `@dxos/ui-theme/src/css/theme/semantic.css` and the per-component files under `@dxos/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`, `flex`, `@container` queries) freely; pass color/size through tokens. 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`). 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 `@dxos/react-ui/src/components/Icon/Icon.tsx`. ## Containers: Panel + ScrollArea `Panel.*` (`@dxos/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/`. ## 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`](../../../@dxos/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 When an ECHO object is passed into a component as a prop and the component must re-render on changes to it, wrap it with **`useObject`** and read from the returned snapshot. A surface receiving an ECHO subject (e.g. via `AppSurface.ObjectArticleProps`) MUST do this — without it, mutations to nested arrays/structs (e.g. `Obj.update(obj, (m) => (m.images = [...]))`) don't trigger a re-render until you navigate away and back: the prop reference stays stable, and the subscription lives inside `useObject`. ```tsx const [gallery] = useObject(subject); // reads (gallery.images) re-render reactively; // writes still go through the original subject: const handleDelete = (index: number) => Obj.update(subject, (obj) => { const mutable = obj as Obj.Mutable; mutable.images = (mutable.images ?? []).filter((_, idx) => idx !== index); }); ``` The snapshot type is narrow — cast as needed (`obj as Obj.Mutable` inside `Obj.update`, or `as T` to read fields not surfaced on `Snapshot`). For _collections_ of objects use the reactive `useQuery` rather than holding a plain array. (Pure presentational components that just receive scalar props don't need any of this — keep `useObject` at the container boundary where the ECHO object enters.) ## State management Two state stores — don't conflate them (full detail: `@dxos/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 `` / `