@reqvire-org/ads 0.3.0 → 0.3.2

package/README.md

@@ -272,7 +272,7 @@ The [dummy project](tests/fixtures/guard-project/README.md) tests the generic gu
 There are two different starting points in this checkout:
 
 - [bootstrap-ds/](bootstrap-ds/README.md) is an empty React application starter:
-  token defaults, build setup, empty component/pattern folders, and a project preview compiler adapter. It is bundled with `ads-designer` so an agent can copy it when starting
+  token defaults, build setup, empty product component folders, a project-owned token review pattern, and a project preview compiler adapter. It is bundled with `ads-designer` so an agent can copy it when starting
   from zero. `ads init` uses its empty foundation files when a project has no ADS.
 - [design-system/](design-system/README.md) is this repository's working example,
   with real components, patterns, and scenarios inspected through the built-in showcase. It demonstrates the architecture

package/dist/bootstrap-ds/ADS.md

@@ -40,6 +40,35 @@ 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.
+
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+layout, component-specific focus rules and hover/disabled skins are rejected.
+Shared token definitions belong in value sheets, not `base.css`. No project token
+names are embedded in this policy. A zero-specificity `:where()` wrapper does not
+change ownership. Put component design and animation in Linaria owners, and
+scenario layout variations in typed public review-pattern props. Browser review
+still checks the effects and accessibility of permitted defaults.
+
 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`.
@@ -114,13 +143,24 @@ design-system/
 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.
+Token entries under the configured token directory declare
+`export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
+`TokenSamples` is any project-owned public review pattern, not a required name.
+Its colocated fixture declares literal `samples: [{ token, property, probe }]`.
+Each token must exist and have sample coverage; duplicate bindings, missing probes,
+empty covers and value-only inspectors fail. The default entry passes the declared
+samples to a rendered public pattern's `samples` prop. No token-name/property mapping
+or sample values are embedded in the tool. Display values come from foundation CSS;
+probes are isolated verification inputs owned by the fixture.
+
+The renderer marks the actual styled element with `data-ads-token` and
+`data-ads-property`. In a browser, the App validates the declared property/value and
+probe using `CSS.supports`, checks the sample is rendered, then temporarily changes
+that token to its fixture probe. Its computed sample property must respond. Values
+are restored before yielding to painting; hardcoded lookalikes fail. Source gates
+prove the contract structure, not successful rendering. The browser check covers
+the mounted scenario and theme; visual quality and other states still need review.
+
 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

package/dist/bootstrap-ds/README.md

@@ -1,8 +1,8 @@
 # Empty native design system
 
-This private React/TypeScript workspace contains semantic CSS tokens, an empty
-public barrel, Linaria extraction and a project preview compiler adapter. It has
-no components, patterns, icons, fonts or example screens. The minimal showcase
+This private React/TypeScript workspace contains semantic CSS tokens, a project-owned
+token review pattern, a public barrel, Linaria extraction and a preview compiler
+adapter. It has no product components, icons, fonts or example screens. The minimal showcase
 shell and MCP client come from ADS tooling.
 
 Read the local [contract](ADS.md) and the
@@ -13,7 +13,7 @@ Read the local [contract](ADS.md) and the
 Copy the contents of `bootstrap-ds/`, including dotfiles, into a new project.
 The installed `ads-designer` skill contains the same files in
 `assets/bootstrap-ds/`. Set the project name in `package.json`. Use Node 22.12 or
-newer and ADS 0.3 or later for the shared-resource preview compiler.
+newer and ADS 0.3.1 or later for the shared-resource preview compiler.
 
 ```sh
 npx @reqvire-org/ads init --framework react
@@ -25,7 +25,7 @@ npm run dev:showcase
 For unreleased tooling, run init using the real local package:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.0.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
 npm run build
@@ -44,7 +44,7 @@ native Preact app without a saved ADS framework, use `ads init --framework preac
 Init records that choice and generates native hook imports without migrating the
 app or rewriting its compiler. Subsequent init runs reuse the saved choice.
 Init adds missing foundation files and connects architectural checks; it does
-not configure Linaria or generate component source. Generated `.ds/` files are
+not configure Linaria or generate product component source. Generated `.ds/` files are
 ignored; original artwork and provenance belong in `assets/brand/`.
 
 ## Inspect and add UI
@@ -56,10 +56,12 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture inspect all
-starter token values. Add/remove fixture names alongside token definitions;
-`ads check` rejects missing coverage and invented names. Styled token samples
-belong to your public review patterns and mount through the same scenario pipeline.
+The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+starter token values. The fixture owns `{ token, property, probe }` bindings;
+the public `TokenPreview` pattern owns their presentation and applies the real CSS
+variables. Add/remove samples alongside token definitions. `ads check` rejects
+missing coverage and invented names; the App verifies the declared CSS bindings
+in the browser. Extend or replace the project-owned pattern as your tokens evolve.
 
 Create a component under `design-system/components/`, export it through `@ds`,
 and colocate `Scenario.tsx` plus `fixture.ts` (or `<Owner>.scenario.tsx` and

package/dist/bootstrap-ds/design-system/index.ts

@@ -2,4 +2,4 @@
 import "./styles.css";
 
 // Add public component and pattern exports here as they are implemented.
-export {};
+export { TokenPreview } from "./patterns/token-preview/TokenPreview";

package/dist/bootstrap-ds/design-system/patterns/token-preview/Scenario.tsx

@@ -0,0 +1,4 @@
+import { TokenPreview } from "@ds";
+import { fixture } from "./fixture";
+export const scenario = { title: fixture.title, covers: ["TokenPreview"] };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/bootstrap-ds/design-system/patterns/token-preview/TokenPreview.tsx

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useRef } from "react";
+import { css, cx } from "@linaria/atomic";
+
+export interface TokenSample { token: `--${string}`; property: string; }
+export interface TokenPreviewProps { title: string; samples: readonly TokenSample[]; text: string; }
+const sampleStyle = css`
+  display: inline-block;
+  position: relative;
+  white-space: pre-line;
+  &[data-ads-property="animation-duration"] { animation-duration: var(--ux-token-preview-value); }
+  &[data-ads-property="animation-timing-function"] { animation-timing-function: var(--ux-token-preview-value); }
+  &[data-ads-property="background-color"] { background-color: var(--ux-token-preview-value); }
+  &[data-ads-property="border-radius"] { border-radius: var(--ux-token-preview-value); }
+  &[data-ads-property="box-shadow"] { box-shadow: var(--ux-token-preview-value); }
+  &[data-ads-property="color"] { color: var(--ux-token-preview-value); }
+  &[data-ads-property="font-family"] { font-family: var(--ux-token-preview-value); }
+  &[data-ads-property="font-size"] { font-size: var(--ux-token-preview-value); }
+  &[data-ads-property="font-weight"] { font-weight: var(--ux-token-preview-value); }
+  &[data-ads-property="line-height"] { line-height: var(--ux-token-preview-value); }
+  &[data-ads-property="width"] { width: var(--ux-token-preview-value); }
+  &[data-ads-property="z-index"] { z-index: var(--ux-token-preview-value); }
+`;
+function Sample({ sample, text }: { sample: TokenSample; text: string }) {
+  const ref = useRef<HTMLSpanElement>(null);
+  useLayoutEffect(() => { ref.current?.style.setProperty("--ux-token-preview-value", `var(${sample.token})`); }, [sample.token]);
+  return <span ref={ref} className={cx("ux-token-preview__sample", sampleStyle)} data-ads-token={sample.token} data-ads-property={sample.property}>{text}</span>;
+}
+/** Project-owned review UI. Values always come from the real foundation CSS. */
+export function TokenPreview({ title, samples, text }: TokenPreviewProps) {
+  return <section className="ux-token-preview"><h1>{title}</h1>{samples.map(sample => <div key={`${sample.token}:${sample.property}`} className="ux-token-preview__item"><code className="ux-token-preview__name">{sample.token}</code><Sample sample={sample} text={text}/></div>)}</section>;
+}

package/dist/bootstrap-ds/design-system/patterns/token-preview/fixture.ts

@@ -0,0 +1,8 @@
+export const fixture = {
+  "title": "Token preview",
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+  ]
+} as const;

package/dist/bootstrap-ds/design-system/tokens/Foundation.fixture.ts

@@ -1,47 +1,48 @@
 export const fixture = {
   "title": "Foundation",
-  "tokens": [
-    "--accent",
-    "--accent-fg",
-    "--accent-hover",
-    "--bg-canvas",
-    "--bg-hover",
-    "--bg-surface",
-    "--border-default",
-    "--border-focus",
-    "--border-w",
-    "--dur-fast",
-    "--dur-normal",
-    "--ease-standard",
-    "--focus-offset",
-    "--focus-w",
-    "--font-mono",
-    "--font-sans",
-    "--leading-normal",
-    "--leading-tight",
-    "--radius-lg",
-    "--radius-md",
-    "--radius-sm",
-    "--shadow-raised",
-    "--shadow-xs",
-    "--space-0",
-    "--space-12",
-    "--space-16",
-    "--space-2",
-    "--space-4",
-    "--space-6",
-    "--space-8",
-    "--text-base",
-    "--text-body",
-    "--text-inverse",
-    "--text-lg",
-    "--text-muted",
-    "--text-sm",
-    "--text-strong",
-    "--text-xl",
-    "--weight-medium",
-    "--weight-normal",
-    "--weight-semibold",
-    "--z-overlay"
+  "text": "Aa",
+  samples: [
+    {"token": "--accent", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-fg", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--accent-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-canvas", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-hover", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--bg-surface", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-default", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-focus", "property": "background-color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--border-w", "property": "width", "probe": "13.375px"},
+    {"token": "--dur-fast", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--dur-normal", "property": "animation-duration", "probe": "0.375s"},
+    {"token": "--ease-standard", "property": "animation-timing-function", "probe": "cubic-bezier(.13,.27,.61,.83)"},
+    {"token": "--focus-offset", "property": "width", "probe": "13.375px"},
+    {"token": "--focus-w", "property": "width", "probe": "13.375px"},
+    {"token": "--font-mono", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--font-sans", "property": "font-family", "probe": "monospace, serif"},
+    {"token": "--leading-normal", "property": "line-height", "probe": "2.375"},
+    {"token": "--leading-tight", "property": "line-height", "probe": "2.375"},
+    {"token": "--radius-lg", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-md", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--radius-sm", "property": "border-radius", "probe": "13.375px"},
+    {"token": "--shadow-raised", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--shadow-xs", "property": "box-shadow", "probe": "1px 3px 5px rgb(31, 97, 163)"},
+    {"token": "--space-0", "property": "width", "probe": "13.375px"},
+    {"token": "--space-12", "property": "width", "probe": "13.375px"},
+    {"token": "--space-16", "property": "width", "probe": "13.375px"},
+    {"token": "--space-2", "property": "width", "probe": "13.375px"},
+    {"token": "--space-4", "property": "width", "probe": "13.375px"},
+    {"token": "--space-6", "property": "width", "probe": "13.375px"},
+    {"token": "--space-8", "property": "width", "probe": "13.375px"},
+    {"token": "--text-base", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-body", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-inverse", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-lg", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-muted", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-sm", "property": "font-size", "probe": "41.375px"},
+    {"token": "--text-strong", "property": "color", "probe": "rgb(31, 97, 163)"},
+    {"token": "--text-xl", "property": "font-size", "probe": "41.375px"},
+    {"token": "--weight-medium", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-normal", "property": "font-weight", "probe": "327"},
+    {"token": "--weight-semibold", "property": "font-weight", "probe": "327"},
+    {"token": "--z-overlay", "property": "z-index", "probe": "367"},
   ]
 } as const;

package/dist/bootstrap-ds/design-system/tokens/Foundation.scenario.tsx

@@ -1,14 +1,4 @@
-import { useEffect, useState } from "react";
+import { TokenPreview } from "@ds";
 import { fixture } from "./Foundation.fixture";
-export const scenario = { title: fixture.title, covers: [], tokens: fixture.tokens };
-export default function Scenario() {
-  const [values, setValues] = useState<Record<string, string>>({});
-  useEffect(() => {
-    const read = () => { const style = getComputedStyle(document.documentElement); setValues(Object.fromEntries(fixture.tokens.map(name => [name, style.getPropertyValue(name).trim()]))); };
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(document.documentElement, {attributes: true, attributeFilter: ["data-theme"]});
-    return () => observer.disconnect();
-  }, []);
-  return <section><h1>{fixture.title}</h1><dl>{fixture.tokens.map(name => <div key={name}><dt><code>{name}</code></dt><dd>{values[name]}</dd></div>)}</dl></section>;
-}
+export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
+export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/bootstrap-ds/design-system/tokens/base.css

@@ -1,3 +1,6 @@
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+
 *,
 *::before,
 *::after {
@@ -5,7 +8,7 @@
 }
 
 body {
-  margin: var(--space-0);
+  margin: 0;
   background: var(--bg-canvas);
   color: var(--text-body);
   font-family: var(--font-sans);

package/dist/bootstrap-ds/design-system/tokens/colors.css

@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light;
+
   --bg-canvas: #faf9f6;
   --bg-surface: #fff;
   --bg-hover: #f1efea;
@@ -15,7 +15,7 @@
 }
 
 :root[data-theme="dark"] {
-  color-scheme: dark;
+
   --bg-canvas: #17191e;
   --bg-surface: #20232a;
   --bg-hover: #2c3039;

package/dist/bootstrap-ds/ds.config.json

@@ -9,5 +9,15 @@
         "--watch"
       ]
     }
+  },
+  "boundaries": {
+    "styleWrites": [
+      {
+        "file": "design-system/patterns/token-preview/TokenPreview.tsx",
+        "properties": [
+          "--ux-token-preview-value"
+        ]
+      }
+    ]
   }
 }

package/dist/check.mjs

@@ -5,7 +5,7 @@ import postcss from "postcss";
 import valueParser from "postcss-value-parser";
 import { importViolation, isInside, loadConfig, sourceFiles, isDevelopmentFile, isTestFile } from "./config.mjs";
 import { inspectTokens, references } from "./tokens.mjs";
-import { foundationFiles, isSharedToken } from "./token-policy.mjs";
+import { foundationFiles, foundationImportTarget, isSharedToken } from "./token-policy.mjs";
 import { inspectAssets } from "./assets.mjs";
 import { appImportViolation, showcaseImportViolation, checkComponentVariable, importResolver, projectCompilerOptions, isUiCssProperties, styleWriteViolation } from "./boundaries.mjs";
 import { inspectPublicProps } from "./public-props.mjs";
@@ -14,6 +14,7 @@ import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
 import { inspectScenarioCoverage } from "./scenarios.mjs";
 import { uiOperation, importedUiApi } from "./ui-framework.mjs";
+import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
 
 const showcaseControls = new Set(["a", "button", "input", "select", "textarea", "option", "optgroup", "table", "thead", "tbody", "tfoot", "tr", "td", "th", "dialog", "details", "summary", "progress", "meter"]);
 const svgTags = new Set(["svg", "g", "path", "circle", "rect", "ellipse", "line", "polyline", "polygon", "text", "tspan", "use", "defs", "clipPath", "mask", "filter", "linearGradient", "radialGradient", "stop", "marker", "pattern"]);
@@ -51,23 +52,17 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const css = postcss.parse(readFileSync(foundationEntry, "utf8"), { from: foundationEntry });
     const imports = css.nodes.filter((node) => node.type !== "comment");
     const expected = foundationFiles.filter((name) => name !== "fonts.css" || existsSync(path.join(dsRoot, config.tokenDir, name))).map((name) => path.join(dsRoot, config.tokenDir, name));
-    const actual = imports.map((node) => {
-      if (node.type !== "atrule" || node.name !== "import" || node.nodes) return null;
-      const parts = valueParser(node.params).nodes.filter((part) => part.type !== "space" && part.type !== "comment");
-      if (parts.length !== 1) return null;
-      const part = parts[0];
-      const value = part.type === "string" ? part.value : part.type === "function" && part.value === "url" && part.nodes.length === 1 ? part.nodes[0].value : null;
-      return value ? path.resolve(path.dirname(foundationEntry), value) : null;
-    });
+    const actual = imports.map(node => foundationImportTarget(node, foundationEntry));
     if (actual.length !== expected.length || actual.some((file, index) => file !== expected[index] || !existsSync(file))) report(foundationEntry, "styles-entry", "Foundation CSS must import only fonts (when present), colors, typography, spacing, elevation, and base, in that order.");
   } catch (error) { report(foundationEntry, "css-syntax", error.reason ?? error.message, error.line ?? 1); }
-  function checkCss(file, text, offset = { line: 1, column: 1 }) {
+  function checkCss(file, text, offset = { line: 1, column: 1 }, foundation = false) {
     let css;
     try { css = postcss.parse(text, { from: file }); }
     catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
-    if (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
+    if (!foundation && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
     if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", "Scenarios and fixtures define no styles. Put the frame/layout in a public ADS pattern and product UI in ADS components or patterns.", offset.line);
     css.walkAtRules("import", (rule) => {
+      if (foundation) report(file, "foundation-import", "Import foundation sheets through the configured styles entry. Token sheets cannot import an unchecked styling layer.", rule.source.start.line);
       const first = valueParser(rule.params).nodes.find((node) => node.type !== "space" && node.type !== "comment");
       const specifier = first?.type === "string" ? first.value : first?.type === "function" && first.value === "url" ? first.nodes[0]?.value : null;
       if (!specifier || /^(?:[a-z]+:|\/\/)/i.test(specifier)) return;
@@ -76,19 +71,40 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (showcaseImportViolation(specifier, file, options, resolveImport)) report(file, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.", line);
     });
     css.walkRules((rule) => {
+      if (foundation) {
+        if (rule.parent.type === "rule") report(file, "foundation-role", "Foundation rules cannot nest owner/context selectors. Use root theme conditions or Linaria owners.", rule.source.start.line);
+        const violation = foundationSelector(rule.selector, { definitions: rule.nodes.some(node => node.type === "decl" && node.prop.startsWith("--")) });
+        if (violation) report(file, "foundation-selector", violation, rule.source.start.line, rule.source.start.column);
+      }
       if (isInside(path.join(dsRoot, "showcase"), file) && /:(?:hover|active|focus(?:-visible|-within)?|checked|disabled|enabled)\b|\[(?:aria-(?:selected|pressed|checked|disabled|expanded)|data-state)\b/.test(rule.selector)) report(file, "showcase-state", "Interactive state styling belongs to the real ADS component or pattern, not showcase or mock styles.", offset.line + rule.source.start.line - 1);
       if (/\.ads-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "components"), file)) report(file, "style-ownership", "ADS component internals are owned by components, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
       if (/\.ux-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "patterns"), file)) report(file, "style-ownership", "Pattern internals are owned by patterns, not app or showcase CSS.", offset.line + rule.source.start.line - 1);
       if (/\.showcase-[\w-]+/.test(rule.selector) && !isInside(path.join(dsRoot, "showcase"), file)) report(file, "style-ownership", "Showcase internals are owned by showcase scaffolding.", offset.line + rule.source.start.line - 1);
     });
+    if (foundation) css.walkAtRules(rule => {
+      if (/(?:^|-)keyframes$|^(?:scope|custom-selector|starting-style)$/i.test(rule.name)) report(file, "foundation-role", "Animations and scoped UI styles belong in their component/pattern's Linaria source, not the token foundation.", rule.source.start.line);
+      if (rule.name === "font-face" && path.basename(file) !== "fonts.css") report(file, "foundation-role", "Font faces belong in the canonical fonts.css foundation sheet.", rule.source.start.line);
+    });
     css.walkDecls((decl) => {
+      if (foundation && decl.prop.startsWith("--")) {
+        if (path.basename(file) === "base.css") report(file, "foundation-role", "Shared token definitions belong in value sheets, not base.css.", decl.source.start.line, decl.source.start.column);
+        return; // Definition names, values and aliases are validated by inspectTokens.
+      }
+      const fontDescriptor = foundation && path.basename(file) === "fonts.css" && decl.parent.type === "atrule" && decl.parent.name === "font-face";
+      if (foundation && !fontDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
+      if (foundation && path.basename(file) === "base.css" && decl.parent.type === "rule") {
+        const violation = foundationDeclaration(decl.parent, decl);
+        if (violation) report(file, "foundation-role", violation, decl.source.start.line, decl.source.start.column);
+      }
       const variable = checkComponentVariable(decl.prop, file, options);
       if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
       for (const ref of references(decl.value)) {
         const local = /^(?:--ds-|--ux-|--showcase-)/.test(ref.name);
+        if (foundation && local) report(file, "foundation-role", "Foundation defaults consume shared tokens, not component, pattern or scenario-local variables.", offset.line + decl.source.start.line - 1, decl.source.start.column);
         if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
         else if (!local && !declaredTokens.has(ref.name) && !ref.fallback) report(file, "token-reference", `Undefined shared token ${ref.name}.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
       }
+      if (fontDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
@@ -98,12 +114,12 @@ export function checkProject(directory, { trackingRoot } = {}) {
         if (node.type === "word" && /^ease(?:-in|-out|-in-out)?$/.test(node.value)) violations.add("Use a motion token for easing.");
         if (node.type === "word" && /^(?:color|background-color|(?:border|outline|caret|text-decoration|column-rule)(?:-[a-z]+)?-color|fill|stroke)$/.test(decl.prop) && /^[a-z]+$/i.test(node.value) && !/^(?:inherit|initial|unset|revert|currentcolor|transparent|none)$/i.test(node.value)) violations.add("Use a semantic color token.");
       });
-      if (/^(?:font-family|font-weight|z-index)$/.test(decl.prop) && !/^(?:var\(|inherit$|auto$)/.test(decl.value)) violations.add("Use a semantic typography or layering token.");
+      if (/^(?:font-family|font-weight|z-index)$/.test(decl.prop) && !/^(?:var\(|inherit$|initial$|unset$|revert(?:-layer)?$|auto$)/.test(decl.value) && !(foundation && decl.prop === "font-weight" && /^(?:bolder|lighter)$/.test(decl.value))) violations.add("Use a semantic typography or layering token.");
       for (const message of violations) report(file, "style-token", message, offset.line + decl.source.start.line - 1, decl.source.start.column);
     });
   }
   for (const file of files) {
-    if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) continue;
+    if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
     if (file.endsWith(".css")) {
       const text = readFileSync(file, "utf8");