docs(spec): modern web guidance design

This commit is contained in:
bchanot committed 2026-11-21 23:18:50 +01:00
1 parent 071f7a5bd8
commit 7cc1e6c42d
1 file changed
+123
@@ -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>/<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`, `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 "<id>"` means: Read `guides/*/<id>.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: <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), 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`.