@starklab/stark-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandro Giordano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @starklab/stark-mcp
+
+MCP server that exposes the Stark design system — component catalog, usage
+rules, prop mappings, layout schemas, and deterministic layout conformance
+checks — to any MCP-compatible coding agent, without needing the
+`stark-workspace` monorepo checked out.
+
+This is a companion to (not a replacement for) the Figma MCP bridge used
+elsewhere in this workspace: the Figma bridge talks to the *live Figma file*
+(variables, nodes, component properties); this server talks to the
+*published code/token contract* (the JSON already checked into
+`@starklab/stk`). A client can have both connected, but generating
+or validating UI only needs this one.
+
+## Usage
+
+Add to your MCP client config (e.g. `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "stark": {
+      "command": "npx",
+      "args": ["-y", "@starklab/stark-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Wraps | Returns |
+|---|---|---|
+| `list_components` | `prop-mapping/components/*.mapping.json` + `usage/components/*.usage.json` | name, slug, status, description, platforms |
+| `get_component_usage` | `usage/loader.js` (`loadUsage`) | dos/donts, props, figmaUrl, status |
+| `get_component_props` | `prop-mapping/components/{c}.mapping.json` (+ `tokens/components/{c}.json` when `includeTokens` is set) | React↔Figma `propMap` for a platform, optionally the component's token JSON |
+| `get_manifest` | all of the above, aggregated | usage + props (per platform) + tokens for every component in one call |
+| `get_layout_catalog` | `conformance/catalog.js` (`buildCatalogFromDir`) | every layout-capable component's props/slots |
+| `get_layout_schema` | same, filtered to one component | one component's layoutSchema |
+| `validate_layout` | `conformance/index.js` (`runConformance`) | deterministic findings (`Critical`/`Warning`/`Info`), no LLM involved |
+| `get_generation_protocol` | `generation-protocol.json` | the enforced step checklist Vecna runs |
+
+## CLI
+
+The same catalog is also available from a terminal, without an MCP client:
+
+```bash
+npx --package=@starklab/stark-mcp stark-cli list
+npx --package=@starklab/stark-mcp stark-cli usage Button
+npx --package=@starklab/stark-mcp stark-cli props Button --platform=web --tokens
+npx --package=@starklab/stark-mcp stark-cli manifest
+npx --package=@starklab/stark-mcp stark-cli eject Button --out=./src/stark-eject/Button
+npx --package=@starklab/stark-mcp stark-cli eject Button --platform=native
+```
+
+The package name and the `stark-mcp` bin match, so plain `npx
+@starklab/stark-mcp` runs the MCP server by default — `--package=`
+is what selects the second (`stark-cli`) bin instead. Once installed locally
+or globally, just run `stark-cli <command>`. Run `stark-cli --help` for the
+full command list. Output is always JSON on stdout; errors go to stderr with
+a non-zero exit code.
+
+## Public manifest
+
+`npm run generate-manifest` writes the full catalog (usage + props + tokens
+for every component) to `manifest.json` inside the installed
+`@starklab/stk` package. Run it before publishing a new version of
+`stk` so the manifest ships with it and stays fetchable as a static file —
+e.g. via a CDN mirror of the npm package — without needing an MCP session at
+all. It's not checked into git (same as `stk`'s `build/` output); regenerate
+it from source on demand.
+
+## Eject a component
+
+`stark-cli eject <Component>` copies one component's source out of your
+installed component package into your own project — an escape hatch for the
+rare case where a component's token/prop API genuinely can't express what you
+need. The copy is yours to edit freely; it stops receiving upstream fixes for
+that component.
+
+`--platform=web` (default) copies `.jsx` + `.css` from
+`@starklab/stk-components`. `--platform=native` copies the `.jsx`
+(RN components have no separate stylesheet file — styles are inline
+`StyleSheet.create()`) from `@starklab/stk-react-native`. Either
+way, the source package must be installed in the project you run it from
+(resolved from your current directory, not from `stark-mcp`'s own
+dependencies) — and the target component must actually support the platform
+you ask for.
+
+Defaults to `./stark-eject/<Component>`; pass `--out=<dir>` to change it, and
+`--force` to overwrite a non-empty target.
+
+## Known limitation
+
+`validate_layout` accepts an optional `canvasCases` argument — the list of
+node types your renderer actually supports. Stark's own catalog↔renderer
+parity check (`checkCatalogRendererParity`) is skipped when it's omitted,
+since an external caller's renderer isn't `LayoutCanvas.jsx`. Pass your own
+supported-type list if you have an equivalent check to run.
+
+## Prerequisite
+
+Requires `@starklab/stk` to ship `prop-mapping/`, `conformance/`,
+and `generation-protocol.json` in its published `files` — added in this same
+change (previously only `build/`, `tokens/`, `usage/`, and `layout-rules/`
+were published, so this server would have had no data to read once actually
+installed from the npm registry rather than resolved via the workspace
+symlink).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@starklab/stark-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing the Stark design system catalog, usage rules, prop mappings, and layout conformance checks to any MCP-compatible coding agent — without needing the stark-workspace monorepo checked out.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "stark-mcp": "src/index.js",
+    "stark-cli": "src/cli.js"
+  },
+  "main": "./src/server.js",
+  "files": [
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "generate-manifest": "node scripts/generate-manifest.js"
+  },
+  "dependencies": {
+    "@starklab/stk": "^1.1.0",
+    "@babel/parser": "^7.29.7",
+    "@babel/traverse": "^7.29.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-glob": "^3.3.3",
+    "postcss": "^8.5.25",
+    "zod": "^4.0.0"
+  }
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Home.jsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { Button } from '@starklab/stk-components';
+import { AppButton } from '../wrappers/AppButton';
+import { BrandButton } from '../wrappers/BrandButton';
+import { FeatureCard } from '../wrappers/FeatureCard';
+
+export function Home() {
+  return (
+    <div className="dark:bg-primary">
+      <AppButton>Save</AppButton>
+      <BrandButton>Buy now</BrandButton>
+      <BrandButton>Learn more</BrandButton>
+      <BrandButton>Get started</BrandButton>
+      {/* Direct (non-wrapper) catalog call site — invalid enum value plus a
+          className passthrough, exercising resolvePropApi's two checkable
+          rules against the real button.mapping.json data. */}
+      <Button variant="primry" className="cta-override">Go</Button>
+      <FeatureCard content={<p>Feature</p>} />
+    </div>
+  );
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Menu.jsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { DropdownMenu } from '@starklab/stk-components';
+
+// Compound Foo.Bar usage — <DropdownMenu.SubTrigger/> is a JSXMemberExpression
+// and must attribute back to the DropdownMenu catalog entry, not go unmatched
+// as a component literally named "DropdownMenu.SubTrigger".
+export function Menu() {
+  return (
+    <DropdownMenu>
+      <DropdownMenu.SubTrigger>Open</DropdownMenu.SubTrigger>
+    </DropdownMenu>
+  );
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Profile.jsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import { BrandButton } from '../wrappers/BrandButton';
+
+export function Profile() {
+  return (
+    <div>
+      <BrandButton>Edit</BrandButton>
+      <BrandButton>Delete</BrandButton>
+    </div>
+  );
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/theme.css

@@ -0,0 +1,34 @@
+:root {
+  /* nested aliases — app-base -> app-mid -> app-top -> app-deep, terminal
+     depth 4 (deeper than tokenAliasResolver's WARN_DEPTH of 3), exercising
+     both transitive resolution and the deep-alias-chain finding */
+  --app-base: var(--stk-surface-brand-1-strong);
+  --app-mid: var(--app-base);
+  --app-top: var(--app-mid);
+  --app-deep: var(--app-top);
+
+  /* raw fallback — resolves conformant, still flagged info-level since the
+     fallback silently becomes load-bearing the day
+     --stk-surface-brand-1-strong is renamed */
+  --app-cta: var(--stk-surface-brand-1-strong, #1956dd);
+
+  /* primitive alias — layer violation: a consumer property pointing straight
+     at a base/primitive token instead of a semantic one */
+  --app-gap: var(--stk-spacing-md);
+
+  /* scoped-override target — conformant at :root */
+  --app-accent: var(--stk-surface-brand-1-strong);
+}
+
+/* scoped override — same property, different selector, resolving to a raw
+   hex under .theme-promo: :root and .theme-promo disagree, so the property
+   overall is partial-conformance rather than collapsed to one scope */
+.theme-promo {
+  --app-accent: #1956dd;
+}
+
+/* Tailwind v4 theme entry — Home.jsx's className="dark:bg-primary" resolves
+   through this back to a Stark token */
+@theme {
+  --color-primary: var(--stk-surface-brand-1-strong);
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/AppButton.jsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import { Button } from '@starklab/stk-components';
+
+// Transparent wrapper — spreads props through unmodified, no hardcoded or
+// style-only attributes.
+export function AppButton(props) {
+  return <Button {...props} />;
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/BrandButton.jsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import { Button } from '@starklab/stk-components';
+
+// Divergent wrapper — a hardcoded className makes this a styling override,
+// not a faithful passthrough. Used from several call sites (see
+// pages/Home.jsx and pages/Profile.jsx) to exercise high fanout.
+export function BrandButton(props) {
+  return <Button className="brand-button" {...props} />;
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/CardBase.jsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import { Card } from '@starklab/stk-components';
+
+// First hop of a two-level wrapper chain (see FeatureCard.jsx) — transparent
+// passthrough. Only consumed internally by FeatureCard, so its own external
+// fanout should be zero (the chain edge itself is excluded from fanout).
+export function CardBase(props) {
+  return <Card {...props} />;
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/FeatureCard.jsx

@@ -0,0 +1,7 @@
+import React from 'react';
+import { CardBase } from './CardBase';
+
+// Second hop of the chain — resolves through CardBase down to Card.
+export function FeatureCard(props) {
+  return <CardBase {...props} />;
+}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/SectionCard.jsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { Card } from '@starklab/stk-components';
+
+// An "as"-polymorphic call site. ADOPTION_APP_PLAN.md §4 "Polymorphism" calls
+// for a declared `polymorphicProp` field in prop-mapping/schema.json as
+// future work — no dedicated `as`-detection exists in wrapperResolver.js yet,
+// so a hardcoded `as` attribute is classified through the ordinary
+// hardcodedProps -> "constraining" path, same as any other literal prop.
+// This fixture documents that current (pre-declaration) behavior.
+export function SectionCard(props) {
+  return <Card as="section" {...props} />;
+}

package/src/adopt/catalog.js

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { stkRoot } from '../data.js';
+
+// catalog.json calls the RN platform "rn"; every other surface in this repo
+// (getComponentProps, ejectComponent, prop-mapping "platforms" arrays) calls
+// it "native". The adopt module speaks the latter to stay consistent with the
+// rest of stark-mcp's public API and translates internally.
+const CATALOG_KEY = { web: 'web', native: 'rn' };
+
+const PACKAGE_NAME = {
+  web: '@starklab/stk-components',
+  native: '@starklab/stk-react-native',
+};
+
+/**
+ * Reads a flat re-export barrel (`export { A, B } from './x';` lines only)
+ * and returns the exported symbol names. Mirrors
+ * packages/stk/scripts/reconcile-catalog.js's readBarrel — existence is
+ * derived from the barrel and nowhere else, so this resolver's denominator
+ * can never drift from what reconcile-catalog.js already enforces in CI.
+ */
+function readBarrel(file) {
+  const src = readFileSync(file, 'utf-8');
+  const names = [];
+  for (const line of src.split('\n')) {
+    const bare = line.trim();
+    if (!bare || bare.startsWith('//') || bare.startsWith('*') || bare.startsWith('/*')) continue;
+    const m = bare.match(/^export\s*\{([^}]+)\}\s*from\s*['"][^'"]+['"];?$/);
+    if (!m) continue;
+    for (const part of m[1].split(',')) {
+      const name = part.trim().split(/\s+as\s+/).pop().trim();
+      if (name) names.push(name);
+    }
+  }
+  return names;
+}
+
+const toSlug = (s) =>
+  String(s)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase();
+
+/**
+ * The catalog denominator for one platform: every barrel export whose
+ * catalog.json kind is "component" (the only kind that's countable — see
+ * catalog.json's own $comment and ADOPTION_APP_PLAN.md §2). Never derive
+ * this list from a scan; the reference resolver left-joins scan counts onto
+ * this list so zero-usage components show up as 0, not as absent (§4 blind
+ * spot 1).
+ */
+export function loadCatalog(platform = 'web') {
+  const catalogKey = CATALOG_KEY[platform];
+  if (!catalogKey) {
+    throw new Error(`Unsupported platform "${platform}". Available: ${Object.keys(CATALOG_KEY).join(', ')}.`);
+  }
+
+  const root = stkRoot();
+  const manifest = JSON.parse(readFileSync(path.join(root, 'catalog.json'), 'utf-8'));
+  const cfg = manifest.platforms[catalogKey];
+  if (!cfg) {
+    throw new Error(`catalog.json has no "${catalogKey}" platform entry.`);
+  }
+
+  const barrelPath = path.resolve(root, cfg.barrel);
+  const exported = readBarrel(barrelPath);
+  const classified = cfg.exports ?? {};
+
+  const components = exported
+    .filter((name) => classified[name]?.kind === 'component')
+    .map((name) => ({ name, slug: toSlug(name) }));
+
+  return {
+    platform,
+    package: PACKAGE_NAME[platform],
+    components,
+  };
+}
+
+export function packageNameForPlatform(platform) {
+  const name = PACKAGE_NAME[platform];
+  if (!name) {
+    throw new Error(`Unsupported platform "${platform}". Available: ${Object.keys(PACKAGE_NAME).join(', ')}.`);
+  }
+  return name;
+}

package/src/adopt/dominionFixture.test.js

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveReferences } from './referenceResolver.js';
+import { resolveWrappers } from './wrapperResolver.js';
+import { resolveTokenAliases } from './tokenAliasResolver.js';
+import { resolveTailwindTokens } from './tailwindResolver.js';
+import { resolvePropApi } from './propApiResolver.js';
+
+// This fixture app (__fixtures__/dominion-fixture-app/) is the shared
+// consumer app ADOPTION_APP_PLAN.md's Phase 1 roadmap calls for — one app
+// exercising every element the plan names (a theme file, nested aliases, a
+// scoped override, a raw fallback, a primitive alias, a Tailwind variant, a
+// transparent wrapper, a divergent high-fanout wrapper, a two-level wrapper
+// chain, an "as"-polymorphic call site, a compound Foo.Bar usage, a direct
+// invalid-enum-value call site, and a className passthrough) run through all
+// five web resolvers together — treated as their test suite.
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '__fixtures__', 'dominion-fixture-app');
+
+describe('dominion fixture app — resolveReferences', () => {
+  it('attributes direct and compound-tag usages to the right catalog components', () => {
+    const result = resolveReferences(root, { platform: 'web' });
+    const byName = new Map(result.components.map((c) => [c.name, c]));
+
+    expect(byName.get('Button').counts.jsx).toBe(3); // AppButton.jsx, BrandButton.jsx, Home.jsx
+    expect(byName.get('Card').counts.jsx).toBe(2); // CardBase.jsx, SectionCard.jsx
+    // outer <DropdownMenu> opening tag + <DropdownMenu.SubTrigger>'s object ref
+    expect(byName.get('DropdownMenu').counts.jsx).toBe(2);
+  });
+});
+
+describe('dominion fixture app — resolveWrappers', () => {
+  it('classifies faithfulness, chain depth, and fanout for every wrapper', () => {
+    const result = resolveWrappers(root, { platform: 'web' });
+    const byExportedAs = new Map(result.wrappers.map((w) => [w.exportedAs, w]));
+
+    const appButton = byExportedAs.get('AppButton');
+    expect(appButton.component).toBe('Button');
+    expect(appButton.chain[0].faithfulness).toBe('transparent');
+    expect(appButton.depth).toBe(1);
+
+    const brandButton = byExportedAs.get('BrandButton');
+    expect(brandButton.component).toBe('Button');
+    expect(brandButton.chain[0].faithfulness).toBe('divergent');
+    expect(brandButton.fanout.counts.jsx).toBe(5); // 3x Home.jsx + 2x Profile.jsx
+
+    const cardBase = byExportedAs.get('CardBase');
+    expect(cardBase.component).toBe('Card');
+    expect(cardBase.chain[0].faithfulness).toBe('transparent');
+    // Only consumer is FeatureCard's own chain edge — excluded from fanout.
+    expect(cardBase.fanout.counts.jsx).toBe(0);
+
+    const featureCard = byExportedAs.get('FeatureCard');
+    expect(featureCard.component).toBe('Card');
+    expect(featureCard.depth).toBe(2);
+    expect(featureCard.warnDepth).toBe(false);
+    expect(featureCard.fanout.counts.jsx).toBe(1); // Home.jsx
+
+    const sectionCard = byExportedAs.get('SectionCard');
+    expect(sectionCard.component).toBe('Card');
+    // No dedicated `as`-polymorphism detection yet (ADOPTION_APP_PLAN.md §4)
+    // — a hardcoded `as` attribute takes the generic hardcodedProps path.
+    expect(sectionCard.chain[0].faithfulness).toBe('constraining');
+
+    const byComponent = new Map(result.byComponent.map((c) => [c.name, c]));
+    expect(byComponent.get('Card').viaWrappers.map((w) => w.exportedAs).sort()).toEqual([
+      'CardBase',
+      'FeatureCard',
+      'SectionCard',
+    ]);
+    expect(byComponent.get('Button').viaWrappers.map((w) => w.exportedAs).sort()).toEqual([
+      'AppButton',
+      'BrandButton',
+    ]);
+  });
+});
+
+describe('dominion fixture app — resolveTokenAliases', () => {
+  it('resolves nested aliases, flags deep chains, layer violations, raw fallbacks, and partial conformance', () => {
+    const result = resolveTokenAliases(root, { platform: 'web' });
+    const byName = new Map(result.properties.map((p) => [p.name, p]));
+
+    expect(byName.get('--app-base').state).toBe('conformant');
+    expect(byName.get('--app-mid').state).toBe('conformant');
+    expect(byName.get('--app-top').state).toBe('conformant');
+    expect(byName.get('--app-deep').state).toBe('conformant');
+
+    const deepChain = result.findings.find((f) => f.rule === 'deep-alias-chain' && f.property === '--app-deep');
+    expect(deepChain).toBeDefined();
+    expect(deepChain.depth).toBe(4);
+    // Shallower hops in the same chain stay under WARN_DEPTH (3).
+    expect(result.findings.some((f) => f.rule === 'deep-alias-chain' && f.property === '--app-top')).toBe(false);
+
+    const rawFallback = result.findings.find((f) => f.rule === 'raw-fallback' && f.property === '--app-cta');
+    expect(rawFallback).toBeDefined();
+
+    const layerViolation = result.findings.find((f) => f.rule === 'layer-violation' && f.property === '--app-gap');
+    expect(layerViolation).toBeDefined();
+    expect(layerViolation.severity).toBe('critical');
+
+    expect(byName.get('--app-accent').state).toBe('partial-conformance');
+    expect(
+      result.findings.some(
+        (f) => f.rule === 'drift-behind-alias' && f.property === '--app-accent' && f.selector === '.theme-promo'
+      )
+    ).toBe(true);
+    expect(result.findings.some((f) => f.rule === 'partial-conformance' && f.property === '--app-accent')).toBe(true);
+  });
+});
+
+describe('dominion fixture app — resolveTailwindTokens', () => {
+  it('resolves a v4 @theme entry through a variant-prefixed utility class back to a Stark token', () => {
+    const result = resolveTailwindTokens(root, { platform: 'web' });
+
+    expect(result.detected).toBe(true);
+    expect(result.source).toBe('v4');
+
+    const colorPrimary = result.properties.find((p) => p.name === '--color-primary');
+    expect(colorPrimary.state).toBe('conformant');
+
+    const usage = result.usages.find((u) => u.className === 'dark:bg-primary');
+    expect(usage).toBeDefined();
+    expect(usage.classification).toBe('aliased');
+    expect(result.report.aliased).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('dominion fixture app — resolvePropApi', () => {
+  it('flags an invalid enum value and every className/style passthrough against real button/card mapping data', () => {
+    const result = resolvePropApi(root, { platform: 'web' });
+
+    // Only one literal enum value appears anywhere in the fixture app
+    // (Home.jsx's `variant="primry"`) — everything else is either a spread
+    // passthrough (AppButton.jsx, CardBase.jsx), an untracked attribute
+    // (`as` on SectionCard.jsx's Card, absent from both propMap and ignore),
+    // or has no attributes at all (Menu.jsx's DropdownMenu tags).
+    expect(result.report).toEqual({ total: 1, valid: 0, validPct: 0, invalid: 1, invalidPct: 100, unresolved: 0, unresolvedPct: 0 });
+
+    const enumFinding = result.findings.find((f) => f.rule === 'invalid-enum-value');
+    expect(enumFinding).toMatchObject({
+      component: 'Button',
+      prop: 'variant',
+      value: 'primry',
+      allowed: ['primary', 'ghost', 'outline', 'danger'],
+      severity: 'critical',
+      file: 'src/pages/Home.jsx',
+    });
+
+    // className shows up on two real Button call sites — BrandButton.jsx's
+    // hardcoded wrapper prop and Home.jsx's own direct passthrough.
+    const styleFindings = result.findings.filter((f) => f.rule === 'style-escape-hatch');
+    expect(styleFindings.map((f) => f.file).sort()).toEqual([
+      'src/pages/Home.jsx',
+      'src/wrappers/BrandButton.jsx',
+    ]);
+    expect(styleFindings.every((f) => f.component === 'Button' && f.prop === 'className' && f.severity === 'warning')).toBe(true);
+
+    // SectionCard.jsx's hardcoded `as="section"` is neither in Card's
+    // propMap nor its ignore list — absence of evidence, never a violation.
+    expect(result.findings.some((f) => f.file === 'src/wrappers/SectionCard.jsx')).toBe(false);
+
+    expect(result.findings).toHaveLength(3);
+  });
+});