tutti-ui-system

# Tutti UI System

Use this skill as the single entrypoint for `@tutti-os/ui-system` component
reuse, extraction, promotion, metadata, and storyboard work.

## Non-Negotiable Standard

Any UI promoted into `@tutti-os/ui-system` must fully follow the UI-system
design standard before it can be reported as complete.

Treat these as hard requirements, not cleanup suggestions:

- use UI-system semantic tokens and existing shared CSS variables; do not leave
  raw `hex`, `rgb(...)`, `rgba(...)`, ad hoc gradients, or app-local palette
  values in promoted components or their storyboard examples unless the source
  of truth already exposes them as approved tokens
- compose existing UI-system `base` primitives such as `Card`, `Button`,
  `Tooltip`, `Dialog`, and related vocabulary before creating custom panel,
  button, field, or overlay treatments
- use icon components from `@tutti-os/ui-system/icons` for promoted
  components and storyboard examples. Do not inline SVG/data URI assets, import
  app-local icon files, or pull third-party icon packages directly from promoted
  UI. If the source UI depends on an icon that is not in the UI system, promote
  the source-derived icon into `packages/ui/system/src/icons` with metadata
  first, then consume the UI-system icon export.
- make storyboard examples render the real component surface and states; do not
  rely on surrounding docs chrome to hide component-level visual drift or to
  fake the final panel/surface language
- when a consumer is migrated, its final rendered result must also follow the
  same UI-system visual standard; a temporary bridge may help wiring, but it is
  not acceptable as the final visual implementation if it keeps a second token
  system or divergent component styling

If these conditions are not met, report the promotion as incomplete or blocked,
not complete.

## Source Of Truth

Read these before editing:

1. nearest `AGENTS.md` for the target code
2. local `AGENTS.md` bundled with this skill
3. local `ui-system.md` bundled with this skill
4. component metadata from the first available source:
   - `GET http://127.0.0.1:4100/components`
   - `packages/ui/system/src/metadata/components.json`
   - `@tutti-os/ui-system/metadata` from the installed package

Use stable public imports only:

- `@tutti-os/ui-system`
- `@tutti-os/ui-system/components`
- `@tutti-os/ui-system/icons`
- `@tutti-os/ui-system/metadata`
- `@tutti-os/ui-system/styles.css`
- `@tutti-os/ui-system/utils`

Never deep import `@tutti-os/ui-system/src/*` or per-file component paths.

## Route The Task

Read only the reference file that matches the task.

- Using or querying existing components:
  `references/use-existing-component.md`
- Extracting a low-level base primitive:
  `references/extract-base-component.md`
- Promoting reusable business UI into a shared component:
  `references/promote-business-component.md`
- Maintaining ids, metadata, exports, or storyboard inventory:
  `references/maintain-inventory.md`

## Global Boundaries

Keep these outside `@tutti-os/ui-system` components:

- daemon, Electron, filesystem, router, or host adapter calls
- data fetching, cache mutation, persistence, polling, and global store
  ownership
- workflow orchestration such as onboarding, workspace registration, install or
  uninstall flows, confirmation dialogs, queueing, or navigation
- i18n key lookup and business-specific copy derivation unless supplied by
  props, children, or labels

For any promoted public component, add stable exports, metadata, and storyboard
coverage that match the chosen reference workflow.

For promoted base components, preview coverage is not satisfied by metadata
alone. DOM components need a real renderable example in `apps/ui-storyboard`.
React Native components need a real renderable example in the Mobile
development gallery because the DOM storyboard cannot render their final
surface. In both cases, the example must use the stable public entrypoint and
show the component's public states.

For business component promotion, use a copy-first workflow: move the existing
business component structure as intact as possible, preserve the real DOM,
visual hierarchy, state branches, and interaction layout, then progressively
remove host dependencies and standardize the public API. Do not begin by
inventing a cleaner abstraction or new visual treatment. The state matrix,
props boundary, and candidate source UI define what to copy, what to keep
caller-owned, and what to standardize after parity exists.

Treat business component promotion as an iterative migration-review loop, not a
single extraction pass:

1. migrate the source UI copy-first
2. recreate source-backed states in storyboard
3. run independent review against the original source and screenshot
4. migrate again to close review findings
5. repeat review until source/design parity is acceptable

Only after that loop should the API be generalized further. Do not report the
component as complete after the first migration if review still shows material
DOM, visual, token, state, icon, or storyboard coverage drift.

The promoted UI must follow the original design exactly unless the user
explicitly approves a visual change. Do not add new decoration, controls,
icons, layout chrome, copy, motion, states, spacing, or visual hierarchy that
does not exist in the source UI or provided screenshot. If UI-system token or
primitive replacement is needed, it must preserve the observed design and
interaction path rather than becoming a redesign.

Copy-first also applies to dependent presentational subcomponents and
third-party-library wrappers used by the candidate UI. Do not copy only the top
level JSX and recreate nested behavior from memory. Trace the dependency tree:
pure display helpers should move with the component; reusable wrappers around
Radix, floating UI, resizable panels, virtualization, or similar libraries
should be promoted or reused as `base` primitives first; host-coupled children
must be sp