feat(design-systems): check the components against the sheet they claim to use

"The snippets use the tags from the sheet" was a relation nobody could verify.
Now it is three checks, and all three currently fail SILENTLY in this codebase:

  unknown             `var(--x)` where the system declares no `--x`. Renders as
                      nothing at all — no error, no failing test, no visual clue
                      beyond the element quietly not being styled.
  superseded literals a value the sheet said to stop writing, paired with the
                      token to write instead. Only possible because `supersedes`
                      is declared rather than inferred.
  local definitions   custom properties a snippet mints for itself instead of
                      reusing the sheet's — the bloat a shared sheet exists to
                      prevent, where a value stops being reused and starts being
                      restated per component.

The first is not hypothetical. Writing DesignSystemsView.vue earlier in this
same session I used `--color-accent` throughout; it does not exist, and nothing
in the toolchain noticed. This check is the thing that would have.

A token that is both defined and read locally is reported ONCE, as an unknown
reference — "--btn-bg does not exist in the sheet" is the more precise statement
of the same problem, and reporting both would double-count one fact.

Literal matching is boundary-aware and case-insensitive: `#fff` must not fire
inside `#ffffff` (different colours, and a finding on the wrong one sends
someone to change correct code), while `#FFFFFF` in a rulebook has to match
`#ffffff` in a stylesheet — the same trap `normalize_hex` exists for.

Snippets with nothing to report are omitted entirely. A list of everything that
is fine is a list nobody reads twice — the same principle the auto-inject menu
and the drift panel are both built on.

Two integration mistakes fixed while wiring it: `list_snippets` returns
`(rows, total)` and caps its limit at 100, and `get_snippet` returns a Note
model rather than a dict. The list rows carry a preview, not the code, so the
check reads each full body — checking the preview would have reported on a
truncation.

frontend/src/api/designSystems.ts

@@ -178,3 +178,27 @@ export interface StylesheetResult {
  *  rather than restated per element. */
 export const fetchStylesheet = (id: number) =>
   apiGet<StylesheetResult>(`/api/design-systems/${id}/stylesheet`);
+
+export interface SnippetFinding {
+  snippet_id: number;
+  title: string;
+  /** References that resolve against the sheet. */
+  used: string[];
+  /** `var(--x)` where the system has no `--x` — renders as nothing at all. */
+  unknown: string[];
+  /** Literals the sheet says to stop writing, paired with what to write. */
+  superseded_literals: { literal: string; use_instead: string }[];
+  /** Custom properties the snippet mints for itself instead of reusing. */
+  local_definitions: string[];
+}
+
+export interface SnippetCheck {
+  design_system_id: number;
+  checked: number;
+  /** Only snippets with something to act on; clean ones are omitted. */
+  findings: SnippetFinding[];
+}
+
+/** Which recorded snippets disagree with this design system's sheet. */
+export const checkSnippets = (id: number) =>
+  apiGet<SnippetCheck>(`/api/design-systems/${id}/snippet-check`);

frontend/src/views/DesignSystemsView.vue

@@ -29,6 +29,7 @@ import {
   fetchDesignSystems,
   fetchDesignTokens,
   fetchResolvedTokens,
+  checkSnippets,
   fetchStylesheet,
   importFromRulebook,
   updateDesignSystem,
@@ -37,6 +38,7 @@ import {
   type DesignToken,
   type ImportReport,
   type ResolvedToken,
+  type SnippetCheck,
   type StylesheetResult,
 } from "@/api/designSystems";
 import { listRulebooks, type Rulebook } from "@/api/rulebooks";
@@ -433,6 +435,33 @@ watch([selectedId, ownTokens], () => {
 
 const duplicateEntries = computed(() => Object.entries(sheet.value?.duplicates ?? {}));
 
+// --- do the snippets use the sheet? -----------------------------------------
+
+const snippetCheck = ref<SnippetCheck | null>(null);
+const checkingSnippets = ref(false);
+
+/** The component layer checked against the sheet.
+ *
+ *  Run on demand rather than on open: it reads every snippet's full body, which
+ *  is a real cost, and the answer only changes when the sheet or the snippets
+ *  do. */
+async function runSnippetCheck() {
+  if (selectedId.value === null || checkingSnippets.value) return;
+  checkingSnippets.value = true;
+  try {
+    snippetCheck.value = await checkSnippets(selectedId.value);
+  } catch {
+    snippetCheck.value = null;
+    toast.show("Couldn't check the snippets", "error");
+  } finally {
+    checkingSnippets.value = false;
+  }
+}
+
+watch(selectedId, () => {
+  snippetCheck.value = null;
+});
+
 // --- import from a rulebook -------------------------------------------------
 
 const rulebooks = ref<Rulebook[]>([]);
@@ -693,6 +722,66 @@ function isColourish(value: string): boolean {
             </template>
           </section>
 
+          <!-- Do the components use the sheet? -->
+          <section class="ds-section">
+            <div class="section-head">
+              <h2>Components using this sheet</h2>
+              <button
+                class="btn-ghost btn-small" :disabled="checkingSnippets"
+                @click="runSnippetCheck"
+              >
+                {{ checkingSnippets ? "Checking…" : "Check snippets" }}
+              </button>
+            </div>
+            <p class="section-note">
+              Snippets are the component layer — buttons, tables, input schemes —
+              and they are meant to use the tags this sheet declares. This finds
+              the three ways that goes wrong silently.
+            </p>
+
+            <template v-if="snippetCheck">
+              <p class="section-note">
+                <strong>{{ snippetCheck.checked }}</strong> snippets checked ·
+                <strong>{{ snippetCheck.findings.length }}</strong> with something
+                to act on
+              </p>
+
+              <p v-if="!snippetCheck.findings.length" class="muted">
+                Nothing to report. Every snippet checked uses tags this system
+                declares, writes no superseded literals, and mints no tokens of
+                its own.
+              </p>
+
+              <ul v-else class="finding-list">
+                <li v-for="f in snippetCheck.findings" :key="f.snippet_id">
+                  <router-link :to="`/snippets/${f.snippet_id}`" class="finding-title">
+                    {{ f.title || `Snippet #${f.snippet_id}` }}
+                  </router-link>
+
+                  <p v-if="f.unknown.length" class="finding-line">
+                    <span class="spec-status violated">renders as nothing</span>
+                    references
+                    <code v-for="name in f.unknown" :key="name">{{ name }}</code>
+                    — no such token in this system.
+                  </p>
+
+                  <p v-if="f.superseded_literals.length" class="finding-line">
+                    <span class="spec-status missing">write the token instead</span>
+                    <span v-for="s in f.superseded_literals" :key="s.literal">
+                      <code>{{ s.literal }}</code> → <code>{{ s.use_instead }}</code>
+                    </span>
+                  </p>
+
+                  <p v-if="f.local_definitions.length" class="finding-line">
+                    <span class="spec-status missing">defines its own</span>
+                    <code v-for="name in f.local_definitions" :key="name">{{ name }}</code>
+                    — a value restated here rather than reused from the sheet.
+                  </p>
+                </li>
+              </ul>
+            </template>
+          </section>
+
           <!-- Import from a rulebook -->
           <section class="ds-section">
             <div class="section-head">
@@ -1330,6 +1419,51 @@ function isColourish(value: string): boolean {
   gap: 0.35rem;
 }
 
+.finding-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.finding-list li {
+  padding: 0.6rem 0;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.finding-title {
+  font-weight: 500;
+  color: var(--color-text);
+}
+
+.finding-line {
+  margin: 0.3rem 0 0;
+  font-size: 0.85rem;
+  color: var(--color-text-secondary);
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.spec-status {
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 0.1rem 0.45rem;
+  border-radius: var(--radius-sm);
+  flex: none;
+}
+
+.spec-status.violated {
+  background: var(--color-priority-high-bg);
+  color: var(--color-priority-high);
+}
+
+.spec-status.missing {
+  background: var(--color-priority-medium-bg);
+  color: var(--color-priority-medium);
+}
+
 .sheet {
   background: var(--color-bg);
   border: 1px solid var(--color-border);