Source ownership
Runway owns generic interface primitives. Application rules, action names and feature adapters belong in consumers.
The public CSS entry points compose component files in a fixed order:
| Entry point | Implementation directory | Ownership |
|---|---|---|
styles/patterns.css |
styles/patterns/ |
Resources, inventory slots, choices, objectives, dock, view tabs, section tabs, reduced motion |
styles/fields.css |
styles/fields/ |
Base inputs, select picker, select variants, accessibility |
styles/forms.css |
styles/forms/ |
Switch, checkbox/radio, range, fields, choices, accessibility |
styles/social.css |
styles/social/ |
Segmented control, avatar, person chip, leaderboard, accessibility, pace |
styles/cozy.css |
styles/cozy/ |
Cozy theme tokens, controls, surfaces, badges, meters, patterns, desk workspace, charts, dialog, accessibility |
styles/charts.css |
styles/charts/ |
Frames, columns, series, area, data tables, density, responsive behavior and forced colors |
styles/instruments.css |
styles/instruments/ |
Console, range and line history, impact, appearance, timeline, responsive behavior and forced colors |
styles/feedback.css |
styles/feedback/ |
Animated numbers, toast surfaces, confetti, keyframes and reduced motion |
styles/observatory.css |
styles/observatory/ |
Workspace, resource ledger, context popover, decisions, responsive behavior |
Edit the component that owns the selector. The entry points contain imports only; change them when adding a component or deliberately changing cascade order. Accessibility files own cross-component reduced-motion and forced-color rules. Each implementation declares its existing cascade layer, so splitting a file does not change specificity or layer precedence. These are the only implementations; there are no duplicate compatibility styles.
styles/dialog.css owns the dialog surface, backdrop, motion and modifiers in
the runway-ui.dialog layer. Its TypeScript helper remains in behaviors/; declarations compile to dist/behaviors/.
Other styles already have dedicated feature files. Keep behavior implementations and their public types together in behaviors/, and examples in the corresponding
Storybook feature. A new variant of an existing component belongs with that
component, without changes to index.css or the package exports.
Run bun run check, bun run build and bun run build-storybook after changing styles.
The recursive build resolves the composition imports into the self-contained
dist/runway-ui.css. Never edit that generated bundle by hand. When resolving a
merge, resolve authored components first, then rebuild the bundle once. Commit
the bundle because GitHub archive consumers use it without a package build step.
Run bun run check-generated to rebuild and verify both dist/runway-ui.css and
styles/icons.css against the current commit. The package CI job runs this on
pull requests and pushes to main; stale, missing or untracked generated files
fail with instructions to rebuild and commit them. The command regenerates the
working copies, so commit intentional source and generated changes together
before checking locally.
Automated boundary checks
Run bun run check-boundaries before committing a module change. It checks authored
JavaScript, TypeScript and CSS dependencies for missing local targets and circular
imports, including re-exports and literal dynamic imports. Runtime behaviors may
import other behaviors only, with no external runtime dependencies. Component
styles may import other styles; index.css is the public composition entry point.
Library implementation modules must not depend on stories, examples, build scripts
or application entry points.
Runway has no application action registry. Duplicate protection therefore checks
object keys (including handler maps) and public behavior export names across
runtime entry modules. It does not treat repeated data-action attributes in
independent examples as conflicting registrations. bun run test-boundaries exercises
the checker with valid and invalid fixtures so enforcement changes are checked too.
The Package GitHub Actions workflow runs lint, boundary checks/tests and package
build verification as independent jobs on pull requests and pushes to main.
Pull requests also build Storybook and the documentation site in parallel, then
run bun run check-docs to verify generated local links, anchors and assets. On main, the existing Pages
workflow builds Storybook and checks documentation links before deployment. New
commits cancel superseded Package runs for the same branch or pull request.
These jobs report check results; repository branch-protection settings determine
whether GitHub requires those checks before a merge.
Behavior types are authored in the owning TypeScript module. Generate declarations with bun run build-types; verify source and consumer fixtures with bun run check-types. Do not edit .d.ts output. See type ownership and the behavior map.
Storybook composition ownership
The welcome showcase lives in stories/start-here/. Its layout stylesheet is
imported by that story only; it assembles the real panel, button, badge, resource
and objective classes rather than duplicating their visual recipes. Keep
documentation layouts here and reusable component styles in styles/.
styles/patterns.css remains the compatible aggregate entry. Its component
imports retain the runway-ui.patterns layer and original cascade order;
accessibility.css owns shared dock and inventory motion preferences. Import
the aggregate for the complete patterns set, or choose component files through
@kahwee/runway-ui/styles/patterns/*.css alongside the base tokens and primitives.
Controls own their shared states
styles/controls.css owns button pressed-state colors and rw-shortcut, including
when controls are used outside a dock. styles/patterns/dock.css owns only the
dock surface, button arrangement and dock-specific animations. Its animation
preferences remain in styles/patterns/accessibility.css. Neither shared control
recipe requires importing game patterns.
Primitives and compositions
Primitives own reusable recipes: controls.css owns buttons and shortcuts,
fields.css / forms.css own native form controls, and panels.css owns the
panel surface, header, title and elevation. primitives.css remains the compatible
aggregate. A standalone panel can import @kahwee/runway-ui/styles/tokens.css and
@kahwee/runway-ui/styles/panels.css without loading buttons, fields or game patterns.
The boundary checker rejects imports from these foundational modules into
composition styles, including imports from their implementation directories.
Composition entry points retain their names, layers and import order:
| Entry | Component ownership |
|---|---|
styles/workspace.css |
workspace/command-bar.css, folio-tabs.css, sheet.css, dossier.css, control-console.css, accessibility.css |
styles/studio.css |
Paper command bar, navigation, surfaces, season cover, leaderboard, viewport responsiveness, accessibility and container layout in studio/ |
styles/observatory/workspace.css |
Shell and identity, metric tiles, panel placement and content, footer in observatory/workspace/ |
Compositions may arrange or apply scoped appearances to primitives; a primitive
must never import a composition to finish its appearance. Studio appearances
remain scoped to rw-paper-*; observatory placement rules remain scoped to
rw-observatory*. Neither redefines an unscoped button, field or panel recipe.
Use Isolation / Panels in Storybook to verify the independent panel entry.
React component ownership
react/index.ts is the public, export-only facade. Named component owners contain
implementation and props together; no owner imports the facade. Internal files
are not additional package entry points. Consumers keep importing
@kahwee/runway-ui/react. The client boundary remains explicit in component
modules. Do not duplicate upstream component state machines.
| Owner | Responsibility |
|---|---|
root.ts |
Theme and density root |
button.ts, input.ts |
Styled Base UI primitives; preserve upstream refs and state-dependent classes |
progress.ts, meter.ts |
Native progress and labelled bounded meter |
panel.ts, badge.ts, resource.ts |
Surfaces, status and resource readouts |
command-bar.ts, control-console.ts |
Workspace status and workflow controls |
folio-tabs.ts, sheet.ts |
Section navigation and paper sections |
dossier.ts |
Dossier and its aligned list; these share one component contract |
animated-number.ts, confetti.ts, reduced-motion.ts |
Value animation, celebrations and shared motion preference |
toast.ts |
Base UI toast provider, stack and hook |
dialog.ts, dialog-policy.ts |
Native modal component and local cancellation/backdrop compatibility |
inventory.ts, range.ts |
Roving slot focus and native slider state |
input-scope.ts, input-navigation.ts, input-bindings.ts, input-hints.ts, gamepad-input.ts |
Local remappable bindings, opt-in directional/controller input and visible hints |
chart.ts |
TanStack Charts exports and chart card |
classes.ts |
Plain and state-dependent class composition |
React owners may import other owners and the approved React, Base UI and TanStack
peers. They cannot import vanilla behaviors, styles, stories or tooling. Vanilla
behaviors and CSS cannot depend on React. stories/react/ owns example state,
layout and React root teardown. See React usage.
Tooling ownership
scripts/check-boundaries.ts coordinates parsing, import validation, cycle
checks and public behavior export checks. scripts/boundaries/source-files.ts
owns source inventory; policy.ts owns dependency and aggregate rules. The
checker rejects component implementations in the React facade, imports of that
facade from owners, and declarations inside import-only CSS aggregates. Fixtures
exercise permitted and forbidden dependencies.
scripts/lib/generated-files.ts synchronizes one generated file type within one
output directory. Runtime compilation owns .js; declaration compilation owns
.d.ts. Both compile before synchronizing and remove retired output only after
successful compilation. Concurrent generators never delete one another's file
types. Declaration check mode detects stale or retired files without writing.
Nested source owners retain their relative paths in generated output.
dist/behaviors and dist/react are disposable package outputs. dist/runway-ui.css
and styles/icons.css remain committed assets. A rebuild must not ship deleted
features merely because their old generated files exist locally. See
build ownership.
Performance fixtures
stories/performance/ owns synthetic workload rendering and measurement. It
composes actual resource, inventory and TanStack chart components; no benchmark
code enters the distributed React runtime. scripts/bench-game-ui.ts runs the
production Storybook fixture with agent-browser, retains raw samples locally,
and compares optional reference regression budgets. See performance.
Chart geometry
TanStack Charts is the only plotting engine. styles/charts/ owns figure/table
layout, never quantitative marks. examples/charts/ owns generic example data
and one React renderer shared by standalone pages and chart stories. Build-site
bundles it once for native-module examples; it is not a new package API.