component-conformance-review
Checks every component in the AST-derived inventory against its spec in components.md, flagging undocumented variants, !important, inline style= and unwrapped primitives. Use when a design-test run has finished token-conformance-review.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- component-conformance-review
- metadata
- { "cacheable": "false", "model_tier": "reasoning", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
- description
- Checks every component in the AST-derived inventory against its spec in components.md, flagging undocumented variants, !important, inline style= and unwrapped primitives. Use when a design-test run has finished token-conformance-review.
02 资源文件 8
- 参考文档agents/openai.yaml180 B
- 资产文件assets/output.template.md592 B
- 参考文档references/component-conformance-checklist.md2.2 KB
- 脚本scripts/derive-inventory.sh1.5 KB
- 脚本scripts/diff-inventories.sh2.2 KB
- 脚本scripts/lint-findings.sh1.5 KB
- 脚本scripts/parse-components-md.sh2.2 KB
- 参考文档skill.meta.yaml403 B
03 SKILL.md 正文
What It Does
Audits the project's UI components against components.md. The AST-derived component inventory is the subject; the contract is the standard. Every component used in source must appear in components.md with declared variants, states, and permitted compositions. Override sprawl (!important, inline style=, undocumented Tailwind combinations, shadcn primitives wrapped without spec) is a finding.
Use This When
For every design-test run, after token-conformance-review. The two together form the "is the contract followed at the source level" pair.
Inputs
- Read
docs/instructions/design-system/components.md. - Read the contract-summary from
design-system-coverage(declared component clauses). - Read
references/component-conformance-checklist.mdbefore scanning.
Procedure
The set difference between source and contract is deterministic, drive it with the scripts. Reserve LLM judgment for severity and the "is this primitive correctly wrapped" question.
- Run
scripts/derive-inventory.sh [components-dir]→<name>\t<source-file>TSV. The script already excludes tests, stories, type decls, barrels, and lower-case helpers. - Run
scripts/parse-components-md.sh <components.md>→<name>\t<variants-csv>\t<states-csv>TSV. Empty CSV slots are-. - Run
scripts/diff-inventories.sh --source <derived> --declared <parsed>. Each row is a deterministic gap:in-source-not-declared\tName\t<file>→documentation-driftfinding, medium.declared-not-in-source\tName\t-→documentation-driftfinding (contract references a non-existent component), medium to high depending on whether the contract is what the team intends to build.
- Run
runtime/scripts/design/scan-overrides.shto enumerate!important, inlinestyle=, arbitrary Tailwind brackets, undocumented utility combos. The LLM decides whether each hit is a missing prop on a declared component or genuine code smell. - For each declared component, verify its declared variants are implemented in the source file. Missing variant →
componentfinding, high.
Output Contract
- Match
assets/output.template.md.contract_refiscomponents.md → <ComponentName>orpatterns.md → override budget. - Default severity
highfor missing-variant findings,mediumfor override sprawl,lowfor cosmetic deviations. - Output must pass
scripts/lint-findings.sh(exit 0).
Escalate / Stop Conditions
- Ask when
components.mdhas no entries: defer todesign-system-coverage(tier likelybare). - Warn when the inventory exceeds 100 components: the audit may need to be chunked.
Resources
references/component-conformance-checklist.mdscripts/derive-inventory.sh: AST-ish inventory ofsrc/components/**.scripts/parse-components-md.sh: declared inventory + variants/states fromcomponents.md.scripts/diff-inventories.sh: set difference between source and declared.scripts/lint-findings.shassets/output.template.mdagents/openai.yaml
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.