2 changed files with 1208 additions and 0 deletions

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -0,0 +1,137 @@
# 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> [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 <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 | 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/<dest>` (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/<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 (`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`, `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>`.
- 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. Read `INDEX.md` whole (210 lines, ~14 KB) and pick the guides by title (Grep and
Glob are absent in some sessions, Read always exists); a body search only when a
text-search tool is at hand.
2. Read the matching guide(s) and the discipline guide of each category touched (id =
category: html, css, js, forms, accessibility, performance, security, privacy).
3. Apply them, keeping the guide's fallbacks and Baseline notes. A guide line
`npx … retrieve "<id>"` means: find `<id>` in `INDEX.md`, Read
`guides/<category>/<id>.md`. 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: <id>, <id>` (or `Modern Web Guidance: checked <topics>, none
applied`). No quotes.
- Guides missing (dangling links): say so, remedy `make update`; continue without them.
- `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` (or `doctor.sh`): `skills-external/mwg/INDEX.md` present and
its `.vendored-commit` equals the lock commit; `chrome-extensions` link present.
- `lib/tests/vendor-tree.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. `lib/tests/mwg-skill.test.sh`: our `SKILL.md` contains no `npx` command to
run, Read only, no row, links, 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`.