@tutti-os/ui-system 0.0.1

package/agent/nextop-ui-system/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: nextop-ui-system
+description: Use when working with @tutti-os/ui-system components, replacing local UI with shared components, querying component ids or metadata, promoting UI into shared base or business components, or maintaining UI-system storyboard inventory.
+---
+
+# Nextop 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, storyboard coverage is not satisfied by metadata
+alone. The promotion flow must also add or update a real renderable example in
+`apps/ui-storyboard` so the component is visible in navigation and can be
+visually reviewed in shared docs immediately after promotion.
+
+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 split into caller-owned data, labels, callbacks, or slots before the
+business component is considered promoted.
+
+## Design Foundation Verification
+
+Every promoted component must comply with
+`ui-system.md`, especially the shared tokens,
+theme variables, spacing, radius, typography, surface language, interactive
+states, and existing `base` primitive vocabulary.
+
+Explicitly check and report all of these before completion:
+
+- color and surface styling come from UI-system semantic tokens rather than raw
+  palette values
+- panels, rows, controls, and overlays compose existing base primitives where
+  applicable instead of recreating them locally
+- storyboard shows the component's real promoted surface rather than only a
+  documentation wrapper
+- migrated consumers no longer depend on a separate visual token system for the
+  promoted surface
+
+Run the Nextop promotion review gate before reporting completion. The gate is
+adapted from frontend design review practice but constrained to Nextop's dense
+workbench product language:
+
+- Frictionless: the migrated consumer preserves the original task path, keeps a
+  clear action hierarchy, and does not bury primary or recovery actions.
+- Quality craft: visual parity evidence is captured for selected states, shared
+  tokens and primitives are used, light/dark and interactive states work, and no
+  unapproved raw palette, spacing, radius, typography, or motion drift remains.
+- Trustworthy: empty, loading, disabled, error-like, permission-limited, and
+  AI-generated-content states keep clear labels, actionable recovery, and
+  host-owned policy or provenance outside the shared component.
+
+After promoting a base or business component, start an independent subagent to
+review design-foundation compliance before reporting completion. Provide the
+subagent with the promoted files, source usage, selected states, storyboard and
+metadata entries, and the UI-system guidelines. If subagents are unavailable,
+state that design-foundation verification is blocked and do not claim full
+compliance.
+
+Report the gate result with:
+
+- context: source usage, promoted component id/layer, user task, selected states
+- status: pass, needs work, or blocked
+- pillar assessment: Frictionless, Quality craft, Trustworthy
+- issues grouped as blocking, major, and minor
+- validation commands and exact results
+- remaining risks, uncovered states, or approved visual deltas
+
+## API Composition Review
+
+When converting source states into public props, review the API shape before
+writing the promoted component:
+
+- avoid boolean prop proliferation for rendering modes; mode axes such as
+  `isFoo`, `showBar`, or `withBaz` must come from code evidence and usually
+  become a finite variant, discriminated union, explicit component variant,
+  slot, or composed child
+- keep standard UI booleans such as `disabled`, `loading`, `selected`, `open`,
+  `required`, and `invalid` only when they represent real component state and
+  cannot create impossible combinations
+- prefer `children` or named slots for caller-owned visual regions; use render
+  props only when the shared component must pass data back to the caller
+- use compound components and context only for genuinely complex reusable
+  structures where consumers need to compose subparts without prop drilling
+- if shared state is needed, define a narrow context value as `state`,
+  `actions`, and `meta`; providers may inject state but must not own daemon,
+  Electron, router, store, query, persistence, or workflow side effects
+- for new React components in this React 19 codebase, prefer the React 19 API
+  shape such as `ref` as a prop; do not churn shadcn or Radix-acquired code only
+  to normalize style when behavior and public API are already sound
+
+Report the API composition decision with the state matrix: which differences
+became props, variants, slots, children, explicit variants, provider state, or
+stayed host-owned.
+
+## Validation Commands
+
+Run the smallest relevant checks from the selected reference. Common checks are:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @tutti-os/ui-storyboard typecheck
+```
+
+If runtime component code changed, also run the relevant package typecheck or
+consumer build.
+
+When a base component is promoted, verify both of these conditions before
+reporting completion:
+
+- the component metadata opts into storyboard visibility when appropriate
+- `apps/ui-storyboard` contains a concrete rendered example for the promoted
+  component states, not just inventory wiring

package/agent/nextop-ui-system/references/extract-base-component.md

@@ -0,0 +1,87 @@
+# Extract Base Component
+
+Use this reference when the target is a low-level visual primitive.
+
+## Base Criteria
+
+Proceed only if the public API has no domain noun and props describe generic UI
+concerns:
+
+- presentation and variants
+- interaction and accessibility
+- refs, slots, class names, and children
+- controlled or uncontrolled primitive state
+
+If the component represents a workspace, file, task, agent, run, project,
+account, or other business concept, use `promote-business-component.md`
+instead.
+
+## Workflow
+
+1. Check metadata and existing exports first.
+2. Read the bundled `ui-system.md` before implementation and
+   treat it as a hard gate for the extraction. The component must follow the
+   shared token, theme variable, spacing, radius, typography, surface,
+   interactive-state, accessibility, and reduced-motion rules from
+   `@tutti-os/ui-system`; do not preserve or introduce caller-local styling
+   when it conflicts with those guidelines.
+3. If the primitive exists in the shadcn registry, acquire it through shadcn CLI
+   targeted at `packages/ui/system`.
+4. Decide the primitive API before editing:
+   - use finite variants or discriminated unions for mutually exclusive visual
+     modes
+   - keep standard UI booleans such as `disabled`, `loading`, `selected`,
+     `open`, `required`, and `invalid` only when they represent real states
+   - prefer `children`, slots, refs, and class names for composition instead
+     of broad render props
+   - use compound components or context only when consumers need to assemble
+     reusable subparts that share primitive state
+   - follow the React 19 baseline for new hand-authored components, but do not
+     rewrite shadcn or Radix internals only for API-style churn
+5. Adapt only package aliases, icon routing, tokens, stable exports, metadata,
+   storyboard examples, and boundary-check issues.
+6. Keep helper exports minimal and directly tied to primitive support.
+7. Add metadata with `layer: "base"`.
+8. Add storyboard coverage for the public states and variants exposed by the
+   primitive.
+   - This is mandatory for base-component promotion.
+   - Do not treat `storyboard: true` in metadata as sufficient by itself.
+   - Add or update a real renderable example in `apps/ui-storyboard` so the
+     component appears in navigation and can be visually reviewed immediately.
+9. Replace duplicated local UI only after the shared primitive exists.
+10. Run the promotion review gate from
+    `ui-system.md`: verify Frictionless task
+    preservation, Quality Craft visual/token/state parity, and Trustworthy
+    status/error/accessibility behavior for the migrated consumer.
+11. Start an independent design-foundation review subagent after promotion. The
+    review must check the promoted files against
+    `ui-system.md`, existing tokens, primitives,
+    API shape, storyboard coverage, and metadata. Resolve any reported design
+    drift before completion.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @tutti-os/ui-storyboard typecheck
+pnpm --filter @tutti-os/ui-system typecheck
+```
+
+If a consumer was migrated, also run that consumer's typecheck or build.
+
+Before reporting completion, confirm storyboard delivery at two levels:
+
+- inventory: the component is discoverable from storyboard navigation
+- rendering: the component has a concrete example that renders its public
+  states or variants inside `apps/ui-storyboard`
+
+Do not report full design-foundation compliance unless the subagent review ran
+and found no unresolved drift. If subagents are unavailable, report the
+verification as blocked.
+
+Report the promotion review result with the component id, selected states,
+Frictionless / Quality Craft / Trustworthy pillar status, blocking/major/minor
+issues, validation commands, and remaining risks or approved visual deltas.

package/agent/nextop-ui-system/references/maintain-inventory.md

@@ -0,0 +1,45 @@
+# Maintain Inventory
+
+Use this reference when changing component ids, metadata, exports, or storyboard
+inventory without promoting a new component.
+
+## Metadata Rules
+
+Every public UI-system entry must have metadata with:
+
+- stable readable `id`
+- globally unique kebab-case id
+- `layer` as `base` or `business`
+- `source` under `packages/ui/system/src`
+- stable public `from` entrypoint
+
+Do not expose `src/*` layout as public API and do not encourage per-file deep
+imports.
+
+## Storyboard Rules
+
+Keep storyboard grouped by:
+
+- `Foundation`
+- `Base Components`
+- `Business Components`
+
+Visible component stories should support copying the component id.
+
+When a base component is newly promoted into `@tutti-os/ui-system`, updating
+inventory alone is not enough. The same change must also add or refresh a real
+renderable example in `apps/ui-storyboard` so the promoted component is
+immediately reviewable from the shared storyboard.
+
+When changing metadata or storyboard inventory, keep ids stable unless the
+rename is intentional and callers or docs are updated together.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @tutti-os/ui-storyboard typecheck
+```

package/agent/nextop-ui-system/references/promote-business-component.md

@@ -0,0 +1,316 @@
+# Promote Business Component
+
+Use this reference when business-side UI should become a reusable
+host-agnostic display component.
+
+## Business Criteria
+
+Proceed only if the component can render from props with no host side effects.
+Business components may expose domain display props such as workspace, file,
+task, agent, run, project, account, status, permission, labels, and callbacks.
+
+Do not promote UI that owns daemon, Electron, router, store, query, persistence,
+polling, filesystem access, or workflow orchestration.
+
+## Agent-Owned Analysis
+
+The agent must automatically analyze the candidate from code evidence. Do not
+ask the user to provide the state matrix or props boundary unless the code has
+conflicting evidence or an unclear business meaning.
+
+Scan:
+
+- source component and nearby helpers
+- dependent presentational subcomponents imported by the source component
+- third-party-library wrappers used by the candidate UI, such as Radix,
+  floating UI, resizable panels, drag/drop, virtualization, or editor shells
+- call sites and conditional rendering branches
+- props, types, tests, mocks, fixtures, and sample data
+- relevant i18n keys and resolved labels
+- existing UI-system metadata and components
+
+Build a state matrix from that evidence. For each candidate state, record:
+
+- state name
+- source file or branch proving the state
+- props or data needed to render it
+- variation axes and whether each axis is visual, structural, behavioral, or
+  host-owned
+- host-owned behavior that must stay outside the shared component
+- whether the state belongs in the shared component contract
+
+## Agent-Owned Boundary Decision
+
+The agent decides the proposed component boundary before implementation:
+
+- component `id` and `layer: "business"`
+- source usage being replaced
+- intended reuse surfaces
+- public props and callbacks
+- API shape decision: variants, discriminated unions, slots, children, explicit
+  component variants, compound subcomponents, provider state, and host-owned
+  caller logic
+- host-owned state and side effects that remain outside
+- states that will appear in storyboard
+- stable export path and metadata entry
+
+If the candidate is not reusable or cannot stay host-agnostic, do not promote
+it. Prefer using existing components or keeping the UI local.
+
+## API Composition Gate
+
+Before writing the promoted component, convert the state matrix into a public
+API deliberately:
+
+1. List every visual, structural, and behavioral variation found in source
+   evidence.
+2. Keep only standard state booleans such as `disabled`, `loading`, `selected`,
+   `open`, `required`, or `invalid` when they represent real states and do not
+   create impossible combinations.
+3. Replace mode booleans such as `isFoo`, `showBar`, and `withBaz` with a
+   finite variant, discriminated union, explicit component variant, slot, or
+   composed child.
+4. Prefer `children` or named slots for caller-owned visual regions. Use render
+   props only when the shared component needs to pass data back to the caller.
+5. Use compound components and context only when consumers need to assemble
+   subparts while sharing state. A simple row, card, badge, toolbar, or display
+   panel should stay as a direct props-driven component.
+6. If shared state is necessary, define a narrow injectable context contract as
+   `state`, `actions`, and `meta`. Providers may adapt caller state, but daemon,
+   Electron, router, store, query, persistence, filesystem, i18n lookup, and
+   workflow orchestration remain outside `@tutti-os/ui-system`.
+7. For new React components, use the repository's React 19 baseline, including
+   `ref` as a prop when needed. Do not rewrite shadcn or Radix-acquired
+   internals solely to normalize API style.
+
+Stop promotion if the only way to represent the source states is a broad bag of
+unrelated boolean props or leaked host state. Narrow the boundary, create
+explicit variants, or keep the UI local.
+
+## Implementation Blueprint
+
+Use a copy-first promotion workflow. The first implementation should be a
+props-driven copy of the source business UI, not a new abstraction designed from
+memory. Preserve the source DOM hierarchy, visual structure, spacing, state
+branches, slots, and interaction affordances until parity is visible in
+storyboard. Only after parity exists should the API be tightened and generalized.
+
+Run promotion as a loop: migrate, review, migrate, review. The first migration
+must make source-backed parity visible; review then measures drift against the
+original code and screenshot; the next migration closes those findings without
+redesigning. Continue until no material DOM, visual, token, state, icon, or
+storyboard coverage drift remains. Do not treat the first extracted abstraction
+as done if review still reports medium or high difference.
+
+The promoted UI must follow the original design. Do not introduce new visual
+ideas while promoting: no extra decoration, layout chrome, icons, controls,
+copy, motion, spacing, state branches, or hierarchy that cannot be traced to the
+source UI or the user's screenshot. Token replacement and primitive composition
+are allowed only when they preserve the observed design and interaction path.
+
+Icons are part of that source-derived visual contract and must still enter the
+shared package through the UI-system icon layer. When the source UI uses an
+icon, first reuse an existing `@tutti-os/ui-system/icons` export. If no
+matching icon exists, promote the source-derived SVG or mark into
+`packages/ui/system/src/icons`, add metadata, and consume that exported icon
+from the business component or storyboard. Do not leave inline SVG/data URI
+icons, app-local asset imports, or direct third-party icon imports in promoted
+components or storyboard examples.
+
+Copy and classify dependent subcomponents during the same migration. If a
+nested helper is pure display, move it with the business component and convert
+host data to props. If it wraps a third-party UI behavior that is reusable
+outside the business domain, promote or reuse it as a `base` primitive first and
+compose it from the business component. If it owns host state, i18n lookup,
+daemon calls, router/filesystem access, persistence, or workflow orchestration,
+leave that behavior in the caller and replace the nested region with data,
+labels, callbacks, or slots. Do not rewrite a new nested component from memory
+while the original source behavior still exists to copy.
+
+Implement the promoted component directly from three inputs:
+
+- the code-evidence state matrix
+- the proposed public props and callback boundary
+- the existing candidate source UI or visual surface being extracted
+
+The promoted component should start as a props-driven version of the candidate
+source with host-owned behavior removed. Preserve the real visual structure,
+component composition, class names, spacing, icons, and state-specific branches
+unless they depend on host-owned behavior. Replace host-owned behavior with
+public props, callbacks, caller-owned slots, or explicit variants. Add
+storyboard examples for every accepted public state in the same change so the
+review can inspect the finished implementation instead of a preflight draft.
+Do not add states, controls, copy, icons, animation, or visual wrappers that the
+source component did not have unless the user explicitly asks for that design
+change.
+
+Generalize in this order:
+
+1. Copy the existing component structure and nearby presentational helpers.
+2. Trace dependent subcomponents and third-party wrappers; move pure display
+   helpers with the component, promote reusable third-party wrappers to `base`
+   primitives, and mark host-coupled children as caller-owned slots or data.
+3. Replace host imports, data derivation, i18n lookup, store reads, side effects,
+   and daemon/router/filesystem calls with props, labels, callbacks, or slots.
+4. Recreate the original visual states in storyboard before simplifying the API.
+5. Run independent review against the source UI and close material drift before
+   simplifying the API.
+6. Standardize the API names and types around data, labels, actions, variants,
+   and slots while preserving visual and behavioral parity.
+7. Replace app-local styling with UI-system tokens and base primitives only when
+   the replacement does not change the observed UI or interaction path.
+8. Reject or remove any invented UI added during promotion unless it is backed
+   by source evidence or an explicit user-approved visual change.
+
+Do not skip directly to a polished abstraction. If the first promoted version
+cannot be compared against the source screenshot or source state, the promotion
+is incomplete.
+
+If the draft still needs app state, navigation, fetching, persistence, i18n key
+lookup, or host adapters to render, stop and revise the component boundary
+instead of promoting it.
+
+## Promotion Chain Demo
+
+Example request:
+
+```text
+Promote the managed agent settings table into @tutti-os/ui-system.
+```
+
+Expected chain:
+
+1. **Analyze source evidence**
+   - Read the source table, settings panel call sites, tests, mocks, and i18n
+     labels.
+   - Check existing metadata for reusable table, badge, button, dialog, and
+     icon primitives.
+2. **Build the state matrix**
+
+   ```text
+   normal
+   - Evidence: settings table renders installed agents with status and actions.
+   - Props/data: rows, status labels, action labels, icon slots, callbacks.
+   - Host-owned: install/uninstall orchestration, queue state derivation, i18n.
+   - Contract: yes.
+
+   empty
+   - Evidence: settings surface renders no configured agents.
+   - Props/data: empty title/body.
+   - Host-owned: deciding whether inventory is empty.
+   - Contract: yes.
+
+   disabled
+   - Evidence: actions disabled while an operation is pending.
+   - Props/data: disabled rows or disabled actions.
+   - Host-owned: permission and pending-operation calculation.
+   - Contract: yes.
+
+   error-like
+   - Evidence: row can show install failure or unavailable status.
+   - Props/data: tone, status label, supporting text.
+   - Host-owned: failure classification and retry behavior.
+   - Contract: yes.
+   ```
+
+3. **Decide the boundary before implementation**
+   - `id`: a stable kebab-case business component id, for example
+     `example-business-component`
+   - `layer`: `business`
+   - Export: a matching PascalCase component name, for example
+     `ExampleBusinessComponent`
+   - Public props: rows, labels, icon render slots, action callbacks, disabled
+     flags, status/tone fields, empty-state copy.
+   - API shape: row status as finite tone values, callbacks as host-provided
+     actions, empty state copy as labels, and no install/uninstall mode
+     booleans. If the table later needs caller-owned row adornments, prefer a
+     named slot or composed child over a broad render prop.
+   - Host-owned behavior: i18n lookup, daemon calls, install queue,
+     confirmation dialogs, persistence, routing, and state derivation.
+4. **Implement the promoted component with copy-first parity**
+   - Copy the current candidate source into the final
+     `packages/ui/system/src/components/<component-dir>/index.tsx` component.
+   - Copy dependent presentational helpers and classify any third-party
+     wrappers before changing behavior. Reuse or promote base primitives for
+     reusable library wrappers instead of rebuilding them in the business file.
+   - Route icons through `@tutti-os/ui-system/icons`: reuse existing exports or
+     promote source-derived icons into the package icon layer with metadata
+     before using them in the component or storyboard.
+   - Keep the real table layout, status cells, action affordances, icon
+     placement, empty state, nested display helpers, and disabled/error branches.
+   - Replace host behavior with props, labels, callbacks, and caller-owned
+     slots: i18n lookup, queue state, confirmation dialog decisions, daemon
+     calls, and install orchestration stay outside the component.
+   - Only after storyboard parity is visible, simplify the copied API toward
+     durable `items`, `labels`, `actions`, explicit variants, and slots.
+   - Make only package integration edits: final exported prop types, imports,
+     class cleanup, and package-local helpers.
+   - Export it from stable barrels.
+   - Add metadata with `layer: "business"` and storyboard coverage for the
+     accepted states.
+   - Replace the original app UI with `@tutti-os/ui-system` imports while
+     leaving host-owned behavior in the caller.
+5. **Validate and report**
+   - Review the finished implementation through the storyboard states and the
+     migrated consumer surface.
+   - Start an independent design-foundation review subagent. Give it the
+     promoted files, original source usage, selected state matrix, storyboard
+     entry, metadata entry, and `ui-system.md`.
+   - Include the API shape review in the handoff: accepted booleans, variants,
+     slots or children, explicit variants, provider state if any, and
+     host-owned behavior kept in the caller.
+   - Resolve any subagent-reported design drift before reporting completion.
+   - Run the promotion review gate: Frictionless task path and action hierarchy,
+     Quality Craft visual parity and token/state coverage, and Trustworthy
+     labels, recovery, policy, and provenance behavior.
+   - Run metadata, boundary, storyboard, and relevant package checks.
+   - Report the state matrix summary, final boundary, promotion review result,
+     subagent design-foundation result, validation results, and uncovered
+     risks.
+
+## Implementation
+
+1. Copy the existing business component structure into `packages/ui/system`
+   before abstracting it.
+2. Keep all host-owned behavior in the caller by replacing it with props,
+   labels, callbacks, or caller-owned slots.
+3. Preserve the source visual and interaction shape until storyboard parity is
+   visible.
+4. Standardize the API incrementally. Do not add new mode booleans or
+   host-owned state while moving the candidate UI into the shared package.
+5. Add stable exports and metadata with `layer: "business"`.
+6. Add storyboard examples for normal, empty, disabled, loading, and error-like
+   states when those states exist in the public contract.
+7. Migrate callers by replacing only the visual surface.
+8. Run the promotion review gate from
+   `ui-system.md` against the promoted component
+   and migrated consumer.
+9. Start the design-foundation review subagent and resolve any reported drift.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @tutti-os/ui-storyboard typecheck
+pnpm --filter @tutti-os/ui-system typecheck
+```
+
+If a consumer was migrated, also run that consumer's typecheck or build.
+
+Report:
+
+- state matrix summary
+- component boundary decision
+- API composition decision and any rejected boolean or state combinations
+- promotion review result with Frictionless / Quality Craft / Trustworthy
+  pillar status and blocking/major/minor issues
+- design-foundation subagent result
+- validation commands and results
+- remaining risks or uncovered states
+
+Do not report full design-foundation compliance unless the subagent review ran
+and found no unresolved drift. If subagents are unavailable, report the
+verification as blocked.