tutti/packages/ui/system/ui-system.md

# UI System

This document defines the responsibility boundary for the shared visual-system package under `packages/ui/*`.

## Purpose

The shared UI system package exists to hold product-facing visual foundations that are reused across renderer surfaces.

The current package is:

- `packages/ui/system`

It is organized into two public component layers:

- `base`
  Basic visual primitives and foundations such as tokens, icons, Button,
  Input, Dialog, Select, Card, Badge, and Toast.
- `business`
  Multi-end reusable Tutti business display components. These components may
  expose domain display props such as workspace, file, task, or agent state, and
  should compose `base` primitives instead of recreating them.

The package owns:

- design tokens
- shared theme styles
- icon exports
- presentation primitives
- reusable business display components

It does not own:

- business logic or host-side side effects
- app-specific workflows
- daemon, Electron, router, or host adapter calls

## Sortable foundation

`Sortable`, `SortableContent`, `SortableItem`, `SortableItemHandle`, and
`SortableOverlay` are stable `base` primitives installed from the Dice UI
shadcn registry and narrowly adapted to Tutti's input, accessibility, and
reduced-motion contracts. The primitive owns sensors, drag state, layout
strategies, handles, overlays, and caller-provided announcements. Consumers own
business ordering, persistence, optimistic updates, localized copy, and error
recovery.

The adopted Dice UI revision and the Radix/Lucide source-derived helpers are
recorded in the package `NOTICE`. Update that provenance whenever registry
source is refreshed. Storyboard coverage is the visual inventory for enabled,
disabled, keyboard-focus, and overlay states.

## Avatar foundation

`Avatar` is the single high-level identity-image primitive. It owns decorative
image loading, rendered-box-aware image transformation, broken-image fallback,
initial or empty fallback modes, loading presentation, named or numeric sizing,
and a caller-owned overlay slot through `children`. Sources are requested
unchanged with a `no-referrer` request policy by default; callers may override
that policy through `imageProps` for a source that requires it. When the caller
passes `transform`, HTTP(S) sources
request a bucketed two-times-size WebP variant with `fit=inside`, while
preserving the original query string. A failed variant retries the original
source once. Consumers own identity resolution, directly consumable image URLs,
transformation capability, labels, fallback colors, presence semantics, and
overlay content. They never pass buckets or object keys to the component.
The underlying Radix/shadcn parts are intentionally not public. `fallbackColor`
is the narrow exception for caller-owned dynamic identity data; component
defaults still use semantic tokens. Initial fallback content appears only when
both the delivered image and its original fallback are unavailable, never
while a valid image URL is still loading.

`NativeAvatar` is the React Native counterpart for the same identity-image
contract. It uses Native semantic tokens and finite control-backed sizes, keeps
the image decorative, shows loading feedback while a valid source is pending,
and falls back to the caller's stable label when the source is absent or fails.

`NativeProgressBar` is the React Native progress primitive. It clamps
determinate values to the inclusive zero-to-one range, exposes progressbar
accessibility semantics, and accepts `null` for an indeterminate task. Product
phase labels, byte counts, cancellation, and workflow state stay caller-owned.

`NativeControlGlyph` is the decorative React Native control-glyph primitive.
Its finite variants cover add, back, chevron, send, status, and stop shapes;
callers supply the semantic token color and keep the localized accessible name
on the owning control. Chevron direction is explicit, and glyph content remains
hidden from the accessibility tree.

## Current Package Role

`@tutti-os/ui-system` is the single source of truth for:

- CSS token definitions
- structural shared workbench CSS in `packages/workbench/surface/src/styles/workbench.css`
- structural shared terminal CSS in `packages/workspace/terminal/src/styles/terminal.css`
- Tailwind-facing semantic theme variables
- shared SVG and icon APIs
- shadcn-derived React primitives

Desktop renderer code should consume this package instead of defining a second token or primitive layer in `apps/desktop`.

The visual language that this package should serve is defined in [Desktop Visual Language](../../../docs/conventions/desktop-visual-language.md).

## Public API

`@tutti-os/ui-system` should expose a small, stable surface:

- `@tutti-os/ui-system`
  Root runtime entry for shared primitives, icon components, and the small set of utility exports that primitives depend on
- `@tutti-os/ui-system/styles.css`
  Shared stylesheet entry loaded by renderer shells
- `@tutti-os/ui-system/native.css`
  NativeWind stylesheet entry loaded once by React Native renderer shells
- `@tutti-os/ui-system/native`
  React Native primitive and semantic-token entry; this is separate from the
  DOM component entry and must not be imported by desktop renderers. Native
  consumers provide React Native; `react-dom` is optional for this
  platform-specific entry.
- `@tutti-os/ui-system/components`
  Stable component barrel for tooling and rare category-focused imports
- `@tutti-os/ui-system/icons`
  Stable icon barrel for tooling and rare category-focused imports
- `@tutti-os/ui-system/utils`
  Stable utility entry for shadcn CLI integration and primitive support code
- `@tutti-os/ui-system/metadata`
  Tooling entry for component metadata used by storyboard, dev server, and
  agent skills
- `@tutti-os/ui-system/dev-vite`
  Development-tooling entry for external Vite apps that opt into local source
  sync; this is not a runtime component API

Default consumption rules:

- application code should prefer importing primitives and icons from `@tutti-os/ui-system`
- renderer entrypoints should import `@tutti-os/ui-system/styles.css` once
- React Native renderer entrypoints should import
  `@tutti-os/ui-system/native.css` once
- React Native components and screens should import Native primitives and
  semantic tokens from `@tutti-os/ui-system/native`, never from a private app
  palette
- shadcn monorepo aliases may target `@tutti-os/ui-system/components` and `@tutti-os/ui-system/utils`
- application runtime code must not import `@tutti-os/ui-system/dev-vite`
- consumers must not deep import `@tutti-os/ui-system/src/*` or component file
  paths; use the root package and stable subpaths instead

## Automated Enforcement

The repository enforces the shared UI boundary with:

- `pnpm check:ui-boundaries`
- `pnpm check:ui-boundaries:staged`

Use the script output as the source of truth for the mechanically-checkable rules.

- `check:ui-boundaries:staged` is the fast local hook variant for staged files
- `check:ui-boundaries` is the full-repository variant for `pre-push` and CI
- `@tutti-os/workbench-surface/styles.css`, `@tutti-os/workspace-terminal/styles.css`, and `@tutti-os/agent-gui/styles.css` are the only non-UI-system package stylesheets allowed by the boundary check
- `@tutti-os/workbench-surface/styles.css` and `@tutti-os/workspace-terminal/styles.css` should remain structural and variable-driven, not product-branded
- `@tutti-os/agent-gui/styles.css` is a deliberate package contract for the carried agent GUI and workspace-agent panel selectors that still rely on package-owned class names

Keep this check aligned with the package exports and file boundary rules:

- if a new stable public subpath is intentionally added, update both `packages/ui/system/package.json` and the import-check script
- do not "fix" the script by broadening the allowed list unless the package boundary itself is intentionally changing

## Metadata Rules

Every public UI-system metadata entry must have a stable `id`.

- `id` is the user-facing tooling identifier for storyboard anchors, dev server
  metadata, and agent skill lookups
- `id` must be globally unique and use readable kebab-case, for example
  `button`, `dialog-content`, `button-variants`, or `styles-css`
- `id` should not be derived at runtime by consumers; read it from
  `@tutti-os/ui-system/metadata`
- `name` and `export` remain the TypeScript API identity, while `id` is the
  stable human-readable inventory identity
- `layer` must be either `base` or `business`
- `business` components may use business display nouns in their props, but
  should still receive data, labels, status, and callbacks from the consuming
  host

## Component Promotion Protocol

Use this protocol when moving UI from an application or business package into
`@tutti-os/ui-system`.

The UI system follows a shadcn-like self-owned source model:

- Radix or equivalent headless primitives provide accessible interaction
  behavior where a proven primitive exists
- CVA-style variant definitions keep component variants explicit and typed
- Tailwind classes consume shared semantic tokens instead of local palettes
- Tutti owns the checked-in source, public exports, metadata, storyboard
  examples, and boundary validation

Before extracting a component, decide whether the target is `base`, `business`,
or not suitable for UI-system promotion.

Promote to `base` when the component is a foundation primitive:

- it has no product workflow or domain noun in its public contract
- props describe presentation, interaction, accessibility, variants, refs,
  slots, class names, or children
- the component can be reused by unrelated surfaces without explaining a
  business concept
- a known shadcn or Radix primitive can provide the starting point, or the
  exception is documented in review

Promote to `business` when the component is a reusable business display unit:

- it represents a cross-surface Tutti concept such as workspace, file, task,
  agent, run, project, or account display state
- it receives all business data, labels, statuses, permissions, and callbacks
  from the host through props
- it receives user-visible copy through props, labels, or children instead of
  introducing new hardcoded product strings inside the shared component body
- it composes `base` components for buttons, fields, dialogs, cards, icons, and
  overlays instead of rebuilding those primitives locally
- it can be rendered in storyboard with controlled sample data and no daemon,
  router, store, or host adapter

Business promotion uses a copy-first workflow. Move the existing application
component structure into `@tutti-os/ui-system` as intact as possible, preserve
the source DOM hierarchy, visual states, and interaction layout, then remove
host-owned dependencies and standardize the API incrementally. Do not start by
inventing a cleaner abstraction or new visual treatment. Storyboard should first
prove source/screenshot parity; only then should props be generalized into
stable data, labels, actions, variants, and slots.

Promotion is not a redesign. The promoted UI must preserve the original design
unless the user explicitly approves a visual change. Do not add decoration,
layout chrome, controls, icons, copy, motion, states, spacing, or hierarchy that
cannot be traced to the source component or source screenshot. UI-system tokens
and primitives should replace local styling only when they keep the same
observed design and interaction path.

Copy-first promotion includes the candidate's dependent display subcomponents
and third-party-library wrappers. Pure presentational helpers should migrate
with the business component. Reusable wrappers around Radix, floating UI,
resizable panels, drag/drop, virtualization, editor shells, or similar libraries
should become or reuse `base` primitives before the business component composes
them. Host-coupled children must be split into caller-owned data, labels,
callbacks, or slots rather than rewritten from memory inside the promoted
component.

Do not promote a component when it owns:

- daemon, Electron, filesystem, router, or host-adapter calls
- data fetching, cache mutation, persistence, or polling
- global app store ownership
- workspace registration, navigation, onboarding, or other app workflow
  orchestration
- product copy that cannot be supplied by props or children

For every promoted component, define this contract before editing code:

- component `id` and `layer`
- source usage being replaced
- intended reuse surfaces
- public props and callbacks
- host-owned state and side effects that remain outside the component
- stable export path
- metadata entry
- storyboard states and examples
- validation commands

The bundled `packages/ui/system/agent/tutti-ui-system/SKILL.md` skill is the
standard prompt-level workflow for this judgment-heavy promotion step. Boundary
scripts are still required, but they only catch mechanical violations.

## API Shape And Composition

The public API must be derived from the source state matrix and intended reuse
surfaces, not from every conditional branch in the original component.

- Avoid boolean prop proliferation for rendering modes. Standard UI booleans
  such as `disabled`, `loading`, `selected`, `open`, `required`, or `invalid`
  are acceptable when they represent real state. Mode switches such as `isFoo`,
  `showBar`, and `withBaz` should usually become a finite variant,
  discriminated union, explicit component variant, slot, or composed child.
- Use explicit variants when combinations would otherwise create impossible
  states. Prefer a narrow discriminated union or named component variant over a
  component that accepts unrelated mode booleans.
- Prefer `children` and named slots for caller-owned visual regions. Use render
  props only when the shared component must pass data back to the caller.
- User-visible copy must stay caller-owned by default. Do not add hardcoded
  product strings inside `@tutti-os/ui-system` components when the text can be
  supplied by `labels`, `title`, `description`, `children`, or other explicit
  props. If a legacy-compatible fallback string must exist temporarily, treat it
  as compatibility debt rather than the preferred API pattern.
- Use compound components and context only when the component is complex enough
  that consumers need to assemble subparts while sharing state. Do not add a
  provider for a simple card, row, badge, or button wrapper.
- If shared state is necessary, make the context contract narrow and
  injectable: `state`, `actions`, and `meta`. State implementation remains
  outside the visual subcomponents, and host-owned daemon, Electron, router,
  store, query, persistence, filesystem, or workflow behavior remains outside
  the UI-system package.
- For new components, follow the repository's React 19 baseline, including
  `ref` as a prop where a ref is part of the public contract. Do not rewrite
  shadcn or Radix-acquired components only to chase API style parity.

Document the API shape decision before promotion: which state axes became
variants, props, slots, children, compound subcomponents, provider state, or
host-owned caller logic.

## Token Rules

- `src/tokens/renderer-theme.json` is the single semantic-token manifest for
  the shared Web/Native subset. It generates Web CSS renderer variables and
  Native light/dark palettes; renderer-specific literal values may differ when
  their color syntaxes or current visual languages require it. Do not duplicate
  these values in application code.
- `NativeThemeProvider` resolves the operating-system scheme by default, or a
  caller-provided `"light" | "dark"` product preference. Native primitives and
  Mobile composition consume `useNativeTheme()` rather than application-local
  palettes. `nativeTheme` remains only as a dark compatibility value for
  non-rendering callers; this does not yet promise full Desktop/Mobile visual
  parity.
- `pnpm check:ui-boundaries` verifies generated renderer-token outputs stay in
  sync with the manifest. Regenerate them with
  `node tools/scripts/check-ui-renderer-tokens.mjs --write` before formatting
  and committing a manifest change.
- Shared theme styles must support both host-managed
  `html[data-theme="light" | "dark"]` and workspace-app CSS
  `prefers-color-scheme`; explicit `data-theme` values should override system
  preference when both are present.
- Tailwind utilities should consume the same token layer rather than defining a parallel color system
- prefer semantic token names such as `background`, `foreground`, `primary`, `muted`, and `destructive` over raw palette leakage in public APIs
- keep tutti-specific token extensions additive and minimal
- Build primitives for a calm workbench shell, not for marketing-card
  theatrics.

### Native renderer review

The DOM storyboard cannot render React Native primitives faithfully. Each
public Native primitive must therefore have a concrete example in the Mobile
development gallery and be reviewed on a Native renderer before it is promoted
from experimental status. The gallery must import only the stable
`@tutti-os/ui-system/native` entrypoint and render the primitive's public
states; it is the Native counterpart of a DOM storyboard example, not a second
component implementation.

`NativeSheet` uses React Native's window-level `Modal` for its controlled
overlay and does not require a portal provider. It owns the semantic scrim,
bottom-aligned panel, system-back dismissal, screen-reader escape gesture,
accessible backdrop dismissal, keyboard avoidance, and optional fixed `height`.
Its window-level keyboard container uses padding on iOS and height reduction on
Android, with no caller-supplied keyboard height. Callers must supply the
localized `closeAccessibilityLabel`; one fixed height replaces the former
single-value `snapPoints` usage. Keep `@gorhom/bottom-sheet` app-owned for
genuinely complex gesture, animated keyboard, or multi-snap-point sheets rather
than routing the shared compact sheet through its React 19-incompatible portal.

For cross-surface stacking, use shared semantic `z-index` tokens instead of
local magic numbers. Current global layer tokens live in
`packages/ui/system/src/styles/theme.css` and should be the default source of
truth for:

- workbench chrome overlays
- popovers and menus
- toasts
- full-panel overlays
- dialogs and their backdrops

When a surface needs a new global layer, add a responsibility-named token to the
shared theme rather than introducing another raw `z-[12345]` value in app code.
Small component-internal stacking such as `z-1` on a pseudo-element can stay
local when it does not participate in global overlay ordering.

### Z-Index Design Rules

Treat `z-index` as an ordering system, not as a per-component escape hatch.

Use these rules:

- use shared global tokens when a layer can overlap content owned by another component, feature, portal, or renderer surface
- use package-local or component-local variables when the layer only needs to order parts inside one isolated surface
- keep local decorative layering simple; values such as `0`, `1`, `2`, or `3` are acceptable when they never compete with global overlays
- do not introduce new raw high values such as `9999`, `10000`, or `z-[12345]` in app code
- prefer a new responsibility-named token over “one bigger number” when an existing global layer is not sufficient

Questions to ask before adding or changing a layer:

1. Can this element ever overlap a portal, popover, toast, dialog, or another feature-owned overlay?
2. Is this a global interaction layer or only internal ordering inside one component?
3. Would another engineer understand the layer’s purpose from its token name alone?

If the answer to the first question is yes, the layer should almost always use a
shared global token.

### Current Global Layers

The current shared global `z-index` tokens are:

- `--z-workbench-chrome`
  Top or bottom workbench chrome rendered above window content but below global popovers and dialogs.
- `--z-workbench-genie`
  The genie animation layer that must stay above ordinary workbench chrome.
- `--z-popover`
  Cross-feature floating UI such as menus, switchers, and layout popovers.
- `--z-panel`
  Full-panel overlays such as workspace settings surfaces.
- `--z-panel-popover`
  Popovers or menus that are portaled from within a full-panel overlay and must stay above the panel but below dialog backdrops.
- `--z-dialog-overlay`
  Dialog backdrops that should dim or block panel surfaces beneath them.
- `--z-dialog`
  Dialog content rendered above dialog backdrops.
- `--z-dialog-popover`
  Floating controls or host-owned preview windows that must stay above dialog content and backdrop while remaining below tooltips.
- `--z-toast`
  Toast notifications that must remain visible above dialogs and their portaled controls while staying below tooltips.
- `--z-tooltip`
  Short hover/focus guidance that should stay above panels, drawers, and their popovers so clipped text can be inspected across overlay boundaries.

These tokens are intentionally semantic and ordered by responsibility, not by
visual implementation detail.

### Local Layering Rules

Local layers should stay local when they only solve ordering inside one bounded
surface. Good examples:

- a selected tile border inside one settings grid
- a resize handle above adjacent pane content inside one file manager surface
- a tooltip above its own dock icon inside one workbench dock
- background decorations behind launcher content

For these cases:

- prefer package-local variables such as `--workbench-z-dock-tooltip` or `--workspace-file-manager-dialog-overlay-z-index`
- keep the numeric scale tight and relative to the owning surface
- do not promote a local layer into the global theme unless another surface needs to reason about it

### Migration Rules

When touching existing code:

- replace raw high `z-index` values with the nearest existing semantic token when the layer is globally meaningful
- if no existing token matches, add a new one in `packages/ui/system/src/styles/theme.css` and document it here
- if the layer is local-only, prefer a package or component variable instead of a new global token
- remove transitional duplicate declarations such as a Tailwind `z-*` class plus an overriding inline `style.zIndex`

## Reusable Package Styling Rules

Reusable packages outside `packages/ui/*` should not create their own visual
systems. They should consume `@tutti-os/ui-system` primitives, icons, tokens, and
token-backed Tailwind utilities as their default styling model.

For reusable packages that render Tailwind utility classes, consumers are
responsible for including the published package output in Tailwind source
scanning. For example, a consumer of `@tutti-os/workbench-surface` should include
that package's built output in its Tailwind entrypoint or equivalent build
configuration:

```css
@source "../node_modules/@tutti-os/workbench-surface/dist";
```

Within this monorepo, reusable packages that require consumer Tailwind scanning
should declare that requirement in their `package.json`:

```json
{
  "tutti": {
    "tailwindSourceRoot": "src"
  }
}
```

`pnpm check:ui-boundaries` validates that the desktop renderer entrypoint
`apps/desktop/src/renderer/src/style.css` includes matching `@source` directives
for any imported workspace package that declares `tutti.tailwindSourceRoot`.
It also validates that the path matches the declared source root and reports the
exact `@source` line to add or replace.

Tailwind source troubleshooting checklist:

- if a reusable package introduces new utility classes but the desktop UI does not change at runtime, confirm the package declares `tutti.tailwindSourceRoot` when it renders runtime Tailwind classes
- confirm the desktop renderer Tailwind entrypoint includes the package source path through `@source`
- re-run `pnpm check:ui-boundaries` before assuming the issue is a hot-reload or build-cache problem

Package-local CSS in reusable packages is an exception, not the default. Add it
only when the package needs selectors, keyframes, or structural behavior that is
awkward to express through UI system primitives and Tailwind utilities.

When package-local CSS is necessary:

- use UI system CSS variables or Tailwind-facing semantic tokens
- keep the CSS structural and package-responsibility-specific
- do not define raw palette values, a second token layer, or app-specific visual roles
- do not include product styling, product copy, or app-specific state concepts
- document the public stylesheet entrypoint in the package README and package release docs

If a reusable package repeatedly needs visual primitives or new semantic tokens,
prefer moving that foundation into `@tutti-os/ui-system` before adding more
package-local CSS.

## Design Foundation Compliance

All components promoted into `@tutti-os/ui-system` must fully follow the
existing design foundations owned by this package. Promotion must align with the
shared token model, theme variables, spacing rhythm, radius scale, typography,
surface language, focus states, disabled states, and the existing `base`
primitive vocabulary.

Do not introduce a second visual language during promotion. Avoid raw palette
values, ad hoc spacing scales, local radius conventions, duplicate button or
field treatments, or component-specific CSS that should be expressed through
existing tokens or primitives.

Current shared control contracts:

- routine `Button` and `Input` surfaces use `32px` height, the shared `6px`
  `--radius-md`, token-backed text and surface colors, and no decorative
  shadows
- chrome icon buttons stay compact, transparent by default, and use the shared
  chrome text/hover states rather than app-local canvas colors
- text fields use `--transparency-block` for the default surface and
  `--transparency-hover` for hover/focus surfaces
- destructive controls use semantic danger tokens such as `--state-danger` and
  `--state-danger-hover`
- `UnderlineTabs` labels and counts use `font-medium`, so English contexts
  render at `font-weight: 500`; CJK contexts remain aligned through the global
  CJK emphasis rule

After a component is promoted, start an independent design-foundation review
subagent before reporting completion. Give the subagent the promoted component
files, source usage, selected states, storyboard entry, metadata entry, and this
document. The subagent should verify that the component follows the design
foundation and report any drift. If a subagent cannot be started in the current
environment, report the verification as blocked instead of claiming full
design-foundation compliance.

## Component Rules

- `base` primitives should stay low-level and presentation-focused
- `business` components may include reusable business display semantics, but
  must stay host-agnostic and side-effect-free
- `packages/ui/system` is the repository's shared Radix and shadcn host package
- for primitives that exist in the shadcn registry, start from shadcn CLI output targeted at `packages/ui/system`; do not hand-author a fresh component body when the upstream primitive can be downloaded
- keep `packages/ui/system/components.json` healthy enough that `pnpm dlx shadcn@latest add <component> -c packages/ui/system` remains the default acquisition path
- treat CLI-generated source as the canonical starting point; repository-specific edits should stay narrow and mechanical, such as package import aliases, stable barrel exports, icon-layer routing, and token-backed class adjustments required by boundary checks
- if a desired primitive is not available from shadcn, prefer composing directly from `radix-ui` inside `packages/ui/system` and document that exception in the change review or follow-up docs
- if the current package structure makes CLI acquisition awkward, fix the host package structure or configuration first instead of silently replacing the workflow with a handwritten primitive
- keep primitive APIs close to upstream shadcn patterns unless product-specific constraints require a deviation
- do not place app-specific workflows such as launcher flows, workspace
  registration, or route-owned panels in the shared package
- do not add new hardcoded user-visible copy inside `@tutti-os/ui-system`
  components when the text can be supplied by props, `labels`, `title`,
  `description`, or `children`; keep translation lookup and copy selection in
  the caller
- export UI-system components through stable package barrels instead of exposing
  per-file component paths
- only move a component into `@tutti-os/ui-system` when it is a real
  visual-system primitive or reusable business display component with more than
  one plausible consumer
- every public component, icon, utility, style entry, or tooling-visible UI
  export must have metadata in
  `packages/ui/system/src/metadata/components.json`
- metadata `source` paths must point at existing files under `packages/ui/system/src`
  and `from` must use a stable public entrypoint
- run `node tools/scripts/check-ui-metadata.mjs` or
  `pnpm check:ui-boundaries` after adding, removing, or renaming UI-system
  public exports

### Primitive Sourcing Workflow

Use this workflow when adding or replacing a shared primitive:

1. Run shadcn CLI against `packages/ui/system` when the primitive exists in the registry.
2. Keep the downloaded component body as the baseline implementation.
3. Apply only the minimum package-specific adaptation required to satisfy repository rules.
4. Export the primitive through the stable `@tutti-os/ui-system` barrels.
5. Re-run `pnpm check:ui-boundaries` after the adaptation pass.

Repository-specific adaptation is allowed for:

- replacing direct third-party icon imports with `@tutti-os/ui-system` icon exports when the UI boundary check requires it
- switching import aliases to package-local `#components`, `#icons`, or `#lib` paths
- aligning classes with shared CSS tokens or other repository-owned boundary rules

Repository-specific adaptation is not a reason to skip CLI acquisition. The rule of thumb is:

- download first
- adapt second
- do not handwrite the primitive body from scratch unless there is no upstream shadcn primitive to start from

### Business Component Workflow

Use this workflow when promoting reusable business UI:

1. Read existing `@tutti-os/ui-system/metadata` and storyboard entries first.
2. Reuse existing `base` and `business` components when they cover the need.
3. Keep host state, side effects, data loading, routing, and daemon calls in the
   original app or package.
4. Extract only the reusable display surface and typed callback contract.
5. Compose `base` primitives for controls, overlays, cards, icons, and layout
   affordances.
6. Add metadata with `layer: "business"` and a readable stable `id`.
7. Add storyboard examples that cover empty, loading, normal, disabled, and
   error-like display states when those states are part of the public contract.
8. Replace the original duplicated UI with a stable public import from
   `@tutti-os/ui-system`.

Business components should look like controlled React components:

```tsx
<WorkspaceSummaryCard
  workspace={workspace}
  status={workspaceStatus}
  disabled={!canOpenWorkspace}
  onOpen={handleOpenWorkspace}
/>
```

They should not reach back into the host:

```tsx
useWorkspaceStore();
useNavigate();
invokeDaemon();
fetch("/api/workspaces");
localStorage.setItem("workspace", id);
```

## Promotion Review Gate

Use this gate for every base or business component promotion. It adapts
frontend design review practice to Tutti's product standard; do not import
general marketing, portfolio, or decorative frontend heuristics into the shared
workbench system.

### Frictionless

- The migrated consumer preserves the original task path and interaction count
  unless the user approved a behavior change.
- Primary, secondary, destructive, cancel, and recovery actions keep their
  visual hierarchy and remain reachable by keyboard.
- The shared component does not introduce dead ends, hidden required steps, or
  new caller-owned state requirements.

### Quality Craft

- Selected states have before/after visual parity evidence from the source
  route, storyboard, or smallest reproducible view.
- The implementation uses existing `@tutti-os/ui-system` primitives and
  canonical tokens before adding component-local CSS.
- Light, dark, focus-visible, hover, disabled, invalid, selected, loading, and
  reduced-motion states are covered when they exist in the public contract.
- Layout, density, spacing, radius, typography, icon sizing, border, color,
  opacity, shadow, and responsive behavior have no unapproved drift.
- Any intentional delta is named, justified, and reported as approved rather
  than hidden inside the promotion.

### Trustworthy

- Loading, empty, disabled, error-like, and permission-limited states keep clear
  labels and actionable recovery where the source had them.
- AI-generated or inferred content keeps provenance, confidence, or disclaimer
  treatment host-owned and visible when applicable.
- Error copy and status labels are supplied by the caller or labels props; the
  shared component must not invent product policy or workflow meaning.
- New user-visible copy should enter the component boundary through props,
  labels, or children rather than new hardcoded strings inside the shared
  component.
- The component boundary leaves daemon, Electron, router, persistence, query,
  filesystem, polling, i18n lookup, and workflow orchestration in the host.

Report the promotion review in this structure:

- context: component id/layer, source usage, user task, selected states, and
  intended reuse surfaces
- summary: pass, needs work, or blocked
- pillar assessment: Frictionless, Quality craft, Trustworthy
- design-system compliance: tokens, primitives, metadata, storyboard, stable
  exports, and public imports
- issues: blocking, major, and minor, with concrete file references
- validation: exact commands and results
- risks: uncovered states, unavailable visual evidence, unresolved subagent
  review, or approved visual deltas.

## Agent Skill Rules

Use the bundled `tutti-ui-system` skill for prompt-level work involving
`@tutti-os/ui-system`. The source lives under
`packages/ui/system/agent/tutti-ui-system/SKILL.md` so it can ship with the UI
system package.

The skill should route internally across these scenarios:

- use an existing UI-system component
- extract a new `base` component
- extract a new `business` component
- maintain metadata, ids, exports, or storyboard coverage

The skill must treat this document, `packages/ui/AGENTS.md`, metadata, and
boundary scripts as the source of truth. It should not duplicate long copies of
the rules; it should point the coding agent to the right files, force the
base/business decision, and require validation.

External business repositories that promote UI into the shared system should add
a short agent instruction such as:

```md
When promoting business UI into @tutti-os/ui-system, use the
tutti-ui-system skill and follow packages/ui/system/ui-system.md.
```

After installing `@tutti-os/ui-system`, external repositories can configure the
bundled skill with:

```bash
pnpm exec tutti-ui-system-install-skill
```

The command copies the bundled skill into `.codex/skills/tutti-ui-system` in
the current repository. When `.tutti-ui-system-dev/` is present, the installer
prefers the synced source checkout so the skill and bundled UI-system rules stay
aligned with the current local UI-system source. It refuses to overwrite local
changes unless run with `--force`.

## Storyboard Rules

`apps/ui-storyboard` is the local component inventory and example surface for
`@tutti-os/ui-system`.

- the component list, categories, statuses, and inventory counts must come from
  `@tutti-os/ui-system/metadata`
- storyboard navigation should group component stories by `layer`
- examples may stay hand-written so they can show realistic composition and
  edge states
- visible component stories should display the component `id` prominently and
  support copying it from the UI
- the storyboard should import public UI-system entrypoints and metadata, not
  private component file paths
- keep the storyboard as a development surface; it should not become a product
  shell or marketing page

## External Dev Server Rules

The UI-system dev server exists only for local external development. It lets an
external app keep normal `@tutti-os/ui-system` imports while temporarily resolving
the stable entrypoints to a generated local cache.

- start it with `pnpm --filter @tutti-os/ui-system dev:server`
- external Vite apps opt in with `tuttiUISystemDev` from
  `@tutti-os/ui-system/dev-vite`
- when the server is unavailable, external apps must fall back to their
  installed package in `node_modules`
- the generated `.tutti-ui-system-dev/` cache belongs in the external app's
  `.gitignore`
- Tailwind consumers must include both the installed package output and the
  generated dev cache in source scanning, for example
  `@source "../node_modules/@tutti-os/ui-system/dist";` and
  `@source "../.tutti-ui-system-dev";`
- do not make CI, production builds, or package publishing depend on the dev
  server
- `@tutti-os/ui-system/dev-vite` may be imported only from bundler config or
  tooling files

## Icon Rules

- renderer-visible icons should be exported through the root package or the stable `@tutti-os/ui-system/icons` barrel
- promoted components and storyboard examples must consume icons from
  `@tutti-os/ui-system/icons`; do not leave inline SVG/data URI icons,
  app-local icon assets, or direct third-party icon imports in promoted UI
- generic system icons may wrap a third-party icon set
- product marks and custom status glyphs should live as local SVG components in the package
- icons should default to `currentColor` unless a specific token-driven treatment is required

## Review Heuristics

When reviewing a change under `packages/ui/*`, prefer these checks:

- is the new export responsibility-named and stable enough to support for a while
- could a consumer do the same work through the root package instead of a new subpath
- is a proposed helper really part of primitive support, or should it stay local to one app
- does the change make the package easier to consume without exposing its folder layout

## Review Questions

When reviewing a change under `packages/ui/*`, ask:

1. Is this a visual-system concern or an app-specific component?
2. Does this change preserve CSS tokens as the source of truth?
3. Is the package API still narrow, stable, and responsibility-named?
4. Would this be clearer if it stayed local to one app instead?
5. Are consumers being nudged toward the root package and stable barrels instead of internal paths?