8.5 KiB
Modern Web Guidance in the kit — design
Date: 2026-11-21. Contract: .claude/tasks/contracts/2026-11-21-modern-web-guidance-2314.md
(all user decisions are in its CLARIFICATIONS). Branch: feature/modern-web-guidance.
Goal
Every front-end task (HTML, CSS, client-side JS, components, in any flow and any profile) consults Google's Modern Web Guidance before writing code, so the agent applies current platform practice instead of patterns from its training data. The guidance is read from a pinned local copy: no npx, no network and no remote code at use time.
Upstream
GoogleChrome/modern-web-guidance, tag v1.0.1 = commit
64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65 (2026-11-16). Stewarded by Chrome, Edge,
Firefox and MDN. Code Apache-2.0, guide content CC-BY 4.0.
skills/modern-web-guidance/:SKILL.md(runsnpx -y modern-web-guidance@latest search|retrieve, never used here) andguides/<17 categories>/<id>.md, 210 files, ~2 MB, no frontmatter, id = basename (unique). 174 lines in 67 guides cross-reference other guides asnpx -y modern-web-guidance@latest retrieve "<id>".skills/chrome-extensions/:SKILL.md+references/(24 files, no npx); it names themodern-web-guidanceskill and maintains aCHROMEWEBSTORE.mdin extension projects.
Components
1. Pinned fetch (lib/vendor-skills.sh, new function)
vendor_pinned_tree <lock-key> reads a new plugins.lock.json entry:
"modern-web-guidance": {
"source": "https://github.com/GoogleChrome/modern-web-guidance",
"commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65",
"tag": "v1.0.1",
"license": "Apache-2.0 (code), CC-BY 4.0 (guides)",
"managed_by": "git-tree",
"always_on": true,
"trees": {
"mwg": {"guides": "skills/modern-web-guidance/guides", "LICENSE": "LICENSE", "README.md": "README.md"},
"chrome-extensions": {".": "skills/chrome-extensions"}
}
}
- One
git init+git fetch --depth 1 <source> <commit>in amktemp -dpath, checkoutFETCH_HEAD, thengit rev-parse HEADmust equalcommit(else refuse, nothing written). - Copies only the listed repo paths into a staging dir per destination; the upstream
skills/modern-web-guidance/SKILL.mdis never copied. - For
mwg: generatesINDEX.md(one line per guide:- id | category | summary, the summary from the upstream README description, else the guide's H1) and an attributionNOTICE.md(source, tag, commit, CC-BY 4.0 for guides, Apache-2.0 code). - Swaps each staging dir into
skills-external/<dest>(old dir removed after the new one is complete, restored if the swap fails), so guides dropped upstream disappear on a pin bump. - One mode: a dest whose
.vendored-commitequals the pin and whose.vendored-specequals its allowlist is skipped; anything else (absent copy, older pin, edited allowlist) is fetched. A dest that exists without.vendored-commitis never replaced. A symlink in the fetched content, or a listed path resolving outside the checkout, is refused with nothing swapped. - Same validation as
vendor_pinned_skills:commit40 lowercase hex,sourcehttps://github.com/<o>/<r>, paths[A-Za-z0-9._/-], no.., no leading/. AVENDOR_BASE_URL=file://…override serves the hermetic suite (same rule as the existing helper). - Both
skills-external/mwg/andskills-external/chrome-extensions/are gitignored (machine-owned, regenerated by the install step, LRN-086).
Callers: install-plugins.sh Step 8e and update-all.sh 7.3, both
if ! vendor_pinned_tree modern-web-guidance; then warn …; fi (a fetch failure keeps
the previous copy and the script goes on). The pin moves only by editing the lock entry.
2. Our skill skills/modern-web-guidance/ (tracked, ours, always on)
SKILL.mdwithname,description(front-end triggers; not backend, infra, tooling; at most 400 characters, listing budget),allowed-tools: Read. Noeffort:and norouting.jsonrow: a rowed skill reroutes the main loop on load ("last rowed skill wins"), which would pull design work offreflect; listed inNO_ROW_SKILLSlikefind-docs.allowed-toolsonly pre-approves Read for the invoking turn, it restricts nothing (Claude Code skills docs); the no-npx guarantee rests on the skill's text and the settings soft-deny on undeclarednpx <pkg>.- One tracked relative symlink:
mwg -> ../../skills-external/mwg(INDEX.md, NOTICE.md, guides/ behind it). - Workflow in the body:
- Read
mwg/INDEX.mdwhole (~210 lines, ~39 KB with descriptions) and pick the guides by summary (Grep and Glob are absent in some sessions, Read always exists); a body search under~/.claude/skills/modern-web-guidance/mwg/guides/only when no summary fits and a text-search tool is at hand. - Read the matching guide(s). A discipline guide (id = category: html, css, js, forms, accessibility, performance, security, privacy) only for a new component or page, or when no specific guide matched: they are long.
- A guide line
npx … retrieve "<id>"means: find<id>inmwg/INDEX.md, Readmwg/guides/<category>/<id>.md. Never run npx or any network command for this skill. - Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule
of
rules/web-building.mddisagree on how to use the platform, the guide wins. An executor whose closed plan contradicts a guide reports it as an open choice. - The answer that delivers the front-end change (a sub-agent: its report) ends with one
line:
Modern Web Guidance: <id>, <id>(orModern Web Guidance: checked <topics>, none applied). No quotes.
- Read
- Copy missing (dangling link): say so, remedy
make update; continue without it. test-prompts.json(darwin convention).
3. chrome-extensions (vendored, always on, as is)
Added to link.sh EXTERNAL_SKILLS (always-on flat link, the superpowers class;
BDR-093 forbids only default-off packs there). Its CHROMEWEBSTORE.md behaviour is kept.
No routing row (untracked linked external; a row would reroute the main loop on load).
4. Wiring
rules/web-building.md, new section right after the title: before writing or changing front-end code, run themodern-web-guidanceskill; the guide wins on platform usage; end with its disclosure line. Motion line becomes: "transform and opacity for continuous or scroll-linked motion; other transitions per the guides". Globs unchanged.§ Design work(heading kept byte-identical): one line, every step of the stack (Build, polish, motion, scroll) consultsmodern-web-guidancefor the platform features it uses. This is the only durable route into the foreign design skills.skills/pack-design/skills/site-motion/SKILL.md(ours): the same line.CLAUDE.global.mdunchanged (320/320); its design pointer already sends design work toweb-building.md.- Known: the path rule also loads inside sub-agents (LRN-232), so front agents see it too.
The executors (feater, bugfixer, hotfixer) have no Skill tool in their
tools:, so the rule adds: without the Skill tool, Read~/.claude/skills/modern-web-guidance/SKILL.mdand follow it. The relative links resolve through the~/.claude/skillslink (checked on a fixture). Limit: a Write of a new file loads no path rule (LRN-238). - model-router: any main-loop Skill call opens the write guard for the session
(
st.skillRun). A reference-skill list (modern-web-guidance,find-docs) never opens it, so a direct front-end request still gets redirected to /hotfix or /feat (user decision 2026-11-22).
5. Checks and docs
lib/doctor-vendored.shcheck_vendored_trees: each git-tree dest's.vendored-commitequals the lock commit, else a warning namingmake plugin; never an error, and doctor survivesset -euo pipefailwhen a vendored copy is missing.lib/tests/vendor-tree.test.shon a local git fixture: fetch at the pinned commit, refuse a commit not upstream, allowlist only (no upstream SKILL.md), INDEX generation, prune of a dropped guide on a pin bump, install of an absent copy, path validation, allowlist edit re-fetched, foreign dest kept, symlinks refused.lib/tests/mwg-skill.test.sh: ourSKILL.mdcontains nonpxcommand to run, Read only, no row, themwglink, disclosure, and the rule wiring.- README, USAGE, CHANGELOG; BDR recording the decisions, including the fixed pin as an assumed exception to BDR-056.
Out of scope
Audit skills (a11y, web-validate, guardrails, seo), agents' own briefs, a .js/.ts path
glob, a search CLI or embedding index, legacy-scan.