@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/skills/ads-designer/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: ads-designer
+description: Bootstrap an empty local React design system from bundled scaffolding, or build UI using a project's existing design system. Covers shared token contracts, local ownership, public APIs, external source integration, showcase inspection, and validation.
+---
+
+Inspect the target before editing. Read its `README.md`, `docs/ARCHITECTURE.md`
+and `docs/ADS.md` when present (or existing project guides), public exports, and relevant
+component guides. Preserve its
+framework and contracts. Starting from zero works from the bundled empty
+scaffold without an example repository.
+
+Linaria is required for ADS component and pattern styling. Preserve the target's
+UI framework and integrate compatible Linaria extraction with both application
+and preview builds. The bundled React/TypeScript starter already configures it;
+`ads init` does not install or configure Linaria. Use the starter when its
+framework is appropriate. Current core
+guards inspect JS/TS/JSX, CSS, and imported Linaria templates, not Vue/Svelte
+single-file components or general HTML component templates. Entry HTML mount
+CSS is checked; that is not component-template coverage. Preserve the target stack and matching
+framework checks; do not claim unchecked formats have full guard coverage.
+
+React and native Preact are supported. Preserve the target runtime in both
+production and scenario builds; never alias React to Preact just to shrink a
+preview. Native Preact uses its own JSX transform, hooks and DOM events (live
+text updates use `onInput`). Native SVG uses DOM names such as `stroke-width`,
+not React presentation aliases. Keep Linaria extraction and the same public APIs.
+The shipped empty starter uses React; the tool repository's working example
+uses Preact. Neither is a component dependency of the receiving project.
+
+When initializing a project without a saved framework, pass `--framework react`
+or `--framework preact` for its actual runtime. Init saves the choice and later
+runs reuse it. The bundled starter already declares React. Resolve any explicit
+JSX/configuration conflict deliberately; do not change frameworks to make init
+pass. Init does not install the runtime or configure the application's compiler.
+
+ADS is tooling only. The target project owns its ADS source and token values;
+applications use its local public barrel, normally through `@ds`. Components,
+patterns, themes and scenarios come from external sources through explicit
+ADS import/adaptation workflows. Do not treat the tool repository as a built-in
+or optional UI catalogue. Tool upgrades preserve project values and customized
+implementations; external source updates require explicit imports or merges.
+
+## MCP access when available
+
+Use `ads_status` and `ads_catalog` to discover the connected project's public UI,
+guides, showcase URL and addressable scenarios. `ads_tokens` inspects definitions; `ads_show_tokens` renders token scenarios;
+`ads_scenarios` discovers previews and `ads_show_scenario` opens the selected real entry. Read relevant source
+and inspect the actual view before changing it. HTML delivery alone is not a
+rendering check. Use the normal showcase when the host lacks Apps support.
+Use the returned `projectRoot` and `project.commands`; the connected ADS may be
+inside a different or nested repository. Inspect the selected public API, owning
+source/available guides and relevant tokens, then mount its discovered scenario.
+Metadata and source reads do not prove rendered behavior.
+
+When `ads_status.mutations.enabled`, discover the owner with `ads_units`, read
+relevant ranges with `ads_read_file` and send only a Git unified diff through
+`ads_apply_patch({ unit, patch, dryRun })`. A unit includes its own implementation,
+scenarios and fixtures; imported peers remain separate. `tokens` is the token
+foundation unit. Unit discovery and file ownership are distinct from preview IDs.
+Include only that owner's required re-exports in the public entry. Use
+`dryRun: true` to inspect validation; applying re-runs the gates. Fix rejected
+patches in their owner. Shared styles/helpers use `foundation`, root guides use
+`documentation`, and branding/fonts use their discovered `assets/*` unit.
+Intentional configuration, rule exceptions, registered guard code and compiler
+changes use `configuration`; validate the proposed settings and keep mandatory
+ADS gates. For binary/large assets, generate `git diff --binary --full-index` into
+`.ds/patches/<name>.patch` and send `patchFile` instead of inline `patch`, so bytes
+stay out of model context. Binary changes require Git. When editing is disabled,
+use the client's normal source-editing tools.
+
+Check `ads_status.previewWatch` before launching another preview builder. With a
+managed watcher, edit owned sources, wait for the rebuild and invoke the preview
+again; the client already starts and stops the builder through `ads mcp`. Check
+`ads_status.build` or `ads://project/build` explicitly: a running process, older
+artifact or unreported freshness does not establish current source. Fix reported
+diagnostics in the owning source; notifications may not reach the agent.
+When this skill is served over MCP, resolve relative references/assets from its
+`SKILL.md` URI and fetch supporting files lazily. The host controls native skill
+activation; ordinary resource reads do not establish it. For a scaffold copy,
+use the complete manifest and verify file bytes/digests rather than saving
+truncated model-visible text or binary snippets.
+
+## Start from zero
+
+Create the application first, then initialize ADS inside it. The CLI requires
+an existing `package.json`; `ads init` accepts no directory argument and does not
+generate an application. Read [references/cli.md](references/cli.md) to use an
+actual published version or local tarball. Init adds the tool as a development
+dependency and connects ADS checks to the existing build. If no tool distribution
+is available, the bundled files below still support bootstrapping and general
+checks; do not fetch the unpublished package.
+
+Read [assets/bootstrap-ds/README.md](assets/bootstrap-ds/README.md) and its
+[contract](assets/bootstrap-ds/ADS.md). The scaffold contains semantic token
+defaults, React/TypeScript/Linaria configuration, general lint, an empty public
+barrel, empty component/pattern directories, and a project preview compiler adapter. The browser shell is supplied by ADS tooling.
+It contains no components, shell patterns, vendored fonts, or example screens.
+
+Resolve assets relative to this skill's `SKILL.md`, including after installation
+by `npx skills`. In the tool checkout, root `bootstrap-ds/` is canonical.
+For a new empty project, copy its **contents**, including dotfiles:
+
+```sh
+starter_dir="/absolute/path/to/ads-designer/assets/bootstrap-ds"
+target_dir="/absolute/path/to/new-project"
+mkdir -p "$target_dir"
+cp -a "$starter_dir/." "$target_dir/"
+cd "$target_dir"
+# Run ads init here when an actual tool distribution is available.
+npm install
+npm run build
+```
+
+Replace the example paths with actual directories. Set the project package
+name. Add only requested components and patterns, export them through the
+local barrel, and demonstrate their public API in the project showcase.
+The bundled application defaults to npm. For a new Bun application,
+translate nested npm script calls to `bun run` and omit the starter npm lockfile;
+preserve an existing app's package manager and lockfile when merging.
+Initialize/install ADS before running `npm run dev:showcase` for visual inspection.
+Use an existing MCP runtime URL when connected; do not leave an unrequested
+server running.
+
+For an existing app without an ADS, run init inside that app when the tool is
+available, then integrate its local public alias, CSS entry, and Linaria
+extraction with the existing framework. Init detects the package manager from
+the app and preserves its scripts and lockfile. Without a tool distribution,
+merge only the required ADS source and dependencies from the bundled scaffold.
+Inspect files before editing; preserve configuration and application entry
+points. Never copy the standalone package/configuration over an existing app.
+
+## External references and content
+
+Accept an external example/source repository URL or local path supplied with the
+request. If source content is needed and no location is known, ask for the source;
+continue independent local discovery first. Do not invent a repository URL or
+use the tooling checkout's origin as an example library. Bootstrap needs no
+external source.
+
+Inspect the external repository's instructions, architecture, actual ADS folder,
+public exports, item guides, token contract, styles, build, and license.
+Do not assume it has a particular component, hook, font, or token helper.
+Record the source revision and required dependencies.
+
+Use the ADS import workflow to bring selected existing ADS items into the target,
+or assimilation to create a native component from an upstream library. Follow
+those workflows directly if the corresponding skills are unavailable: copy
+selected source and its dependency closure, or study/reproduce the upstream
+contract; integrate local ownership, exports, styles, assets, credits, applicable
+notices, and checks. Do not copy the whole catalogue or source configuration.
+Mocks and example screens remain development fixtures unless explicitly requested.
+
+Preserve the target's performance strategy when changing ownership: lazy imports,
+worker execution, caches, memoization, cancellation, and stale-result rejection.
+Public exports must not eagerly load heavy renderers for unrelated consumers.
+Compare relevant bundle loading and existing performance/lifecycle tests before
+and after a migration. Shared screen patterns can accept injected services;
+architectural reuse does not require moving application services into the ADS.
+
+## Token and component ownership
+
+- Token names and prefixes are fixed by ADS architecture. Use existing shared
+  names; `--ds-*` belongs to components, `--ux-*` to patterns, and
+  `--showcase-*` is reserved for showcase-local boundaries, not fixture styling.
+  ADS-owned frame patterns use `--ux-*`. Do not introduce configurable or
+  product-prefixed token vocabularies.
+- Shared token names, meanings, types, and alias relationships form the contract;
+  project values and theme overrides can differ. Item imports retain existing
+  values and add missing definitions. Explicit token-values imports adopt source
+  values and theme variants.
+- Scaffold defaults are dense 13px UI text, a 4px grid, warm surfaces, slate
+  text, rose accents, restrained elevation, and system fonts. Treat these as
+  initial project values; honor requested branding and preserve existing themes.
+- Reuse existing public components, patterns, and shared icons when compatible.
+  Add missing primitives in their owning layer; inspect exports rather than
+  assuming they exist.
+- Components own hover, selected, active, focus, disabled, loading, and motion.
+  Change these through typed props/variants in the component. Consumers and
+  showcase CSS must not override internals.
+- Put visual constants in tokens. Avoid inline visual styles, arbitrary visual
+  string props, and broad imperative style mutations. Measured geometry can use
+  a narrow documented boundary while visual policy stays in tokens and styles.
+- Keep product data, routing, effects, and callbacks in application code.
+  Reusable layouts and controls belong in the local ADS.
+- Document detailed API, behavior, motion, token hooks, validation, and source
+  credits beside each component or pattern. Shared project architecture belongs
+  in its ADS guide.
+
+## Branding
+
+Discover existing tokens and artwork before changing identity. Keep UI values
+in the existing token files using fixed ADS names, and original artwork plus its
+usage, backgrounds, credits, and licenses in `assets/brand/`. Keep fonts in
+`assets/fonts/`, with optional `tokens/fonts.css` imported first. Follow the
+canonical foundation import order: fonts (if present), colors, typography,
+spacing, elevation, base. Artwork can have fixed SVG colors; UI styles must
+still use tokens and must not override primitive state.
+
+For standard web icons, set `assets.iconSource` to an SVG under `assets/brand/`,
+relative to the ADS folder. After init, the normal build runs ADS/Oxlint checks,
+then `ads assets`, then existing prebuild/build steps. Mount ignored `.ds/assets/`
+through the application's own bundler without public asset collisions. Keep
+manifest metadata and other platform exports project-owned. Verify the actual
+consumer paths, dimensions, and transparent/background variants. With no icon
+source, generation is a no-op. Component imports retain destination branding;
+artwork replacement and token-value adoption are explicit selections.
+
+## Design craft and mobile behavior
+
+For component polish, state completeness, content/layout decisions, or showcase
+quality, read [references/design-craft.md](references/design-craft.md). For touch,
+small screens, browser chrome, safe areas, or mobile forms, read
+[references/mobile.md](references/mobile.md). Load these when relevant rather
+than imposing mobile application setup on every component task.
+
+Implement motion inside the owner using existing tokens and reduced-motion
+policy. Use the project's existing driver, preserve documented exceptions, and
+verify interruption and cleanup. Dedicated motion or stress-test skills can
+help when installed; they are not required for this workflow. Use the real
+public-API showcase and the checks below when they are unavailable.
+
+Selected guidance adapts Emil Kowalski's design/mobile skills. Preserve its
+[credits](README.md) and [MIT notice](LICENSE.upstream) with redistributed material.
+
+## Use the showcase as the design workspace
+
+Discover the existing showcase and its run/build commands before visual work.
+Open its MCP-reported URL to inspect the current design. If the installed tool
+supports the built-in client, use it; add the project compiler/scenario adapters
+needed for real previews instead of building another browser app.
+
+The showcase is a minimal shell plus an MCP client and Apps host, supplied by ADS
+tooling. It discovers Tokens/Components/Patterns/Composition entries through MCP
+tools and renders their scenarios in the preview App. Navigation, theme and
+pane/header visibility belong to the tool client. Do not create page files,
+copy its shell into the project or assemble a second catalogue/rendering pipeline.
+
+When MCP is connected, open the running URL from `ads_status`. Otherwise run the
+installed `ads showcase` or the project's `dev:showcase` script. Do not launch a
+second runtime/compiler for the same connected project. A configured project
+preview watcher publishes a shared graph on first demand and after source
+changes. The built-in client refreshes discovery and the active scenario in the
+same App after a successful build. Shared runtime, foundation CSS, fonts and
+selected scenario modules load through MCP
+resources inside the sandboxed App. Never inject project styles/runtime into
+the outer host. Keep the configured framework, compiler and mount/unmount adapter
+consistent; scenario teardown must release owned timers, portals and workers.
+The host shows errors and marks retained output as stale. Other hosts may need an
+explicit preview-tool invocation. Compilation remains project-owned and required
+for TSX/Linaria; it is automatic, not eliminated.
+
+Reusable review layouts belong in public project ADS patterns, while scenario
+files define no CSS, custom classes or widget replicas. Keep real presentation in
+its component/pattern owner. The tooling shell's CSS is outside that project
+contract. Legacy custom showcase pages may be retained during migration; new
+projects require no TokensPage/ComponentsPage/PatternsPage/CompositionPage files.
+
+Colocate `Scenario.tsx` and `fixture.ts` with tokens and each component/pattern; flat owners
+may use `<Owner>.scenario.tsx` and `<Owner>.fixture.ts`. Put larger entries under
+`composition/<Name>/Scenario.tsx` with their own `fixture.ts`. Export a default
+zero-input mountable view and literal metadata, for example
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Import the real UI from the public ADS alias. Keep fixture inputs, simulated
+services and initial state/callback adapters beside the scenario. Empty fixtures
+are valid for an entry with no inputs. Extra development helpers use a
+`scenario/` or `fixtures/` subfolder, or `<Owner>.scenario-adapter.ts`, so guards
+recognize their role even beside runtime code. Never require a page, router or store to
+initialize the entry. Several contextual public parts may share one scenario.
+
+IDs derive from ADS-relative filenames: both `components/core/Button/Scenario.tsx`
+and `components/core/Button.scenario.tsx` identify `components/core/Button`.
+Use one form, no duplicate IDs or hand-maintained registry. Renames change IDs.
+The showcase and external hosts mount the same discovered entry. The Vite
+adapter uses `previewEntriesPlugin` and `createPreviewResources` with
+`runScenarioCompiler` to publish the shared graph. Its framework mount adapter
+returns cleanup; the project owns rendering and Linaria extraction. The older
+`scenarioRegistryPlugin` is only for retained legacy browsers. MCP discovers
+metadata without importing executable TSX. Existing apps need an explicitly
+integrated compiler; init alone adds no compiler or extraction setup.
+Use `ads_scenarios` (query/kind/limit) and `ads_show_scenario({id})` to open an exact
+entry. Check its build freshness; HTML delivery is not browser verification.
+If Apps or resource forwarding are unavailable, open that scenario in the real
+showcase, using the tool result's URL. Do not build a preview-only replica.
+
+For a production screen, find and render the application's public screen pattern.
+Its owner supplies structure, controls, layout and presentation. Scenario fixtures
+supply data/state/callbacks. Move shared presentation into a pattern if needed,
+preserving existing behavior and lazy imports, workers, caching and cancellation.
+Do not reassemble an alternative screen or substitute placeholder content.
+Screen reuse remains skill guidance, not a dedicated screen-parity lint.
+
+Resolve `scenario-contract`, `scenario-render` and `scenario-coverage` findings
+with meaningful entries. Every public renderable component and pattern needs an
+addressable scenario, including unused exports; types/constants/utilities do not.
+Only public render references reachable from the default entry count. Tests and
+unused imports/functions do not. Static reachability does not prove successful
+mounting, correct content, every branch/state or visual parity: open each affected
+entry independently and verify real behavior at narrow/wide sizes in both themes.
+The older `showcase-coverage` policy separately checks application references.
+
+Token previews use that same scenario pipeline. Colocate a token scenario and
+fixture under the configured token directory. Use static metadata
+`{ title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens }` with
+literal const fixture fields; names/sample text are fixture data, values come
+from the real foundation CSS. Reuse a public project review pattern for styled
+samples. The minimal starter's foundation value scenario can have `covers: []`.
+Every declared token needs reachable scenario coverage; adding/removing a token
+requires fixture updates. Fix `token-scenario-reference`, `token-scenario-render`
+and `token-scenario-coverage` findings. Metadata and unused fixture fields do not
+count. Discover exact token IDs with `ads_scenarios({kind:"tokens"})`; mount them
+with `ads_show_scenario({id})` or `ads_show_tokens({category:id})`. With the shared
+resource compiler, omitting category opens the first project token scenario.
+Legacy compilers retain the generic definition inspector. Use `ads_tokens` for
+source definitions and values; inspecting definitions does not prove UI parity.
+The tool keeps the shared naming contract; sample templates and their token
+lists belong to the project.
+
+Scenarios, colocated fixtures and helpers are development-only. Never export them
+from the runtime barrel or import them in production, including through aliases,
+re-exports or dynamic imports. They may not import application stores, routers,
+providers or HTTP clients. Live business data is application-owned; UI uses typed
+inputs or injected services/callbacks. Direct global fetch/XHR/WebSocket/EventSource
+is rejected; custom clients and computed access require review/project guards.
+Use local simulated services in fixtures. Tests may import fixtures; load real
+foundation CSS rather than assigning shared token values in JavaScript. Keep
+full-app integration harnesses and workflow coverage in application test support.
+
+
+
+Register component/project Oxlint plugins and rules in `ds.config.json`. Use
+scoped `oxlint.overrides` for justified file-specific settings; never edit
+`.ds/oxlintrc.json`. These overrides configure Oxlint, not the independent
+architecture checks in `ads check`. Measured renderer properties and documented
+non-state hooks use explicit `boundaries`; shared token writes and primitive
+state overrides cannot be allowlisted. Add generic architectural protections to
+ADS core and keep domain/component-specific rules registered in project setup.
+
+Examples and composition scenarios must consume the same public components, patterns,
+foundation CSS, and token values as the application. Scenario adapters may own sample data,
+state, callbacks, and example selection. A missing reusable control or pattern
+must be implemented/exported in its owning ADS layer, then imported through the
+public API. Never finish a mock with a separately styled component replica.
+The outer shell, navigation and theme controls belong to the tool client.
+Scenario labels and sample layouts use known public ADS entities with defined
+APIs, owned by project patterns. Keep review layouts minimal so they do not
+influence the product design. Showcase/scenario
+files define no CSS, custom class names, inline styling, or widget markup.
+Use semantic fixture content and public entities; a missing frame/layout is an
+explicit ADS pattern change. Component appearance, states, sizing policy,
+accessibility, and motion stay in the shared owner.
+
+Update examples when creating/changing components, patterns, or token values.
+Include meaningful variants, difficult content, supported states, themes, and
+container sizes. Run ADS and registered project guards for both app and showcase
+builds; do not exclude scenarios or loosen ownership rules to make a demo pass.
+For unchecked source formats or styling engines, retain the project's matching
+guards and report the gap. A clean static check does not prove all UI is shared.
+
+Inspect the rendered examples and relevant interactions. Fix shared design in
+the implementation so the showcase and application receive it together. Give
+the human a full running URL, or an exact command when the server is stopped,
+and identify what is ready to review. Continue already-authorized work without
+adding an approval step solely because a showcase exists.
+
+## Notifications when a local Toast exists
+
+Read the local notification guide before using its API; the empty scaffold has
+no Toast. Follow its host/provider mounting, routing, scope, duration, and focus
+contracts instead of assuming Sonner compatibility or a particular native API.
+
+Create transient notifications from client handlers/callbacks, rather than render
+or server execution. Follow documented stable-ID policy for effects. Use the
+component's promise/loading lifecycle API when available and settle manual
+loading notifications on success and failure. Keep field errors and persistent
+information in the relevant form, inline alert, or dialog.
+
+Customize through local tokens and documented variants. Stacking, gestures,
+measured geometry, and animation belong to the component. Register applicable
+component-local usage rules in project tooling; do not assume the empty scaffold
+includes them or that core tooling bundles this component.
+
+## Validate
+
+Use the target's actual lint/typecheck/build commands. The empty scaffold provides:
+
+```sh
+npm run typecheck
+npm run build
+```
+
+Run meaningful component/rule tests when behavior or enforcement changes.
+Follow [references/cli.md](references/cli.md) to integrate the tool as a
+development dependency in the target's actual lint/build pipeline. Initialization
+already does this. Routine builds refresh configuration and run core checks
+automatically; npx remains useful for bootstrap or ad hoc inspection. Core checks do
+not replace framework type checking, component rules, or interaction tests.
+For visual work, inspect the real project showcase, including keyboard/focus,
+relevant pointer/touch behavior, dark theme, and reduced motion as needed.
+A screenshot alone does not prove behavior or animation. Validate public imports,
+CSS/asset resolution, required setup, and local documentation links.

package/dist/skills/ads-designer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ADS Designer"
+  short_description: "Bootstrap a local ADS or build UI with its public API"
+  default_prompt: "Use $ads-designer to build UI using this project’s local design system, or bootstrap an empty one."

package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md

@@ -0,0 +1,203 @@
+# Design-system contract
+
+This is the local contract for the copied starter. The project owns its source,
+token values, and branding. Tool updates preserve those values and customized
+code; source and theme imports are explicit operations.
+
+For the architectural rationale, see the
+[ADS architecture](https://github.com/reqvire-org/design-system/blob/main/docs/ARCHITECTURE.md).
+The rules and commands needed to use this starter are included locally.
+
+## Ownership
+
+| Layer | Owns | Location |
+|-------|------|----------|
+| Tokens | Colors, typography, spacing, radii, motion, elevation | `tokens/` |
+| Primitives | Generic controls, states, interaction and accessibility | `components/` |
+| Patterns | Reusable layout and composition | `patterns/` |
+| Scenarios | Colocated development entries and inputs | Beside their owner; larger entries in `composition/` |
+| Showcase host | Navigation and MCP client | Packaged ADS tooling |
+| Preview compiler adapter | Framework mount/unmount and foundation imports | `showcase/mcp/` |
+| Application | Domain data, routing, effects and callbacks | Consuming application |
+
+The starter declares React in `ds.config.json`. Keep that choice, JSX, runtime
+dependencies and the preview mount adapter consistent. Init records a choice for
+an unconfigured project; it does not convert copied React source to Preact.
+
+The starter has no components or patterns yet. Add only what the product needs.
+Keep the ADS in root `design-system/`, beside application `src/`.
+Keep public exports in `design-system/index.ts`; consumers use its `@ds` alias.
+`styles.css` is the foundation CSS entry and contains token imports only.
+
+## Visual and interaction policy
+
+Use semantic CSS tokens for visual values. Raw values belong in the token files.
+Projects sharing this ADS use the same token names, meanings, and value types;
+their concrete values and theme overrides can differ. Reuse existing local values
+when importing components/patterns, add missing shared definitions, and import
+source token values only when adopting that theme is requested.
+Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
+are rejected. Shared assignments belong in token files. Components own
+`--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
+assign those local variables or override component state.
+Own primitive markup, focus, hover, selected, disabled, loading, and motion in
+the primitive. Use typed props for variations. Keep reusable structure and skin
+in colocated Linaria blocks using `css` and `cx` from `@linaria/atomic`.
+Linaria is required for component and pattern styling. This starter already
+configures extraction in both builds; `ads init` does not install or configure it.
+
+Use `ads-*` classes and `--ds-*` variables for primitives, and `ux-*` for patterns,
+including the ADS-owned frame. Scenario files define no CSS or custom
+class names and must not target component internals. Avoid inline visual styles and arbitrary visual
+string props. Omit `style` from inherited DOM prop types. Document narrow measured
+geometry exceptions if a component needs them.
+
+Use semantic HTML and test relevant keyboard/focus behavior. Motion should
+consume duration/easing tokens and respect reduced motion. Brand changes belong
+in tokens or documented component hooks. The starter uses system fonts and has
+no icon component; add a shared icon primitive when it is needed.
+
+## Showcase
+
+The showcase is a minimal shell plus an MCP client and Apps host, shipped with
+ADS tooling. It discovers token/component/pattern/composition
+scenarios from MCP tool results, invokes preview tools and responds to resource
+notifications. The project does not author a second catalogue or browser app.
+
+`ads mcp` starts the loopback website alongside stdio. Open the URL returned by
+`ads_status`. Without an agent connection, `ads showcase` starts the same runtime
+for browser use. Both transports share one configured preview compiler.
+
+The shell owns section tabs, collapsible navigation, theme controls and the App
+slot. Components, patterns, token values, scenarios, fixtures and their Linaria
+styles remain project-owned. Only the sandboxed App loads and applies project
+runtime, CSS and fonts, through MCP resources. App presentation comes from the
+selected compiled scenario; reusable review layouts live in public ADS patterns. Do not recreate
+production widgets inside the client or scenario.
+
+There are four sections: Tokens, Components, Patterns and Composition. There are
+no required `TokensPage`/`ComponentsPage`/`PatternsPage`/`CompositionPage` files.
+Legacy custom browsing pages remain checked when present, but new projects use
+the built-in client. Its tooling CSS is separate from the project style contract.
+
+The shared resource compiler builds one graph for all discovered scenarios on
+first demand. Selections reuse the App and load their dependency closure. The
+project's `mountScenario(Scenario, container)` adapter returns an unmount callback
+that releases owned roots, listeners, timers, portals and workers. Switching or
+rebuilding a scenario resets its state while retaining unchanged shared modules.
+Host context selects the project theme; it does not replace the project's skin.
+
+
+Colocate development entries and fixture inputs:
+
+```text
+design-system/
+  tokens/
+    typography.css
+    Typography.scenario.tsx
+    Typography.fixture.ts
+  components/core/Button/
+    Button.tsx
+    Scenario.tsx
+    fixture.ts
+  patterns/Editor/
+    Editor.tsx
+    Scenario.tsx
+    fixture.ts
+  composition/Workspace/
+    Scenario.tsx
+    fixture.ts
+  showcase/mcp/                 Project compiler adapter
+    main.tsx
+```
+
+Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
+`Scenario.tsx` exports a default independently mountable view and literal metadata
+`export const scenario = { title: "Button states", covers: ["Button"] };`.
+Token entries under the configured token directory also declare `tokens`:
+`export const scenario = { title: "Typography", covers: ["TokenSamples"], tokens: fixture.tokens };`.
+Metadata may read literal const fixture fields; it cannot run expressions,
+functions, wildcard lists or token discovery. The same fixture list must be
+consumed by the default entry. `covers: []` is valid for a minimal token value
+inspection entry without public UI; styled samples use a real public review
+pattern. Names and sample text belong to the fixture, values to foundation CSS.
+It imports real public UI through `@ds` and its local fixture. The adapter supplies
+initial state, callbacks and simulated services. The default entry needs no
+mandatory caller inputs or prior page initialization. Related parts may share a
+scenario containing their required public parent. Larger composition scenarios
+reuse production screen patterns; that screen reuse remains skill guidance.
+
+IDs derive from the ADS-relative path: `components/core/Button/Scenario.tsx` and
+`components/core/Button.scenario.tsx` both identify `components/core/Button`.
+Use one form per owner. Renaming moves the ID. No manually assigned ID or parallel
+registry is maintained. Fixture files use `fixture.ts`/`<Owner>.fixture.ts`; JS,
+TSX or JSON equivalents are supported. An empty fixture is valid without inputs. Extra development helpers use
+`scenario/` or `fixtures/` subfolders, or `<Owner>.scenario-adapter.ts`.
+
+`scenario-contract`, `scenario-render` and `scenario-coverage` checks require valid
+entries and reachable public render references for every public renderable
+component/pattern, including unused exports and Linaria styled exports. Types, constants and utility functions
+are excluded. Coverage is a static source policy; it does not prove runtime
+mounting, correct props, every branch/state or visual parity. The older
+`showcase-coverage` policy also checks application render references.
+
+`token-scenario-reference` rejects undeclared token names in metadata and reachable
+inputs. `token-scenario-render` rejects claimed tokens with no reachable input
+reference; `token-scenario-coverage` requires every discovered foundation token
+to have coverage. A new or removed token therefore needs a scenario/fixture
+update. All three are errors in `ads check`, run by `lint:ds` and the build.
+Coverage is static reachability, not proof that every branch actually renders
+or applies the right CSS property. Browser review still verifies the samples.
+
+Scenarios and fixture helpers are development-only wherever colocated. Runtime
+source and the public barrel cannot import or re-export them. Showcase/scenario
+code defines no CSS, custom classes or native controls; use public ADS APIs.
+Neither ADS implementations nor scenarios import application code. Live business
+data belongs to application adapters; ADS receives inputs or injected callbacks.
+Direct global `fetch`, XHR, WebSocket and EventSource use is rejected. Renderer
+workers, lazy imports and injected services remain supported; custom HTTP clients
+and computed API access need project checks and review.
+
+Tests may import local fixtures. Load real foundation CSS in DOM/browser tests
+instead of assigning shared tokens in JavaScript. Full application harnesses
+belong in application test support. Run ADS/project checks before application,
+preview builds; review meaningful states in both themes and sizes.
+
+## Branding
+
+Keep original artwork, variants, usage, credits, and licenses in
+`design-system/assets/brand/`. This starter has only guidance there, no artwork.
+Font assets belong in `assets/fonts/`; add optional `tokens/fonts.css` first in
+the import-only foundation entry. The fixed import order is fonts (when
+present), colors, typography, spacing, elevation, base.
+
+Select an SVG with `assets.iconSource` in `ds.config.json`, relative to the ADS
+folder. Initialized builds run checks and Oxlint, then `ads assets`, then existing
+build steps. Standard icons go into ignored `.ds/assets/`; integrate that
+directory with the application's asset mount and reject duplicate paths.
+Application metadata and custom platform exports remain project-owned. See
+[brand guidance](design-system/assets/brand/README.md).
+
+## Component guides and rules
+
+Keep detailed API, examples, interactions, token hooks, tests, and source credits
+in a README beside the component. When adapting another library, record its
+version, author, links, concrete influences, and agreed differences. Shared
+architecture belongs here rather than duplicating each component contract.
+
+General Oxlint and Biome CSS checks are included. They do not enforce the entire
+ownership or token contract. Add component-local lint only for concrete,
+statically provable misuse; register tooling centrally and keep it outside the
+runtime barrel. Core checks must work without any particular component library.
+Use configured token and ownership guards as the system grows; bring applicable
+component-specific rules with an external item and register them in project
+tooling. Configure project plugins, rules, and scoped `oxlint.overrides` in
+`ds.config.json`. Overrides configure Oxlint, not independent `ads check` policies.
+Use explicit `boundaries` for documented renderer properties and non-state hooks.
+
+## Verification
+
+Run `npm run build` after adding or changing components. Add meaningful tests
+for stateful behavior, accessibility, gestures, or async lifecycle where needed.
+Run `npm run dev` to inspect the real showcase. A screenshot alone does not
+verify interaction or animation. Generated output and dependencies are not source.