Files
claude/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md
T

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 (runs npx -y modern-web-guidance@latest search|retrieve, never used here) and guides/<17 categories>/<id>.md, 210 files, ~2 MB, no frontmatter, id = basename (unique). 174 lines in 67 guides cross-reference other guides as npx -y modern-web-guidance@latest retrieve "<id>".
  • skills/chrome-extensions/: SKILL.md + references/ (24 files, no npx); it names the modern-web-guidance skill and maintains a CHROMEWEBSTORE.md in 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 a mktemp -d path, checkout FETCH_HEAD, then git rev-parse HEAD must equal commit (else refuse, nothing written).
  • Copies only the listed repo paths into a staging dir per destination; the upstream skills/modern-web-guidance/SKILL.md is never copied.
  • For mwg: generates INDEX.md (one line per guide: - id | category | summary, the summary from the upstream README description, else the guide's H1) and an attribution NOTICE.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-commit equals the pin and whose .vendored-spec equals its allowlist is skipped; anything else (absent copy, older pin, edited allowlist) is fetched. A dest that exists without .vendored-commit is 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: commit 40 lowercase hex, source https://github.com/<o>/<r>, paths [A-Za-z0-9._/-], no .., no leading /. A VENDOR_BASE_URL=file://… override serves the hermetic suite (same rule as the existing helper).
  • Both skills-external/mwg/ and skills-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.md with name, description (front-end triggers; not backend, infra, tooling; at most 400 characters, listing budget), allowed-tools: Read. No effort: and no routing.json row: a rowed skill reroutes the main loop on load ("last rowed skill wins"), which would pull design work off reflect; listed in NO_ROW_SKILLS like find-docs. allowed-tools only 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 undeclared npx <pkg>.
  • One tracked relative symlink: mwg -> ../../skills-external/mwg (INDEX.md, NOTICE.md, guides/ behind it).
  • Workflow in the body:
    1. Read mwg/INDEX.md whole (~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.
    2. 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.
    3. A guide line npx … retrieve "<id>" means: find <id> in mwg/INDEX.md, Read mwg/guides/<category>/<id>.md. Never run npx or any network command for this skill.
    4. Apply them, keeping the guide's fallbacks and Baseline notes. Where a guide and a rule of rules/web-building.md disagree on how to use the platform, the guide wins. An executor whose closed plan contradicts a guide reports it as an open choice.
    5. The answer that delivers the front-end change (a sub-agent: its report) ends with one line: Modern Web Guidance: <id>, <id> (or Modern Web Guidance: checked <topics>, none applied). No quotes.
  • 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 the modern-web-guidance skill; 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) consults modern-web-guidance for 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.md unchanged (320/320); its design pointer already sends design work to web-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.md and follow it. The relative links resolve through the ~/.claude/skills link (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.sh check_vendored_trees: each git-tree dest's .vendored-commit equals the lock commit, else a warning naming make plugin; never an error, and doctor survives set -euo pipefail when a vendored copy is missing.
  • lib/tests/vendor-tree.test.sh on 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: our SKILL.md contains no npx command to run, Read only, no row, the mwg link, 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.