Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d74dd2c8fa | ||
|
|
05446b2e79 | ||
|
|
79a48f76c1 | ||
|
|
ea1d5ab400 | ||
|
|
7cc1e6c42d |
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`.
|
||||
Reference in new issue
Block a user