# @tutti-os/ui-system

> Shared Tutti UI tokens, styles, icons, and low-level React primitives.

Latest version **0.0.427** (published 2026-08-28) · 0 weekly downloads

## Install

```sh
npm install @tutti-os/ui-system
pnpm add @tutti-os/ui-system
yarn add @tutti-os/ui-system
bun add @tutti-os/ui-system
```

Provides the command `tutti-ui-system-install-skill`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.427 |
| Published | 2026-08-28 |
| First published | 2026-06-11 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 14 |
| Unpacked size | 1.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3843 |
| Maintainers | hugozhou0638, jomeswang, vorshen, rv4no, jacksooon.0113 |

## Links

- npm: https://www.npmjs.com/package/@tutti-os/ui-system
- Repository: https://github.com/tutti-os/tutti
- Homepage: https://github.com/tutti-os/tutti#readme
- Issues: https://github.com/tutti-os/tutti/issues
- npm.io page: https://npm.io/package/@tutti-os/ui-system

## Dependencies (14)

- [ws](https://npm.io/package/ws.md) ^8.20.1
- [clsx](https://npm.io/package/clsx.md) ^2.1.1
- [vaul](https://npm.io/package/vaul.md) ^1.1.2
- [sonner](https://npm.io/package/sonner.md) ^2.0.7
- [radix-ui](https://npm.io/package/radix-ui.md) ^1.4.2
- [@dnd-kit/core](https://npm.io/package/@dnd-kit/core.md) ^6.3.1
- [tailwind-merge](https://npm.io/package/tailwind-merge.md) ^3.3.0
- [tw-animate-css](https://npm.io/package/tw-animate-css.md) ^1.3.1
- [@dnd-kit/sortable](https://npm.io/package/@dnd-kit/sortable.md) ^10.0.0
- [@dnd-kit/modifiers](https://npm.io/package/@dnd-kit/modifiers.md) ^9.0.0
- [@dnd-kit/utilities](https://npm.io/package/@dnd-kit/utilities.md) ^3.2.2
- [react-resizable-panels](https://npm.io/package/react-resizable-panels.md) ^4.11.1
- [class-variance-authority](https://npm.io/package/class-variance-authority.md) ^0.7.1
- [@fontsource-variable/lexend](https://npm.io/package/@fontsource-variable/lexend.md) ^5.2.11

## Recent versions

- 0.0.427 (latest) — 2026-08-28
- 0.0.426 — 2026-08-27
- 0.0.425 — 2026-08-26
- 0.0.424 — 2026-08-26
- 0.0.423 — 2026-08-26
- 0.0.422 — 2026-08-26
- 0.0.421 — 2026-08-25
- 0.0.420 — 2026-08-25
- 0.0.419 — 2026-08-24
- 0.0.418 — 2026-08-24
- 0.0.417 — 2026-08-24
- 0.0.416 — 2026-08-24
- 0.0.415 — 2026-08-24
- 0.0.414 — 2026-08-23
- 0.0.413 — 2026-08-23
- … 412 more at https://npm.io/package/@tutti-os/ui-system/versions

## README

# @tutti-os/ui-system

Shared Tutti UI tokens, styles, icons, and low-level React primitives.

This package is published to npm as `@tutti-os/ui-system`.

Import the stylesheet once from the renderer or application shell:

```ts
import "@tutti-os/ui-system/styles.css";
```

Application code should prefer the root package export and the documented stable
subpaths over deep imports from internal files.

## External Development

External consumers should install the package normally:

```bash
pnpm add @tutti-os/ui-system
```

For local source sync from a Tutti checkout, start the UI system dev server:

```bash
pnpm --filter @tutti-os/ui-system dev:server
```

Then add the Vite plugin in the external app:

```ts
import { tuttiUISystemDev } from "@tutti-os/ui-system/dev-vite";

export default defineConfig({
  plugins: [tuttiUISystemDev()]
});
```

When the dev server is reachable, the plugin mirrors the allowed UI-system
source and skill-support files into `.tutti-ui-system-dev/` and aliases the
stable package entrypoints to that cache. When the dev server is unavailable,
resolution falls back to the installed package in `node_modules`.

Add the generated cache to the external app's `.gitignore`:

```text
.tutti-ui-system-dev/
```

If the external app uses Tailwind CSS, include both the installed package output
and the generated dev cache in the app's Tailwind source scan:

```css
@source "../node_modules/@tutti-os/ui-system/dist";
@source "../.tutti-ui-system-dev";
```

## Agent Usage

Coding agents should read component metadata before creating or promoting UI:

```ts
import { uiSystemMetadata } from "@tutti-os/ui-system/metadata";
```

When promoting business UI into this package, use the bundled
`agent/tutti-ui-system/SKILL.md` skill when it is available. In the source
checkout, also read `AGENTS.md`, `ui-system.md`, and
`docs/conventions/desktop-visual-language.md`. The durable rules are:

1. prefer existing metadata entries before creating a component
2. classify the component as `base` or `business`
3. keep business components host-agnostic and side-effect-free
4. before promoting a business component, scan source usage and define the
   public props boundary from code evidence
5. compose business components from base primitives
6. add metadata, stable exports, and storyboard examples for public UI
7. run metadata and boundary validation before shipping

External repositories can install the bundled skill into their local Codex
skill directory with one command:

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

This copies the package skill into:

```text
.codex/skills/tutti-ui-system/SKILL.md
```

When `.tutti-ui-system-dev/` is present, the installer prefers the synced
source checkout so the installed skill and bundled UI-system rules stay aligned
with the current local UI-system source. The installer does not overwrite a
locally modified skill unless `--force` is provided.

---
_Source: https://npm.io/package/@tutti-os/ui-system · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._