adsa-cli 0.1.4 → 0.1.5

package/README.md

@@ -49,7 +49,7 @@ the version checked out in front of them instead of reading files and guessing.
 
 | Score | System | Repository | Package audited |
 | :-- | :-- | :-- | :-- |
-| 33/45 | Astryx · Meta | `facebook/astryx` | `@astryxdesign/core` |
+| 35/45 | Astryx · Meta | `facebook/astryx` | `@astryxdesign/core` |
 | 29/45 | Chakra UI | `chakra-ui/chakra-ui` | `@chakra-ui/react` |
 | 25/45 | React Spectrum · Adobe | `adobe/react-spectrum` | `@react-spectrum/s2` |
 | 25/45 | shadcn/ui | `shadcn-ui/ui` | `v4` |
@@ -60,12 +60,12 @@ the version checked out in front of them instead of reading files and guessing.
 | 19/45 | Base UI · MUI | `mui/base-ui` | `@base-ui/react` |
 | 19/45 | Carbon · IBM | `carbon-design-system/carbon` | `@carbon/react` |
 | 17/45 | Primer · GitHub | `primer/react` | `@primer/react` |
+| 15/45 | Untitled UI React | `untitleduico/react` | `@untitledui/react` |
 | 13/45 | Radix Primitives · WorkOS | `radix-ui/primitives` | `radix-ui` |
-| 13/45 | Untitled UI React | `untitleduico/react` | `@untitledui/react` |
 
 Two things follow, and both are the point of publishing this table.
 
-**45 is nobody's score.** The best-documented public design system reaches 33. The
+**45 is nobody's score.** The best-documented public design system reaches 35. The
 bands are anchored to that measured field rather than to a wish: **31+ agent-ready**,
 **24–30 good foundation**, **15–23 gaps to address**, **below 15 not ready**. A system
 in the low twenties is in the middle of the field, not failing.
@@ -77,6 +77,38 @@ on an excellent website scores low here and may well be the better system for pe
 Every row is reproducible: clone the repository and run `npx adsa-cli audit <clone>`.
 `npx adsa-cli reference` prints this table from the tool.
 
+## Systems that are not component libraries
+
+Plenty of design systems are not a package of React components with a guide per
+component, and that is a decision rather than an omission — a stylesheet and a class
+vocabulary survives contact with engineers on four different stacks, which is why
+small teams keep choosing it.
+
+**A stylesheet is read as a surface.** When nothing is importable, the class
+vocabulary is the API: the classes in the shipped stylesheet are counted as the
+components, elements and modifiers fold into the block they belong to
+(`card__title`, `card-footer` → `card`), utilities and state classes are left out, and
+a class counts as documented when an example applies it — `.dialog` in prose, or
+`class="dialog"` in an HTML block.
+
+**Examples are read in the language they are written in.** HTML, CSS, Vue, Svelte and
+Astro blocks count, alongside TypeScript, Swift and Kotlin.
+
+**Tokens are read from the stylesheet, not from a heading.** Custom properties
+declared at the root — including inside Tailwind's `@theme` — are named decisions in
+the format the browser itself reads, exactly as an `.xcassets` catalog or an Android
+`colors.xml` already was. A page documenting them counts whether or not its title
+contains the word "token", and the hex inside `--brand: #0af` is a definition, not a
+raw value to be penalised.
+
+**A dimension that cannot apply is dropped from the maximum.** A repository with no
+importable surface and no component source files at all is not asked whether every
+component has a guide: `docs-coverage` and `docs-freshness` are skipped and the score
+is out of 35, and the comparison against the field is recomputed on the same seven
+dimensions. This only happens when the shape is unambiguous — a repository full of
+`.tsx` files where the scan found no exports is this tool failing, and it keeps the
+low score and says so on the `scanned:` line.
+
 ## The nine dimensions
 
 | | Dimension | The question |

package/bin/adsa.mjs

@@ -21,7 +21,7 @@ import { scan } from "../lib/scan.mjs";
 import { RUBRIC, score, scoreFile } from "../lib/score.mjs";
 import { buildTodo, html, markdown } from "../lib/report.mjs";
 import { band, badgeEndpoint, badgeMarkdown } from "../lib/badge.mjs";
-import { REFERENCE, standing } from "../lib/reference.mjs";
+import { REFERENCE, scoredIds, standing } from "../lib/reference.mjs";
 import { exists, isDir } from "../lib/fsx.mjs";
 import { DIR, appendHistory, compare, readHistory, write } from "../lib/history.mjs";
 import { FIXES, applyFix } from "../lib/fix.mjs";
@@ -189,7 +189,11 @@ async function dispatch(command, args, flags, io, out, json) {
  */
 function scannedLine(facts) {
     const s = facts.scanned;
-    const parts = [`guides ${s.guides.length ? s.guides.join(", ") : "none found"}`, `source ${s.source.length ? s.source.join(", ") : "none found"}`];
+    // A stylesheet system has no source directory and is not supposed to: naming the
+    // file the classes were read from is the honest version of "source none found".
+    const source = s.shape === "classes" ? `classes from ${s.stylesheets.join(", ")}` : `source ${s.source.length ? s.source.join(", ") : "none found"}`;
+    const parts = [`guides ${s.guides.length ? s.guides.join(", ") : "none found"}`, source];
+    if (s.shape === "docs-only") parts.push("no component surface: two dimensions do not apply");
     if (s.colocatedGuides) parts.push(`${s.colocatedGuides} colocated`);
     if (facts.monorepo) parts.push(`repo-level files from ${basename(facts.repoRoot)}/`);
     return `  scanned: ${parts.join(" · ")}`;
@@ -286,7 +290,7 @@ function cmdAudit(dir, flags, out, json) {
                 out(delta.delta > 0 ? green(move) : delta.delta < 0 ? red(move) : dim(move));
             }
             // A score out of 45 answers nothing until you know what 45 is worth.
-            out(dim(standing(scored.total).sentence));
+            out(dim(standing(scored.total, scoredIds(scored)).sentence));
         }
     }
 

package/lib/reference.mjs

@@ -14,19 +14,36 @@ import { dirname, join } from "node:path";
 const here = dirname(fileURLToPath(import.meta.url));
 export const REFERENCE = JSON.parse(readFileSync(join(here, "..", "rubric", "reference.json"), "utf8"));
 
-/** Where a score sits in the field: how many of the reference systems it beats. */
-export function standing(total) {
-    const systems = REFERENCE.systems;
-    const below = systems.filter((s) => s.total < total).length;
+/**
+ * Where a score sits in the field: how many of the reference systems it beats.
+ *
+ * When dimensions do not apply — a system with no importable surface is not asked
+ * whether every component has a guide — the comparison is recomputed over exactly the
+ * dimensions that were scored. Otherwise a 9 out of 35 gets measured against thirteen
+ * systems scored out of 45, and the sentence is arithmetic about two different things.
+ */
+export function standing(total, applicable = null) {
+    const all = Object.keys(REFERENCE.systems[0].dimensions).length;
+    const ids = applicable && applicable.length && applicable.length < all ? applicable : null;
+    const comparable = (s) => (ids ? ids.reduce((n, id) => n + (s.dimensions[id] ?? 0), 0) : s.total);
+    const systems = [...REFERENCE.systems].map((s) => ({ ...s, comparable: comparable(s) })).sort((a, b) => b.comparable - a.comparable);
+    const max = ids ? ids.length * 5 : 45;
+    const below = systems.filter((s) => s.comparable < total).length;
     const best = systems[0];
+    const scale = ids ? ` on the ${ids.length} dimensions that apply here` : "";
     return {
         count: systems.length,
         below,
         best,
-        median: systems[Math.floor(systems.length / 2)].total,
+        median: systems[Math.floor(systems.length / 2)].comparable,
         sentence:
-            total >= best.total
-                ? `${total}/45 is at or above ${best.name} (${best.total}), the highest of the ${systems.length} public design systems measured with this rubric.`
-                : `${total}/45 sits above ${below} of the ${systems.length} public design systems measured with this rubric; ${best.name} leads at ${best.total}.`,
+            total >= best.comparable
+                ? `${total}/${max} is at or above ${best.name} (${best.comparable}), the highest of the ${systems.length} public design systems measured with this rubric${scale}.`
+                : `${total}/${max} sits above ${below} of the ${systems.length} public design systems measured with this rubric${scale}; ${best.name} leads at ${best.comparable}.`,
     };
 }
+
+/** The dimensions a run actually scored, in rubric order — the basis for a fair comparison. */
+export function scoredIds(scored) {
+    return scored.dimensions.filter((d) => !d.skipped).map((d) => d.id);
+}

package/lib/report.mjs

@@ -11,7 +11,7 @@
  */
 import { RUBRIC } from "./score.mjs";
 import { band as scoreBand, badgeColor, badgeMarkdown } from "./badge.mjs";
-import { standing } from "./reference.mjs";
+import { scoredIds, standing } from "./reference.mjs";
 
 /** What the accessibility dimension is called on each platform. */
 const A11Y_STAT_LABEL = {
@@ -66,7 +66,7 @@ export function html(facts, scored, history = []) {
     const verdict = scoreBand(scored.total, scored.max);
     const band = BAND_CLASS[verdict.id];
     const [verdictTitle, verdictLine] = VERDICT[verdict.id];
-    const field = standing(scored.total);
+    const field = standing(scored.total, scoredIds(scored));
     const dims = scored.dimensions;
     const live = dims.filter((d) => !d.skipped);
     const weakest = [...live].sort((a, b) => a.score - b.score).slice(0, 3);
@@ -698,7 +698,7 @@ export function markdown(facts, scored) {
         "",
         VERDICT[band][1],
         "",
-        standing(scored.total).sentence,
+        standing(scored.total, scoredIds(scored)).sentence,
         "",
         `| Dimension | Score | Evidence |`,
         `| :-- | :-- | :-- |`,

package/lib/scan.mjs

@@ -7,7 +7,19 @@ import { basename, dirname, join } from "node:path";
 import { exists, isDir, read, readJson, rel, walk, walkDirs } from "./fsx.mjs";
 import { COLOCATED_GUIDE, defaultGuideDirs, loadConfig, workspaceDirs } from "./config.mjs";
 
-const CODE_FENCE = /```(tsx|jsx|ts|js|typescript|javascript|swift|kotlin|kt)\s*\n([\s\S]*?)```/g;
+/**
+ * The languages a guide writes its examples in. HTML and CSS belong here for the same
+ * reason Swift does: a system distributed as a stylesheet and a class vocabulary
+ * documents itself in HTML, and reading only TypeScript reported its every example as
+ * absent — the tool then said "no examples" about a repository full of them.
+ */
+const CODE_FENCE = /```(tsx|jsx|ts|js|typescript|javascript|swift|kotlin|kt|html|vue|svelte|astro|css|scss)\s*\n([\s\S]*?)```/g;
+/** `--brand: #0af` is where a colour is *given* a name. The hex in it is the definition, not a raw value used in place of one. */
+const TOKEN_DEFINITION = /--[A-Za-z0-9_-]+\s*:[^;\n}]*/g;
+/** `--brand: #0af`, `--space-2: 4px` — a named decision in the format the browser itself reads. */
+const CUSTOM_PROPERTY = /(--[A-Za-z0-9_-]+)\s*:\s*([^;\n}]+)/g;
+/** Where a token is declared when it belongs to the system rather than to one component. */
+const GLOBAL_SCOPE = /(?:^|,|\s)(?::root|html|@theme|:host)\b|\[data-theme/;
 const PALETTE = "slate|gray|grey|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
 const RAW_PALETTE = new RegExp(`\\b(?:bg|text|border|ring|fill|stroke|from|to|via|divide|outline|shadow|decoration)-(?:${PALETTE})-\\d{2,3}\\b`, "g");
 const RAW_NEUTRAL = /\b(?:bg|text|border)-(?:white|black)\b/g;
@@ -76,7 +88,9 @@ export function scan(root, config, repoRoot = root) {
     facts.ci = readCi(repoRoot, pkg, repoPkg, platform.primary);
     facts.coverage = matchCoverage(facts.components, facts.guides);
     facts.freshness = checkFreshness(facts.guides, facts.symbols, facts.name, facts.ci);
-    facts.tokens = checkTokens(facts.guides, facts.ci, root, platform.primary);
+    facts.stylesheets = platform.primary === "web" ? findStylesheets(root, pkg, config) : [];
+    facts.shape = describeShape(root, config, platform.primary, facts.components);
+    facts.tokens = checkTokens(facts.guides, facts.ci, root, platform.primary, facts.stylesheets);
     facts.patterns = checkPatterns(facts.guides);
     facts.a11y = checkA11y(facts.guides, facts.ci, root, platform.primary);
     facts.verification = checkVerification(root, pkg, repoPkg, facts.ci, platform.primary);
@@ -156,6 +170,8 @@ function describeScan(facts, config, guideDirs) {
         repo: facts.repoRoot,
         guides: guideDirs.map((d) => rel(facts.root, d) || "."),
         source: [...config.source],
+        shape: facts.shape.kind,
+        stylesheets: (facts.stylesheets || []).slice(0, 3).map((f) => rel(facts.root, f)),
         colocatedGuides: facts.guides.filter((g) => g.colocated).length,
     };
 }
@@ -314,9 +330,134 @@ function findComponents(root, pkg, config, platform) {
             }
         }
     }
+    // Nothing importable anywhere. Before concluding "not a design system", ask the
+    // other question: is the surface a class vocabulary rather than an import list?
+    if (!out.size) return findClassComponents(root, pkg, config);
     return [...out.values()].sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
+/**
+ * What kind of thing this repository is, which decides which questions apply to it.
+ *
+ * "No components found" has two completely different meanings, and conflating them is
+ * how a stylesheet-and-conventions system got judged against a rubric written for an
+ * import list. If there are component source files and none of them parsed, that is
+ * this tool failing and the score should say so. If there are none at all, the repo is
+ * a different shape, and the dimensions that assume an importable API are not questions
+ * it can answer — so they are dropped from the maximum instead of scored as failures.
+ */
+function describeShape(root, config, platform, components) {
+    if (components.some((c) => c.kind === "class")) {
+        return { kind: "classes", surface: "CSS classes", componentFiles: 0 };
+    }
+    if (components.length) return { kind: "components", surface: "importable components", componentFiles: 0 };
+
+    const exts = platform === "swift" ? [".swift"] : platform === "android" ? [".kt"] : [".tsx", ".jsx", ".vue", ".svelte"];
+    const dirs = config.source.length ? config.source : ["."];
+    let componentFiles = 0;
+    for (const dir of dirs) {
+        componentFiles += walk(join(root, dir), exts, 6).filter((f) => !isNoiseFile(rel(root, f))).length;
+        if (componentFiles) break;
+    }
+    return componentFiles
+        ? { kind: "undetected", surface: null, componentFiles }
+        : { kind: "docs-only", surface: null, componentFiles: 0 };
+}
+
+/* ------------------------------------------------------- class-based systems */
+
+const CLASS_SELECTOR = /\.(-?[A-Za-z_][A-Za-z0-9_-]*)/g;
+/** State and layout classes are how a component behaves, not another component. */
+const CLASS_STATE = /^(?:is|has|js|no)-|^(?:active|open|closed|disabled|hidden|visible|selected|current|loading|error|success|warning|sr-only|visually-hidden|clearfix|container|wrapper|row|col|grid|flex|left|right|center)$/i;
+/**
+ * `mt-4`, `text-sm`, `w-full` — a utility names a value, not a thing. Deliberately
+ * narrow: the suffix has to be a scale step, so `text-field` and `border-box` survive
+ * as the components they are.
+ */
+const UTILITY_CLASS = /^[a-z]{1,6}(?:-[a-z]+)?-(?:\d{1,3}|xs|sm|md|lg|xl|\d?xl|full|auto|none|px)$/i;
+const PALETTE_CLASS = new RegExp(`^(?:bg|text|border|ring|fill|stroke)-(?:${PALETTE})-\\d{2,3}$`, "i");
+
+/**
+ * A design system distributed as a stylesheet, where what a consumer reaches for is a
+ * class name and not an import. It is a deliberate shape, not an unfinished one: it
+ * survives contact with engineers on four different stacks, which is exactly why teams
+ * without a designer keep choosing it.
+ *
+ * Reading only `exports` and JSX reported such a repository as having no components at
+ * all, and then judged its documentation against that zero. The class vocabulary *is*
+ * the API, so it is counted as one.
+ */
+function findClassComponents(root, pkg, config) {
+    const files = findStylesheets(root, pkg, config);
+    if (!files.length) return [];
+    const names = new Set();
+    for (const file of files) {
+        for (const m of selectorText(read(file) || "").matchAll(CLASS_SELECTOR)) names.add(m[1]);
+    }
+    const blocks = classBlocks([...names]);
+    // Under five and this is a page's own stylesheet; over three hundred and it is a
+    // utility framework, whose classes are values rather than components.
+    if (blocks.length < 5 || blocks.length > 300) return [];
+    const from = rel(root, files[0]);
+    return blocks
+        .map((slug) => ({ slug, name: pascal(slug), from, kind: "class", selector: `.${slug}` }))
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Selectors only: declarations are where `1.5rem` and `url(...)` live, and neither is a class. */
+function selectorText(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\{[^{}]*\}/g, "{}");
+}
+
+/**
+ * The blocks in a class vocabulary. `card__title--large` and `card-header` are parts
+ * of the card, not two more components, so both fold into it — the count answers
+ * "how many things does a consumer choose between", which is the question the
+ * coverage dimension goes on to ask a guide for.
+ */
+function classBlocks(names) {
+    const kept = unique(
+        names
+            .map((n) => n.replace(/__.*$/, "").replace(/--.*$/, "").replace(/^-+/, ""))
+            .filter((n) => n.length >= 3 && !CLASS_STATE.test(n) && !UTILITY_CLASS.test(n) && !PALETTE_CLASS.test(n)),
+    ).sort((a, b) => a.length - b.length || a.localeCompare(b));
+
+    const blocks = [];
+    for (const name of kept) {
+        if (blocks.some((b) => name.startsWith(`${b}-`))) continue;
+        blocks.push(name);
+    }
+    return blocks.sort();
+}
+
+/**
+ * The stylesheets this package actually ships, preferring what it declares over what
+ * happens to be lying around: an `exports` entry or `style` field is the file a
+ * consumer links, and a repository's own site CSS is not.
+ */
+function findStylesheets(root, pkg, config) {
+    const out = new Set();
+    const add = (value) => {
+        if (typeof value !== "string" || !/\.(css|scss)$/.test(value)) return;
+        const path = join(root, value.replace(/^\.\//, ""));
+        if (exists(path)) out.add(path);
+    };
+    for (const [key, value] of Object.entries(pkg.exports || {})) {
+        add(key);
+        add(typeof value === "string" ? value : value?.default || value?.style);
+    }
+    add(pkg.style);
+    add(pkg.main);
+    add(pkg.unpkg);
+    if (out.size) return [...out];
+    for (const dir of unique([...config.source, "styles", "css", "src", "."])) {
+        for (const file of walk(join(root, dir), [".css", ".scss"], dir === "." ? 0 : 4)) {
+            if (!/\.min\.css$/.test(file)) out.add(file);
+        }
+    }
+    return [...out].slice(0, 40);
+}
+
 /**
  * A registry ships components as source rather than as an import, and `registry.json`
  * declares which of its items are components: a block, an example and a chart are all
@@ -559,7 +700,10 @@ function guideFacts(root, file, text, colocated = false) {
         generated: GENERATED.test(text) || PROP_COMPONENT.test(text),
         hasA11y: A11Y_HEADING.test(text),
         rawPalette: unique([...(code.match(RAW_PALETTE) || []), ...(code.match(RAW_NEUTRAL) || [])]),
-        hex: unique(code.match(HEX) || []),
+        // Hex inside `--brand: #0af` is the token being defined. Counting it as a raw
+        // value punished the guide that does the exact thing this dimension asks for.
+        hex: unique(code.replace(TOKEN_DEFINITION, "").match(HEX) || []),
+        customProperties: unique([...code.matchAll(CUSTOM_PROPERTY)].map((m) => m[1])),
         body: text,
     };
 }
@@ -791,12 +935,15 @@ function matchCoverage(components, guides) {
     const documented = [];
     const missing = [];
     for (const c of components) {
-        const guide = bySlug.get(c.slug) || bySlug.get(depluralize(c.slug)) || bySlug.get(c.slug + "s") || byPrefix(guides, c.slug) || byMention(guides, c.name);
+        const mentioned = c.kind === "class" ? byClass(guides, c.slug) : byMention(guides, c.name);
+        const guide = bySlug.get(c.slug) || bySlug.get(depluralize(c.slug)) || bySlug.get(c.slug + "s") || byPrefix(guides, c.slug) || mentioned;
         if (guide) documented.push({ ...c, guide: guide.path });
         else missing.push(c);
     }
     const total = components.length;
-    return { total, documented: documented.length, missing: missing.map((c) => c.name), ratio: total ? documented.length / total : 0 };
+    // A class system's reader looks for `.dialog`, not `Dialog`: name the missing thing
+    // the way the person would have to type it.
+    return { total, documented: documented.length, missing: missing.map((c) => c.selector || c.name), ratio: total ? documented.length / total : 0 };
 }
 
 function depluralize(slug) {
@@ -807,6 +954,12 @@ function byPrefix(guides, slug) {
     return guides.find((g) => g.slug.length >= 4 && (slug.startsWith(g.slug + "-") || slug.startsWith(depluralize(g.slug) + "-")));
 }
 
+/** A class is documented where an example applies it: `.btn` in prose, `class="btn"` in HTML. */
+function byClass(guides, slug) {
+    const re = new RegExp(`\\.${slug}\\b|class(?:Name)?=["'\`][^"'\`]*\\b${slug}\\b`);
+    return guides.find((g) => re.test(g.body));
+}
+
 function byMention(guides, name) {
     const re = new RegExp(`(<|\\b)${name}\\b`);
     return guides.find((g) => re.test(g.body));
@@ -834,20 +987,29 @@ function checkFreshness(guides, symbols, packageName, ci) {
     };
 }
 
-function checkTokens(guides, ci, root, platform) {
-    const docs = guides.filter((g) => /token|colour|color|typography|spacing|motion|elevation|shadow|radius|theme|palette/i.test(g.slug + " " + g.title));
+function checkTokens(guides, ci, root, platform, stylesheets = []) {
+    // Two ways a guide can be about tokens. The name is the cheap one, and it fails on
+    // the system whose page is headed "Values" — so a guide that actually carries named
+    // custom properties counts as token documentation whatever it is called.
+    const named = /token|colour|color|typography|spacing|motion|elevation|shadow|radius|theme|palette|variable|value/i;
+    const docs = guides.filter((g) => named.test(g.slug + " " + g.title) || (g.customProperties || []).length >= 3);
     const rawHits = guides.flatMap((g) => g.rawPalette.map((c) => ({ guide: g.path, value: c })));
     const hexHits = guides.flatMap((g) => g.hex.map((c) => ({ guide: g.path, value: c })));
+    const source = findSourceTokens(root, platform, stylesheets);
+    // A `--duration-fast` in the stylesheet is a motion decision with a name, whether or
+    // not a heading anywhere spells the word "motion".
+    const documented = (re, headings, flag) =>
+        docs.some((g) => re.test(g.slug + g.title) || headings.test(g.body) || (g.customProperties || []).some((n) => re.test(n))) || Boolean(source && source[flag]);
     return {
         docs: docs.map((g) => g.path),
-        motion: docs.some((g) => /motion|duration|easing|transition/i.test(g.slug + g.title) || /^#{1,4}\s.*(motion|easing|duration)/im.test(g.body)),
-        spacing: docs.some((g) => /spacing|space|layout|grid/i.test(g.slug + g.title) || /^#{1,4}\s.*(spacing|space scale)/im.test(g.body)),
+        motion: documented(/motion|duration|easing|transition/i, /^#{1,4}\s.*(motion|easing|duration)/im, "motion"),
+        spacing: documented(/spacing|space|layout|grid/i, /^#{1,4}\s.*(spacing|space scale)/im, "spacing"),
         rawPalette: rawHits.slice(0, 30),
         rawPaletteCount: rawHits.length,
         hex: hexHits.slice(0, 20),
         hexCount: hexHits.length,
         lintEnforced: /(eslint|biome).*(token|palette)|no-restricted-syntax/i.test(Object.values(ci.scripts).join(" ")),
-        source: findSourceTokens(root, platform),
+        source,
     };
 }
 
@@ -857,7 +1019,26 @@ function checkTokens(guides, ci, root, platform) {
  * `colors.xml`/`themes.xml`. Real files, real counts — an agent can open either and
  * see the same semantic names a guide would otherwise have to spell out.
  */
-function findSourceTokens(root, platform) {
+function findSourceTokens(root, platform, stylesheets = []) {
+    // The web had no branch here at all, which meant the one file holding the answer —
+    // `:root { --colour-brand: … }` — was the only resource format this tool refused to
+    // open, while it happily read an asset catalog and an Android colors.xml.
+    if (platform === "web" && stylesheets.length) {
+        const names = new Set();
+        for (const file of stylesheets) {
+            for (const name of globalCustomProperties(read(file) || "")) names.add(name);
+        }
+        if (names.size < 3) return null;
+        const all = [...names];
+        return {
+            kind: "CSS custom properties",
+            files: stylesheets.slice(0, 4).map((f) => rel(root, f)),
+            count: all.length,
+            names: all.slice(0, 6),
+            motion: all.some((n) => /duration|easing|transition|motion|delay/i.test(n)),
+            spacing: all.some((n) => /space|spacing|gap|size|radius|inset/i.test(n)),
+        };
+    }
     if (platform === "swift") {
         const catalogs = walkDirs(root, [".xcassets"], 6);
         const colorSets = catalogs.flatMap((c) => walkDirs(c, [".colorset"], 3));
@@ -885,6 +1066,41 @@ function findSourceTokens(root, platform) {
     return null;
 }
 
+/**
+ * Custom properties declared at the root, where they are a decision the whole system
+ * shares. `--actionbar-height` inside `.ActionBar` is a local variable: counting it as
+ * a design token would let any CSS-modules repo claim a token system it does not have.
+ */
+function globalCustomProperties(css) {
+    const clean = css.replace(/\/\*[\s\S]*?\*\//g, "");
+    const names = new Set();
+    const stack = [];
+    let buf = "";
+    // A hand-rolled walk rather than a regex, because the block that matters nests:
+    // Tailwind's `@theme` holds `@keyframes`, and a pattern that stops at the first
+    // brace reads the largest token file in the repository as empty.
+    const global = () => stack.some((sel) => GLOBAL_SCOPE.test(sel));
+    const collect = (text) => {
+        if (!global()) return;
+        for (const prop of text.matchAll(CUSTOM_PROPERTY)) names.add(prop[1]);
+    };
+    for (const ch of clean) {
+        if (ch === "{") {
+            const cut = buf.lastIndexOf(";");
+            collect(buf.slice(0, cut + 1));
+            stack.push(buf.slice(cut + 1).trim());
+            buf = "";
+        } else if (ch === "}") {
+            collect(buf);
+            stack.pop();
+            buf = "";
+        } else {
+            buf += ch;
+        }
+    }
+    return names;
+}
+
 function checkPatterns(guides) {
     const files = guides.filter((g) => /pattern|template|recipe|layout|page|blueprint|composition/i.test(g.slug + " " + g.title));
     // A pattern is worth 5 only if it carries structure: states, traps, a skeleton.

package/lib/score.mjs

@@ -71,9 +71,10 @@ const SCORERS = {
 
     "docs-coverage"(f) {
         const c = f.coverage;
-        if (!c.total) return { score: 1, evidence: ["No importable components detected — check `source` in adsa.config.json."] };
+        if (!c.total) return { score: 1, evidence: [`${f.shape.componentFiles} component source files were read and none exported a component — check \`source\` in adsa.config.json.`] };
         const gate = f.verification.docChecks || f.verification.scoreGate;
-        const ev = [`${c.documented} of ${c.total} importable components have a guide (${pct(c.ratio)}).`];
+        const noun = f.shape.kind === "classes" ? "component classes" : "importable components";
+        const ev = [`${c.documented} of ${c.total} ${noun} have a guide (${pct(c.ratio)}).`];
         if (f.icons) ev.push(`${f.icons} icon or logo exports were set aside; nobody writes a guide per icon.`);
         if (c.missing.length) ev.push(`Undocumented, first few: ${c.missing.slice(0, 8).join(", ")}.`);
         ev.push(gate ? "CI runs a documentation check." : "Nothing in CI stops a new export from shipping without a guide.");
@@ -158,12 +159,32 @@ const SCORERS = {
     },
 };
 
+/**
+ * Dimensions this repository cannot answer, because of what it is rather than what it
+ * is missing. A system with no importable surface at all — a stylesheet, a token
+ * package, a documentation repo — has nothing for "does every component have a guide"
+ * to be about, and scoring that 1 out of 5 twice reports a shape as a failure.
+ *
+ * Only the unambiguous case skips. A repo full of `.tsx` files where the scan found no
+ * exports is this tool failing, and it keeps its low score and says so.
+ */
+function autoSkipped(facts, config) {
+    if (config.autoSkip === false || facts.shape.kind !== "docs-only") return new Map();
+    const why = `No importable components and no component source files in ${facts.scanned.package}: this dimension does not apply, so it is out of the maximum rather than scored as a failure.`;
+    return new Map([
+        ["docs-coverage", why],
+        ["docs-freshness", why],
+    ]);
+}
+
 /** @returns {{ total:number, max:number, dimensions:Array }} */
 export function score(facts, config = {}) {
     const skip = new Set(config.skip || []);
+    const auto = autoSkipped(facts, config);
     const dimensions = RUBRIC.dimensions.map((dim) => {
-        if (skip.has(dim.id)) {
-            return { id: dim.id, title: dim.title, score: null, max: 5, skipped: true, evidence: ["Skipped by configuration."], fixes: [] };
+        if (skip.has(dim.id) || auto.has(dim.id)) {
+            const why = skip.has(dim.id) ? "Skipped by configuration." : auto.get(dim.id);
+            return { id: dim.id, title: dim.title, score: null, max: 5, skipped: true, evidence: [why], fixes: [] };
         }
         const result = SCORERS[dim.id](facts);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "adsa-cli",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "description": "Score a design system on how well coding agents can use it, then fix what is missing.",
     "type": "module",
     "bin": {

package/rubric/reference.json

@@ -11,14 +11,14 @@
             "package": "@astryxdesign/core",
             "version": "0.5.4",
             "packageDir": "packages/core",
-            "total": 33,
+            "total": 35,
             "max": 45,
             "dimensions": {
                 "agent-instructions": 3,
                 "machine-surface": 5,
                 "docs-coverage": 3,
                 "docs-freshness": 3,
-                "tokens": 3,
+                "tokens": 5,
                 "patterns": 5,
                 "a11y": 3,
                 "verification": 5,
@@ -246,21 +246,21 @@
             }
         },
         {
-            "name": "Radix Primitives",
-            "org": "WorkOS",
-            "repo": "radix-ui/primitives",
-            "commit": "f7ecd5ab16",
-            "package": "radix-ui",
-            "version": "1.6.7",
-            "packageDir": "packages/react/radix-ui",
-            "total": 13,
+            "name": "Untitled UI React",
+            "org": "",
+            "repo": "untitleduico/react",
+            "commit": "c981a73bcd",
+            "package": "@untitledui/react",
+            "version": "0.0.0",
+            "packageDir": ".",
+            "total": 15,
             "max": 45,
             "dimensions": {
                 "agent-instructions": 3,
                 "machine-surface": 1,
                 "docs-coverage": 1,
                 "docs-freshness": 1,
-                "tokens": 1,
+                "tokens": 3,
                 "patterns": 1,
                 "a11y": 1,
                 "verification": 3,
@@ -268,13 +268,13 @@
             }
         },
         {
-            "name": "Untitled UI React",
-            "org": "",
-            "repo": "untitleduico/react",
-            "commit": "c981a73bcd",
-            "package": "@untitledui/react",
-            "version": "0.0.0",
-            "packageDir": ".",
+            "name": "Radix Primitives",
+            "org": "WorkOS",
+            "repo": "radix-ui/primitives",
+            "commit": "f7ecd5ab16",
+            "package": "radix-ui",
+            "version": "1.6.7",
+            "packageDir": "packages/react/radix-ui",
             "total": 13,
             "max": 45,
             "dimensions": {

package/skills/ds-audit/SKILL.md

@@ -104,7 +104,14 @@ reproduce any figure you are unsure of with `npx adsa-cli audit <clone>`.
 
 Two things to say out loud, because a reader will otherwise assume the opposite:
 
-- **45 is nobody's score.** The best-documented public system measured reaches 33.
+- **45 is nobody's score.** The best-documented public system measured reaches 35.
+- **Not every system is a component library.** A stylesheet with a class vocabulary is
+  a deliberate shape: the tool reads its classes as the surface and its HTML examples
+  as examples. If the `scanned:` line says `classes from <file>`, that is what happened,
+  and the coverage number is about classes.
+- **A score out of 35 is not a broken run.** When a repository has no importable
+  surface at all, the two dimensions that assume one are skipped and the maximum drops.
+  Say which dimensions were skipped and why; do not report it as 35/45.
   A number in the twenties is the middle of the field, not a failing grade.
 - **This is not a ranking of design systems.** It measures what a coding agent can
   find in the repository. A system whose documentation lives on an excellent website