tutti/packages/ui/system/AGENTS.md

# AGENTS.md

## Scope

This file applies to `packages/ui/system/*`.

`packages/ui/system` is the source package for `@tutti-os/ui-system`, the
shared Tutti UI component library. It owns shared CSS tokens, theme styles,
icon exports, presentation primitives, reusable host-agnostic business display
components, component metadata, storyboard inventory, and the bundled
`tutti-ui-system` agent skill.

Before changing components, icons, metadata, styles, storyboard examples, or
the bundled skill, read `ui-system.md`.

UI-system design compliance is a release gate for this package, not a follow-up
task. If a promoted component does not yet follow the shared token model,
surface language, primitive vocabulary, and storyboard evidence standard, do
not report it as complete.

## Public API

Stable public imports are:

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

Rules:

- prefer adding exports to an existing public barrel before introducing a new
  public subpath
- do not expose `src/*` layout as public API
- do not encourage per-file deep imports such as
  `@tutti-os/ui-system/components/button`
- if package exports change intentionally, update both the package exports and
  the UI-boundary check script

## Component Library Rules

- keep `base` components low-level, generic, and
  frontend-foundation-focused
- allow `business` components only when they are reusable business display
  components that remain host-agnostic and side-effect-free
- business components may expose domain display props such as workspace, file,
  task, agent, status, permission, and callbacks, but must not own daemon,
  Electron, router, store, query, filesystem, persistence, or workflow calls
- before promoting a business component, scan source usage, build a
  code-evidence state matrix, and define the public props boundary from that
  evidence; after that, promote it directly into `packages/ui/system` and add
  storyboard coverage for the accepted states
- business components should compose `base` primitives instead of recreating
  buttons, fields, dialogs, cards, icons, or overlays
- promoted components and their storyboard examples must use UI-system semantic
  tokens and approved shared CSS variables; do not leave raw `hex`,
  `rgb(...)`, `rgba(...)`, ad hoc gradients, or app-local palette values in the
  final UI-system implementation unless they already come from approved shared
  tokens
- storyboard coverage must show the component's real promoted surface and
  states; do not rely on surrounding docs chrome or wrapper panels to mask
  component-level visual drift
- UI storyboard foundation content is JSON-driven. When changing documented
  token, color, typography, spacing, radius, motion, or overview display data,
  edit `apps/ui-storyboard/src/foundation/*.json` directly instead of
  hardcoding those values in `apps/ui-storyboard/src/App.tsx`
- migrated consumers must end on the same UI-system visual implementation for
  the promoted surface; temporary bridges are allowed only for wiring, not as a
  separate long-lived token or styling system
- treat this package as the shared shadcn and Radix host package
- when a primitive exists in the shadcn registry, acquire it through shadcn CLI
  targeted at this package instead of handwriting the component body
- keep `components.json` and package aliases usable enough that CLI download
  remains the default path for shared primitives
- after CLI acquisition, limit edits to narrow package-specific adaptation such
  as icon routing, import aliases, stable exports, and boundary-check fixes
- keep CSS variables as the source of truth for token values
- prefer semantic token naming over raw palette leakage in public APIs
- keep helper exports minimal and tied to primitive support, not general
  convenience reuse
- build primitives for a calm workbench shell, not for marketing-card theatrics
- every public component, icon, utility, or style entry must have metadata with
  a stable readable `id` and `layer`
- use the single `tutti-ui-system` skill for component reuse, extraction,
  base/business classification, metadata, and storyboard work

## React Component Splitting Rules

- default to one component per directory; keep the component file, tests,
  stories, local styles, and tightly coupled implementation-detail helpers
  colocated inside that directory
- default to one React component per file; allow multiple small stateless
  helpers in one file only when they are tightly coupled implementation detail
  of the exported component
- split presentational components away from host wiring; components promoted
  into ui-system must receive data, labels, status, and callbacks through props
  rather than owning side effects or app workflow
- if a component does not need internal state or refs, prefer a plain function
  component; introduce heavier component structure only when state, refs, or
  lifecycle-like coordination is actually required
- when behavior is reusable but host-owned, extract it into caller-owned hooks,
  adapters, or controller code instead of embedding that logic in the ui-system
  component body
- do not use mixin-style reuse or implicit component coupling; prefer explicit
  composition through child components, slots, helper modules, or narrow
  wrappers
- keep component APIs semantic and stable; do not repurpose DOM prop names such
  as `style` or `className` to carry business meaning when a clearer prop like
  `variant`, `tone`, `status`, or `layout` is intended
- use spread props sparingly on public components; pass explicit props whenever
  possible so the boundary stays readable and host-agnostic
- list and collection components must render with stable identity from caller
  data; do not rely on array index keys in promoted UI-system surfaces
- when a component grows multiple visual regions or branches, first try to
  split subparts into local render helpers or child components before adding
  more mode booleans to one large component
- avoid boolean-prop sprawl for mutually exclusive modes; prefer a finite
  variant, discriminated union, explicit slot, or separate subcomponent when
  states represent distinct rendering modes
- keep user-visible copy caller-owned by default; if text changes by host,
  locale, or workflow, expose it through props, labels, or children instead of
  hardcoding it inside the shared component
- use the filename as the component name and keep exported component names in
  PascalCase so file boundaries stay obvious during promotion, review, and
  migration

## Validation

- Run `pnpm typecheck`
- Run `pnpm check:ui-boundaries`
- If component metadata changed, run `node tools/scripts/check-ui-metadata.mjs`
- If storyboard inventory changed, run
  `pnpm --filter @tutti-os/ui-storyboard typecheck`
- If a change affects desktop integration, also run
  `pnpm --filter @tutti-os/desktop build`
- In the handoff, explicitly state whether tokens, primitives, storyboard
  surface, and migrated consumer all comply with the UI-system standard; if any
  of those are still divergent, the work is not complete

## Related Docs

- `ui-system.md`
- `docs/conventions/desktop-visual-language.md`
- `docs/conventions/local-git-hooks.md`