React components

React is required. Components are in @kahwee/runway-ui/react. Wrap them in Runway, which sets the theme root (cozy by default). Charts use @tanstack/charts; form controls use Base UI primitives.

Install

bun add @kahwee/runway-ui react@^19 react-dom@^19 @base-ui/react@^1.9 @tanstack/charts
import "@kahwee/runway-ui/bundle.css";
import { Button, Meter, Panel, Runway } from "@kahwee/runway-ui/react";

export function Briefing() {
  return (
    <Runway theme="cozy">
      <Panel kicker="Today" title="Morning briefing">
        <Meter label="Team energy" value={72} tone="morale" />
        <Button data-variant="primary">Next day</Button>
      </Panel>
    </Runway>
  );
}

Import @kahwee/runway-ui/bundle.css once (self-contained) or @kahwee/runway-ui for the modular entry. @kahwee/runway-ui/cozy.css is the theme on its own. Try React / Desk and React / Components in Storybook for playable examples.

Component reference

Component Renders Key props
Runway Theme root div.rw-ui theme (cozy, cozy-night, ledger, orbital, parchment, whimsy, midnight), density
Panel section.rw-panel title, kicker, actions
Icon Decorative Phosphor icon (span.rw-icon) name (coins, heart, users, lightning, rocket, sun, ...), weight, size
Badge span.rw-badge tone (warning, danger)
Meter div[role=meter] capsule label, value, max, tone
Progress native <progress> native props
Resource Resource bar entry icon, label, value
Button, Input Base UI Button and Input with Runway classes Base UI props, data-variant, data-size
Field, Checkbox, Select Base UI compound primitives See Base UI docs
Range Native slider with filled track and <output> label, format, onValueChange, native range props
Dialog Native <dialog> modal open, onClose, canDismiss
Inventory Slot grid with roving focus items, columns, selected, onSelect
CommandBar Desk status bar title, stats
FolioTabs Vertical section navigation label, items, value, onValueChange
Sheet Paper section title, description
DossierList, Dossier Aligned record rows kicker, status, title, description, actions
ControlConsole Time and workflow controls children
AnimatedNumber Counting span.rw-number value, format, duration
Confetti Fixed overlay burst active, onDone, count
ToastProvider, useToasts Base UI Toast with a Runway-styled stack timeout, limit; push(message, tone), dismiss(id)
Chart, ChartCard, defineChart TanStack Charts adapter and card definition, height, ariaLabel

CommandBar stats, FolioTabs items and Meter accept an icon (use Icon). Meter clamps value to 0..max for both its fill and aria-valuenow. Invalid or nonpositive maxima use 100; nonfinite values use 0. Dialog keeps the browser in charge of focus and inertness. Pass canDismiss={() => false} to veto Escape and backdrop dismissal while a decision is required; the policy is reapplied on every render. Inventory moves focus with arrows, Home and End, skipping disabled slots. Focus is remembered by item id; keep IDs unique and stable when reordering items. Removing or disabling the remembered slot makes the first available slot the Tab entry. Empty or fully disabled inventories have no slot in the Tab order. It does not virtualize, so keep lists to a few hundred slots.

Range

Use defaultValue for local state, or pass value and onValueChange for a controlled slider. The latter lets presets and application state update the native thumb, filled track and formatted output together. Consumer styles and native input props are forwarded. Keep values within min and max and aligned to step, as with a native controlled range input.

const [allocation, setAllocation] = useState(25);
<Range label="Resource allocation" value={allocation} onValueChange={setAllocation}
  min={0} max={100} step={5} format={(value) => `${value}%`} />;

The rw-field rw-range-field wrapper uses the shared slider layout. A native label and output reference the input's supplied id (or a generated unique ID), so the formatted value does not become part of the slider's accessible name. Try React / Interactions for presets, keyboard navigation, disabled slots and inventory changes.

Game input

Use InputScope, application-owned InputBinding[], and InputHints for local, remappable shortcuts. Opt in with gamepad for standard-controller navigation; mark directional targets with data-rw-focus-item. Native Tab, editing widgets, nested scopes and modal focus retain their contracts. See game input for props, mappings, limitations and a complete example.

Motion and feedback

AnimatedNumber tweens to its new value and bumps; Resource and CommandBar use it for numeric values automatically. Meter flashes when its value changes and pulses at 25% or below (data-low). Confetti bursts when active turns true, then calls onDone. Toasts use Base UI's Toast (swipe to dismiss, hover to pause, stacking): mount ToastProvider once inside Runway, then call useToasts().push(message, tone) from any child. Give the main action data-attention for a soft pulsing ring in the cozy theme. All of it is skipped under prefers-reduced-motion. haptic("tap" | "success" | "warning" | pattern) vibrates touch devices and returns false where unsupported, so it is always safe to call. See React / Feedback in Storybook.

Charts

Chart is the @tanstack/charts/react adapter. Build a definition with defineChart, memoize it, and render it inside a Runway root so the cozy palette (--ts-chart-1 to -6) applies:

const chart = useMemo(
  () =>
    defineChart({
      marks: [lineY(history, { x: "day", y: "cash" })],
      scales: { x: { scale: scaleLinear }, y: { scale: scaleLinear, nice: true, grid: true } },
    }),
  [history],
);
<ChartCard title="Credits by day"><Chart definition={chart} height={240} ariaLabel="Credits by day" /></ChartCard>;

For recorded histories, try React / Recorded history in Storybook. The recipe keeps zero and negative observations, splits lines at missing/nonfinite values, labels the measurement unit and always renders an exact-data table. Its gaps/zero/signed/empty/narrow states use synthetic observations, not a simulation. Keep this data adapter in your application: the library must not infer missing observations, interpolate history or read saves. Retain stable chart identity during updates, and preserve keyboard selection by recorded ID when remounting is unavoidable; never restore focus after intentional navigation.

Marks, scales and tooltips come from @tanstack/charts subpaths. See its documentation for the full grammar.

Portals and themes

A portal attached to document.body does not inherit a themed .rw-ui ancestor. Give Select.Portal an explicit container inside the relevant theme root, as the story does, or supply a separate themed .rw-ui portal host. Keep that host outside any clipping scroll region. A consumer's event-ownership guards must recognize its own portal host; a body portal is not a descendant of the original trigger.

The React entry does not wrap dialogs. The existing native dialog helper remains unchanged, including mandatory-decision cancel vetoes and native focus/inertness. Do not replace it with a different dialog primitive as an incidental migration.

Packaging and validation

The optional entry ships JavaScript and generated declarations, in built package archives. Run bun install --frozen-lockfile && bun run build after checking out a GitHub source archive. It has no JSX compilation requirement, but a consumer bundler must resolve its React/Base UI bare imports. Named imports support tree shaking; the package retains CSS side effects. A tested Button-only bundle drops other primitive imports.

Run bun run build-react-types, bun run check-types, bun run test-behaviors, bun run check-boundaries, and bun run build-storybook. bun run check-generated also verifies the committed React declaration. The boundary checker rejects React and other external dependencies in behaviors/ and styles/.

Progress

Progress styles a native <progress> with rw-progress; it accepts native props and React refs. Import the full bundle or styles/meters.css with the base tokens. Always provide a label (aria-label, aria-labelledby, or a native <label>). Pass the original work units with value and max; use aria-valuetext when those units matter. Omit value for indeterminate work. The browser owns range clamping and progress semantics. No live region is added on frequent updates.

<Progress aria-label="Experiment" value={3} max={10} aria-valuetext="3 of 10 workdays" />

The shared meter color/height tokens apply. Forced colors restore native progress appearance; indeterminate work retains the browser's native rendering.

SelectMenu, ComboboxMenu and Popover wrap Base UI Select, Combobox and Popover with Runway styling. Pass options as { value, label, disabled? }. The popup renders in a portal, so each takes a theme prop (default cozy) to match the surrounding Runway root.

<SelectMenu aria-label="Stage" options={stages} value={stage} onValueChange={setStage} />
<ComboboxMenu aria-label="Market" options={markets} onValueChange={setMarket} />
<Popover trigger="Help" title="Stages">Each stage changes your starting cash.</Popover>