[Bug]: components-manifest extractor: token refs lost for every other CSS rule and for nested rules; substring class matchers create false-positive groups

[dapsychyoo]

What happened?

extractComponentsManifest (packages/contracts/src/design-systems/components-manifest.ts) builds the component-inventory summary that is pasted into the agent's system prompt (## Reference component manifest). While packaging a third-party design system for Open Design we ran the extractor directly against our fixture and found three defects that make the inventory silently wrong. "Silently" is the problem: the agent is told the design system has components it doesn't have, and is not told about token wiring it does have — and then follows the prompt instruction "Prefer these manifest entries over inventing new component shapes" against bad data.

1. Token attribution drops every other CSS rule

extractSelectorTokenReferences uses

const rulePattern = /(?:^|[{}])\s*([^@{}][^{}]*?)\s*\{([^{}]*)\}/g;

The match consumes the rule's closing }. The next rule then has no [{}] anchor left to start from, so it is skipped, and its {/} braces serve as the anchor for the rule after it. Net effect: for consecutive flat rules, every second rule loses its token attribution. A :root block swallows the rule that follows it the same way (the :root rule is matched, continued, and its closing brace is consumed).

Minimal repro (any fixture, run against the built contracts module):

const { extractComponentsManifest } = await import('<repo>/packages/contracts/dist/design-systems/components-manifest.mjs');
const fixtureHtml = `<style>
.btn-a { color: var(--a); }
.btn-b { color: var(--b); }
.btn-c { color: var(--c); }
.btn-d { color: var(--d); }
</style>
<button class="btn-a">x</button>`;
const g = extractComponentsManifest({ brandId: 'repro', fixtureHtml }).groups.find((g) => g.id === 'buttons');
console.log(g.selectors);        // [".btn-a", ".btn-b", ".btn-c", ".btn-d"]
console.log(g.tokenReferences);  // ["--a", "--c"]   ← --b and --d are gone

extractCssSelectors is not affected (its pattern stops at { without consuming the body), which is why the summary shows all selectors but an arbitrary subset of tokens. In realistic CSS the loss is masked semi-randomly — repeated selectors (base rule + state rule) give a selector several chances to land on an "odd" position — so the symptom shows up as plausible-looking but understated token lists rather than an obvious failure.

2. Rules with nested blocks lose their tokens and produce garbage "selectors"

The same [^{}]* body cannot match a rule containing a nested block (CSS nesting is what Tailwind v4 emits for states by default):

const fixtureHtml = `<style>
:root { --chip-bg: #eee; --chip-hover: #ddd; }
.chip-demo { background: var(--chip-bg); &:hover { background: var(--chip-hover); } }
</style>
<span class="chip-demo">chip</span>`;

Result for the badges group: selectors: [".chip-demo"], tokenReferences: [] — and the token map internally attributes --chip-hover to the "selector" background: var(--chip-bg); &:hover, i.e. the declaration text before the nested block. The summary line becomes Badges, chips, and status labels: selectors .chip-demo; tokens none.

3. Substring class matchers create false-positive groups

Several classMatchers are unanchored substring tests: /form/i, /control/i, /input/i (inputs), /grid/i, /layout/i (layout), /status/i (badges), /button/i, /cta/i (buttons), /caption/i (typography). Any Tailwind utility in the fixture markup trips them:

• transition-transform → contains form → inputs group present: true
• grid-cols-2 → contains grid → layout group present: true
• the .select-none utility rule matches the \bselect\b selector matcher → inputs gains a selector

With the fixture above (one card, one chip, zero form controls) the prompt summary reads:

Available component groups:
- Form fields and controls: selectors none; tokens none
- Cards and panels: selectors .card-demo; tokens none
- Badges, chips, and status labels: selectors .chip-demo; tokens none
- Layout primitives: selectors none; tokens none

The agent is told the design system has form-field and layout components. It has neither.

Steps to reproduce

1. node --input-type=module with either snippet above (import extractComponentsManifest from the built @open-design/contracts — same behavior in the packaged app 0.16.1 and in current main; packages/contracts/src/design-systems/components-manifest.ts is unchanged since feat(design-systems): extract component manifests #2051).
2. Compare groups[].selectors with groups[].tokenReferences, and groups[].present with what the fixture actually contains.
3. Or end-to-end: install any design-system package whose components.html uses consecutive flat rules / Tailwind v4 nested output / common utilities in markup, and inspect the ## Reference component manifest block in the agent context.

Expected behavior

1. Every rule's var(--*) references are attributed to its selector — the token list should match what a human reads in the CSS (e.g. a lookahead (?=[{}])-style anchor, or a small brace-depth scanner instead of one regex).
2. Rules with nested blocks either parse (flatten one level) or at minimum attribute the pre-nesting declarations to the real selector — never to declaration text as a pseudo-selector.
3. Group membership from class names shouldn't fire on arbitrary substrings of utility classes; anchored patterns (like the existing /^btn(?:$|-)/i) avoid transition-transform → "form fields". If substring matchers stay, it would help to document the naming contract for third-party design systems (root class must match a group's selector matcher, e.g. .card-* not .rack-card) — right now a mismatch produces no warning, just an empty/absent group.

Happy to split this into separate issues if that's easier to track — filing together because all three live in the same extractor and were found in one packaging effort.

Open Design version

0.16.1 (extractor identical in current main)

[open-design-bot]

🎉 ✨ Welcome to Open Design, @dapsychyoo!

✨ 🔥 Lit the spark.

🌱 Your first contribution adds energy to the project. Thanks for showing up and helping Open Design grow.

💛 Thanks for helping Open Design grow. Keep building in the open. 🚀

🔗 Share on X (English) · 分享到 X（中文）

[lefarcen]

Hey @dapsychyoo — thanks for the extremely careful write-up. I read through packages/contracts/src/design-systems/components-manifest.ts, and this looks confirmed from the current extractor shape: extractSelectorTokenReferences is using a rule regex that consumes the closing brace, so consecutive flat rules can get skipped; the same [^{}]* body also can't represent nested CSS blocks; and several classMatchers are broad substring matches (/form/i, /grid/i, /status/i, etc.), which can misclassify utility classes.

I've labeled this as a bug and help wanted. Keeping the three symptoms together makes sense for now since they're all in the same extractor path and likely want one pass over the parser/matcher logic plus fixtures/tests. If you decide to open a PR for it, happy to review — especially if it adds coverage for consecutive rules, a nested-rule fixture, and the false-positive utility-class cases.

[lefarcen]

If you'd like to take this on, comment /claim and we can route it to you.
A PR with coverage for the consecutive-rule, nested-rule, and false-positive matcher cases would be especially helpful.

[lefarcen]

A fix is now in review in PR #6226. It addresses the three confirmed extractor problems from this thread in one pass: consecutive flat rules dropping token attribution, nested CSS rules losing token references / producing bogus selector text, and substring class matchers misclassifying utility classes.

Keeping #6224 open until #6226 lands, but the implementation path is now tracked there.

[lefarcen]

Another implementation is now open in PR #6250. It targets the same three confirmed extractor failures from this issue — consecutive flat rules dropping token attribution, nested CSS blocks leaking token refs, and substring class matchers over-classifying groups.

Keeping #6224 open until one of the linked PRs lands.

[lefarcen]

PR #6226 is open to address this. The fix corrects three bugs in the CSS component manifest extractor (packages/contracts/src/design-systems/components-manifest.ts):

1. Consecutive rule token loss — the CSS rule regex was consuming the closing }, causing every other rule to be dropped during tokenization.
2. Nested block failure — the [^{}]* body pattern couldn't handle nested blocks (e.g. Tailwind v4 variant states), so rules inside nested selectors were silently skipped.
3. Substring class matcher false positives — unanchored class matching created spurious groups for partial class-name matches.

All 150 design-system components.manifest.json files have been regenerated from the corrected extractor. The PR is currently approved by @mrcfps and waiting for CI re-dispatch and a QA pass before it can merge. This issue stays open until the fix lands.