@reqvire-org/ads 0.3.1 → 0.3.3

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`.

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/boundaries.mjs

@@ -90,31 +90,29 @@ function isWrite(node) {
     || ts.isDeleteExpression(parent);
 }
 
-// Inspects style access itself, so aliases, computed keys, cssText and bulk writes
-// cannot silently turn a narrow property exception into a whole-file exception.
+/** Exact writes and known reads share one interpretation with exception audits.
+ * undefined = unrelated, false = read, null = unknown/bulk, string = exact write. */
+export function styleAccessProperty(node) {
+  if (!isMember(node) || memberName(node) !== "style") return undefined;
+  const access = unwrapped(node), parent = access.parent;
+  if (!isMember(parent) || parent.expression !== access) return null;
+  const property = cssName(memberName(parent)), target = unwrapped(parent);
+  if (ts.isCallExpression(target.parent) && target.parent.expression === target) {
+    if (["set-property", "remove-property"].includes(property)) {
+      const name = target.parent.arguments[0];
+      return name && ts.isStringLiteralLike(name) ? name.text : null;
+    }
+    return ["get-property-value", "get-property-priority", "item"].includes(property) ? false : null;
+  }
+  if (isWrite(target)) return property ?? null;
+  return property && !["set-property", "remove-property"].includes(property) ? false : null;
+}
+
+// Aliases, computed keys, cssText and bulk writes cannot widen an exception.
 export function styleWriteViolation(node, filename, { root, config }) {
   const allowed = config.boundaries.styleWrites.find((boundary) => path.resolve(root, boundary.file) === filename)?.properties ?? [];
-  if (isMember(node) && memberName(node) === "style") {
-    const access = unwrapped(node);
-    const parent = access.parent;
-    let property;
-    if (isMember(parent) && parent.expression === access) {
-      property = cssName(memberName(parent));
-      const target = unwrapped(parent);
-      if (ts.isCallExpression(target.parent) && target.parent.expression === target) {
-        if (["set-property", "remove-property"].includes(property)) {
-          const name = target.parent.arguments[0];
-          property = name && ts.isStringLiteralLike(name) ? name.text : null;
-        } else if (["get-property-value", "get-property-priority", "item"].includes(property)) return null;
-        else property = null;
-      } else if (!isWrite(target)) {
-        // Plain property reads are allowed. Passing a method reference or a
-        // computed member elsewhere is not a known property read.
-        if (property && !["set-property", "remove-property"].includes(property)) return null;
-        property = null;
-      }
-    }
-    if (property && property !== "css-text" && allowed.includes(property)) return null;
+  const property = styleAccessProperty(node);
+  if (property !== undefined && property !== false && !(property && property !== "css-text" && allowed.includes(property))) {
     return "Imperative styles require a file boundary and an explicit property. Bulk writes, computed property names, and style-object escapes are forbidden.";
   }
   if (ts.isCallExpression(node) && isMember(node.expression) && ["setAttribute", "setAttributeNS"].includes(memberName(node.expression))) {

package/dist/check.mjs

@@ -14,6 +14,11 @@ import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
 import { inspectScenarioCoverage } from "./scenarios.mjs";
 import { uiOperation, importedUiApi } from "./ui-framework.mjs";
+import { inspectStyleBoundaries, pointerCaptureAdvisories } from "./style-boundaries.mjs";
+import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
+
+const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
+const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
 
 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"]);
@@ -23,7 +28,7 @@ const widgetRoles = new Set(["button", "link", "checkbox", "radio", "switch", "c
 export function checkProject(directory, { trackingRoot } = {}) {
   const options = { ...loadConfig(directory), ...(trackingRoot ? { trackingRoot: path.resolve(trackingRoot) } : {}) };
   const { root, config, dsRoot, sourceRoot } = options;
-  const diagnostics = [];
+  const diagnostics = [], advisories = [];
   for (const [field, file] of [["dsDir", dsRoot], ["publicEntry", path.join(dsRoot, config.publicEntry)], ["stylesEntry", path.join(dsRoot, config.stylesEntry)]]) {
     if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
   }
@@ -35,13 +40,15 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const resolveImport = importResolver(options);
   const rootHtml = path.join(root, "index.html");
   const files = [...new Set([...sourceFiles(sourceRoot), ...sourceFiles(dsRoot), ...(existsSync(rootHtml) ? [rootHtml] : [])])];
-  const scriptFiles = files.filter((file) => /\.[cm]?[jt]sx?$/.test(file));
+  const boundaryFiles = [...config.inlineStyleFiles, ...config.boundaries.styleWrites.map(entry => entry.file)].map(file => path.resolve(root, file)).filter(file => existsSync(file) && statSync(file).isFile());
+  const scriptFiles = [...new Set([...files, ...boundaryFiles])].filter((file) => /\.[cm]?[jt]sx?$/.test(file));
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
+  inspectStyleBoundaries(options, program, report);
   inspectShowcasePages(options, program, resolveImport, report);
   inspectShowcaseCoverage(options, program, report);
   inspectScenarioCoverage(options, program, report);
@@ -54,13 +61,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
     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 (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);
+    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. ${scenarioLayoutGuidance}`, 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;
@@ -69,19 +77,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;
@@ -91,12 +120,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");
@@ -105,6 +134,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     const source = program.getSourceFile(file);
     if (!source) continue;
+    advisories.push(...pointerCaptureAdvisories(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
     for (const diagnostic of program.getSyntacticDiagnostics(source)) {
       const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
@@ -163,14 +193,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
         for (const property of properties) {
           if (!ts.isPropertyAssignment(property) || !(ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name))) continue;
           if (tag && ts.isStringLiteralLike(tag) && svgTags.has(tag.text) && importedUiApi(node.expression, checker)?.module === "preact") checkSvgAttribute(property, property.name.text);
-          if (property.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(property, "no-inline-style", "UI factories follow the same style ownership as JSX. Use semantic ADS props or a narrow renderer boundary.");
+          if (property.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(property, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
           if (property.name.text === "style") inspectProperty(property.initializer);
           if (property.name.text === "className") inspectClass(property.initializer);
-          if (showcase && property.name.text === "className") nodeReport(property, "showcase-class", "Scenarios use public ADS props, not custom class names.");
+          if (showcase && property.name.text === "className") nodeReport(property, "showcase-class", `Scenarios define no custom class names. ${scenarioLayoutGuidance}`);
         }
         if (showcase && tag && ts.isStringLiteralLike(tag)) {
           const role = properties.find(property => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === "role")?.initializer;
-          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) nodeReport(node, "showcase-control", "Scenario controls must render public ADS components.");
+          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) nodeReport(node, "showcase-control", `Scenario controls must render public ADS components for actual interaction. ${scenarioLayoutGuidance}`);
         }
       }
       if (isInside(dsRoot, file) && (ts.isIdentifier(node) && ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"].includes(node.text) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node))) {
@@ -181,9 +211,9 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (showcase && (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
         const role = node.attributes.properties.find((attr) => ts.isJsxAttribute(attr) && attr.name.text === "role")?.initializer;
         const roleValue = role && ts.isStringLiteralLike(role) ? role.text : role && ts.isJsxExpression(role) && role.expression && ts.isStringLiteralLike(role.expression) ? role.expression.text : null;
-        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) nodeReport(node, "showcase-control", "Showcase and mock controls must use public ADS components. Implement missing reusable controls in the ADS, then import them here.");
+        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) nodeReport(node, "showcase-control", `Scenario controls must render public ADS components for actual interaction. ${scenarioLayoutGuidance}`);
       }
-      if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") nodeReport(node, "showcase-class", "Showcase and mocks use known public ADS entities and props, not custom class names. Put styling in the owning ADS component or frame pattern.");
+      if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") nodeReport(node, "showcase-class", `Scenarios define no custom class names. ${scenarioLayoutGuidance}`);
       let specifier;
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifier = node.arguments[0].text;
@@ -191,13 +221,13 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");
-      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", "Move visual policy into the local ADS, or document a narrow measured-geometry exception in inlineStyleFiles.");
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && node.initializer) {
         inspectProperty(node.initializer);
       }
       const mutation = styleWriteViolation(node, file, options);
       if (mutation) nodeReport(node, "style-mutation", mutation);
-      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Do not expose CSSProperties-based visual plumbing. Use semantic props, or document a narrow JSX renderer boundary.");
+      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a public review pattern.");
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
         inspectClass(node.initializer);
       }
@@ -211,5 +241,5 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     visit(source);
   }
-  return { ok: diagnostics.length === 0, diagnostics };
+  return { ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) };
 }

package/dist/cli.mjs

@@ -96,6 +96,7 @@ async function main(args) {
   if (!json && result.diagnostics?.length) {
     for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
   }
+  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [advisory:${advisory.rule}] ${advisory.message}`);
   if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
 }
 

package/dist/contracts/foundation.json

@@ -0,0 +1,211 @@
+{
+  "document": [
+    "color",
+    "background",
+    "background-color",
+    "font",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "font-style",
+    "font-stretch",
+    "line-height",
+    "letter-spacing",
+    "word-spacing",
+    "text-rendering",
+    "font-synthesis",
+    "font-kerning",
+    "font-feature-settings",
+    "font-variation-settings",
+    "font-optical-sizing",
+    "-webkit-font-smoothing",
+    "-moz-osx-font-smoothing",
+    "-webkit-text-size-adjust",
+    "text-size-adjust",
+    "color-scheme",
+    "scrollbar-color",
+    "scrollbar-width"
+  ],
+  "reset": {
+    "box-sizing": [
+      "border-box",
+      "content-box"
+    ],
+    "font": [
+      "inherit"
+    ],
+    "font-family": [
+      "inherit"
+    ],
+    "font-size": [
+      "inherit",
+      "100%"
+    ],
+    "font-weight": [
+      "inherit",
+      "bolder",
+      "lighter"
+    ],
+    "font-style": [
+      "inherit",
+      "normal"
+    ],
+    "line-height": [
+      "inherit",
+      "normal"
+    ],
+    "letter-spacing": [
+      "inherit",
+      "normal"
+    ],
+    "word-spacing": [
+      "inherit",
+      "normal"
+    ],
+    "text-align": [
+      "inherit",
+      "start"
+    ],
+    "text-transform": [
+      "inherit",
+      "none"
+    ],
+    "text-decoration": [
+      "inherit",
+      "none"
+    ],
+    "text-indent": [
+      "0"
+    ],
+    "color": [
+      "inherit",
+      "currentcolor"
+    ],
+    "background": [
+      "transparent",
+      "none"
+    ],
+    "background-color": [
+      "transparent"
+    ],
+    "border": [
+      "0",
+      "none"
+    ],
+    "border-width": [
+      "0"
+    ],
+    "border-style": [
+      "none"
+    ],
+    "border-color": [
+      "inherit",
+      "currentcolor",
+      "transparent"
+    ],
+    "border-radius": [
+      "0"
+    ],
+    "border-collapse": [
+      "collapse",
+      "separate"
+    ],
+    "border-spacing": [
+      "0"
+    ],
+    "list-style": [
+      "none"
+    ],
+    "list-style-type": [
+      "none"
+    ],
+    "list-style-image": [
+      "none"
+    ],
+    "vertical-align": [
+      "baseline",
+      "middle"
+    ],
+    "box-shadow": [
+      "none"
+    ],
+    "text-shadow": [
+      "none"
+    ],
+    "appearance": [
+      "none",
+      "auto"
+    ],
+    "-webkit-appearance": [
+      "none",
+      "auto"
+    ],
+    "overflow": [
+      "visible"
+    ],
+    "cursor": [
+      "inherit",
+      "default"
+    ],
+    "-webkit-tap-highlight-color": [
+      "transparent"
+    ]
+  },
+  "replacedElements": [
+    "img",
+    "svg",
+    "video",
+    "canvas",
+    "audio",
+    "iframe",
+    "embed",
+    "object"
+  ],
+  "replacedReset": {
+    "display": [
+      "block",
+      "inline-block"
+    ],
+    "max-width": [
+      "100%"
+    ],
+    "width": [
+      "auto"
+    ],
+    "height": [
+      "auto"
+    ]
+  },
+  "focus": [
+    "outline",
+    "outline-width",
+    "outline-style",
+    "outline-color",
+    "outline-offset"
+  ],
+  "reducedMotion": [
+    "animation-duration",
+    "animation-delay",
+    "animation-iteration-count",
+    "transition-duration",
+    "transition-delay",
+    "scroll-behavior"
+  ],
+  "selection": [
+    "color",
+    "background",
+    "background-color"
+  ],
+  "scrollbar": [
+    "width",
+    "height",
+    "background",
+    "background-color",
+    "background-clip",
+    "border",
+    "border-width",
+    "border-style",
+    "border-color",
+    "border-radius"
+  ]
+}

package/dist/foundation.mjs

@@ -0,0 +1,114 @@
+import selectorParser from "postcss-selector-parser";
+import { readFileSync } from "node:fs";
+
+// CSS-language policy, not a project token catalogue or renderer classification.
+const policy = JSON.parse(readFileSync(new URL("./contracts/foundation.json", import.meta.url), "utf8"));
+const cssWide = /^(?:inherit|initial|unset|revert|revert-layer)$/i;
+
+function rootAnchor(nodes) {
+  return nodes.some(node => node.type === "tag" && !node.namespace && node.value.toLowerCase() === "html"
+    || node.type === "pseudo" && node.value.toLowerCase() === ":root"
+    || node.type === "pseudo" && /^:(?:is|where)$/i.test(node.value) && node.nodes.length && node.nodes.every(selector => !selector.nodes.some(node => node.type === "combinator") && rootAnchor(selector.nodes)));
+}
+
+function rootCompound(node) {
+  for (let current = node; current.parent; current = current.parent) {
+    const parent = current.parent;
+    if (parent.type !== "selector") continue;
+    const index = parent.nodes.indexOf(current);
+    let start = index, end = index + 1;
+    while (start && parent.nodes[start - 1].type !== "combinator") --start;
+    while (end < parent.nodes.length && parent.nodes[end].type !== "combinator") ++end;
+    // A negative/relational argument cannot establish root context, but an
+    // explicit root outside it still can: :root:not([data-theme=light]).
+    const argument = parent.parent?.type === "pseudo" && !/^:(?:is|where)$/i.test(parent.parent.value);
+    if (!argument && rootAnchor(parent.nodes.slice(start, end))) return true;
+  }
+  return false;
+}
+
+/** Global defaults may address native elements and explicit document themes, not UI owners. */
+export function foundationSelector(selector, { definitions = false } = {}) {
+  try {
+    let violation = false;
+    selectorParser(root => {
+      if (definitions && root.nodes.some(selector => selector.nodes.some(node => node.type === "combinator") || !rootAnchor(selector.nodes))) violation = true;
+      root.walk(node => {
+        if (["class", "id"].includes(node.type) && !rootCompound(node)) violation = true;
+        if (node.type === "tag" && node.value.includes("-")) violation = true;
+        if (node.type === "attribute" && /^(?:class|id|style|data-.+|aria-.+)$/i.test(node.attribute) && !rootCompound(node)) violation = true;
+        if (node.type === "pseudo" && node.value.toLowerCase() === ":has") violation = true;
+        if (node.type === "combinator") {
+          const before = node.parent.nodes.slice(0, node.parent.nodes.indexOf(node));
+          if (before.some(node => node.type === "combinator") || !rootAnchor(before)) violation = true;
+        }
+      });
+    }).processSync(selector);
+    return violation ? "Foundation defaults address native elements or explicit document-root themes. Component/pattern hooks, contextual layout and relational state selectors belong to their Linaria owner." : null;
+  } catch (error) { return `Invalid foundation selector: ${error.message}`; }
+}
+
+function subjects(nodes) {
+  let variants = [[]];
+  for (const node of nodes) {
+    if (node.type === "pseudo" && /^:(?:where|is)$/i.test(node.value)) {
+      variants = variants.flatMap(prefix => node.nodes.flatMap(selector => subjects(selector.nodes).map(subject => [...prefix, ...subject])));
+    } else variants.forEach(subject => subject.push(node));
+  }
+  return variants;
+}
+
+function reducedMotion(rule) {
+  for (let parent = rule.parent; parent; parent = parent.parent) {
+    if (parent.type === "atrule" && parent.name.toLowerCase() === "media"
+      && /^\(\s*prefers-reduced-motion\s*:\s*reduce\s*\)$/i.test(parent.params.trim())) return true;
+  }
+  return false;
+}
+
+function reset(property, value, nodes) {
+  const words = value.toLowerCase().split(/\s+/);
+  if (/^(?:margin|padding)(?:-(?:top|right|bottom|left|block|inline)(?:-(?:start|end))?)?$/.test(property)) return words.every(word => word === "0") || cssWide.test(value);
+  const tag = nodes.find(node => node.type === "tag")?.value.toLowerCase();
+  if (property === "font-weight" && /^(?:bolder|lighter)$/.test(value)) return ["b", "strong"].includes(tag);
+  if (policy.reset[property]) return policy.reset[property].includes(value.toLowerCase()) || cssWide.test(value);
+  if (policy.replacedElements.includes(tag) && policy.replacedReset[property]) return policy.replacedReset[property].includes(value.toLowerCase()) || cssWide.test(value);
+  return tag === "textarea" && property === "resize" && /^(?:vertical|inherit|initial|unset|revert(?:-layer)?)$/.test(value);
+}
+
+function roleAllows(rule, nodes, property, value) {
+  const pseudos = nodes.filter(node => node.type === "pseudo");
+  const tag = nodes.find(node => node.type === "tag")?.value.toLowerCase();
+  const universal = nodes.every(node => node.type === "universal" || node.type === "pseudo" || node.type === "comment");
+  if (universal && pseudos.some(node => node.value === ":focus-visible") && pseudos.every(node => node.value === ":focus-visible")) return policy.focus.includes(property) && !/^(?:none|0)$/.test(value);
+  if (universal && pseudos.some(node => node.value === "::selection") && pseudos.every(node => node.value === "::selection")) return policy.selection.includes(property);
+  if (universal && pseudos.every(node => ["::before", "::after"].includes(node.value)) && reducedMotion(rule)) {
+    if (policy.reducedMotion.includes(property)) return property !== "scroll-behavior" || value === "auto";
+    if (["animation", "transition"].includes(property) && value === "none") return true;
+  }
+  const document = (rootAnchor(nodes) || tag === "body") && pseudos.every(node => [":root", ":not"].includes(node.value));
+  if (document && policy.document.includes(property)) return true;
+  const documentScrollbar = (rootAnchor(nodes) || tag === "body") && pseudos.some(node => /^::-webkit-scrollbar(?:-thumb|-track)?$/.test(node.value))
+    && pseudos.every(node => node.value === ":root" || /^::-webkit-scrollbar(?:-thumb|-track)?$/.test(node.value) || node.value === ":hover");
+  if (documentScrollbar) return policy.scrollbar.includes(property);
+  if (pseudos.some(node => node.value === "::placeholder") && pseudos.every(node => node.value === "::placeholder")) return property === "color" || property === "opacity" && value === "1";
+  if (pseudos.some(node => ![":root", ":not", "::before", "::after"].includes(node.value))) return false;
+  if (pseudos.some(node => node.value === ":not") && !rootAnchor(nodes)) return false;
+  return reset(property, value, nodes);
+}
+
+/** Closed foundation roles apply even when a native selector uses valid tokens. */
+export function foundationDeclaration(rule, declaration) {
+  try {
+    const selectors = selectorParser().astSync(rule.selector);
+    const property = declaration.prop.toLowerCase(), value = declaration.value.trim();
+    for (const selector of selectors.nodes) {
+      const lastCombinator = selector.nodes.findLastIndex(node => node.type === "combinator");
+      for (let nodes of subjects(selector.nodes.slice(lastCombinator + 1))) {
+        nodes = nodes.slice(nodes.findLastIndex(node => node.type === "combinator") + 1);
+        if (!roleAllows(rule, nodes, property, value)) return "base.css permits document-root/body typography and canvas defaults, limited native normalization, global focus indicators and reduced-motion rules. Put control skins, layout and state styling in their Linaria owner.";
+      }
+    }
+    return null;
+  } catch (error) { return `Invalid foundation declaration context: ${error.message}`; }
+}