@reqvire-org/ads 0.0.0-stage → 0.3.0

package/docs/ADS.md

@@ -0,0 +1,310 @@
+# ADS tooling contract
+
+This document defines enforceable ownership, token, integration, and build
+rules. [ARCHITECTURE.md](ARCHITECTURE.md) explains their purpose and the Data,
+UX, and Skin pillars. [GUIDE.md](GUIDE.md) gives setup and configuration steps.
+
+## Ownership boundary
+
+MCP source editing is opt-in through `ads mcp --mutations`. Its write operation
+accepts a Git unified diff for one ADS unit and validates its source, scenario and
+fixture changes against core checks, registered Oxlint rules and project checks
+before application. This includes
+foundation, documentation, original assets and an explicit configuration unit for
+project settings, registered guard code and compiler integration. Configuration
+patches validate the proposed policy; mandatory core gates remain enabled.
+Source checks do not establish visual correctness; normal lint/build gates
+remain required for edits made through other tools.
+See the [MCP editing contract](MCP.md#guarded-editing).
+
+Tooling updates must preserve project-owned source and token values. Content
+imports and adaptations are explicit operations; tool installation and upgrades
+load no UI catalogue. Empty scaffold files become project-owned when copied or
+generated.
+
+Application code imports its local public barrel, normally through `@ds`.
+The default layout keeps application code in `src/` and project ADS source in
+root `design-system/`. Configure existing alternate layouts explicitly.
+
+
+Framework choice belongs to the receiving project. Linaria is required for the
+component and pattern styling pipeline. Source checks support React and native Preact, including JSX, UI factories and
+DOM/CSS types. The empty scaffold uses React; the working example uses Preact. See [implementation support](GUIDE.md#implementation-support)
+for checked formats and gaps.
+
+## Showcase contract
+
+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. The browser host uses a separate-origin sandbox proxy; project runtimes,
+styles, fonts and UI execute/apply only in the App iframe. Components, patterns,
+token values, scenarios, fixtures and their Linaria styles remain project-owned.
+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.
+
+## Shared token contract
+
+Keep compatible token names, meanings, value types, and alias relationships;
+project values and theme overrides may differ. The
+[Data pillar](ARCHITECTURE.md#data-gives-implementations-a-common-language)
+explains the model.
+
+Consume token references instead of raw visual values. Color formulas, effects,
+durations, easing, typography, sizing, and layering values belong in the token
+source.
+
+Token names and ownership prefixes are fixed by ADS architecture, not project
+configuration. `--ds-*` belongs to components, `--ux-*` to patterns, and
+`--showcase-*` is reserved to showcase-local boundaries; it does not authorize
+custom styling in fixture files. The ADS frame pattern uses `--ux-*`. Foreign brand prefixes are rejected. Foundation
+CSS imports the approved token files in order; shared assignments belong in
+those token files, never in consumer styles or component state overrides.
+
+Store original branding and its usage, credits, and licenses in
+`assets/brand/`, and fonts in `assets/fonts/`. Configure generated icons and
+asset mounts as described in the [branding guide](GUIDE.md#branding).
+
+- Component, pattern, and style imports reuse destination values and add
+  missing shared definitions with initial values.
+- An explicit token-values import adopts all source-provided compatible values
+  and theme variants, preserving target-only definitions and variants.
+- Incompatible names, meanings, or types require a documented mapping or
+  contract migration. Do not create a second prefixed token vocabulary as the
+  normal import strategy.
+- New tool token definitions must preserve existing project values.
+  Importing a theme is a separate operation.
+
+Tool updates may add or migrate definitions, types, aliases, and validation.
+They must not silently replace a project's brand, typography, spacing, or
+motion values.
+
+## External source workflows
+
+External content workflows are agent skills; there is no CLI
+`ads import` command. Use the [skill guide](../skills/README.md) for installation,
+selection, import, assimilation, stress testing, and motion workflows.
+
+Record the source revision and integrate selected source, dependencies, public
+exports, assets, documentation, and applicable rules. Preserve destination token
+values unless a theme-value import is requested. Keep project-specific renderer,
+framework, and component guards during adoption; shared checks complement them.
+See [guard configuration](GUIDE.md#generic-architecture-guards).
+
+## Project integration
+
+Keep the framework, application configuration, and unrelated dependencies.
+Declare React or native Preact in `ds.config.json` through the first
+`ads init --framework react` or `ads init --framework preact` run. Existing saved
+choices are reused; init does not migrate the application's framework.
+Merge the needed scaffold or source into the destination rather than replacing
+its project configuration.
+
+Resolve `@ds` to the project's local public barrel in TypeScript and its app
+bundler. Export components and their public types through that barrel. Load the
+local foundation CSS once and integrate Linaria extraction with both the app
+and preview builds. Init does not install or configure Linaria; follow the
+[setup guide](GUIDE.md#linaria-integration). Follow the target's component, pattern, and style
+ownership rules. Export a new entity and its public types before migrating
+consumers; consumers import through the public barrel. Keep lint modules,
+fixtures, and generators out of that runtime API.
+
+Keep detailed usage, API, lifecycle, motion, token hooks, tests, and provenance
+in each item's local README. Record source repository/file links, revision,
+authors, concrete influences, and integration differences. Preserve applicable
+license notices for copied/adapted source and assets. The project guide records
+local implementation choices and links to the local item guides.
+
+## Build contract
+
+The installed tool is a project development dependency. `ds.config.json`
+describes source locations, public entry points, asset sources, and explicit
+boundaries. Initialized builds use the local CLI in this order:
+
+```text
+ads lint-config → ads check → Oxlint → ads assets → existing prebuild → existing build
+```
+
+`lint-config` regenerates ignored `.ds/oxlintrc.json` for the installed tool and
+registered project rules. `ads check` validates the architecture before asset
+generation; Oxlint runs the core and registered usage rules. `ads assets`
+generates configured browser icons from the source SVG into ignored `.ds/assets/`.
+A failed check or generation stops the build. Keep the project's CSS lint,
+type checks, behavior tests, and framework compilation in its build/test flow.
+`ads init` preserves existing lint tools and build commands.
+
+Application and project preview builds validate the same source and use the same
+foundation and component style processing. The built-in client is already bundled
+in the tool; the project compiler validates and publishes the shared scenario graph.
+Init also wires an existing `build:showcase` script; other preview build entry
+points need the same checks explicitly. Build output and generated configuration/assets remain
+separate from authored ADS source. Source assets and public asset mounts must
+have distinct output paths; collisions fail validation.
+
+## Lint ownership
+
+Core tooling owns reusable checks for token use, public imports, and style
+ownership. It must remain usable with an empty ADS and without any particular
+external component library.
+
+The checks enforce the architecture's ownership boundaries:
+
+| Boundary | Core enforcement |
+|----------|------------------|
+| Tokens and styles | Fixed token vocabulary, required definitions, declared value types and references, raw visual values, shared-token assignments, foundation import order, and component/pattern namespaces |
+| Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
+| Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
+| Renderer exceptions | Inline JSX styles and imperative style writes require narrow configured boundaries; public props omit inherited style and reject open-ended visual strings |
+| Preview ownership | Scenarios define no CSS, custom classes, or native controls; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
+| Assets | Source/public collisions and configured generated artifacts in source are rejected |
+
+Document a new ownership exception with its guard/configuration change and
+tests. Passing static checks establishes only the policies and source formats
+they cover. Browser review and behavior tests still verify accessibility,
+interaction, responsive layout, themes, and motion.
+
+Component-specific usage rules belong to that component in the receiving
+project. Import applicable rules with the item and register them through
+project configuration or maintained tooling integration. Core tooling must
+not hardcode imports from an external catalogue or assume Toast, Button, or a
+particular shell is installed.
+
+Register project plugins and rules in `ds.config.json` under `oxlint`. Use scoped
+`oxlint.overrides` for file-specific rule settings. These settings configure
+Oxlint; they do not disable the independent architecture checks in `ads check`.
+Renderer property boundaries and documented component hooks use `boundaries`,
+not broad rule suppression. See the [configuration guide](GUIDE.md#generic-architecture-guards).
+
+Add a rule only for a concrete misuse that static analysis can establish.
+Keep rule modules, generators, and test harnesses out of runtime exports.
+Validate accepted and rejected cases, configuration, and false-positive limits.
+
+## Bootstrap and updates
+
+Root [bootstrap-ds/](../bootstrap-ds/README.md) is the canonical empty scaffold.
+Its identical copy under `skills/ads-designer/assets/bootstrap-ds/` makes the
+skill self-contained. Run `npm run sync:skill-starter` after edits and
+`npm run check:skill-starter` to verify the copy. Both contain empty component
+and pattern directories, not a catalogue.
+
+Tool releases should version contract changes, rules, skills, bootstrap support,
+and migration guidance. Existing project implementations and external source
+revisions have their own update lifecycle. Apply external changes through
+explicit source imports or reviewed merges that preserve local customizations.
+
+Validate the relevant tooling and scaffold changes. For imported items, run the
+receiving project's lint, type checking, build, and meaningful behavior/rule
+tests, plus browser comparisons where interaction or animation warrants them.
+Do not require a particular component's tests in every project.
+
+## Current checkout
+
+The root package builds the ADS tool from `src/`; its tests and dummy project
+live under `tests/`. Runtime dependencies contain no React or UI library.
+Dependencies for the working example are development-only. The package allowlist contains only
+the CLI, core checks, MCP/Apps tooling and its browser client, skills, token contract, and empty scaffold. Packed-install tests
+verify it runs in a clean project without this repository's UI implementation.
+
+This repository's own design system lives in `design-system/` for proofs of
+concept, showcase review, and integration tests. Its UI source, project-specific
+scripts, and component registrations remain outside the published tool package.
+Run `npm run build:project` for that implementation into `dist-project/` and
+its shared preview graph into `.ds/preview/` and scenario descriptors into
+`.ds/scenarios/`; `npm run build`
+builds the tool into `dist/`. Core rule integration uses
+explicit project configuration, with no imports from the local component catalogue.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,311 @@
+# Architecture
+
+ADS makes shared design standards a tooling contract while keeping UI source in
+the project. Coding agents can build and evolve that source directly; the tools
+keep changes within a defined architecture. The project owns its components,
+patterns, token values, and branding.
+
+This document explains the what, why, and high-level how. [ADS.md](ADS.md) defines
+the enforceable contract, [GUIDE.md](GUIDE.md) covers tool integration, and the
+[working example guide](../design-system/README.md) covers implementation details.
+
+## Shared tooling, project-owned design
+
+The shared layer supplies architectural rules, token definitions, checks,
+skills, and setup. Components, patterns, themes, and examples are authored in
+the project or brought in through explicit imports and adaptations.
+
+This lets standards evolve without tying the product's UI to a centrally
+distributed component catalogue. A project can change its implementation,
+branding, or external dependencies while retaining compatible contracts.
+Tool updates preserve local values and customized source; content updates have
+their own reviewed lifecycle.
+
+ADS is opinionated about tooling and ownership. Linaria is required for the
+component and pattern styling pipeline. Visual choices belong to the project.
+The project declares React or native Preact in `ds.config.json` and uses the
+matching compiler and mount adapter. Both integrate with the required styling
+and validation pipeline; additional frameworks need explicit tooling support.
+
+ADS checks run during development and builds. The tool adds no production UI
+runtime. Its ownership boundaries preserve a project's optimization strategy:
+lazy loading, code splitting, memoized data, caching, worker execution, and
+cancellable work can remain behind public APIs. Sharing a screen pattern does
+not require eager loading of its renderer or moving application services into
+the ADS. Validate these properties when migrating an existing application.
+
+## Data, UX, and Skin
+
+Every UI implementation has three cooperating responsibilities:
+
+| Pillar | Defines | Implemented through | Result |
+|--------|---------|---------------------|--------|
+| **Data** | Design values, semantic roles, and their relationships | Shared token definitions with project-owned values and themes | A consistent visual vocabulary |
+| **UX** | Structure, behavior, accessibility, states, and layout | Markup, interaction logic, and structural styles in components and patterns | Operable controls and reusable compositions |
+| **Skin** | Visual identity and the appearance of each state or variant | Token-backed styles composed with the UX structure | The project's visual treatment |
+
+The separation makes each decision's purpose clear while keeping related code
+together. A button gets its dimensions and colors from Data, its native semantics
+and focus behavior from UX, and its fills, borders, and typography from Skin.
+A form group or application shell applies the same model to composition.
+
+### Data gives implementations a common language
+
+Data includes both primitive values and semantic roles. A color ramp describes
+available values; a surface or accent token describes their intended use.
+Typography, spacing, elevation, and motion follow the same principle.
+
+Projects share compatible token names, meanings, types, and relationships while
+choosing their own values. Stable names let implementations move between
+projects without importing an unrelated brand. Themes evolve by changing
+values behind those names, and visual formulas have one source of truth.
+
+### UX owns the interaction contract
+
+Components own control semantics, input handling, focus, accessibility, and
+state mechanics. Patterns own reusable layout and composition. Application
+containers provide domain data, routing, application effects, and callbacks through public
+APIs.
+
+The Data pillar describes design values; business data is a separate input to
+the UX contract. Application adapters own live business-data loading,
+authentication, stores, routing, caching and refresh policy. Components and
+patterns receive typed inputs and callbacks. They may invoke an injected
+callback or service to request work and present its loading/error state, while
+the consumer retains ownership of the data source. They do not bind themselves
+to a product backend or application provider.
+
+UI mechanics remain with their owner: lazy implementation imports, asset
+loading, measured geometry and cancellable layout workers are compatible with
+this boundary. Separating business-data access does not require moving renderer
+work into the application or sacrificing performance.
+
+A visual change should preserve the interaction contract unless behavior is
+deliberately changed. A disabled control remains disabled across skins; a field
+keeps its label association and error semantics. Keeping this policy with its
+owner prevents consumers from creating conflicting versions of the same UI.
+
+### Skin applies identity to that structure
+
+Skin maps the visual vocabulary to the structure and its states. Visual
+variants reuse the same UX implementation when their behavior is the same.
+
+Broad identity changes flow through token values. Changes to a particular
+control's treatment live with that control as a supported variant. Changes to
+layout or interaction also involve UX. Some decisions span all three pillars:
+motion uses Data for timing, UX for when transitions happen, and Skin for their
+visual expression.
+
+## Linaria is the implementation mechanism
+
+Linaria connects these responsibilities in the component and pattern styling
+pipeline. The native Preact working example in `design-system/` and the empty React starter
+in `bootstrap-ds/` implement that pipeline. Both are supported: the project
+chooses its rendering runtime, while ADS checks the same architecture and serves
+its actual compiled scenarios. A React application remains React; MCP does not
+substitute a different runtime or a visual reproduction.
+
+The choice serves both architecture and performance:
+
+| Reason | How it supports ADS |
+|--------|--------------------|
+| **Colocation and ownership** | Structural UX styles, Skin styles, and modifiers remain distinct local blocks beside their behavior. A change has one reviewable owner. |
+| **Explicit composition** | Atomic styles assemble a UX base, visual treatment, and size/state variants with precedence for matching declarations. Different visual variants can reuse the same UX implementation. |
+| **Less browser work** | Style templates become CSS at build time, avoiding render-time CSS generation, serialization, and stylesheet injection for those styles. |
+| **Independent CSS caching** | Extracted CSS can be delivered and cached separately from JavaScript. With stable content-hashed assets and suitable cache headers, unchanged CSS can be reused across code changes. |
+| **Bundle optimization** | Colocated style dependencies and static extraction let build tooling analyze usage and remove unreachable code and styles. The result depends on references, extraction, and side-effect configuration. |
+| **Declaration reuse** | Atomic extraction can deduplicate identical declarations across components and combinations, reducing repeated CSS. |
+| **Token-driven themes** | The browser applies theme values to already compiled rules. Changing token values does not need a runtime CSS generator. |
+| **Inspectable policy** | Source checks inspect Linaria templates alongside their owner for token use and ownership violations before bundling. |
+
+Linaria's [colocation and extraction model](https://github.com/callstack/linaria/blob/master/docs/BENEFITS.md)
+and [atomic composition model](https://github.com/callstack/linaria/blob/master/docs/ATOMIC_CSS.md)
+support this combination of local ownership and compiled styling.
+
+Airbnb's 2022 [migration report](https://medium.com/airbnb-engineering/airbnbs-trip-to-linaria-dc169230bd12)
+provides practical evidence for this choice: performance was its leading
+criterion, with separate CSS caching and colocated authoring among the benefits.
+Its measurements describe Airbnb's workloads, not promised gains for ADS projects.
+
+The requirement concerns how styling is authored and built; visual identity
+belongs to the project. Foundation tokens and base document styles remain CSS.
+“Zero runtime” describes CSS generation, not the whole component: rendering,
+interaction, class composition, and dynamic values can still require JavaScript.
+Colocation makes dependencies explicit; it does not by itself guarantee removal
+of every unused variant. Atomic composition still requires care with the cascade.
+
+Apply extraction to application and project preview builds, preserve intentional
+foundation CSS, and inspect compiled output when performance matters. The
+[implementation guide](../design-system/README.md#bundling-notes) covers these details.
+
+## Public APIs preserve the boundary
+
+The application and project-owned preview scenarios consume a project's public ADS entry. Components
+and patterns expose supported behavior and visual variants; internal styling
+blocks and external implementation dependencies stay with their owner.
+
+That boundary lets the project replace or adapt an implementation while
+preserving compatible consumer APIs. Markup, accessibility, events, layout, and
+motion still need verification when an implementation changes. Imported or
+adapted source carries its credits and applicable notices in its local guide.
+
+## The showcase is the shared design workspace
+
+Humans and coding agents inspect the same project through MCP. The showcase is
+**a minimal shell plus an MCP client and Apps host**, shipped as development
+tooling. Its header, section tabs, collapsible left menu, theme switch and preview
+area stay neutral. The client discovers entries, invokes tools, forwards App
+resource requests and subscribes to changes. It contains no project UI catalogue
+or implementation imports.
+
+The server supplies catalogues, discovered token scenarios, source guides, preview Apps,
+build status and diagnostics. Agents connect over stdio; the browser uses a
+loopback HTTP MCP endpoint in the same runtime. Both share one project-configured
+compiler. Starting MCP starts the website; a browser-only command starts the same
+runtime without stdio. Shutdown closes the website, connections and compiler.
+Local and external compatible hosts load the same reusable preview App. The
+browser host uses a separate-origin sandbox proxy around its opaque App iframe.
+Project JavaScript, styles, fonts and UI run only inside that App; the outer
+shell forwards resource bytes without applying project styles or executing its
+runtime. This keeps the host neutral while compositions retain their full skin.
+
+The project compiler publishes a versioned dependency graph: shared runtime and
+foundation assets, plus independently addressable scenario modules. Inside the
+App, a resource loader obtains the selected dependency closure through MCP,
+verifies its content and mounts it using the project's framework adapter. Native
+ES modules preserve shared runtime identity, cycles and live bindings. Switching
+scenarios unmounts the previous view while keeping unchanged dependencies cached.
+Persistence is a host lifecycle choice; a new external widget loads the same
+resources independently. Resource sharing is scoped to an App instance.
+
+```mermaid
+flowchart LR
+  Host[Minimal host: navigation and MCP client] --> Proxy[Separate-origin sandbox proxy]
+  Proxy --> App[Opaque App: loader and project preview]
+  App -->|resource reads via bridge| MCP[ADS MCP server]
+  MCP --> Graph[Compiled graph: runtime, CSS, fonts, scenarios]
+```
+
+The shell belongs to tooling. Components, patterns, design values, scenario inputs
+and the UI rendered inside Apps belong to the project. This keeps the tool useful
+with an empty ADS while making every implementation addressable once its scenario
+exists.
+
+### A preview scenario is the unit of review
+
+A component export alone may need inputs, parent context, local state or callbacks
+to produce useful UI. A scenario supplies that development context around the
+real public implementation. It mounts independently, without opening a showcase
+page or initializing the application's router, store or services first.
+
+Scenarios and their fixtures live beside the tokens, component or pattern they exercise.
+Token scenarios choose real token names and sample inputs; a project-owned
+review pattern applies the foundation variables. The tool contains no project
+token list, sample templates or assumed visual identity. A minimal foundation
+scenario can inspect values before a project has any components.
+Larger scenarios live under `composition/`. They use the same public screen
+patterns as production: application adapters supply live data and effects;
+scenario adapters supply fixture data, local state and simulated services.
+Reassembling a second screen from shared primitives still allows design drift.
+
+The server discovers one path-derived scenario registry. The showcase's four
+sections—Tokens, Components, Patterns and Composition—browse that same registry
+through MCP results. They do not initialize the entry or define
+its UI. The host supplies theme and available space; the public implementation
+supplies presentation. Several related public parts may share a scenario with
+their required parent. Every declared token and every public renderable component
+and pattern needs addressable coverage. Token references must exist in the real
+foundation; claimed token/UI coverage must be reachable from the scenario entry.
+Types, constants and utilities do not require UI scenarios.
+
+After source changes, validation and compilation must both succeed before a new
+graph becomes current. MCP announces build/resource updates. The built-in client
+refreshes discovery and sends the current selection to the existing App, whose
+loader mounts the new module graph. Failed builds retain the previous view with
+visible stale diagnostics. Compilation remains necessary for TSX and Linaria;
+there is one preview pipeline with automatic updates.
+
+Scenario entries, adapters and fixtures are development source even when
+colocated with production components. Runtime imports and public-barrel exports
+cannot cross that boundary. Static checks require real public render references
+reachable from the scenario entry; browser tests still verify mounting, states,
+accessibility and visual parity.
+
+The working example and starter build one shared multi-entry graph on first
+preview demand, then reuse it across selections and unchanged restarts. Only the
+selected scenario's static dependency closure loads in the App; dynamic imports
+remain lazy. Production bundles, workers and cancellation stay project-owned.
+The MCP server serves compiled bytes without evaluating project TSX. Compiler
+adapters normalize each entry to mount/unmount, retaining native React or Preact
+semantics; choosing a framework does not install one into the tooling host.
+
+## Build checks keep the architecture in place
+
+The project build runs ADS checks before producing application or showcase
+output. These checks enforce token use, source ownership, public imports,
+showcase coverage, component state boundaries, and separation of runtime code from development
+fixtures. Component-specific usage rules extend the shared checks when needed.
+
+Static checks establish the policies and source formats they cover. Behavior
+tests and browser review verify the resulting accessibility, layout, themes,
+states, and motion. Both forms of verification support agent-driven iteration.
+
+## MCP makes the project ADS available to agents
+
+The stdio server exposes the same token inspection and core architecture checks
+as the CLI, alongside the project's public UI catalogue and source guides.
+Bounded tools establish what exists; explicit resource reads provide detail.
+Prompts and packaged skills explain how to reason through Data, UX and Skin and
+how to inspect the real implementation before changing it.
+
+Opt-in MCP editing makes validation part of the write operation. The agent sends
+a Git unified diff for one logical ADS unit: its implementation and owned preview
+context, or the shared token foundation. ADS resolves file ownership, reconstructs
+candidate files locally and validates a temporary project copy with architecture
+checks, registered lint rules and project validation scripts. This keeps edits
+focused without requiring entire file bodies in model context. Peer units and
+unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
+branding and guides have their own units. Project configuration, registered guards
+and compiler integration form an explicit configuration unit; their proposed
+settings pass the same mandatory validation. Binary assets can travel as Git patch
+artifacts without entering model context, and compiler configuration changes
+replace the managed process while retaining the MCP connection. Normal build gates
+remain in place for source changes made through other editors; preview review remains
+necessary after either editing path.
+
+The architecture makes that inspection practical. A public export has an owning
+source and addressable preview coverage. Token definitions expose its visual
+vocabulary; local guides explain contracts when present. An agent can discover a
+small set of relevant entities, read their source and mount a real scenario with
+its fixture context. Humans can exercise the same entry in the showcase. This
+keeps inspection connected to the implementation that will reach the application.
+
+MCP provides a progressive interface to those sources: structured listings,
+explicit detail reads, selectable workflows and rendered Apps where supported.
+Reported revisions and diagnostics make preview freshness inspectable after a
+change. Reading source, compiling it and interacting with it are separate forms
+of evidence; source checks and metadata cannot establish visual or behavioral
+correctness. Text/resource access and the normal showcase keep the workflow
+usable when a client lacks experimental presentation capabilities.
+
+Experimental MCP Apps are another development review surface. Token, component,
+pattern and composition views are project-built scenarios with the project's
+own extracted CSS and public implementations. A generic tool-owned definition
+inspector remains available for token source/alias diagnostics, even if project
+previews cannot compile; it does not substitute for token scenario coverage.
+The server serves those artifacts; it does not interpret arbitrary component
+code or introduce production UI dependencies. File-change notifications let
+hosts refresh their views. An optional project-configured compiler watcher is
+managed by MCP, giving clients one launch command while leaving preview builds
+owned by the project. Structured build reports distinguish running compilers
+from successful, current previews; diagnostics remain readable even when a host
+does not forward notifications. Older clients retain tools/resources/prompts;
+native skill discovery and Apps presentation depend on the host's capabilities.
+Concrete setup and compatibility evidence belong in the [MCP guide](MCP.md).
+
+For concrete instructions, use:
+
+- [ADS tooling contract](ADS.md) for naming, ownership rules, updates, and lint responsibilities.
+- [Tool guide](GUIDE.md) for prerequisites, supported formats, configuration, and build wiring.
+- [Working example guide](../design-system/README.md) for Linaria composition, extraction, and project commands.
+- Component-local READMEs for APIs, lifecycle, tests, and provenance.