ds-drift
Skill8 starsChanged 3 months agoMITView on GitHub
Review a branch, PR, or whole repo for design-system conformance. Report-only — verdicts, reviews, and remediation plans.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Report the gap the toolchain can't see: If tsc, eslint, or an existing lint rule would flag it, it is not a finding — it is noise that …
- Distinctive: line 20
Severity comes from policy, not per-run invention: Use the manifest's severity map (fall back to the playbook defaults) and honor its …
- Distinctive: line 85
Before finishing, run the review template's "Quality bar" checklist (or the plan template's, for sweep plans) against each file you wrote, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ds-drift
Judge whether work — increasingly, work produced by other models — conforms to this repo's design system, render a verdict a team can trust, and specify every required change precisely enough that the generating agent or a cheaper executor applies it without you. The review is the product. A noisy gate is an ignored gate, so precision outranks recall everywhere in this skill.
This skill is report-only and every output must survive a cold read — both terms, the family rules they summarize, and the plans/ directory conventions are defined in references/conventions.md. Read it now; it is short and load-bearing.
Skill rules
- Report the gap the toolchain can't see. If tsc, eslint, or an existing lint rule would flag it, it is not a finding — it is noise that erodes the gate's authority.
- Severity comes from policy, not per-run invention. Use the manifest's severity map (fall back to the playbook defaults) and honor its waiver ledger. Consistency between runs is what makes the verdict meaningful.
- Review files carry a
-review-slug (plans/NNN-review-<slug>.md) so reviews and plans read apart in the shared directory.
Done means
A gate/batch run is done when: the review file exists and survives a cold read; every blocking finding carries a verify command with an expected result; every finding is tagged introduced or pre-existing; every element of the Phase 2 scope was audited or named under "Not audited"; and the verdict recomputes mechanically from the stated counts and policy. Phase 5 checks exactly this before you finish.
Workflow
Phase 1 — Recon (always)
Manifest first. The conformance manifest is both the rulebook and your recon cache. Locate it in this order: a --manifest <path> argument → ds/MANIFEST.md + ds/tokens.json in the repo root → node_modules/<ds-package>/ds/ (design systems that publish their manifest; find packages by globbing node_modules/{*,@*/*}/ds/MANIFEST.md). Manifests are per-package: multiple hits are a monorepo consuming several DS packages, not an error — load each, judge every component and token against the manifest of the package that owns it (the package it is imported from, or whose token namespace it matches), and report per package. A component name claimed by two manifests is a conflict to report, never a guess. --manifest restricts a run to one. Read the severity policy, waiver ledger, exclusions table, component inventory, and synonym map — excluded paths are skipped entirely and listed under the review's "Not audited" line.
- Stamp check: three comparisons per manifest. (1) Schema — the header's
Manifest schemanumber against what this skill reads (schema 1–2; see the manifest spec); an unknown schema → stop and report, don't parse by guesswork. (2) Version — the header's package stamp against the installed version. (3) API hash — the header's hash against a recompute over the installed package's.d.tsfiles, per the spec's recipe; a matching version with a mismatched hash means the package moved without a version bump, which is exactly the staleness a version compare misses. On any mismatch, recordmanifest.stalein the review header with a degraded-confidence note — a scope-level condition, never a verdict-counted finding — and do not silently proceed as if current. - No manifest: derive a working inventory and token map from the DS package source or published types, say so in the report, and recommend running
/ds-doctor— the gate's precision is bounded by the rulebook's quality.
Then the standard recon: exact build/typecheck/lint/test commands (these become verification gates in every remediation spec and plan), repo conventions with exemplar files, the default branch and merge-base for gate scoping, and which lint rules already exist (feeds Skill Rule 1). In gate mode, also check plans/ for a ds-plan coverage map covering this branch's feature: a finding against an element the map marks Covered or Composable means the map was wrong — record a one-line "Map corrections" row in the index alongside the finding, so ds-plan's classification bar learns from it.
Phase 2 — Audit
Read references/review-template.md before auditing, not before writing — knowing the shape the evidence must land in changes what you collect. The skeleton you are filling:
Verdict + one-line why → header facts (Scope · Manifest status · Counts, introduced only · Pre-existing count · Not audited · Toolchain note) → Blocking (introduced), each finding carrying Evidence at
file:line, why-blocking with its policy source, and a remediation spec (Change / Verify → expected / STOP if) → Should fix → Advisory → Waived table → Pre-existing backlog → Recurrence counts.
Scope follows the mode:
- Gate (default): files changed since
git merge-base origin/<default> HEAD, plus their direct importers. Tag every findingintroduced(by this branch) orpre-existing(in touched files) — verdicts are rendered onintroducedonly; a gate that blames the branch for legacy debt gets bypassed. The tag is mechanical, not a judgment call: a finding isintroducediff its evidence lines are added or modified ingit diff <merge-base>...HEAD(a regression counts as introduced via the lines that removed the affordance); everything else in touched files ispre-existing. - Batch: gate scope per ref, plus one cross-set pass for divergence — the same pattern independently invented on multiple branches is invisible to any single-branch review and is exactly how parallel agents fork a design system. Read each ref in place —
git show <ref>:<path>,git diff <merge-base>...<ref>,git ls-tree— checkouts and worktrees are working-tree mutations (family rule 2). - Sweep: whole repo, effort dial applies —
quick(hotspots, top findings),standard,deep(every package, LOW-confidence items included).
Audit against the categories in references/audit-playbook.md — read it now: adoption, tokens, usage, a11y, extraction, each with the AI-generation failure signatures to watch for. For sweeps of any real size, fan out parallel read-only subagents per category. Subagents inherit nothing, so each prompt must include: the absolute path to the playbook plus the section headings to read (always including "Finding format"), the recon facts that scope the search, the manifest's waiver ledger and severity digest (so subagents can annotate findings that look waived — they still report them; matching and exclusion happen in Vet, never in a subagent), a findings-only instruction, and a verbatim copy of family rules 3–5.
For token findings, classify literals mechanically — don't eyeball color distance. Pipe the deduplicated literals into this skill's scripts/nearest_token.mjs (requires Node 18+), which reads its two inputs, writes nothing anywhere, and prints exact / near / none / unparsed with ΔE distances as JSON on stdout:
# Reads the token map and the literals below. Writes nothing; prints JSON to stdout.
node <this-skill-dir>/scripts/nearest_token.mjs ds/tokens.json - <<'LITERALS'
#64748b
rgb(15, 98, 254)
LITERALSThree things make this trustworthy, and all three are your responsibility:
- Use the absolute path to this skill's
scripts/directory, not a relative one — the audited repo's cwd has no such file, and a guessed path in a permission prompt reads as a script the user can't place. - Use the
-(stdin) form. It keeps the literals visible in the command the user approves, and it means no scratch file is written into the repo under audit (family rule 2). If the list is too long to inline, write the scratch file under the OS temp dir and say so. - Read the stderr summary before you use the results. It reports the token count, the threshold in effect, and any token the script had to skip. A skipped token cannot be matched against, which silently turns a real exact match into a
none— if the script warns, the token file is wrong and nononefrom that run is reportable.
The classes are the evidence. unparsed rows resolve manually — carry every one of them forward.
Phase 3 — Vet
Subagents and greps over-report. Before anything reaches a verdict or table, open every cited location yourself and confirm it. Expect these failure classes: by-design bespoke (marketing pages, brand moments — flag as "possibly intentional" at most); claimed replacement doesn't cover the used props (open the DS component's actual types and map every used prop before asserting a swap — this domain's signature false positive); already caught by toolchain (drop, per Skill Rule 1); waived (apply the ledger here — match glob × class, record the waiver id, exclude from the verdict but list in the review's Waived table); mis-attributed evidence; duplicates. Record rejections in the output index so they aren't re-litigated next run.
Phase 4 — Render
The modes diverge here:
- Gate / batch → write
plans/NNN-review-<slug>.mdper the review template. Render the verdict from introduced findings only: any blocking → NEEDS CHANGES; should-fix or advisory only → PASS WITH FINDINGS; none or waived-only → PASS.extraction.*findings are excluded from this tiering — they are options, not violations, so a branch whose only findings are extraction candidates is a PASS (candidates still listed under Advisory). Every blocking finding carries an inline remediation spec. No selection step — a gate that asks which violations to spec is not a gate. - Sweep → present the vetted findings table ordered by leverage, with extraction candidates presented separately after it (they are options for the DS owner, not problems ranked against violations). Ask which findings become plans; do not write thirty plans nobody asked for. Selected findings become
plans/NNN-<slug>.mdper references/plan-template.md, stamped with the current commit, excerpts from your own reads only, plus the index.
State violations plainly with evidence, keep severity exactly where policy puts it, prefer "conforms — nothing to report" over padding, and say what was not audited.
Phase 5 — Quality bar
Before finishing, run the review template's "Quality bar" checklist (or the plan template's, for sweep plans) against each file you wrote, and confirm every clause of Done means above. A run that skips this phase is not done.
Invocation variants
- Bare invocation → gate the current branch. If on the default branch or zero commits ahead, say so and offer
sweep. batch <ref> <ref> ...→ gate each ref plus the cross-set divergence pass; one review file per ref plus a batch summary.sweep→ full-repo audit with the selection step.quick/deepanywhere in the invocation set the effort dial; defaultstandard.- Category focus (
tokens,adoption,usage,a11y,extraction) → restrict any mode to that category. Composes:sweep tokens deep. coverage→ metrics only, no findings table, no plans: DS adoption rate, token compliance rate, per-package deltas since the last sweep. The drift dashboard between baselines. Baselines live in the index's "Coverage baselines" table — append a row each run; with no prior row, report absolutes and start the table.upgrade <version|changelog>→ impact audit for a DS version bump: affected call sites per breaking change, codemod-able vs. needs-judgment split, ordered upgrade plan.plan <finding-id|description>→ skip the audit; investigate just enough to spec one remediation properly and write a single plan.review-plan <file>→ critique an existing plan or remediation spec against the template's standards and tighten it.reconcile→ process what happened since last session: verify, refresh, retire. See references/closing-the-loop.md.--issues(modifier) → also publish reviews/plans as GitHub issues, per closing-the-loop.--manifest <path>(modifier) → override manifest discovery.executeis reserved and not implemented — this skill ships report-only. The seam exists in closing-the-loop for when dispatch-and-review is wanted.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

