docs(spec): modern web guidance design
This commit is contained in:
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`.
|
||||
Reference in new issue
Block a user