@nextop-os/ui-system 0.0.17 → 0.0.18

package/UI_SYSTEM_GUIDELINES.md

@@ -1,148 +0,0 @@
-# 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.