@nextop-os/ui-system 0.0.16 → 0.0.17

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Scope
+
+This file applies to `packages/ui/system/*`.
+
+`packages/ui/system` is the source package for `@nextop-os/ui-system`, the
+shared Nextop 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
+`nextop-ui-system` agent skill.
+
+Before changing components, icons, metadata, styles, storyboard examples, or
+the bundled skill, read
+[UI_SYSTEM_GUIDELINES.md](/Users/zhengweibin/Desktop/team-shell/nextop/packages/ui/system/UI_SYSTEM_GUIDELINES.md).
+
+## Public API
+
+Stable public imports are:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-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
+  `@nextop-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 generate a temporary preview outside the
+  repository for user review
+- business components should compose `base` primitives instead of recreating
+  buttons, fields, dialogs, cards, icons, or overlays
+- 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 `nextop-ui-system` skill for component reuse, extraction,
+  base/business classification, metadata, and storyboard work
+
+## 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 @nextop-os/ui-storyboard typecheck`
+- If a change affects desktop integration, also run
+  `pnpm --filter @nextop-os/desktop build`
+
+## Related Docs
+
+- [UI_SYSTEM_GUIDELINES.md](/Users/zhengweibin/Desktop/team-shell/nextop/packages/ui/system/UI_SYSTEM_GUIDELINES.md)
+- [docs/conventions/ui-system.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/ui-system.md)
+- [docs/conventions/desktop-visual-language.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/desktop-visual-language.md)
+- [docs/conventions/local-git-hooks.md](/Users/zhengweibin/Desktop/team-shell/nextop/docs/conventions/local-git-hooks.md)

package/README.md

@@ -42,6 +42,11 @@ source files into `.nextop-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`.
 
+Temporary agent previews should use this same dev-server path instead of
+hardcoding local checkout paths. Generate the preview outside the repository,
+configure its Vite app with `nextopUISystemDev({ serverUrl })`, and import
+components, icons, styles, and utilities through the stable public entrypoints.
+
 Add the generated cache to the external app's `.gitignore`:
 
 ```text
@@ -65,15 +70,18 @@ import { uiSystemMetadata } from "@nextop-os/ui-system/metadata";
 ```
 
 When promoting business UI into this package, use the bundled
-`agent/nextop-ui-system/SKILL.md` skill when it is available. The durable rules
+`agent/nextop-ui-system/SKILL.md` skill when it is available. In the source
+checkout, also read `AGENTS.md` and `UI_SYSTEM_GUIDELINES.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. compose business components from base primitives
-5. add metadata, stable exports, and storyboard examples for public UI
-6. run metadata and boundary validation before shipping
+4. before promoting a business component, scan source usage and generate a
+   temporary preview outside the repository for user review
+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:

package/UI_SYSTEM_GUIDELINES.md

@@ -0,0 +1,148 @@
+# Nextop UI System Guidelines
+
+This document is the shared component-library rulebook for
+`@nextop-os/ui-system`. Both `packages/ui/system/AGENTS.md` and the bundled
+`packages/ui/system/agent/nextop-ui-system` skill should point here before
+component extraction, reuse, metadata, or storyboard work.
+
+## Role
+
+`@nextop-os/ui-system` owns host-agnostic UI foundations:
+
+- CSS tokens and theme styles
+- icon exports
+- shadcn-derived and Radix-backed base primitives
+- reusable business display components
+- component metadata and storyboard inventory
+- small utilities that directly support primitives
+
+It does not own business logic, app-specific workflows, daemon or Electron
+calls, routing, persistence, query/cache mutation, filesystem access, global
+store ownership, or workflow orchestration.
+
+## Stable Public Imports
+
+Use only these public imports from consumers:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-os/ui-system/utils`
+
+Do not import from `@nextop-os/ui-system/src/*` or per-file component paths.
+When a new export is needed, prefer an existing barrel before adding a new
+public subpath. If public exports change, update package exports and the
+UI-boundary check script together.
+
+## Component Layers
+
+`base` components are low-level presentation or interaction primitives. Their
+public API should avoid domain nouns and focus on variants, refs, slots,
+children, class names, accessibility, and generic interaction.
+
+`business` components are reusable display surfaces for shared business
+concepts. They may expose domain display props such as workspace, file, task,
+agent, run, status, permission, labels, and callbacks. They must stay
+host-agnostic and side-effect-free.
+
+Business components should compose `base` primitives instead of recreating
+buttons, fields, dialogs, cards, icons, menus, or overlays.
+
+## Primitive Acquisition
+
+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 `packages/ui/system`.
+- Keep `components.json` and package aliases usable enough that CLI download
+  remains the default path for shared primitives.
+- After CLI acquisition, limit edits to package-specific adaptation such as
+  icon routing, import aliases, stable exports, token alignment, metadata, and
+  boundary-check fixes.
+
+## Visual And Token Rules
+
+- Keep CSS variables as the source of truth for token values.
+- Prefer semantic token names over raw palette leakage in public APIs.
+- Build primitives for a calm workbench shell, not for marketing-card
+  theatrics.
+- Reusable packages outside `packages/ui/*` should consume
+  `@nextop-os/ui-system` primitives and token-backed Tailwind utilities before
+  adding package-local CSS.
+- If repeated package-local CSS needs emerge, move the shared foundation into
+  `@nextop-os/ui-system`.
+
+## Metadata And Storyboard
+
+Every public UI-system component, icon, utility, or style entry must have
+metadata with:
+
+- stable readable `id`
+- `layer` as `base` or `business`
+- `source` under `packages/ui/system/src`
+- stable public `from` entrypoint
+
+Keep component ids globally unique and kebab-case. Storyboard inventory should
+stay grouped by `Foundation`, `Base Components`, and `Business Components`.
+Visible component stories should support copying the component id.
+
+For business components, add storyboard examples for normal, empty, disabled,
+loading, and error-like states when those states exist in the public contract.
+
+## Promotion Checklist
+
+Before promoting local UI into this package, scan the source usage and create a
+preflight state preview:
+
+- inspect the source component, call sites, conditional rendering, props, types,
+  tests, mocks, and relevant i18n keys
+- build a state matrix from code evidence; for each state, record the state
+  name, source file or branch, props or data needed, host-owned behavior, and
+  whether it belongs in the shared component contract
+- generate a temporary preview outside the repository, such as under
+  `$TMPDIR/nextop-ui-system-preview-<component-id>/`
+- start the UI-system dev server with
+  `pnpm --filter @nextop-os/ui-system dev:server`, or verify an existing server
+  by probing `/health`
+- configure the temporary Vite preview with
+  `nextopUISystemDev({ serverUrl })` from `@nextop-os/ui-system/dev-vite`
+  instead of hardcoding checkout paths
+- import UI-system components, icons, styles, and utilities through stable
+  public entrypoints; use the local state matrix file or `/components` for
+  metadata context
+- render all candidate states in that preview using a draft component or copied
+  visual surface
+- start a local preview URL and get user confirmation before writing the
+  component into `packages/ui/system`
+
+Do not put draft preview files in the Nextop checkout. The temporary preview is
+a visual review gate, not part of the package source.
+
+Before promotion, identify:
+
+- 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
+- state matrix summary and temporary preview URL
+- export path, metadata entry, storyboard states, and validation commands
+
+Prefer existing metadata entries before creating a component. Replace only the
+visual surface with stable UI-system imports; keep host state, data loading,
+routing, daemon calls, i18n keys, and business transforms in the caller.
+
+## Validation
+
+Run the smallest relevant checks and report exact commands and results:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+```
+
+If runtime component code changed, also run the relevant package typecheck or
+build for the consumer that was migrated.

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

@@ -1,21 +1,22 @@
 ---
 name: nextop-ui-system
-description: Use when working with @nextop-os/ui-system components, replacing local UI with shared components, querying component ids or metadata, promoting business UI into shared base or business components, or maintaining UI-system storyboard inventory.
+description: Use when working with @nextop-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 `@nextop-os/ui-system` use,
-promotion, metadata, and storyboard work.
+Use this skill as the single entrypoint for `@nextop-os/ui-system` component
+reuse, extraction, promotion, metadata, and storyboard work.
 
 ## Source Of Truth
 
 Read these before editing:
 
 1. nearest `AGENTS.md` for the target code
-2. `packages/ui/AGENTS.md`
-3. `docs/conventions/ui-system.md`
-4. component metadata from the first available source:
+2. `packages/ui/system/AGENTS.md`
+3. `packages/ui/system/UI_SYSTEM_GUIDELINES.md`
+4. `docs/conventions/ui-system.md`
+5. component metadata from the first available source:
    - `GET http://127.0.0.1:4100/components`
    - `packages/ui/system/src/metadata/components.json`
    - `@nextop-os/ui-system/metadata` from the installed package
@@ -33,76 +34,40 @@ Never deep import `@nextop-os/ui-system/src/*` or per-file component paths.
 
 ## Route The Task
 
-### Use Existing Component
+Read only the reference file that matches the task.
 
-Use when replacing local UI or answering what components exist.
+- 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`
 
-1. Check metadata first by `id`, `name`, `export`, `layer`, and `useCases`.
-2. Prefer existing components before creating or extracting new ones.
-3. Read the source and props type for the selected export.
-4. Keep host state, data loading, routing, daemon calls, i18n keys, and business
-   transforms in the caller.
-5. Replace only the visual surface with stable UI-system imports.
+## Global Boundaries
 
-### Extract Base Component
-
-Use when the target is a low-level visual primitive.
-
-Proceed only if the public API has no domain noun and props describe
-presentation, interaction, accessibility, variants, refs, slots, class names, or
-children.
-
-1. If the primitive exists in shadcn, acquire it through shadcn CLI targeted at
-   `packages/ui/system`.
-2. Adapt only package aliases, icons, tokens, exports, and boundary issues.
-3. Add stable exports, metadata with `layer: "base"`, and storyboard coverage.
-4. Replace duplicated local UI with the shared component.
-
-### Extract Business Component
-
-Use when business-side UI should become a reusable display component.
-
-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, status, permission, labels, and callbacks.
-
-Before editing, state:
-
-- 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
-- export path, metadata entry, storyboard states, and validation commands
-
-Keep these outside the component:
+Keep these outside `@nextop-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, or
-  navigation
-
-Implement the business component by composing `base` primitives. Add metadata
-with `layer: "business"` and storyboard examples for normal, empty, disabled,
-loading, and error-like states when those states exist in the public contract.
-
-### Maintain Inventory
+- 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
 
-Use when changing component ids, metadata, exports, or storyboard.
+For any promoted public component, add stable exports, metadata, and storyboard
+coverage that match the chosen reference workflow.
 
-1. Keep each public entry's `id` stable, readable, globally unique, and
-   kebab-case.
-2. Keep `layer` as `base` or `business`.
-3. Ensure `source` points under `packages/ui/system/src`.
-4. Ensure `from` is a stable public entrypoint.
-5. Keep storyboard grouped by `Foundation`, `Base Components`, and
-   `Business Components`; visible component stories should support copying the
-   component id.
+For business component promotion, the temporary preview must be built from the
+state matrix, proposed props boundary, and candidate source UI. Treat the
+confirmed preview draft as the implementation blueprint for
+`packages/ui/system`, not as a disposable mockup.
 
-## Validation
+## Validation Commands
 
-Run the smallest relevant checks, then report exact commands and results:
+Run the smallest relevant checks from the selected reference. Common checks are:
 
 ```bash
 node tools/scripts/check-ui-metadata.mjs
@@ -111,4 +76,4 @@ pnpm --filter @nextop-os/ui-storyboard typecheck
 ```
 
 If runtime component code changed, also run the relevant package typecheck or
-build for the consumer that was migrated.
+consumer build.

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

@@ -0,0 +1,43 @@
+# 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. If the primitive exists in the shadcn registry, acquire it through shadcn CLI
+   targeted at `packages/ui/system`.
+3. Adapt only package aliases, icon routing, tokens, stable exports, metadata,
+   storyboard examples, and boundary-check issues.
+4. Keep helper exports minimal and directly tied to primitive support.
+5. Add metadata with `layer: "base"`.
+6. Add storyboard coverage for the public states and variants exposed by the
+   primitive.
+7. Replace duplicated local UI only after the shared primitive exists.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+pnpm --filter @nextop-os/ui-system typecheck
+```
+
+If a consumer was migrated, also run that consumer's typecheck or build.

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

@@ -0,0 +1,40 @@
+# 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 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 @nextop-os/ui-storyboard typecheck
+```