@nextop-os/ui-system 0.0.17 → 0.0.18

package/AGENTS.md

@@ -11,8 +11,12 @@ 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).
+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
 
@@ -45,10 +49,26 @@ Rules:
   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
+  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
@@ -75,10 +95,12 @@ Rules:
   `pnpm --filter @nextop-os/ui-storyboard typecheck`
 - If a change affects desktop integration, also run
   `pnpm --filter @nextop-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_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)
+- `ui-system.md`
+- `docs/conventions/desktop-visual-language.md`
+- `docs/conventions/local-git-hooks.md`

package/README.md

@@ -38,14 +38,9 @@ export default defineConfig({
 ```
 
 When the dev server is reachable, the plugin mirrors the allowed UI-system
-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.
+source and skill-support 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`.
 
 Add the generated cache to the external app's `.gitignore`:
 
@@ -71,14 +66,14 @@ 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. In the source
-checkout, also read `AGENTS.md` and `UI_SYSTEM_GUIDELINES.md`. The durable rules
-are:
+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 generate a
-   temporary preview outside the repository for user review
+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
@@ -96,5 +91,7 @@ This copies the package skill into:
 .codex/skills/nextop-ui-system/SKILL.md
 ```
 
-The installer does not overwrite a locally modified skill unless `--force` is
-provided.
+When `.nextop-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.

package/agent/install-skill.mjs

@@ -14,8 +14,9 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const sourceDirectory = join(packageRoot, "agent", "nextop-ui-system");
 const skillName = "nextop-ui-system";
+const devCacheDirectoryName = ".nextop-ui-system-dev";
+const companionFiles = ["AGENTS.md", "ui-system.md"];
 
 const options = parseArgs(process.argv.slice(2));
 
@@ -26,8 +27,15 @@ if (options.help) {
 
 const targetRoot = resolve(options.cwd, ".codex", "skills");
 const targetDirectory = join(targetRoot, skillName);
+const sourceRoot = await resolveSourceRoot(options.cwd);
+const sourceDirectory = join(sourceRoot, "agent", skillName);
 
 await assertReadableDirectory(sourceDirectory);
+await Promise.all(
+  companionFiles.map((fileName) =>
+    assertReadableFile(join(sourceRoot, fileName))
+  )
+);
 await mkdir(targetRoot, { recursive: true });
 
 if (await pathExists(targetDirectory)) {
@@ -38,7 +46,7 @@ if (await pathExists(targetDirectory)) {
   }
 
   if (!options.force) {
-    if (await directoriesMatch(sourceDirectory, targetDirectory)) {
+    if (await directoriesMatch(sourceRoot, sourceDirectory, targetDirectory)) {
       console.log(
         `nextop-ui-system skill already configured at ${targetDirectory}`
       );
@@ -59,6 +67,15 @@ await cp(sourceDirectory, targetDirectory, {
   force: true,
   recursive: true
 });
+await Promise.all(
+  companionFiles.map((fileName) =>
+    cp(join(sourceRoot, fileName), join(targetDirectory, fileName), {
+      errorOnExist: false,
+      force: true,
+      recursive: false
+    })
+  )
+);
 
 console.log(`Installed nextop-ui-system skill to ${targetDirectory}`);
 console.log(
@@ -121,6 +138,15 @@ async function assertReadableDirectory(path) {
   }
 }
 
+async function assertReadableFile(path) {
+  await access(path, constants.R_OK);
+  const pathStats = await stat(path);
+
+  if (!pathStats.isFile()) {
+    throw new Error(`Expected file: ${path}`);
+  }
+}
+
 async function pathExists(path) {
   try {
     await access(path, constants.F_OK);
@@ -130,8 +156,24 @@ async function pathExists(path) {
   }
 }
 
-async function directoriesMatch(leftDirectory, rightDirectory) {
-  const leftEntries = await listFiles(leftDirectory, leftDirectory);
+async function resolveSourceRoot(cwd) {
+  const devCacheRoot = resolve(cwd, devCacheDirectoryName);
+  const devCacheSkillDirectory = join(devCacheRoot, "agent", skillName);
+
+  if (
+    (await pathExists(devCacheSkillDirectory)) &&
+    (await pathExists(join(devCacheRoot, "AGENTS.md"))) &&
+    (await pathExists(join(devCacheRoot, "ui-system.md")))
+  ) {
+    return devCacheRoot;
+  }
+
+  return packageRoot;
+}
+
+async function directoriesMatch(sourceRoot, sourceDirectory, rightDirectory) {
+  const sourceEntries = await listBundleFiles(sourceRoot, sourceDirectory);
+  const leftEntries = sourceEntries.map((entry) => entry.targetRelativePath);
   const rightEntries = await listFiles(rightDirectory, rightDirectory);
 
   if (leftEntries.length !== rightEntries.length) {
@@ -143,7 +185,7 @@ async function directoriesMatch(leftDirectory, rightDirectory) {
       return false;
     }
 
-    const leftFile = join(leftDirectory, leftEntries[index]);
+    const leftFile = sourceEntries[index].sourceAbsolutePath;
     const rightFile = join(rightDirectory, rightEntries[index]);
 
     const [leftContent, rightContent] = await Promise.all([
@@ -159,6 +201,24 @@ async function directoriesMatch(leftDirectory, rightDirectory) {
   return true;
 }
 
+async function listBundleFiles(sourceRoot, sourceDirectory) {
+  const skillFiles = await listFiles(sourceDirectory, sourceDirectory);
+  const companionEntries = companionFiles.map((fileName) => ({
+    sourceAbsolutePath: join(sourceRoot, fileName),
+    targetRelativePath: fileName
+  }));
+
+  return skillFiles
+    .map((relativePath) => ({
+      sourceAbsolutePath: join(sourceDirectory, relativePath),
+      targetRelativePath: relativePath
+    }))
+    .concat(companionEntries)
+    .sort((left, right) =>
+      left.targetRelativePath.localeCompare(right.targetRelativePath)
+    );
+}
+
 async function listFiles(rootDirectory, directory) {
   const entries = await readdir(directory, { withFileTypes: true });
   const files = await Promise.all(

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

@@ -8,15 +8,39 @@ description: Use when working with @nextop-os/ui-system components, replacing lo
 Use this skill as the single entrypoint for `@nextop-os/ui-system` component
 reuse, extraction, promotion, metadata, and storyboard work.
 
+## Non-Negotiable Standard
+
+Any UI promoted into `@nextop-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
+- 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. `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:
+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`
    - `@nextop-os/ui-system/metadata` from the installed package
@@ -60,10 +84,90 @@ Keep these outside `@nextop-os/ui-system` components:
 For any promoted public component, add stable exports, metadata, and storyboard
 coverage that match the chosen reference workflow.
 
-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.
+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, derive the promoted component directly from
+the state matrix, proposed props boundary, and candidate source UI, then add
+storyboard coverage for the accepted states in the same promotion pass. Treat
+that evidence and boundary decision as the implementation blueprint for
+`packages/ui/system`, and use review only to verify the finished implementation.
+
+## 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
 
@@ -77,3 +181,10 @@ pnpm --filter @nextop-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

@@ -19,15 +19,45 @@ instead.
 ## Workflow
 
 1. Check metadata and existing exports first.
-2. If the primitive exists in the shadcn registry, acquire it through shadcn CLI
+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
+   `@nextop-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`.
-3. Adapt only package aliases, icon routing, tokens, stable exports, metadata,
+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.
-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
+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.
-7. Replace duplicated local UI only after the shared primitive exists.
+   - 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
 
@@ -41,3 +71,17 @@ pnpm --filter @nextop-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

@@ -26,6 +26,11 @@ Keep storyboard grouped by:
 
 Visible component stories should support copying the component id.
 
+When a base component is newly promoted into `@nextop-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.