v2.9.0 — Gate 3 grades the token system, not the colour notation

Gate 3 grades the token system, not the colour notation

The skill was run against a live site as a working test. The audit it produced failed that page's design system because its colours were written in hex. That was the gate's fault, not the page's.

Hex, rgb and OKLCH are notations. A design system is defined by something else: whether tokens are canonical, whether roles are semantic, whether the same colour means the same thing everywhere. Six tidy hex tokens used consistently are a good system. Two hundred chaotic oklch() calls are not.

---

Changed

Gate 3 is now design-token integrity.

• One canonical :root — no token declared twice with conflicting values
• Component colours come from semantic tokens; a raw literal is allowed only as a stated exception
• Light and dark define the same roles, not ad-hoc pairs
• Hover, focus and disabled reuse the scale instead of inventing colours
• Type scale with clamp(), spacing on a 4px grid, all values as custom properties

Notation is a documented default, not a pass condition. OKLCH stays what the skill writes — equal lightness steps hold across hues, and a contrast fix is one number — but a consistent hex or rgb system passes the gate.

Updated in SKILL.md, quality-gates.md, checklists/global-design-review.md and the project CLAUDE.md.

The banned pattern "hex colors when OKLCH equivalents are available" is gone. What is actually banned is mixing notations inside one system, or a token defined twice with different values.

Converting a palette now carries an instruction: convert numerically and diff the result. An eyeballed "perceptual equivalent" changes the brand colour under cover of a colour-space migration. This was written after the skill produced three such approximations in a real audit and had them caught — the worst was off by 5% lightness and 10° of hue.

Added

verify-rendered.mjs gained a token-conflict check, and it is a hard failure. It reports any custom property declared twice in :root with different values. On the first real page it ran against it found:

FAIL Gate 3 token-conflict: --accent: #bd492e vs #b5462d

Those two values are 1.7% apart in lightness and 0.3° in hue — oklch(55.76% 0.1554 34.5) against oklch(54.07% 0.1497 34.2). No eye separates them, which is why the drift survived. No notation check would ever have surfaced it.

The old literal count remains, demoted to a warning that asks for justification rather than a rewrite:

N rule(s) hold a colour literal rather than a token — confirm each is a stated exception, not drift

Verified

Check	Result
Runner self-test	clean fixture exit 0, defective fixture exit 1
New check against a live site	found a real token conflict unaided
Test suites	42 + 73 pass
gds doctor	installed copy matches source

Upgrading

git pull
python scripts/gds install --tool=claude-code /path/to/your-project
python scripts/gds doctor /path/to/your-project

If you had adopted the old Gate 3 literally, the practical change is this: stop rewriting working hex palettes into OKLCH for the sake of the gate, and start checking that no token is defined twice.

Full detail: CHANGELOG.md.

v2.8.1 — dead paths, found by walking a clean install

Dead paths, found by walking a clean install

A verification pass over a freshly installed copy resolved every file path named in the tree — 936 of them. Three classes did not resolve, one of them a regression introduced by 2.8.0.

If you installed 2.8.0, take this update. Two MCP resources were returning a missing file.

---

Fixed

• MCP server, broken by the 2.8.0 move. mcp-server/server.py read the handoff and component-spec templates from templates/specs/, which 2.8.0 moved into skills/global-design/templates/specs/. Both gds://templates/frontend-tz and gds://templates/component-spec returned a missing file. The test suites did not catch it — they never exercise resource paths. All seven _read_repo_file targets were audited and now resolve.
• Two paths carrying the skills/global-design/ prefix, in rules/20-rendered-verification.md and templates/specs/design-system-master.md. After install the tree is flat, so the prefix points at nothing. This is the defect v2.1.4 stripped from 24 files, reintroduced by files added since.
• Sixteen references to directories that are not bundled and cannot be. examples/ alone is 167MB of before-and-after imagery; redesigns/ and demo/ are repository material. Written as bare relative paths in rules/, patterns/, recipes/, agents/ and references/, they read like skill files and led nowhere once installed. They are now repository URLs, which resolve for a reader and stop pretending to be part of the bundle.
• task-routing.md routing-version footer was still stamped v2.7.0; 2.8.0 missed it. It is a release surface and moves with the other four.

Verified on a clean gds install --tool=all

Check	Result
gds doctor	11 of 11
File paths named across the installed tree	936 checked, 0 dead references to skill files
MCP server import + every exposed resource	7 of 7 read
verify-rendered.mjs self-test	clean fixture exit 0, defective fixture exit 1
Eval suite structure	14 cases, 6 categories, 0 problems
Test suites	42 + 73 pass
Release gate	19 of 19, score 95

Upgrading

git pull
python scripts/gds install --tool=claude-code /path/to/your-project
python scripts/gds doctor /path/to/your-project

Full detail: CHANGELOG.md.

v2.8.0 — the skill folder becomes a real skill

Superseded by v2.8.1. This release moved templates/ into the skill folder but left mcp-server/server.py reading the old path, so the gds://templates/frontend-tz and gds://templates/component-spec resources return a missing file. Take 2.8.1 instead.

The skill folder becomes a real skill

An audit of the installed copy against the repo found the two had diverged in both directions. ~/.claude/skills/global-design/SKILL.md was running a v2.1.4 body — no e-commerce row, no one-shot build, no rendered-verification step, Next.js 15 in the stack table — while carrying a hand-written resource index the repo never had. Three months of routing work shipped to the repo and never reached the thing that actually loads.

Pulling that thread found the cause underneath it: skills/global-design/ was never a self-contained skill. SKILL.md named 46 files that lived at the repo root and only arrived beside it at install time. This release closes that boundary, turns the reference graph back into a tree, and gives the skill two things it can run instead of describe.

	before	after
Broken references in the skill folder	46	0
Reference cycles	57	0
Depth violations	37	0
Executed evals	none	14 of 14 pass
Overall audit score	49	95
Release gate	15 of 19	19 of 19

---

Restructured

• references/, agents/, templates/ and evals/ moved into skills/global-design/. They now sit where Anthropic's layout puts them. The installer bundles nine repo-root directories instead of twelve, and copies agents into .claude/agents/ from the new path. Post-install the tree is identical to before, because everything still flattens into the skill folder.
• The resource index lives in SKILL.md. All 28 reference catalogs, 11 agents and 7 templates are direct links from the entry point, plus a directory map for the nine bundled dirs. Anthropic's guidance is one hop; a separate resource-index.md made it two, so that file is gone. The four sibling files — task-routing.md, quality-gates.md, operating-principles.md, output-formats.md — are linked for the first time. Until now nothing in SKILL.md pointed at them, so roughly 35KB of routing detail and gate criteria never loaded.
• The reference graph is a tree again. Catalogs linked up to the agents that read them, sibling catalogs linked both ways, and 103 files named themselves in their own version footer. Upward links to agents/* are dropped from eight data files, one direction is removed from twelve mutually-linked pairs, and the self-naming footers are gone. Nothing became unreachable: SKILL.md links every one of these files directly.
• Path convention stated. Every path resolves from the skill root, not from the file that mentions it. The convention was already universal in the library and nowhere written down.

Added

• scripts/verify-rendered.mjs — Decision Pipeline step 12 stops being prose. Step 12 demanded rendered proof and shipped no way to produce it; every mechanical check lived as a paste-into-DevTools snippet. The runner loads a URL in Playwright, light and dark, at 390px and 1280px, and reports horizontal overflow (Gate 5), text hidden by -webkit-text-fill-color (Gate 6), sub-44px touch targets (Gate 5), images without width/height (Gate 7), vh where dvh belongs (Gate 5), and hex/rgb/hsl where OKLCH belongs (Gate 3). Exits 1 on a hard failure, so it can gate a deploy; --json for machine use.

  node scripts/verify-rendered.mjs https://example.com

• evals/fixtures/ — a self-test for that runner. rendered-defects.html plants one instance of each check; rendered-clean.html plants none. Defects → 8 failures, 12 warnings, exit 1. Clean → 0 / 0, exit 0.

• evals/agent-cases/ — 14 behavioural evals that get executed, not described. Six categories: discovery, functional, edge-cases, negative, regression, adversarial. Graded on what the answer contains and avoids rather than on prose quality. The regression case pins the stack majors so a stale Next.js 15 cannot come back unnoticed; the adversarial case checks that a fake countdown and a fake stock counter get refused, not built. The one-shot build case needs a long leash — it produced a seven-page site and timed out twice before finishing inside fifty minutes.

  python run_evals.py run skills/global-design/evals/agent-cases \
    --runner "claude -p -" --stdin-query --results results.jsonl

• Nine more trigger evals (15 → 24). Five positives for capabilities added since v2.5.0 that had no coverage: one-shot build, e-commerce, rendered verification, reference extraction, GSAP scroll-pinning. Four hard negatives drawn from the scope boundaries: native mobile UI, HTML email, logo and brand identity, print. The three existing negatives — SQL, Redis, CSV parsing — sit nowhere near the decision boundary and prove nothing.

• An install-drift check. gds doctor gained a tenth item that byte-compares the six copied files against the source and names the ones that diverged. The resource dirs were already junctions and stayed current; only these six could drift silently. Run doctor after every pull.

• Tables of contents in 38 files. Every file over 100 lines in rules/, blueprints/, checklists/ and references/tech-standards.md now opens with a ## Contents list, matching the pass already done across references/. Past 100 lines a partial read hides the file's scope. Insertions only.

Fixed

• Stack re-verified against Tier-1 sources on 2026-09-08. Next.js 16.3.4 stable with Turbopack, the proxy file convention and Cache Components; React 19.2.7; Tailwind 4.3; GSAP's full plugin set free; WCAG 2.2 still the current W3C Recommendation. The runtime copy had been saying Next.js 15.
• Every time-sensitive statement ruled on. All 80 findings from the staleness scan carry a claim and a verdict: 75 dismissed with a written reason per class — WCAG success-criterion identifiers such as 1.4.3 label clauses in a published Recommendation, per-file edit stamps are not release surfaces, Baseline years are facts about the past — and 5 real framework versions verified against the source fetched that day. 91 claims, 0 unresolved.
• Frontmatter name aligned to the directory, as the spec requires. The package name in manifest.yaml stays global-design-skill.
• Description rewritten. Keeps every trigger phrase, drops the internal mechanics, and states the scope boundaries — native mobile UI, email templates, print, brand identity — so the negative cases have something to match. 852 of the 1024 allowed characters.
• Two genuinely broken links. scripts/tokens-to-css.js in the Figma integration docs is a script the reader's project owns, not one this package ships. The rendered-verification runner ships inside the skill folder instead of being named from a path that is not bundled.
• gds install no longer copies dot-directories out of skills/global-design/. Local working state was being copied into installs, which could plant a second SKILL.md inside the installed skill folder.
• Portability. A machine-specific /var/www/... path in a live-audit snippet became a placeholder, and three grep examples moved from the GNU-only \s to the POSIX [[:space:]].

---

Upgrading

Re-run the installer — the layout changed, and an install made before this release still has references/, agents/ and templates/ copied from the old locations:

git pull
python scripts/gds install --tool=claude-code /path/to/your-project
python scripts/gds doctor /path/to/your-project

doctor should report ten passes. The drift check is the new one; if it names a file, re-run the install.

Full detail: CHANGELOG.md.

v2.7.0 — Motion personality, GSAP reference, effects extraction

Five external skills reviewed (zanwei/design-dna, lottiefiles/motion-design-skill, AThevon/genjutsu, cloudai-x/threejs-skills, greensock/gsap), and only the gaps taken. None was adopted wholesale — their weaker conventions (raw hex, force-filled schemas, unpinned CDN versions) were deliberately left behind.

Added

• references/gsap-patterns.md — the library's biggest coverage gap. GSAP previously existed only as scattered snippets in a blueprint and the parallax pattern. Now: tool-choice table with the bundle cost of each tier (CSS → motion/react → GSAP), useGSAP() scoping for React, timeline position parameter, stagger grid distribution, ScrollTrigger.batch, pin/scrub, containerAnimation for horizontal tracks, current SplitText.create() API (autoSplit, mask, aria), gsap.matchMedia() as the reduced-motion gate, and five failure modes that produce working-but-broken scroll animations. Licensing verified against the GreenSock repository at 3.15.0: the full plugin set, SplitText and MorphSVG included, is free for commercial use.

Extended

• rules/05-animation.md — Motion Personality (4 archetypes mapping MOTION_INTENSITY to concrete duration / easing / overshoot values), the three motion layers (primary / secondary / ambient) as the diagnostic for flat-feeling builds, distance-scaled duration, exits at 65–75% of their entrance, the frequency rule, new R13 (no scale(0), third-of-screen travel limit, third-of-elements limit), and a symptom→cause troubleshooting table.
• references/motion-systems.md — spring stiffness/damping table with the damping-ratio explanation, and a context-based overshoot budget (errors at 0%).
• references/3d-animations.md — post-processing pass table with cost ratings (bloom, DOF, vignette, chromatic aberration, noise, SSAO) and the banding fix; custom-shader minimum (uniforms over state, lerped pointer, noise-type selection).
• recipes/extract-design-from-reference.md — Step 2b, the effects layer: code-signal detection for live sites (<canvas>, three/pixi/ogl, GSAP/lenis, feTurbulence, cursor: none), per-effect record format with confidence marker, four cost tiers, mandatory fallback above css tier. Effects inventory added as the 4th artifact. The source skill's force-fill rule is explicitly rejected — an absent effect is absent, not an empty row.
• templates/specs/design-system-master.md — Effect fallback and Fallback triggers in the motion budget.

Wired in

skills/global-design/SKILL.md (frontmatter 2.7.0, Task Routing row, domain enumeration), skills/global-design/task-routing.md (Effects table + knowledge lookup), CLAUDE.md, README.md (badge, references tree 27 → 28), agents/motion-designer.md (new Phase 6 — Personality and layers), checklists/wow-effects-checklist.md (+10 GSAP items), integrations/claude-code/CLAUDE.md (motion rules + 4 banned patterns).

Verified

73 tests pass · 0 broken links · no orphaned files · LF endings throughout.

v2.6.0 — E-commerce blueprint + auth screens pattern

Coverage gaps from the v2.5.0 audit closed: the two most-built surfaces the library didn't cover.

Added

• blueprints/ecommerce-from-scratch.md — 10th build protocol: PLP (filters, card anatomy, pagination strategy), PDP (gallery/LCP discipline, fixed buy-box order, variant rules, sticky mobile add-to-cart), cart (real-total transparency, collapsed promo field), checkout (guest-first, one column, 12-element form budget, full autocomplete map, payment-error state), confirmation. Grounded in Baymard 2026 data: ~70% average cart abandonment — unexpected costs 48%, forced account creation 26%, checkout complexity 18%. Dark-pattern boundary restated for commerce (no fake scarcity, no drip pricing, no preselected add-ons).
• patterns/product-ui/auth-screens.md — the auth flow beyond sign-in (which stays in forms.md Pattern 1): sign-up (live requirement checklist instead of a strength meter, no confirm-password), forgot/reset (enumeration-safe messaging, direct sign-in after reset), magic link (sent-state design, resend cooldown, cross-device), OTP/2FA (one input + autocomplete="one-time-code", not six boxes), anti-pattern table.

Wired in

SKILL.md (Task Routing + blueprints enumeration + version 2.6.0), task-routing.md, CLAUDE.md, README.md (badge, blueprints tree, product-ui 12 → 13).

v2.5.0 — One-shot autonomous build + Next.js 16 stack refresh

Full-repo audit pass (link integrity 1856 refs / 0 broken, 115 tests green, MCP server + evals verified) closed the one remaining gap for the "site in one prompt" scenario and refreshed the stack standard.

Added

• rules/21-one-shot-build.md — protocol for single-prompt builds with no dialogue: Assumption Ledger replaces clarifying questions, mini-MASTER locked inline, Design Dials default one notch bolder (variance 6 — distinctive beats safe when there is no feedback loop), mandatory rule-20 self-verification, deliverable = site + ledger + verification evidence + max 3 open questions. Overrides the Junior Pass blocking step from rules/00 in autonomous contexts.
• pytest.ini — root python -m pytest -q no longer collides with the mcp-server/tests package.

Changed

• Stack standard: Next.js 15 → 16 across SKILL.md, README, tech-standards, performance/SaaS rules, blueprints, integrations (Cursor / ChatGPT / Copilot), MASTER template. references/tech-standards.md documents the 16 deltas: Turbopack default, Cache Components (PPR) + "use cache", proxy.ts replacing middleware.ts, stable React Compiler.

Principle distilled: in one-shot mode the user is not the QA loop — assumptions get declared, not asked, and verification carries the full weight of the conversation that didn't happen.

v2.4.0 — Reference extraction + fidelity & token-drift verification

Additions from a second design-skill audit that complete the v2.2.0–v2.3.1 work (rendered verification + the MASTER template) rather than duplicate it. Full history in CHANGELOG.md.

What's new

Reference → design system (extraction)

• recipes/extract-design-from-reference.md — turn a reference (image / live site / Figma) into a filled design-system-master.md + DTCG design-tokens.json + a component inventory, before building. Prefers extracted values (CSS --*, Figma variables) over inferred ones, tags every inference with confidence (✅ extracted / ⚠️ inferred / ❓ uncertain), and ends with explicit Open Questions instead of fabricating interaction states or dark mode a static frame can't show. Composes with the MASTER template.

rule 20 — verification, completed

• R6 — fidelity to the reference. Correctness gates don't prove the build matches intent. When a reference exists, diff the rendered build against it across layout / type / color / spacing / radii / shadow / assets — and confirm 1px borders + shadow spread by computed value, since vision comparison slips on those.
• R7 — token-drift audit. A declared token isn't proof it's applied: hardcoded literals that should be var(), out-of-sync duplicated copies, defined-but-unused / used-but-undefined tokens. Exactly the failure the demo gallery hit in v2.3.1. New live-audit-snippets.md snippet K (declared :root vs used) backs it.

At a glance

245 files · 21 rules · 46 patterns-and-recipes surface (16 recipes) · 27 references · 11 agents · 13 industry sectors.
Standards floor: CSS 2026 Baseline · React 19 · Next.js 15 · Tailwind v4 · WCAG 2.2 AA · OKLCH-only.

Principle: extraction before building, fidelity-to-reference after — and a token you declared is only real once the rendered DOM proves it.

v2.3.0 — Install hardening + verification depth

First GitHub Release since v1.9.0 — covers the v2.0.0 stable milestone and everything through v2.3.0. Full history in CHANGELOG.md.

Highlights

Design depth (2.2.0–2.3.0)

• rules/20-rendered-verification.md (21 rules total) — Decision Pipeline step 12 is now a mandatory render → audit → fix loop. Verification happens on the rendered DOM across the full mode matrix (theme × viewport × state), not a single default-state screenshot. Consolidates the live-audit snippets, the verify-in-every-mode matrix, and verify-before-tile.
• templates/specs/design-system-master.md — a persisted multi-page design-system source of truth (MASTER) + page-overrides convention: pages inherit by default and declare only justified deviations. Keeps a 15-page site looking like one product, not one template recolored.
• Third before/after case — GEO course landing: a decorative dashboard card + countdown timer (data-slop + fake-urgency dark pattern) replaced by a single "answer-graph" metaphor, editorial hierarchy, and an attributed testimonial.

Install hardening (2.1.1–2.1.4)

• Installer now bundles the resource folders (references/, rules/, patterns/, …) beside SKILL.md — fixes the v2.1.0 flatten bug where reference links resolved to nothing.
• MCP config written to .mcp.json at the project root, not the unread .claude/mcp.json.
• validators/ bundled; core-file path references fixed for the flattened layout.

At a glance

244 files · 21 rules · 45 patterns · 27 references · 11 agents · 13 industry sectors · MCP server (11 tools / 11 resources / 5 prompts).
Standards floor: CSS 2026 Baseline · React 19 · Next.js 15 · Tailwind v4 · WCAG 2.2 AA · OKLCH-only.

v1.9.0 — Behavioral Design Reference (29 cognitive biases)

What's new in v1.9.0

Behavioral Design Reference — references/behavioral-design.md

Full scan of keepsimple.io/uxcore — 105 cognitive biases reviewed, 29 directly applicable to interface design selected and mapped to concrete UI patterns.

Organized by design task:

Section	Biases covered
Pricing pages	Anchoring, Decoy, Contrast, Mental accounting, Hyperbolic discounting, Less-is-better
CTAs & copy	Framing, Loss aversion, Self-reference, Illusory truth, Curse of knowledge, Negativity bias
Navigation & IA	Magical Number 7±2, Serial-position, Ambiguity effect, Unit bias
Trust & social proof	Halo effect, Bandwagon, Authority bias, Confirmation bias, Mere-exposure
Onboarding & retention	Peak-end rule, IKEA effect, Endowment, Escalation of commitment, Reactance
Visual hierarchy	Von Restorff, Picture superiority, Processing difficulty

Each entry includes a definition, where to apply in UI, an HTML/code example, and a "why it works" one-liner from the source.

Ends with a quick reference table mapping 15 common design tasks to their applicable biases.

---

Full changelog: CHANGELOG.md

v1.8.0 — Industry depth, HyperFrames integration, Anthropic skill compliance

What's new in v1.8.0

HyperFrames Integration

Convert HTML/CSS designs to deterministic MP4 video — product demos, social content, changelog animations. Full guide at integrations/hyperframes/guide.md: composition structure, OKLCH token compatibility, animation adapter matrix, pre-render checklist.

Anthropic Skill Compliance

SKILL.md frontmatter restructured to match the official Anthropic skill spec (Reference B): all custom fields moved under metadata:, description rewritten with explicit trigger phrases per WHAT+WHEN requirement.

Industry Sector Depth — 9 sectors expanded

Each sector file now includes a full Design System (OKLCH palette), Key Component Patterns with HTML examples, Copy & Messaging table, and Design References:

Sector	New patterns
Health	Provider card, appointment flow, emergency notice, clinical palette
Finance	Fee table, calculator, security trust bar, tabular-nums rule
Non-profit	Impact counter, donation toggle form, campaign progress bar
Real estate	Property card, gallery, map panel, mortgage estimator
Travel	Date picker, price breakdown, availability scarcity, sticky mobile bar
Government	GDS step form, eligibility checker, doc checklist, plain language rules
Entertainment	Trailer autoplay hero, ticket widget, countdown, streaming grid
Education	Course hero, curriculum accordion, outcome stats, payment plans
Services	Practitioner hero, tier cards, process timeline, testimonial card

Agent Examples — design-director & ux-architect

Both agents now include 3 full concrete example reviews each:

• design-director: REJECT (generic SaaS hero) · PASS (health clinic) · REVISE (e-commerce brand without identity)
• ux-architect: SaaS onboarding blocker · e-commerce checkout IA · admin panel missing states

---

Full changelog: CHANGELOG.md