@reqvire-org/ads 0.0.0-stage → 0.2.9

package/docs/GUIDE.md

@@ -0,0 +1,722 @@
+# ADS tool guide
+
+ADS is development tooling for a project's local design system. This package
+contains a Node CLI, shared token contract, static checks, an Oxlint plugin, and
+empty foundation scaffolding. It includes no component or pattern catalogue,
+fonts, mock screens, or UI runtime dependency.
+
+
+
+## Implementation support
+
+Linaria is required for component and pattern styling. Projects choose their
+UI framework and visual design; `init` preserves framework configuration and
+adds no React runtime dependency. See the
+[architecture](https://github.com/reqvire-org/design-system/blob/main/docs/ARCHITECTURE.md#linaria-is-the-implementation-mechanism)
+for the rationale.
+
+Current source checking supports `.js`, `.jsx`, `.ts`, `.tsx`, their module
+variants, `.css`, and imported Linaria `css` and `styled` templates. JSX style/type checks
+support React and native Preact, including imported factory aliases and
+DOM/CSS types. Scenario discovery, coverage, ownership checks and MCP delivery
+apply to both. The empty application starter uses React; this checkout’s working
+example uses native Preact 11 with TypeScript and Linaria. ADS adds neither runtime
+to a receiving application and never silently aliases React to Preact.
+
+Vue/Svelte single-file components and HTML templates are not parsed by these
+guards. Web Component JS/TS logic and separate CSS can be checked, but HTML
+template strings and Shadow DOM style constructs lack equivalent coverage.
+Retain framework-specific checks; a clean ADS check does not validate those
+unchecked surfaces.
+
+### Linaria integration
+
+Before authoring components or patterns, integrate Linaria extraction with the
+project's existing build:
+
+- Install compatible Linaria packages and the extraction integration for the
+  project's bundler. ADS implementations use `css` and `cx` from
+  `@linaria/atomic`.
+- For Vite, run `@wyw-in-js/vite` before the framework transform. Apply equivalent
+  extraction to application and project preview builds.
+- Resolve `@ds` to the local public entry in the bundler and TypeScript, and load
+  the foundation CSS once. Preserve intentional CSS side effects.
+- Compile an actual styled component and inspect its emitted CSS and browser
+  result. Static source checks do not establish complete extraction or
+  unused-style removal.
+
+The [empty starter's dependencies](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/package.json),
+[entry build](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/vite.config.ts),
+and [preview compiler](https://github.com/reqvire-org/design-system/blob/main/bootstrap-ds/scripts/build-mcp-previews.mjs)
+provide the React/Vite setup. Merge the needed integration into an existing
+project instead of replacing its configuration.
+
+`ads init` does not install Linaria, configure extraction, or verify the complete
+styling pipeline. It sets up token/source checks and build hooks. The copied
+standalone starter already includes Linaria dependencies and Vite integration.
+
+### Native Preact integration
+
+An existing Preact project keeps its own runtime. Use `preact` for rendering and
+DOM types, `preact/hooks` for hooks, and optionally `@preact/signals` for reactive
+state. Configure TypeScript with `"jsx": "react-jsx"` and
+`"jsxImportSource": "preact"`. A Vite build can use its native transform:
+
+```ts
+esbuild: { jsx: "automatic", jsxImportSource: "preact" },
+plugins: [wyw(), /* project plugins */],
+```
+
+Apply that configuration to both application and preview builds. Mount preview
+entries with `render(<Scenario />, root)` from `preact`; React entries use their
+existing React mount. Keep Linaria's `css`/`cx` extraction; native Preact does not
+need `@linaria/react`'s React `styled` wrapper. Use `onInput` for live text updates
+and `event.currentTarget` for the typed element. Native SVG uses DOM names such as
+`stroke-width` and `stroke-linecap`; React’s camel-case presentation aliases are
+not normalized by the native renderer. The `svg-attribute` guard checks those
+attributes when the project/file JSX runtime or factory is native Preact. Preact 11 accepts refs as props
+and exports DOM types such as `HTMLAttributes` directly; Preact 10's `JSX` type
+namespace is also recognized by guards. See the [Preact upgrade guide](https://preactjs.com/guide/v11/upgrade-guide/).
+
+The [working example](https://github.com/reqvire-org/design-system/tree/main/design-system)
+and its [compiler adapter](https://github.com/reqvire-org/design-system/blob/main/scripts/build-mcp-previews.mjs)
+show the native setup. When converting the copied React starter to Preact,
+update its runtime dependencies, JSX settings, framework transform, mount adapter,
+and existing `framework` field together. Change the existing foundation scenario's
+hooks to `preact/hooks`; init preserves copied source. Then run `ads init` using
+the saved choice. For a Preact app without a saved framework, run
+`ads init --framework preact`; newly generated foundation scenarios use native
+hooks. Init preserves the application's compiler, dependencies and mount adapter.
+
+### CSS correctness in the example and starter
+
+The example and empty starter use Biome only for CSS, configured in
+`biome.css.json`. Parsing rejects malformed CSS and invalid hex colors, including
+token values. Explicit lint rules reject duplicate font names and selectors;
+the starter also rejects duplicate properties. Formatting is disabled. Oxlint
+continues to handle JavaScript/TypeScript, and ADS guards enforce token usage and
+ownership separately. `ads init` preserves an existing project's lint tools.
+
+CSS regression tests cover rejected input, valid theme/nesting
+contexts, and exclusion of JavaScript and generated outputs.
+
+## Set up an existing project
+
+Use Node 22.12 or newer. Run inside the project containing `package.json`:
+
+```sh
+npx @reqvire-org/ads init --framework react
+npm install
+npm run build
+```
+
+For a Bun-managed project, use the same init command, followed by `bun install`
+and `bun run build`. No archive or directory argument is needed for a published
+release. `init` requires an existing project; it does not create an application.
+For starting from zero, the `ads-designer` skill carries a standalone empty
+React/TypeScript/Linaria application scaffold. Copy that first, then run `init`
+inside it when a tool distribution is available.
+
+Choose `--framework react` or `--framework preact` when the project has no saved
+framework. Init persists it as `framework` in `ds.config.json`. Subsequent runs
+reuse the saved value, and the copied React starter already declares React.
+There is no implicit framework detection or default for initialization.
+
+A conflicting flag stops init before writes. Init also checks available
+TypeScript/JavaScript JSX settings, including inherited configurations and project
+references, for clear React/Preact conflicts. It preserves compiler files and
+does not install a framework or establish that the complete bundler setup works.
+Projects without JSX settings can still record their choice and configure the
+compiler separately. Svelte and other frameworks are not accepted yet.
+
+Existing ADS configs without `framework` remain readable by checks and inspection.
+On the next init, supply the flag once; init adds that field while preserving
+other settings and existing source. To migrate frameworks, update the project
+and its saved choice explicitly; init is not a framework conversion command.
+
+Initialization:
+
+- Adds the tool to `devDependencies`, with the executing version pinned by
+  default. Keeps an existing tool version unless `--tool-package` overrides it.
+  Adds Oxlint if the project does not already depend on it.
+- Creates missing `ds.config.json`, foundation CSS, a public entry, and empty
+  component/pattern directories, brand guidance, and an empty font directory.
+  Seeds token defaults only when the configured
+  token folder contains no CSS. New foundation scenarios use the selected
+  framework's hooks. Existing ADS source and token values remain unchanged;
+  incomplete existing token contracts need an explicit migration.
+- Adds `lint:ds`, which refreshes lint configuration, runs `ads check`, and
+  executes core and registered project Oxlint rules.
+- Adds `assets:ds` (`ads assets`) after those checks and before the existing
+  `prebuild` hook, preserving the actual
+  `build` command. If the project has no build script, adds a validation/generation
+  build. Repeating init does not duplicate the hook.
+- Adds the same checks and generation to `prebuild:showcase` when a standalone
+  `build:showcase` script exists, preserving its existing hook and build command.
+- Adds `dev:showcase` as `ads showcase` when absent. An existing run command is
+  preserved; deliberately switch it when migrating to the built-in MCP client.
+- Adds `ads-mcp` with guarded editing enabled and `ads-read-mcp` with editing
+  disabled, preserving existing scripts with those names. Both start the showcase.
+- Generates `.ds/oxlintrc.json` and appends `.ds/` to the project's ignore file.
+
+Application files, framework configuration, unrelated scripts/dependencies,
+and lockfiles are preserved. `init` does not install dependencies or configure
+framework aliases, CSS extraction, or application entry points. Resolve `@ds`
+to the local public entry in TypeScript and the bundler, and load foundation CSS
+once when integrating ADS source into the app. Complete the
+[Linaria integration](#linaria-integration) using the existing framework.
+
+An unrelated custom `lint:ds` or `assets:ds` script causes init to stop before writing files;
+rename it or integrate the checks deliberately. Writes are preflighted and do
+not follow symlinks. Keep normal version control review of the resulting changes.
+
+After installation, normal builds use the project's installed tool. They refresh
+lint configuration after tool/plugin changes, cloning/moving the project, or
+removing `.ds/`; they do not rely on the initializing npx cache. Commit the
+updated lockfile. npm CI can use `npm ci`, then `npm run build`.
+
+## Package manager detection
+
+`init` chooses npm or Bun in this order:
+
+1. Explicit `--package-manager npm` or `--package-manager bun`.
+2. The project's `packageManager` field.
+3. Its Bun (`bun.lock` or `bun.lockb`) or npm (`package-lock.json`) lockfile.
+4. The invoking runner's package-manager metadata, otherwise npm.
+
+With both lockfile types and no declared package manager, specify the flag.
+This version supports npm and Bun. It never replaces or removes a lockfile.
+An existing Bun lockfile takes precedence over the npm runner used by `npx`.
+For a Bun project with no lockfile or package-manager metadata yet:
+
+```sh
+npx @reqvire-org/ads init --framework react --package-manager bun
+bun install
+bun run build
+```
+
+The flag chooses the ADS hook's runner; it does not translate the app's existing
+scripts. Node remains required by the tool and Oxlint integration.
+
+## Migrating from DS
+
+ADS uses the package `@reqvire-org/ads`, CLI `ads`, MCP tools named `ads_*`,
+resource namespaces `ads://`, `ui://ads` and `skill://ads`, and skills named
+`ads-*`. Replace the old `@reqvire-org/ds` dependency and package imports, install
+dependencies, then run `ads init` to refresh managed build hooks. Existing
+`ds.config.json`, `.ds/`, `design-system/`, `@ds`, shared token names and
+`--ds-*`/`--ux-*` ownership prefixes remain valid. Project UI requires no rewrite.
+
+Use `ads-mcp` and `ads-read-mcp` for the editing and read-only launch scripts.
+Update MCP client configuration to the new package/server name and reconnect;
+tool names and resource URIs have changed. Install the renamed `ads-*` skills
+when using local skill installation. Rebuild previews with the new tool to
+refresh generated resource manifests. Existing `DS.md` project guides are still
+discovered; the tool's contract and new scaffold use `ADS.md`.
+
+npm has no in-place package rename: publish `@reqvire-org/ads` as a new package.
+Set up its own trusted publisher for `reqvire-org/design-system`, workflow
+`release.yml`, allowing `npm publish` and `npm dist-tag`. Once ADS is available,
+deprecate the old package with a migration message:
+
+```sh
+npm deprecate @reqvire-org/ds "Renamed to @reqvire-org/ads. Install that package instead."
+```
+
+Keep old releases available for existing consumers. See npm's
+[package rename guidance](https://docs.npmjs.com/unpublishing-packages-from-the-registry/),
+[deprecation guidance](https://docs.npmjs.com/deprecating-and-undeprecating-packages-or-package-versions/)
+and [trusted publishing setup](https://docs.npmjs.com/trusted-publishers/).
+
+## Develop ADS locally
+
+To run this checkout's MCP server and showcase together:
+
+```sh
+npm run ads-mcp -- --port 4191       # guarded editing enabled
+# or:
+npm run ads-read-mcp -- --port 4191  # read-only
+```
+
+Run one at a time and open **http://127.0.0.1:4191/**. Both build the local tool
+before starting stdio MCP, the showcase and its managed preview compiler. For an
+MCP client's launch configuration, use `npm --silent run ads-mcp` or
+`npm --silent run ads-read-mcp` so npm's banner does not enter the JSON-RPC stream.
+The local tool build logs go to stderr. Use `--no-showcase` after `--` when only
+the stdio connection is needed. `npm run dev:showcase` remains browser-only.
+
+Use `npm link` to try changes from this checkout in a project already set up
+with ADS. From the ADS repository root:
+
+```sh
+npm install
+npm run build
+npm link
+```
+
+Then run inside the test project, after installing its normal dependencies:
+
+```sh
+npm link @reqvire-org/ads
+npm exec -- ads --version
+npm run build
+```
+
+The project now uses your checkout through a symlink. Keep the normal published
+dependency in its `package.json`; linking is local development setup. The
+versionless `npx -y @reqvire-org/ads mcp` configuration uses that linked copy when
+the client starts in this project. The version check confirms which build is
+running. See [npm's linking documentation](https://docs.npmjs.com/cli/v11/commands/npm-link/)
+and [local-package resolution](https://docs.npmjs.com/cli/v11/commands/npm-exec/).
+
+After changing ADS tool code, packaged skills, starter files or the showcase
+client, run `npm run build` in this checkout and reconnect MCP. The link points
+to the rebuilt `dist/`; it does not compile source automatically. Changes to
+the test project's components and styles still use its managed preview watcher.
+After another `npm install` or `npm ci` in the test project, run
+`npm link @reqvire-org/ads` again if the install replaced the link.
+
+To return to the published version, run `npm unlink --no-save @reqvire-org/ads`
+then `npm install` in the test project. To remove the global development link,
+run `npm unlink --global @reqvire-org/ads`.
+
+For this checkout's diagnostic MCP client, run:
+
+```sh
+npm run dev:mcp-explorer
+```
+
+Open **http://127.0.0.1:4190/**. It builds ADS and starts the real stdio server,
+its showcase and the configured preview compiler. The
+[explorer guide](../mcp-explorer/README.md) covers tools, resources, prompts, skills,
+notifications and widget checks. Run `npm run dev:showcase` instead for normal
+visual review. These development commands are not required in projects using
+the published package.
+
+## Test a local package
+
+Use a tarball to verify the packed release and a clean install before publishing.
+For iterative development, use the linking workflow above. From the repository root:
+
+```sh
+npm install
+npm run build
+npm run pack:tool
+ads_tool_package="$PWD/output/npm/reqvire-org-ads-0.3.0.tgz"
+```
+
+Then change into an existing test project containing `package.json`:
+
+```sh
+cd /absolute/path/to/test-project
+npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
+npm install
+npm run build
+```
+
+Use `bun install` and `bun run build` for Bun. Keep npx options before `ds`.
+`--tool-package` accepts an absolute local tarball path, a version, or a matching
+package/version. A tarball becomes a `file:` development dependency, so keep it
+available for subsequent installs. A published pinned version is portable
+between machines without an archive. Routine builds need no global install.
+
+## Commands and checks
+
+| Command | Behavior |
+|---------|----------|
+| `ads init --framework react` | Add ADS tooling to the current project; accepts `react` or `preact`; saved choices can omit the flag |
+| `ads check [directory]` | Read-only core token, source import, and style checks |
+| `ads tokens [directory]` | List declared values and theme/media scopes |
+| `ads assets [directory]` | Generate standard icons from `assets.iconSource` |
+| `ads lint-config [directory]` | Generate or refresh `.ds/oxlintrc.json` |
+| `ads mcp [directory]` | Serve tools, resources, prompts, skills and preview Apps; start the local showcase |
+| `ads mcp --mutations` | Enable guarded edits to the local ADS, validated before application |
+| `ads showcase [directory]` | Start the same MCP runtime and showcase for browser-only use |
+| `ads --version`, `ads --help` | Version and usage |
+
+`init` accepts no directory argument. Other commands default to the current
+directory and can inspect another directory. `--json` gives structured results
+for inspection/setup commands; `mcp` uses stdout exclusively for JSON-RPC.
+Exit codes are 0 for success, 1 for check findings, and 2 for invalid
+input/configuration or execution errors.
+
+Guarded MCP editing is opt-in. Its mandatory checks and optional project
+`mcp.mutationChecks` scripts run in a temporary project copy with installed
+dependencies. See the [editing contract](MCP.md#guarded-editing) for unit ownership,
+Git patches, bounded reads and preview review. Keep normal build gates enabled
+for edits made by other tools.
+
+`check` validates required shared names in `:root`, readily checkable value
+categories, undefined aliases, alias cycles, and individual theme/media
+overrides. Project-specific values and additional definitions within ADS's fixed
+naming contract are allowed. The contract's `naming` section lists the fixed
+shared families and names; projects cannot configure alternative prefixes.
+`--ds-*`, `--ux-*`, and `--showcase-*` variables remain owned by their layers,
+including when a file is inside `tokens/`. Shared token assignments outside
+`tokens/` fail. Source styles also check shared references for undeclared names.
+It does not change values, import a theme, or synchronize definitions.
+
+Source checks enforce the configured public alias for app/showcase consumers,
+reject JSX inline styling except configured files, and check CSS and imported
+Linaria `css` and `styled` templates for raw visual values and namespace ownership. Private
+ADS implementation imports and showcase-local files are allowed. The checker
+recognizes imported aliases and shadowed bindings.
+
+These are static checks, not framework type checking or browser CSS evaluation.
+Arbitrary computed expressions, combined conditional cascade behavior, computed
+module specifiers, JSX spreads, other styling engines, and renderer-specific APIs
+need the project's existing checks and review. Continue to run its type checking,
+component tests, and browser comparisons. Component-specific rules run through
+Oxlint in `lint:ds`; `ads check` does not execute those plugins.
+
+## Showcase
+
+ADS ships a minimal browser shell, MCP client and Apps host. `ads mcp` serves the
+website alongside its stdio connection; `ads showcase` starts the same runtime
+for browser-only use. Run commands from the project root. Open the printed URL,
+or use `ads_status.showcaseUrl` from an already connected runtime. An available
+loopback port is selected by default; `--port 4185` selects a fixed port.
+`ads mcp --no-showcase` keeps a headless stdio server.
+
+The client negotiates the current modern MCP protocol, discovers menus with
+`ads_tokens`/`ads_scenarios`, invokes `ads_show_tokens`/`ads_show_scenario` and renders
+Apps through the official bridge. It refreshes menus on catalogue notifications
+and refreshes the active scenario in the same App after a successful build. Errors identify
+stale retained output. Its neutral header and left pane align and collapse
+together. Themes flow through the Apps host context. No project catalogue pages
+or direct component imports are used by this client.
+
+The project's responsibilities are the real implementations, colocated scenarios
+and fixtures, foundation CSS/Linaria extraction, and a preview compiler. The
+empty React starter includes a Vite compiler adapter and its tiny mount entry
+under `design-system/showcase/mcp/`. Init alone does not install or wire this
+compiler. For an existing app, adapt the starter's build script and mount entry,
+add its `build:mcp-previews` package script, and configure it explicitly:
+
+```json
+{
+  "mcp": {
+    "showcaseTitle": "My Project Design System",
+    "previewManifest": ".ds/preview/manifest.json",
+    "previewWatch": { "command": "node", "args": ["scripts/build-mcp-previews.mjs", "--watch"] }
+  }
+}
+```
+
+Keep the saved `framework` (`react` or `preact`), JSX transform and mount adapter
+consistent. The optional title defaults to the project package name followed by
+` · Design System`. The browser shell stays the same for both frameworks. There is
+one managed compiler per runtime, shared by stdio and HTTP clients. It builds
+a shared multi-entry graph on first demand and after source changes; the App
+loads only the selected scenario's dependencies. TSX/Linaria compilation still
+happens automatically. Accepted configuration-unit mutations replace the managed
+compiler while keeping MCP connected. External compiler/configuration or dependency
+changes may require restarting the runtime; ordinary owner/fixture/style/asset edits do not.
+See [the compiler contract](MCP.md#configure-the-project-compiler) for revisions,
+diagnostics, invalidation and the shared resource graph.
+
+Colocate `Scenario.tsx` and `fixture.ts` beside tokens and each component/pattern, or use
+`<Owner>.scenario.tsx` and `<Owner>.fixture.ts` for flat owners. Larger entries
+live under `composition/<Name>/`. A default zero-input mountable view imports the
+real public UI and a local fixture, and exports literal metadata:
+
+```tsx
+import { Button } from "@ds";
+import { fixture } from "./fixture";
+export const scenario = { title: "Button states", covers: ["Button"] };
+export default function Scenario() { return <Button>{fixture.label}</Button>; }
+```
+
+IDs derive from filenames; do not maintain another registry or hand-assigned IDs.
+Token scenarios live beside foundation CSS under the configured token directory.
+The starter includes `tokens/Foundation.scenario.tsx` and its local fixture for
+plain value inspection without a component library. For styled samples, use a
+public project review pattern and keep its presentation in that pattern:
+
+```tsx
+import { TokenSamples } from "@ds";
+import { fixture } from "./Typography.fixture";
+export const scenario = { title: fixture.title, covers: ["TokenSamples"], tokens: fixture.tokens };
+export default function Scenario() { return <TokenSamples {...fixture} />; }
+```
+
+`TokenSamples` is an example project-owned pattern, not an npm tool component.
+The fixture defines literal names and sample text, with no copied token values.
+Add/remove names when foundation tokens change. `token-scenario-reference`,
+`token-scenario-render` and `token-scenario-coverage` enforce real references and
+coverage for every token. The same source/style/import checks apply under tokens/.
+
+Fixtures/adapters own development inputs, state, callbacks and simulated services.
+The entry requires no browser page, application router/store or prior setup.
+Several contextual parts may share a scenario with their real parent. Larger
+entries reuse public production screen patterns instead of reassembling screens.
+
+`scenario-contract`, `scenario-render` and `scenario-coverage` require addressable
+coverage for every public renderable component/pattern, including unused exports.
+Only reachable real render references count. Types/constants/utilities are
+excluded. Scenarios and fixture helpers are development-only; runtime code and
+the public barrel cannot import or re-export them. They define no CSS, custom
+classes or native widget replicas. Reusable review layouts are public project
+patterns; the outer browser shell is tooling UI. Full-app integration harnesses
+belong in application tests. See the [contract](ADS.md#showcase-contract).
+
+For this checkout, `npm run dev:showcase` builds the tool and launches its client;
+`npm run build:showcase` compiles scenario artifacts for verification. Use `bun
+run` with the same script names. These commands do not install a UI catalogue.
+The optional `scenarioRegistryPlugin` remains available for legacy Vite browsers,
+but the built-in client reads discovery through MCP. Existing custom showcases
+are preserved by init; replace their run command deliberately when migrating.
+
+Run core and registered project checks before preview compilation, alongside
+framework checks and meaningful tests. Review real entries at narrow/wide sizes,
+in both themes and relevant states. Browser verification still establishes
+layout, keyboard/focus, interactions and motion; compiler success does not.
+
+Public `*Props` declarations omit inherited DOM `style`; arbitrary visual strings
+also fail. Measured geometry uses explicit boundaries. HTML mount styles may
+only establish full root height and body overflow. Project presentation belongs
+in owned component/pattern styles, with tokens supplying visual values.
+
+## Branding
+
+ADS has fixed token names and ownership namespaces. Change values in the existing
+token files; `--accent`, `--font-sans`, `--radius-md`, and the other shared roles
+keep their meanings across projects. Foreign prefixes such as `--nuv-*` or
+`--brand-*` fail. Components own `--ds-*`, patterns own `--ux-*`, and the showcase
+reserves `--showcase-*` for showcase boundaries. Fixture files still define no
+custom styling; the frame pattern uses `--ux-*`. Branding never assigns
+component state variables.
+
+Keep original SVG artwork and a usage/credits/license README in
+`design-system/assets/brand/`, and font files in `assets/fonts/`. Font declarations
+belong in optional `tokens/fonts.css`, imported first. The foundation entry is
+import-only: fonts (when present), colors, typography, spacing, elevation, base.
+Fixed artwork colors and geometry are permitted inside SVG assets; they do not
+permit raw visual values in component or pattern styles.
+
+Select one SVG master with an ADS-relative path:
+
+```json
+{ "assets": { "iconSource": "assets/brand/app-icon.svg" } }
+```
+
+Merge this into `ds.config.json`; the source must be a real SVG inside
+`assets/brand/`. `ads assets` generates these files in ignored `.ds/assets/`:
+
+| Output | Size |
+|--------|------|
+| `favicon.svg` | Copy of the original SVG |
+| `favicon.ico` | 16, 32, 48 px entries |
+| `apple-touch-icon.png` | 180 × 180 |
+| `icon-192.png` | 192 × 192 |
+| `icon-512.png` | 512 × 512 |
+
+Rendering preserves colors, aspect ratio, and transparent padding. Include a
+background in the original if needed for a platform. Every invocation rebuilds
+the small output set; there is no rendering cache, asset registry, or theme
+resolver. With no `iconSource`, it succeeds without writing. All images render
+before generated files are replaced, so invalid artwork leaves prior outputs
+intact. Sources, duplicate output mounts, and symlinked write paths are checked.
+
+Initialized builds run:
+
+```text
+lint-config → ads check → Oxlint → ads assets → existing prebuild → existing build
+```
+
+`lint:ds` remains read-only except for generated lint configuration. `assets:ds`
+runs `ads assets`; checks do not require outputs on a clean checkout. A failed
+check or generation stops the build. Re-running init preserves token values,
+artwork, existing configuration, and unrelated scripts.
+
+Mount `.ds/assets/` using the application's existing bundler. Init does not change
+framework configuration. For a Vite app with no other public directory, a project
+can set `publicDir: path.resolve(import.meta.dirname, ".ds/assets")`; when it
+already has public assets, use its existing asset merge/copy step and reject
+duplicate output paths. Use the same assets in development and production.
+Application manifest metadata and other platform exports remain project-owned.
+
+### Generic architecture guards
+
+`ads check` enforces reusable architecture policies alongside token checks:
+
+| Guard | Shared enforcement |
+|----------------|------------------------------|
+| Public APIs | Inherited/explicit style props and open-ended visual color/fill/stroke strings |
+| Renderer boundaries | JSX inline styles, React/Preact CSS types, imperative `.style` writes, bulk style writes, and style-object escapes |
+| Asset ownership | ADS/public mount collisions, configured generated assets in source, and tracked generated output |
+| Product patterns | CSS/JSX namespace ownership; ADS implementations and showcase cannot import app source |
+| Primitive state | State-variable overrides outside components; undocumented non-state component variables |
+| Fixed token ownership | Foreign token names, shared token overrides, misplaced component/pattern/showcase variables, and noncanonical foundation imports |
+| Showcase ownership | Fixture CSS/Linaria definitions, custom JSX classes, native controls/widget roles, state styling, private CSS/aliased imports, legacy catalogue dependencies and source ownership, and runtime imports of fixtures/test helpers |
+| Scenario coverage | All public renderable UI has path-discovered entries, colocated fixtures, literal metadata and reachable public render references; runtime imports of scenarios/fixtures are rejected |
+| Data access | Direct global fetch/XHR/WebSocket/EventSource in ADS source is rejected; injected services, workers and lazy imports remain allowed |
+| Showcase coverage | Public ADS UI referenced by production JSX/React `createElement` has showcase render references; imports and tests alone do not count |
+
+ES module imports, re-exports, and dynamic imports with literal specifiers use
+TypeScript's project configuration, including aliases and bundler resource
+queries. ADS implementations and showcase fixtures cannot import app code.
+Private imports within ADS implementations remain allowed, including when the ADS
+is nested inside `src/`. Application integration harnesses belong in test support.
+
+Project rule registration is explicit:
+
+```json
+{
+  "oxlint": {
+    "plugins": [{ "name": "project", "path": "scripts/oxlint-project.mjs" }],
+    "rules": { "project/domain-usage": "error" },
+    "overrides": [
+      { "files": ["src/test/**"], "rules": { "project/domain-usage": "off" } }
+    ]
+  }
+}
+```
+
+Override patterns are project-relative, cannot escape the project, and configure
+Oxlint only. They do not suppress architecture checks from `ads check`. A plugin
+can import Node-only `loadConfig`, `importResolver`, and `styleWriteViolation`
+from `@reqvire-org/ads` when it needs the same validated boundaries as core.
+Unknown configuration fields fail rather than silently weakening checks.
+
+Component interaction variables such as `--ds-button-hover-bg` cannot be
+assigned by app code, patterns, or showcase code. This includes static JSX style
+objects in files with inline-style exceptions. Reading a variable is allowed;
+the component owns its state definitions. Documented non-state customizations
+are registered explicitly. State variables cannot be allowlisted.
+
+Keep renderer-, framework-, and component-specific project guards too. The
+shared tool does not validate a third-party graph renderer's own APIs, arbitrary
+runtime spreads, or the semantic meaning of a
+measured value. Register Oxlint plugins through `oxlint.plugins` / `oxlint.rules`
+and continue running standalone checks through the existing build.
+
+### Project boundaries and assets
+
+Optional configuration adds only the permissions and paths that the project
+actually uses; the tool contains no component or product-specific lists:
+
+```json
+{
+  "boundaries": {
+    "styleWrites": [
+      { "file": "design-system/components/geometry.ts", "properties": ["--ds-panel-height"] }
+    ],
+    "componentVariables": ["--ds-panel-gap"]
+  },
+  "assets": {
+    "iconSource": "assets/brand/app-icon.svg",
+    "publicDirs": ["public/assets"],
+    "generatedPaths": ["dist", "dist-showcase", ".vite", ".ds"],
+    "generatedFiles": ["icon-generated.png"]
+  }
+}
+```
+
+Merge these sections into `ds.config.json`. `styleWrites` permits only the
+listed CSS properties in that exact file. Use kebab-case (`user-select`) or an
+exact custom property. Static assignments, `setProperty`, and `removeProperty`
+can use that boundary; `cssText`, computed property names, escaped style
+objects, and bulk writes remain forbidden. Plain property reads are allowed.
+`inlineStyleFiles` is a separate file-level JSX/type exception and never
+permits imperative writes by itself.
+
+Asset checks compare `design-system/assets/` with each configured public mount
+and `design-system/showcase/public/assets/`, adjusting for `dsDir`. A relative
+asset path may have one source owner per mount, even if duplicate contents
+match. `generatedFiles` names asset-relative paths forbidden in those source
+directories; nothing is inferred from filenames such as `favicon.ico`.
+
+`generatedPaths` names project-relative files or directories that must not be
+tracked. Legacy `dist-kit/` and `dist-showcase/` output is also generated;
+the built-in client uses project preview artifacts under `.ds/`.
+Git inspects tracked files, including nested workspaces. Outside a Git repo,
+there are no tracked outputs to check; other asset checks still run. Real Git
+inspection errors fail the check. These guards read files and never delete them.
+
+## Configuration and component rules
+
+`ds.config.json` uses schema version 1. Paths stay within the receiving project:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourceDir": "src",
+  "dsDir": "design-system",
+  "publicAlias": "@ds",
+  "publicEntry": "index.ts",
+  "stylesEntry": "styles.css",
+  "tokenDir": "tokens",
+  "inlineStyleFiles": [],
+  "oxlint": { "plugins": [], "rules": {} }
+}
+```
+
+These source-layout defaults apply when the file is absent; the example omits
+the required init-time framework choice. Run `ads init --framework react` (or
+`preact`) to save it. To use another layout, write this configuration before init. Configure TypeScript and the app bundler to resolve
+the same alias; this file does not rewrite their configuration.
+
+Colocate component-specific rules with the project component and register a
+project-owned Oxlint plugin adapter explicitly:
+
+```json
+{
+  "oxlint": {
+    "plugins": [
+      { "name": "project-ui", "path": "scripts/oxlint-project-ui.mjs" }
+    ],
+    "rules": { "project-ui/feature-usage": "error" }
+  }
+}
+```
+
+Merge that section into the project configuration, then run the normal build.
+Generated configuration registers `ads/public-import`, `ads/no-inline-style`, `ads/no-app-import`, and
+explicit project plugins. Core tooling imports no particular component.
+Registered project configuration and build helpers may import one another;
+this boundary is derived when lint configuration is generated. It does not
+allow application code to import private ADS modules or build helpers to import
+private UI implementation.
+`inlineStyleFiles` should name only documented geometry/renderer boundaries,
+not broad styling exceptions. Ignore `.ds/`; generated paths refer to the project
+and its locally installed tool.
+
+`lint-config` remains a low-level command for custom build integration and
+debugging. For pipelines outside package-manager build hooks, run the same
+sequence before compilation, from the project root with local binaries available:
+
+```sh
+ads lint-config .
+ads check .
+oxlint --deny-warnings --config .ds/oxlintrc.json src design-system
+```
+
+Retain unrelated lint, type checking, and framework build commands.
+
+## External content
+
+Use the repository's `ads-import` skill for selected external ADS source or theme
+values, and `ads-assimilate` for a native implementation inspired by an upstream
+library. These agent workflows handle dependency closure, token mapping, motion
+comparisons, source credits, applicable notices, and local documentation.
+They are agent workflows, rather than CLI import/design subcommands. Install
+them through `npx skills`, or read the packaged skills through the
+[stdio MCP server](MCP.md#skills). MCP serving does not install or automatically
+activate a skill, and the tool still bundles no UI component/example library.
+
+
+## Release maintenance
+
+Choose a version that is not already in `npm view @reqvire-org/ads versions`.
+Published npm versions cannot be replaced, even by moving or recreating a Git
+tag; see [npm publishing rules](https://docs.npmjs.com/cli/v11/commands/npm-publish/).
+
+Update `package.json` and its lockfile with
+`npm version <new-version> --no-git-tag-version --ignore-scripts`, commit and push
+those files, then push the matching `v<new-version>` tag. `release.yml` checks
+version availability, tests packed npm/Bun installs, publishes the package and
+creates the GitHub release. Stable tags publish as `latest`; prerelease tags
+publish as `next`. Check the workflow result and npm version before updating
+consumer dependencies. The manual workflow moves a label to an existing
+published version; it does not publish new source.