@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/skills/ads-designer/assets/bootstrap-ds/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "native-design-system",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Private starter workspace for a project's local React design system.",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "ads showcase",
+    "dev:showcase": "ads showcase",
+    "lint": "oxlint --deny-warnings src design-system && biome lint --config-path=biome.css.json .",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run lint && npm run typecheck && npm run build:lib",
+    "build:lib": "vite build && tsc --project tsconfig.build.json",
+    "build:showcase": "node scripts/build-mcp-previews.mjs",
+    "preview": "ads showcase",
+    "preview:showcase": "ads showcase",
+    "build:mcp-previews": "node scripts/build-mcp-previews.mjs"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@babel/preset-react": "7.29.7",
+    "@babel/preset-typescript": "7.29.7",
+    "@linaria/atomic": "8.0.0",
+    "@types/node": "25.9.4",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.7.0",
+    "@wyw-in-js/vite": "2.1.3",
+    "oxlint": "1.72.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "5.9.3",
+    "vite": "6.4.3"
+  }
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/scripts/build-mcp-previews.mjs

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { build } from "vite";
+import wyw from "@wyw-in-js/vite";
+import react from "@vitejs/plugin-react";
+import { runScenarioCompiler } from "@reqvire-org/ads/scenarios/compiler";
+import { createPreviewResources, previewEntriesPlugin } from "@reqvire-org/ads/scenarios/vite";
+
+const root = path.resolve(import.meta.dirname, "..");
+const runScript = promisify(execFile);
+const projectPackage = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const manager = projectPackage.packageManager?.split("@")[0] ?? (existsSync(path.join(root, "bun.lock")) || existsSync(path.join(root, "bun.lockb")) ? "bun" : "npm");
+await runScenarioCompiler(root, {
+  watched: process.argv.includes("--watch"),
+  compilerFiles: [import.meta.filename],
+  async validate() {
+    try { await runScript(manager, ["run", "lint"], { cwd: root }); }
+    catch (error) { throw new Error([error.stdout, error.stderr].map(value => value?.toString() ?? "").join("\n") || error.message); }
+  },
+  async buildGraph(entries, options, track) {
+    const mount = path.join(options.dsRoot, "showcase/mcp/main.tsx");
+    const output = await build({ configFile: false, root, base: "./", publicDir: false,
+      plugins: [previewEntriesPlugin(entries.map(entry => ({ ...entry, root })), mount), wyw({ include: ["**/*.{ts,tsx}"], exclude: ["**/node_modules/**"] }), react(), track],
+      resolve: { alias: { "@ds": path.join(options.dsRoot, options.config.publicEntry) } },
+      worker: { format: "iife" },
+      build: { write: false, cssCodeSplit: true, assetsInlineLimit: 0, modulePreload: false,
+        rollupOptions: { preserveEntrySignatures: "strict", input: Object.fromEntries(entries.map((_entry, index) => [`scenario-${index}`, `ads-preview-entry:${index}`])) } },
+    });
+    return createPreviewResources(output, options, entries);
+  },
+});

package/dist/skills/ads-designer/assets/bootstrap-ds/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module "@scenario" {
+  import type { ComponentType } from "react";
+  const Scenario: ComponentType;
+  export default Scenario;
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "rootDir": "design-system",
+    "outDir": "dist"
+  },
+  "include": ["design-system/**/*.ts", "design-system/**/*.tsx"],
+  "exclude": ["design-system/showcase"]
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": { "@ds": ["design-system/index.ts"] }
+  },
+  "include": ["src", "design-system", "vite.config.ts"]
+}

package/dist/skills/ads-designer/assets/bootstrap-ds/vite.config.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import wyw from "@wyw-in-js/vite";
+
+export default defineConfig({
+  plugins: [wyw(), react()],
+  resolve: {
+    alias: { "@ds": path.resolve(import.meta.dirname, "design-system/index.ts") },
+  },
+  build: {
+    outDir: "dist",
+    lib: {
+      entry: path.resolve(import.meta.dirname, "design-system/index.ts"),
+      formats: ["es"],
+      fileName: () => "index.js",
+      cssFileName: "styles",
+    },
+    rollupOptions: { external: [/^react(?:\/.*)?$/, /^react-dom(?:\/.*)?$/] },
+  },
+});

package/dist/skills/ads-designer/references/cli.md

@@ -0,0 +1,111 @@
+# Run ADS tooling through npx
+
+Use npx for setup or ad hoc checks alongside this skill's research,
+implementation, documentation, and verification workflow. ADS must be a project
+development dependency, and its checks must run before the project's build.
+Routine builds use the local CLI.
+
+Select an actual published package/version or a real local tarball supplied by
+the user or built from the tool checkout. Respect the project's installed
+version. Confirm the selected published version supports the required features; use a
+local tarball for unreleased changes. Never resolve an unrelated package with
+bare `npx ds`. Read the actual version/help and use only supported commands.
+
+## Published setup
+
+Run **inside the receiving project**, where
+`package.json` lives:
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+```
+
+Use `--framework preact` for native Preact. A saved `framework` in
+`ds.config.json` lets later init runs omit the flag; otherwise the choice is
+required, including for an older config. Init preserves existing framework
+tooling and rejects conflicting saved/JSX settings instead of converting it.
+
+Use the confirmed package name/version if different. For an existing Bun
+project, the same init command detects `packageManager` or `bun.lock`/`bun.lockb`;
+then use `bun install` and `bun run build`. Node 22.12 or newer remains required.
+Only use `--package-manager bun` when the project has no Bun marker yet or needs
+an explicit override. Preserve its existing package-manager policy and lockfile.
+
+`init` accepts no directory argument and requires an existing `package.json`.
+For starting from zero, copy the bundled `ads-designer` application scaffold
+first, then run init inside it. For an existing app, init preserves app files,
+framework configuration, lockfiles, and build scripts. It adds only missing ADS
+foundation files, config, development dependencies, and build checks. Existing
+ADS values are reused; incomplete contracts need an explicit migration.
+
+Init adds `lint:ds` and `assets:ds`, and runs checks then brand generation before
+the existing `prebuild` hook without replacing the actual build command or
+unrelated checks. It rejects conflicting custom scripts before writing.
+It does not configure framework aliases, style
+extraction, or application entry points; integrate these using the target's
+framework and ADS contracts. Install dependencies, review the changes, and
+commit the updated lockfile.
+
+## Local checkout testing
+
+If no published distribution exists, build and pack the tooling checkout with
+`npm run build` and `npm run pack:tool`. Resolve its tarball to an absolute path.
+From inside an existing test project:
+
+```sh
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+npx --yes --package "$ads_tool_package" ads --help
+npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
+npm install
+npm run build
+```
+
+Use Bun's install/build commands for Bun projects. Keep npx options before
+`ds`. `--tool-package` is optional local-testing/version-override support;
+registry users do not need an archive. A `file:` dependency must remain
+available wherever dependencies are installed. A published pinned version is
+portable between machines.
+
+## Checks and rules
+
+For an initialized project, from its root:
+
+```sh
+npx @reqvire-org/ads check
+npx @reqvire-org/ads tokens --json
+npx @reqvire-org/ads assets
+```
+
+Use the selected real distribution; for a local tarball, invoke
+`npx --yes --package "$ads_tool_package" ads check` instead. Other inspection
+commands accept a directory; init deliberately does not.
+
+Every normal build refreshes `.ds/oxlintrc.json`, runs `ads check`, executes
+core/project Oxlint rules, then generates configured standard brand icons in
+`.ds/assets/`. Set `assets.iconSource` to an SVG inside the ADS's `assets/brand/`,
+relative to the ADS folder; no source means generation is a no-op. Integrate that
+directory through the app's existing asset mount. Fixed token names and prefixes
+are required; project values and artwork remain project-owned. Its paths reference the project and local tool;
+builds do not depend on the initializing npx cache. Ignore `.ds/`. Register
+component rules through the project's plugin adapter and `ds.config.json`, then
+run its actual build. Use `lint-config` directly for custom pipeline integration
+or debugging, not as a separate routine setup step.
+
+Use ADS 0.3 or later for the shared-resource preview compiler. `mcp` starts stdio
+plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
+connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
+The tool client discovers entries and renders MCP Apps. Init adds the launch
+script but does not install the project preview compiler. Integrate its graph
+compiler/mount adapter and configure `mcp.previewManifest` plus `mcp.previewWatch`;
+then use the same foundation and Linaria extraction as the application. Source discovery,
+selected component/pattern/style/brand imports, explicit theme-value imports, and
+assimilation are agent workflows. There is no CLI `import` command. Core checks
+do not copy source, import values, or establish behavior/motion parity; continue
+project type checking, meaningful tests, and browser comparisons.
+
+If no CLI distribution is available, continue with the target's existing
+checks. `ads-designer` includes an empty scaffold for offline bootstrapping.
+Install skills separately with `npx skills`; the tool does not install skills
+or fetch an external UI catalogue.

package/dist/skills/ads-designer/references/design-craft.md

@@ -0,0 +1,65 @@
+# Craft UI through the local ADS
+
+Read the target component/pattern contract and inspect it in its real context.
+Preserve the project's typography, density, spacing, icon vocabulary, and themes.
+The upstream advice is a craft reference, not authorization to replace brand
+values or add a new UI library.
+
+## Shape the interaction
+
+Make the primary action and current state legible. Components should expose
+their supported hover, focus, active, selected, disabled, loading, and error
+states through a coherent public API. Show those states in the real showcase;
+don't approximate them with externally styled markup.
+
+Keep ordinary button actions on click/release with keyboard equivalents. Early
+press feedback can be visual without committing an action on pointer-down.
+Check press cancellation, repeated activation, focus visibility, and disabled
+states. Loading should communicate progress and settle on both success and
+failure rather than leaving a control or notification indefinitely pending.
+
+Dialogs, menus, and popovers need coherent focus, dismissal, portal/placement,
+and scroll behavior. Read the existing primitive before implementing these again
+in a caller. Tooltips should complement accessible labels; essential instructions
+must remain available without hover. Match repeat tooltip behavior to the local
+contract rather than adding a delay to every nearby trigger.
+
+Transient feedback can use a local Toast if present. Persistent errors and
+required decisions need the appropriate form, inline, or dialog surface. The
+empty scaffold does not contain those components; add only what the task needs.
+
+## Content, layout, and visual detail
+
+Use the existing token scale for hierarchy and rhythm. Keep icon/text alignment,
+button labels, truncation, contrast, and focus treatment consistent with the
+owner. Stabilize a loading control's dimensions where content replacement would
+otherwise cause distracting layout changes.
+
+Check realistic long names, translated labels, unbroken identifiers, absent
+descriptions, and empty/single/many states when they matter to the component.
+Choose wrapping/truncation based on what users need to read or retrieve. Preserve
+full accessible names when visual labels are shortened.
+
+Support the actual container rather than assuming the viewport determines
+available width. Flexible children often need a meaningful minimum-size policy;
+don't hide overflow globally to conceal a broken layout. Use the owning pattern
+for repeated compositions and keep showcase framing separate from component
+appearance.
+
+Use restrained motion when it explains a change. Timing and easing belong in
+local tokens, with physical origins tied to the trigger. Check rapid reversal,
+exit cleanup, and reduced motion. Established component-specific durations and
+measured geometry can be deliberate choices; diagnose their effect before
+changing them to a generic default.
+
+## Document and verify
+
+Keep typed props, examples, state behavior, token hooks, and important tradeoffs
+in the item README. Record concrete upstream influences, authors, revision, and
+applicable notices when importing or assimilating source. Do not describe an
+adapted implementation as independent solely because it uses native primitives.
+
+Run the actual project's checks after changes and inspect the real consumer
+showcase. Verify keyboard/focus and supported themes alongside visual states.
+Only introduce component-local lint for a demonstrated, statically provable
+misuse; token and ownership checks remain general tooling concerns.

package/dist/skills/ads-designer/references/mobile.md

@@ -0,0 +1,73 @@
+# Mobile web within ADS ownership
+
+Use the actual target framework and existing responsive behavior. Mobile polish
+does not imply adopting iOS styling, a new font, fixed colors, or a native app
+runtime. Read the app and item contracts before changing viewport/scroll policy.
+
+## Input capabilities
+
+Condition decorative hover effects on hover-capable, fine-pointer input when
+that fits the control. Don't infer touch from viewport width alone: laptops can
+have touch input, and phones can use external pointers. Keep keyboard focus
+states available independently of hover.
+
+Provide useful press feedback inside the primitive. Preserve click/release
+activation, dragging out to cancel, pointer cancellation, and keyboard behavior.
+Use gesture-specific touch-action only where the interaction requires it; broad
+`touch-action: none` can block ordinary page scrolling. `manipulation` can suit
+simple controls when compatible with the local policy.
+
+Use the project's target-size tokens and check the actual hit area, including
+small icon controls. Where a larger hit target is needed, give it a supported
+owner-level treatment rather than inflating unrelated global density tokens.
+Don't require hover for essential content or actions.
+
+## Viewport and scrolling
+
+The application owns viewport metadata, document/root scrolling, browser theme
+metadata, and installable-app settings. Reusable components/patterns own local
+layout and scroll behavior. Do not change application metadata as a side effect
+of importing a control.
+
+Choose `svh`, `dvh`, or existing viewport policy based on whether the surface
+should remain stable or follow changing browser chrome. Check toolbars, drawers,
+dialogs, and fixed notifications with the virtual keyboard and rotated viewport.
+Safe-area treatment belongs to the owner of the screen edge; combine `env()`
+insets with token-backed spacing where necessary, avoiding duplicate padding.
+
+Contain scroll chaining only for surfaces that need an independent scrolling
+region. Avoid globally disabling overscroll or hiding page overflow to work
+around a local component problem. Preserve focus visibility and the ability to
+reach the bottom of long content while the keyboard is open.
+
+If application theme metadata is requested, derive it from the actual theme
+rather than copying hardcoded light/dark colors from a reference. Keep browser
+chrome and safe-area backgrounds consistent with the app's own surfaces.
+
+## Forms and typography
+
+Use appropriate input type, autocomplete, inputmode, and labels through the
+existing public API. Those hints complement validation; application code still
+owns domain constraints and error handling.
+
+Check focus zoom in the supported mobile browsers. A 16px-or-larger computed
+input font can avoid common iOS focus-zoom behavior; verify it on the relevant
+device/browser and express any needed size through a local token or variant.
+Do not disable user zoom to conceal a typography/layout issue. Preserve the
+project's dense non-input typography unless the task calls for changing it.
+
+Test realistic content, line wrapping, focus rings, and disabled/loading states.
+Keep essential feedback visible during asynchronous operations. Read the local
+Toast contract before assuming notification position, lifetime, or swipe rules.
+
+## Validate honestly
+
+Use narrow-container tests and browser touch emulation for early feedback.
+Emulation does not prove virtual-keyboard, dynamic browser chrome, real-device
+scroll physics, hover stickiness, or assistive-technology behavior. Test those on
+real supported devices when available, and state any remaining limitation.
+
+Verify keyboard use as well as touch, zoom/reflow, supported themes, safe areas,
+orientation changes, reduced motion, and local scroll cancellation where
+relevant. Keep mobile fixes in their owning layer and run the project's normal
+lint/typecheck/build checks after implementation changes.