@afokapu/atdd-bun 0.1.4 → 0.3.0

package/README.md

@@ -90,6 +90,7 @@ name.
 | `coder`, `tester`, `security`, `architecture`, `metrics`, `runtime` | Bun source and test conventions for that concern |
 | `interlocking` | declared train/interlocking binding, infrastructure, and coverage |
 | `htmx` | htmx-specific source and test conventions |
+| `design` | the design system: tokens ← primitives ← components ← templates, token-only colors, spacing, radii, and motion (also part of `coder`) |
 | `all` | the complete package policy, normally used by CI |
 
 The package ships the canonical planner-node corpus as planning reference, but
@@ -110,6 +111,29 @@ carry Station Master actions; the Bun interlocking family checks those actions r
 Hooks, direct CLI use, and CI invoke this same profile and therefore share the
 same schema source.
 
+### Design system
+
+The `design` profile (also part of `coder`) is the Bun realization of the core
+`coder.design.*` obligations. It recognizes a design system by its directory:
+a folder named `design`, `design_system`, or `design-system`, whose first
+subfolder names the layer:
+
+```text
+design/
+  tokens/ or foundations/   values only: palette, spacing, radii, motion
+  primitives/               Button, Text, Stack … built from tokens
+  components/               composed from primitives
+  templates/                page structure composed from components
+```
+
+Imports flow downward only, and the design system never imports app code.
+Outside the tokens layer, `.tsx`, `.html`, and `.css` files take colors,
+spacing, radii, and durations from tokens (`var(--…)`); app components render
+controls through primitives and import at least one design-system element; and
+every exported component has a consumer. Defining a custom property
+(`--accent: #0ea5e9`) is defining a token and is allowed anywhere. A repository
+without a design directory is not judged by these rules.
+
 ### Theme and contract registry
 
 Theme vocabulary belongs to the repository, not the package. When a plan uses
@@ -142,12 +166,13 @@ when they are absent. It never overwrites another hook path, an existing
 generated workflow, or an existing skill unless you explicitly pass `--replace`. Installing the dependency alone deliberately does
 neither: package installation must not mutate a repository through postinstall.
 
-Use `hooks install`, `ci init`, or `agent init` when only one surface is wanted:
+Use `hooks install`, `ci init`, `agent init`, or `integrity init` when only one surface is wanted:
 
 ```sh
 bun run atdd-bun hooks install
 bun run atdd-bun ci init
 bun run atdd-bun agent init
+bun run atdd-bun integrity init
 ```
 
 The hooks enforce protected-branch blocking, micro-commit limits, mass-delete
@@ -206,6 +231,31 @@ it stays correct as they change; after upgrading, refresh it with
 `bun run atdd-bun agent init --replace`. The skill steers the agent; the
 profiles, hooks, and CI remain the enforcement.
 
+## Integrity: files agents must not change
+
+Coding agents can edit anything on the machine they run on, including
+`node_modules/@afokapu/atdd-bun`, the files this package generates, and
+`atdd-bun.yaml`. `init` therefore writes `atdd-bun.integrity.test.ts` (into the
+`[test] root` from `bunfig.toml`, if one is set), and the generated CI workflow
+runs `bun run atdd-bun integrity` before enforcement. Both run the same check:
+
+| Checked | Canonical source | Restore |
+|---|---|---|
+| Every file of the installed package | `integrity.json`, the hashes published with the package | `bun install --force` |
+| The dependency is an npm version range, locked to the registry with an integrity hash | npm | `bun add -d @afokapu/atdd-bun` |
+| The CI workflow, both skills, the `AGENTS.md` block, and the integrity test | what the installed version generates (its version stamp is ignored) | `bun run atdd-bun init --replace` |
+| `atdd-bun.yaml` is not looser than on the branch being merged into | the merge base; for a push to the base branch, the previous commit | `git checkout <base> -- atdd-bun.yaml` |
+
+A failure is addressed to the agent: it lists every changed file with its
+restore command and tells it to stop and ask a human instead of working around
+the check. Locally, this is a reminder an agent can still ignore, because
+anything on its machine can be edited. In CI the check runs on a clean install,
+so its verdict cannot be faked. Loosening the policy remains possible, as a
+separate change a human approves.
+
+After upgrading to a version that changes generated files, run
+`bun run atdd-bun init --replace` and commit the result.
+
 ## CI: the merge gate
 
 Generate the repository-owned workflow with:

package/conventions/coder.bun/coder.bun.design-connected.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-connected
+kind: rule
+status: active
+name: Every rendering app component is connected to the design system
+statement: An app component (`.tsx`/`.jsx` outside the design root) that renders markup MUST import at least one
+  design-system element — token, primitive, component, or template — so no UI surface is disconnected from the shared
+  system. Bun realization of `coder.design.orphan-ui`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: rendering_component
+  text: a component source file whose code (literals and comments masked) contains a closing tag or a self-closing
+    element.
+content:
+  summary: Flags rendering component files outside the design root that import nothing from it.
+  normative_text: A screen built without the system is where the next one-off style lands. Requiring one design
+    import makes the connection explicit and reviewable.
+  fix_hint: Compose the screen from a template, component, or primitive — at minimum wrap it in the page template.
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - Non-rendering modules (routes, handlers, data) are not judged.
+metadata:
+  aliases:
+  - BUN-DESIGN-CONNECTED-001
+  core_obligation: coder.design.orphan-ui
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-dependency-flow.convention.yaml

@@ -0,0 +1,37 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-dependency-flow
+kind: rule
+status: active
+name: Design-system layers import only their own layer or a lower one
+statement: A file under a design root MUST import only from its own layer or a lower one in the hierarchy tokens/foundations
+  (0) <- primitives (1) <- components (2) <- templates (3). Upward edges — tokens importing primitives, primitives
+  importing components, components importing templates — are forbidden. Bun realization of the core obligation `coder.design.hierarchy-import`,
+  mirroring `coder.vite.design-dependency-flow`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: upward_import
+  text: an import from a design-system file into a HIGHER layer, resolved from a relative path or from an aliased
+    specifier that names the design directory (`@/design/components/Card`).
+content:
+  summary: Resolves each import of a design-system file to its target layer and flags any edge that points upward.
+  normative_text: A hierarchy is only a hierarchy if dependencies flow one way. A primitive that imports a component
+    can no longer be reused without dragging that component along, and the layers collapse into one tangle.
+  fix_hint: 'Move the shared piece down to the lowest layer that needs it, or compose upward: the component imports
+    the primitive, never the reverse.'
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - Imports within the same layer are allowed.
+  - Files directly under the design root, outside any named layer, are not layered.
+metadata:
+  aliases:
+  - BUN-DESIGN-DEPENDENCY-FLOW-001
+  core_obligation: coder.design.hierarchy-import
+  severity: 3
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-orphan-export.convention.yaml

@@ -0,0 +1,36 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-orphan-export
+kind: rule
+status: active
+name: Design-system components have a consumer
+statement: Every component a `primitives`, `components`, or `templates` file exports MUST be imported by at least
+  one other file — a higher design layer or app code — so the system stays lean. Re-exports through an `index.*`
+  barrel are not consumption. Bun realization of `coder.design.orphan-export`, counting consumers the way `coder.vite.design-orphan-ui`
+  does, so composition inside the system (a template using a component) is legitimate.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: consumer
+  text: a non-barrel file whose import clause names the export, or imports it as a default under that name.
+content:
+  summary: Collects capitalized exports of primitives/components/templates and flags those no other file imports.
+  normative_text: Unused components still have to be maintained, themed, and migrated. A design system grows by
+    adjudication, not by accretion of pieces nobody uses.
+  fix_hint: 'Use the component where it was meant to be used, or delete it. Unused chains surface one layer at a
+    time: remove the unused template and its component is reported next.'
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - Token/foundation values and `index.*` barrels are not judged.
+  - Only capitalized (component) exports are judged.
+metadata:
+  aliases:
+  - BUN-DESIGN-ORPHAN-EXPORT-001
+  core_obligation: coder.design.orphan-export
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-primitives.convention.yaml

@@ -0,0 +1,35 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-primitives
+kind: rule
+status: active
+name: App components compose design-system primitives for interactive controls
+statement: An app component (`.tsx`/`.jsx` outside the design root) MUST render interactive controls through a design-system
+  primitive rather than a raw `<button>`, `<input>`, `<select>`, or `<textarea>`, so controls stay themed, accessible,
+  and consistent. Bun realization of `coder.design.primitives`, mirroring `coder.vite.design-primitives`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: raw_control
+  text: a lowercase `<button`, `<input`, `<select`, or `<textarea` element written in app code.
+content:
+  summary: Flags raw interactive platform elements in component source outside the design root.
+  normative_text: Controls are where focus, disabled, error, and loading states live. Each raw control re-implements
+    them, and each re-implementation diverges.
+  fix_hint: 'Render the primitive and pass htmx attributes through it: `<Button hx-post="/orders">Place</Button>`.
+    Add the primitive to `design/primitives/` if it does not exist yet.'
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - The design system's own primitives render the raw elements and are not scanned.
+  - Plain `.html` templates cannot import components and are out of scope.
+metadata:
+  aliases:
+  - BUN-DESIGN-PRIMITIVES-001
+  core_obligation: coder.design.primitives
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-token-color.convention.yaml

@@ -0,0 +1,38 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-token-color
+kind: rule
+status: active
+name: UI files use color tokens, not raw color literals
+statement: Outside the tokens layer, a UI file (`.tsx`, `.jsx`, `.html`, `.htm`, `.css`) MUST NOT write a raw color
+  literal — `#rgb`/`#rrggbb`/`#rrggbbaa`, `rgb()`/`rgba()`, `hsl()`/`hsla()` — in a CSS declaration, a `style` attribute,
+  a `<style>` block, a JSX `style={{…}}` object, or a `fill`/`stroke`/`bgcolor` attribute. Colors come from tokens
+  (`var(--…)`). Bun realization of `coder.design.token-color`, mirroring `coder.vite.design-token-color`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: raw_color_literal
+  text: 'a hex, rgb(a), or hsl(a) color written in a declaration value. Selectors are not values: `#fade:hover {`
+    is never read as a color.'
+content:
+  summary: Reads declarations from stylesheets, style attributes, style blocks, and JSX style objects, and flags
+    raw color literals in their values.
+  normative_text: A raw color is a theme decision made in one place. It does not follow dark mode, it drifts from
+    the palette, and nobody can find it when the palette changes.
+  fix_hint: 'Define the color once as a custom property in the tokens layer and reference it: `color: var(--danger)`.'
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - Custom property definitions (`--danger: #b91c1c`) define tokens wherever they live and are not flagged.
+  - The tokens/foundations layer is where raw colors are defined and is not scanned.
+  - Named colors (`red`, `white`) and `currentColor`/`transparent` are not flagged.
+metadata:
+  aliases:
+  - BUN-DESIGN-TOKEN-COLOR-001
+  core_obligation: coder.design.token-color
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-token-hardcoded.convention.yaml

@@ -0,0 +1,40 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-token-hardcoded
+kind: rule
+status: active
+name: UI files take spacing, radii, and durations from foundations
+statement: Outside the tokens layer, a UI file MUST NOT hardcode a spacing, inset, or border-radius length greater
+  than 1px (`margin`, `padding`, `gap`, `inset`, `top`/`right`/`bottom`/`left`, `border-radius`), nor a non-zero
+  duration in `transition`/`animation`. A bare number in a JSX style object for those properties counts as a length.
+  These values come from foundations tokens. Bun realization of `coder.design.token-hardcoded` and of the raw-pixel
+  part of `coder.design.foundations`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: visual_token
+  text: a spacing, radius, or motion value defined once in foundations and referenced as `var(--…)`.
+content:
+  summary: Flags hardcoded lengths and durations in spacing, radius, and motion declarations across UI files, including
+    the design system's own primitives and components.
+  normative_text: Spacing and motion are the rhythm of an interface. Each hardcoded `13px` is a new step on a scale
+    nobody chose, and the rhythm erodes one component at a time.
+  fix_hint: 'Use the foundations scale: `padding: var(--space-3)`, `border-radius: var(--radius)`, `transition:
+    opacity var(--fast)`. Add a step to the scale in the tokens layer if none fits.'
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - 0 and 1px (hairline borders) are not design decisions and are allowed.
+  - Custom property definitions (`--space-3: 12px`) define tokens wherever they live and are not flagged.
+  - The tokens/foundations layer defines these values and is not scanned.
+  - Widths, heights, and font sizes are out of scope for this rule.
+metadata:
+  aliases:
+  - BUN-DESIGN-TOKEN-HARDCODED-001
+  core_obligation: coder.design.token-hardcoded
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-tokens-pure.convention.yaml

@@ -0,0 +1,35 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-tokens-pure
+kind: rule
+status: active
+name: Token and foundation files hold values, not behaviour
+statement: A code file in the `tokens` or `foundations` layer MUST contain only values — palette, spacing, radii,
+  motion, scales — and MUST NOT import a renderer (`hono/jsx`, `react`, `preact`, `@kitajs/html`), render markup,
+  or branch with `if`/`for`/`while`/`switch`. Bun realization of `coder.design.foundations` (the bottom of the hierarchy
+  is pure), mirroring `coder.vite.design-tokens-pure`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: pure_token
+  text: 'a declaration whose value is data: a string, number, or object of them, including `var(--…)` references.'
+content:
+  summary: Scans token/foundation code files for renderer imports, rendered markup, and control flow.
+  normative_text: Tokens are what every other layer depends on. Once they render or decide, the bottom of the hierarchy
+    has behaviour, and every primitive inherits it.
+  fix_hint: Keep the value in the token file and move the markup to `primitives/` or the logic to the component
+    that needs it.
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - '`.css` token files are values by construction and are not scanned by this rule.'
+metadata:
+  aliases:
+  - BUN-DESIGN-TOKENS-PURE-001
+  core_obligation: coder.design.foundations
+  severity: 2
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/conventions/coder.bun/coder.bun.design-wagons-import.convention.yaml

@@ -0,0 +1,35 @@
+schema_version: 1.1.0
+rule_id: coder.bun.design-wagons-import
+kind: rule
+status: active
+name: The design system never imports app or wagon code
+statement: A file under a design root MUST NOT import a relative path that resolves outside the design root. Wagons
+  and app code import FROM the design system, never the reverse, so the system stays wagon-agnostic. Bun realization
+  of the outward half of `coder.design.hierarchy-import`, mirroring `coder.vite.design-wagons-import`.
+terms:
+- term_id: design_root
+  text: 'a directory named `design`, `design_system`, or `design-system`. The first directory beneath it names the
+    layer: `tokens` or `foundations`, `primitives`, `components`, `templates`. A repository with no design root
+    is not judged (self-scoping): there is no system to connect to yet.'
+- term_id: outward_import
+  text: a relative import from a design-system file whose target lies outside every design root.
+content:
+  summary: Flags relative imports from a design-system file that leave the design root.
+  normative_text: 'A design system that reaches into a wagon has become part of that wagon: it cannot be reused
+    by the next one, and a change to the wagon breaks the system.'
+  fix_hint: Pass the value in as a prop, or move the shared type or constant into the design system (or a shared
+    commons module) so the dependency points inward.
+  exceptions:
+  - Test files (`*.test.*`, `*.spec.*`) and vendored/build directories are never scanned.
+  - Bare package specifiers (`hono/jsx`) are outside the project graph and are not judged.
+  - Aliased specifiers are judged only when they name a design directory.
+metadata:
+  aliases:
+  - BUN-DESIGN-WAGONS-IMPORT-001
+  core_obligation: coder.design.hierarchy-import
+  severity: 3
+  disposition: strict
+  introduced_in: 0.2.0
+implementation:
+  type: validator
+  ref: bun_design_system_detector

package/detectors/bun_design_system_detector/atdd.implementation.yaml

@@ -0,0 +1,28 @@
+schema_version: 1.1.0
+kind: implementation
+subtype: validator
+implementation_id: bun_design_system_detector
+targets_workspace: atdd.workspace.bun
+contract_version: 1.1.0
+emits_rule_ids:
+- coder.bun.design-dependency-flow
+- coder.bun.design-wagons-import
+- coder.bun.design-tokens-pure
+- coder.bun.design-token-color
+- coder.bun.design-token-hardcoded
+- coder.bun.design-primitives
+- coder.bun.design-connected
+- coder.bun.design-orphan-export
+entrypoint: detect.mjs
+report: detect.mjs
+realizes_convention:
+# A family detector owns every rule it emits: the Bun realization of the core
+# coder.design.* obligations (tokens <- primitives <- components <- templates).
+- coder.bun.design-dependency-flow
+- coder.bun.design-wagons-import
+- coder.bun.design-tokens-pure
+- coder.bun.design-token-color
+- coder.bun.design-token-hardcoded
+- coder.bun.design-primitives
+- coder.bun.design-connected
+- coder.bun.design-orphan-export

package/detectors/bun_design_system_detector/checks/_design.mjs

@@ -0,0 +1,112 @@
+// Shared design-system model for the bun_design_system_detector family.
+//
+// A DESIGN ROOT is a directory named `design`, `design_system`, or `design-system`.
+// The first directory beneath it names the file's LAYER, bottom to top:
+//
+//   tokens | foundations  (0)  ←  primitives (1)  ←  components (2)  ←  templates (3)
+//
+// Imports may point to the same layer or a lower one. Every rule self-scopes: a
+// repository with no design root is not judged, because there is no system to
+// connect to yet.
+import { dirname, extname, normalize, resolve, sep } from "node:path";
+import { walk, readText, maskLiteralsAndComments } from "../../../lib/scan.mjs";
+
+export const DESIGN_DIRS = new Set(["design", "design_system", "design-system"]);
+export const LAYERS = { tokens: 0, foundations: 0, primitives: 1, components: 2, templates: 3 };
+export const UI_EXT = new Set([".tsx", ".jsx", ".html", ".htm", ".css"]);
+export const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts"]);
+const ALL_EXT = new Set([...UI_EXT, ...CODE_EXT]);
+
+/** The design root containing `file` and the file's layer, or null when outside any design root. */
+export function designOf(file) {
+  const parts = normalize(file).split(sep);
+  for (let i = parts.length - 2; i >= 0; i--) {
+    if (!DESIGN_DIRS.has(parts[i])) continue;
+    const layerName = parts[i + 1];
+    const layer = i + 1 < parts.length - 1 && layerName in LAYERS ? LAYERS[layerName] : null;
+    return { root: parts.slice(0, i + 1).join(sep) || sep, layerName: layer === null ? null : layerName, layer };
+  }
+  return null;
+}
+
+/** Every source/UI file under the scan roots, once. */
+export function collect(roots, excludes) {
+  const seen = new Set();
+  for (const root of roots) for (const file of walk(root, excludes, ALL_EXT)) seen.add(resolve(file));
+  return [...seen];
+}
+
+const IMPORT_RE = /(?:^|[\n;])\s*(?:import|export)\s+(?:type\s+)?([\s\S]*?)\s*from\s*(['"])([^'"]+)\2|(?:^|[\n;])\s*import\s*(['"])([^'"]+)\4|\bimport\(\s*(['"])([^'"]+)\6\s*\)/g;
+
+/** Import statements of a code file: specifier, the clause text, and its offset. */
+export function importsOf(text) {
+  const out = [];
+  for (const m of text.matchAll(IMPORT_RE)) {
+    const specifier = m[3] ?? m[5] ?? m[7];
+    out.push({ specifier, clause: m[1] ?? "", index: m.index + m[0].indexOf(specifier) });
+  }
+  return out;
+}
+
+/**
+ * Where an import points: a path for relative specifiers, or — for aliased/absolute
+ * specifiers — the design segment it names (`@/design/primitives/Text`). Bare
+ * package names resolve to null.
+ */
+export function target(file, specifier) {
+  if (specifier.startsWith(".")) return { path: resolve(dirname(file), specifier) };
+  const segments = specifier.split("/");
+  const at = segments.findIndex((s) => DESIGN_DIRS.has(s));
+  if (at === -1) return null;
+  const layerName = segments[at + 1];
+  return { alias: true, layerName: layerName in LAYERS ? layerName : null, layer: layerName in LAYERS ? LAYERS[layerName] : null };
+}
+
+/** The design location an import resolves into, or null when it leaves every design root. */
+export function designTarget(file, specifier) {
+  const t = target(file, specifier);
+  if (!t) return null;
+  if (t.alias) return { layer: t.layer, layerName: t.layerName };
+  const d = designOf(t.path + (extname(t.path) ? "" : sep + "_"));
+  return d ? { layer: d.layer, layerName: d.layerName, root: d.root, path: t.path } : null;
+}
+
+export function masked(file) {
+  const text = readText(file);
+  if (text === null) return null;
+  return { text, code: extname(file) === ".css" ? text.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, " ")) : maskLiteralsAndComments(text) };
+}
+
+export const isUi = (file) => UI_EXT.has(extname(file));
+export const isComponentSource = (file) => extname(file) === ".tsx" || extname(file) === ".jsx";
+export const hasDesignRoot = (files) => files.some((file) => designOf(file));
+
+const kebab = (prop) => prop.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+const CSS_DECL_RE = /([-a-zA-Z]+)\s*:\s*([^;{}]+)(?=[;}])/g;
+
+/**
+ * Property/value pairs written in a UI file, with absolute offsets. CSS declarations
+ * must end in `;` or `}` so selectors (`a:hover {`) are never read as values; JSX
+ * style-object keys are converted to kebab-case, and a bare number is kept as-is.
+ */
+export function declarations(file, text) {
+  const out = [];
+  const css = (body, offset) => { for (const m of body.matchAll(CSS_DECL_RE)) out.push({ prop: m[1].toLowerCase(), value: m[2].trim(), index: offset + m.index }); };
+  if (extname(file) === ".css") { css(text.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, " ")), 0); return out; }
+  for (const m of text.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) css(m[1], m.index + m[0].indexOf(m[1]));
+  for (const m of text.matchAll(/\bstyle\s*=\s*(["'])([\s\S]*?)\1/g)) css(m[2] + ";", m.index + m[0].indexOf(m[2]));
+  for (const m of text.matchAll(/\bstyle\s*=\s*\{\{/g)) {
+    let depth = 0, j = m.index + m[0].length - 2;
+    for (; j < text.length; j++) { if (text[j] === "{") depth++; else if (text[j] === "}" && --depth === 0) break; }
+    const body = text.slice(m.index, j + 1);
+    for (const d of body.matchAll(/([A-Za-z]+)\s*:\s*(?:(["'`])([^"'`]*)\2|(-?\d+(?:\.\d+)?)\b)/g)) out.push({ prop: kebab(d[1]), value: d[3] ?? d[4], numeric: d[4] !== undefined, index: m.index + d.index });
+  }
+  for (const m of text.matchAll(/\b(fill|stroke|bgcolor)\s*=\s*(["'])([^"']*)\2/g)) out.push({ prop: m[1], value: m[3], index: m.index });
+  return out;
+}
+
+/** Run a check over the scan roots, self-scoped to repositories that have a design root. */
+export function scope(roots, excludes) {
+  const files = collect(roots, excludes);
+  return hasDesignRoot(files) ? files : [];
+}

package/detectors/bun_design_system_detector/checks/_map.json

@@ -0,0 +1,10 @@
+{
+  "design_dependency_flow": "coder.bun.design-dependency-flow",
+  "design_wagons_import": "coder.bun.design-wagons-import",
+  "design_tokens_pure": "coder.bun.design-tokens-pure",
+  "design_token_color": "coder.bun.design-token-color",
+  "design_token_hardcoded": "coder.bun.design-token-hardcoded",
+  "design_primitives": "coder.bun.design-primitives",
+  "design_connected": "coder.bun.design-connected",
+  "design_orphan_export": "coder.bun.design-orphan-export"
+}

package/detectors/bun_design_system_detector/checks/design_connected.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+// Detector: coder.bun.design-connected
+// Every app component that renders markup imports at least one design-system
+// element, so no UI surface is disconnected from the shared system.
+import { readRoots, readExcludes, readText, emit, locate } from "../../../lib/scan.mjs";
+import { scope, designOf, isComponentSource, masked, importsOf, designTarget } from "./_design.mjs";
+
+const RULE_ID = "coder.bun.design-connected";
+const violations = [];
+for (const file of scope(readRoots(), readExcludes())) {
+  if (!isComponentSource(file) || designOf(file)) continue;
+  const m = masked(file);
+  if (!m) continue;
+  const renders = m.code.search(/<\/[A-Za-z]|\/>/);
+  if (renders === -1 || importsOf(m.text).some((imp) => designTarget(file, imp.specifier))) continue;
+  violations.push({ rule_id: RULE_ID, file, ...locate(m.text, renders), evidence: "component renders markup but imports nothing from the design system" });
+}
+process.stderr.write(`bun-detector[design-connected]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/bun_design_system_detector/checks/design_dependency_flow.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+// Detector: coder.bun.design-dependency-flow
+// A design-system file imports only its own layer or a lower one:
+// tokens/foundations ← primitives ← components ← templates.
+import { readRoots, readExcludes, readText, emit, locate } from "../../../lib/scan.mjs";
+import { scope, designOf, importsOf, designTarget } from "./_design.mjs";
+
+const RULE_ID = "coder.bun.design-dependency-flow";
+const violations = [];
+for (const file of scope(readRoots(), readExcludes())) {
+  const here = designOf(file);
+  if (!here || here.layer === null) continue;
+  const text = readText(file);
+  for (const imp of importsOf(text ?? "")) {
+    const to = designTarget(file, imp.specifier);
+    if (to && to.layer !== null && to.layer > here.layer) violations.push({ rule_id: RULE_ID, file, ...locate(text, imp.index), evidence: `${here.layerName} imports upward into ${to.layerName} ("${imp.specifier}"); depend on the same or a lower layer` });
+  }
+}
+process.stderr.write(`bun-detector[design-dependency-flow]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/bun_design_system_detector/checks/design_orphan_export.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+// Detector: coder.bun.design-orphan-export
+// Every component a primitives/components/templates file exports is imported by at
+// least one other file: a higher design layer or app code. Re-exports through an
+// index.* barrel are not consumption. Dead exports are removed, not kept.
+import { readRoots, readExcludes, readText, emit, locate } from "../../../lib/scan.mjs";
+import { basename, extname } from "node:path";
+import { scope, designOf, importsOf, designTarget, masked, CODE_EXT } from "./_design.mjs";
+
+const RULE_ID = "coder.bun.design-orphan-export";
+const files = scope(readRoots(), readExcludes());
+const consumed = new Set();
+for (const file of files) {
+  if (basename(file).startsWith("index.")) continue;
+  for (const imp of importsOf(readText(file) ?? "")) {
+    if (!designTarget(file, imp.specifier)) continue;
+    const named = imp.clause.match(/\{([^}]*)\}/)?.[1] ?? "";
+    for (const n of named.split(",")) { const name = n.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]; if (name) consumed.add(name); }
+    const fallback = imp.clause.replace(/\{[^}]*\}/, "").replace(/\*\s+as\s+\w+/, "").split(",")[0].trim();
+    if (/^[A-Z]\w*$/.test(fallback)) consumed.add(fallback);
+  }
+}
+const violations = [];
+for (const file of files) {
+  const here = designOf(file);
+  if (!here || !(here.layer >= 1) || !CODE_EXT.has(extname(file)) || basename(file).startsWith("index.")) continue;
+  const m = masked(file);
+  for (const e of (m?.code ?? "").matchAll(/export\s+(?:default\s+)?(?:async\s+)?(?:function|const|let|class)\s+([A-Z]\w*)/g)) {
+    if (!consumed.has(e[1])) violations.push({ rule_id: RULE_ID, file, ...locate(m.text, e.index), evidence: `${here.layerName} export ${e[1]} is imported by no other file` });
+  }
+}
+process.stderr.write(`bun-detector[design-orphan-export]: ${violations.length} violation(s)\n`);
+emit(violations);

package/detectors/bun_design_system_detector/checks/design_primitives.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+// Detector: coder.bun.design-primitives
+// App components (outside the design root) render interactive controls through the
+// design-system primitive, not raw <button>/<input>/<select>/<textarea>.
+import { readRoots, readExcludes, readText, emit, locate } from "../../../lib/scan.mjs";
+import { scope, designOf, isComponentSource, masked } from "./_design.mjs";
+
+const RULE_ID = "coder.bun.design-primitives";
+const violations = [];
+for (const file of scope(readRoots(), readExcludes())) {
+  if (!isComponentSource(file) || designOf(file)) continue;
+  const m = masked(file);
+  for (const c of (m?.code ?? "").matchAll(/<(button|input|select|textarea)\b/g)) violations.push({ rule_id: RULE_ID, file, ...locate(m.text, c.index), evidence: `raw <${c[1]}> in app code; compose the design-system primitive instead` });
+}
+process.stderr.write(`bun-detector[design-primitives]: ${violations.length} violation(s)\n`);
+emit(violations);