diff --git a/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md b/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md new file mode 100644 index 0000000..48ec650 --- /dev/null +++ b/docs/superpowers/specs/2026-11-21-modern-web-guidance-design.md @@ -0,0 +1,123 @@ +# 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>/.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 ""`. +- `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 [refresh]` reads a new `plugins.lock.json` entry: + +```json +"modern-web-guidance": { + "source": "https://github.com/GoogleChrome/modern-web-guidance", + "tag": "v1.0.1", + "commit": "64a6d708f5a43f2cd3fde5d4d7db3905ba1bdf65", + "trees": { + "mwg": ["skills/modern-web-guidance/guides", "LICENSE"], + "chrome-extensions": ["skills/chrome-extensions"] + }, + "always_on": true +} +``` + +- One `git init` + `git fetch --depth 1 ` 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 | H1 title`) 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/` (old dir removed after the new one is + complete), so guides dropped upstream disappear on a pin bump. +- Install mode skips a complete existing copy at the same commit (marker file + `.vendored-commit`); refresh re-fetches; both install a missing copy (fixes the + "refresh skips absent dirs" gap for this entry). +- Same validation as `vendor_pinned_skills`: `commit` 40 lowercase hex, `source` + `https://github.com//`, 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 (`vendor_pinned_tree modern-web-guidance`) and +`update-all.sh` 7.3 (`… refresh`). The pin moves only by editing the lock entry. + +### 2. Our skill `skills/modern-web-guidance/` (tracked, ours, always on) + +- `SKILL.md` with `name`, `effort: low`, `description` (front-end triggers; not backend, + infra, tooling), `allowed-tools: Read, Grep, Glob`. +- Tracked relative symlinks: `guides -> ../../skills-external/mwg/guides`, + `INDEX.md -> ../../skills-external/mwg/INDEX.md`, `NOTICE.md -> ../../skills-external/mwg/NOTICE.md`. +- Workflow in the body: + 1. Grep `INDEX.md` for 1-3 terms of the capability (dialog, popover, table, form + validation, view transition, LCP…); fall back to Grep over `guides/`. + 2. Read the matching guide(s) and the discipline guide when one applies (html, css, + forms, accessibility, performance, security). + 3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line + `npx … retrieve ""` means: Read `guides/*/.md` locally. Never run npx or any + network command for this skill. + 4. Where a guide and a rule of `rules/web-building.md` disagree on how to use the + platform, the guide wins. + 5. End the answer that delivers the front-end change with one line: + `Modern Web Guidance: , ` (or `Modern Web Guidance: checked , none + applied`). No quotes. +- Guides missing (dangling links): say so, remedy `make update`; continue without them. +- `test-prompts.json` (darwin convention), a `routing.json` row (`modern-web-guidance`, + phase `explore`). + +### 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. +A routing row is added if the effort-routing census requires one for linked externals. + +### 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. + +### 5. Checks and docs + +- `lib/doctor-vendored.sh` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and + its `.vendored-commit` equals the lock commit; `chrome-extensions` link present. +- `lib/tests/mwg.test.sh` on a local git fixture: fetch at the pinned commit, refuse a + mismatching commit, whitelist only (no upstream SKILL.md), INDEX generation, prune of a + dropped guide on refresh, install of an absent copy in refresh mode, path validation, + and our `SKILL.md` contains no `npx` command to run. +- 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`.