Best practices for authoring and reviewing guidance. Use this skill any time you're writing or reviewing `guide.md`, `expectations.md`, or `demo.html` files.
Install
npx skillscat add googlechrome/modern-web-guidance-src/project-guides Install via the SkillsCat registry.
Stage 2: Authoring guidance for a use case (Needs guidance)
This is the second of three stages in creating guidance:
- Stage 1: Identifying use cases for a feature
- Stage 2: Authoring guidance for a use case (you are here)
- Stage 3: Evaluating guidance for a use case
What a real-world coding agent sees
When a developer asks an AI coding assistant to implement something, the assistant retrieves the relevant guide.md via a RAG (vector search) system. guide.md is the only project file a real-world coding agent ever sees. Everything else in a use case directory is eval infrastructure:
| File/Directory | Purpose | Seen by real-world agents? |
|---|---|---|
guide.md |
Guidance for implementing the use case | ✅ Yes — this is the only file |
expectations.md |
Verification criteria used to generate target evaluation suites | ❌ No |
demo.html |
Reference implementation of the use case | ❌ No |
targets/<base_app>/solution.patch |
Golden diff against clean base app used to calibrate the grader | ❌ No |
targets/<base_app>/zero-passrate.patch |
Guidance-absent diff used to verify grader assertions fail when requirements are not implemented | ❌ No |
targets/<base_app>/grader.ts |
Playwright test suite run against the eval agent's output | ❌ No |
targets/<base_app>/task.md |
Simulated developer prompts fed to the eval agent by the harness | ❌ No |
Implication for authoring (guide.md, expectations.md, & demo.html): Authors and SMEs strictly author guide.md, expectations.md, and demo.html. You do not author solution.patch, zero-passrate.patch, grader.ts, or task.md—those evaluation files are generated separately by the eval pipeline.
Implication for guide.md: Because guide.md is the agent's only source of truth, it must be entirely self-contained. Do not rely on agents reading expectations.md, any target patch, or any external link to understand how to implement the use case.
MANDATORY RULES FOR WRITING guide.md:
1. YAML Frontmatter Schema
guide.md must start with this YAML frontmatter structure (added in Stage 1):
---
name: slugified-use-case-name
description: <do thing> <with feature> (e.g., "Create dynamic color systems using modern color syntax")
web-feature-ids:
- webstatus-feature-id
---- web-features: Must be a list of accurate IDs found via webstatus.dev. Include ALL features referenced in the guide body, not just the primary one. If an ID is missing, inform the USER.
- Pending Features (
tmp-prefix): If a feature ID is pending upstream in@web-platform-dx/web-features(e.g. an open issue), usetmp-<candidate-slug>(e.g.tmp-scroll-axis-lock) inguide.mdAND register it infeatures/pending-web-features.jsonalong with its upstream issue link. Optionally addgroup(a web-features group ID likescrolling, or an array of them) so ATL triage routes it to that group's owner in.github/atls.json(then runnode src/ci/generate-feature-to-groups.ts), andcompat_features(a@mdn/browser-compat-datakey or array of keys, e.g.["css.properties.scroll-axis-lock"]) so CI can detect when the feature graduates upstream even ifweb-featureschooses a different final ID than<candidate-slug>. On the GitHubnew-featureissue itself, annotate the predicted final ID without thetmp-prefix (<candidate-slug>); the sync and triage scripts automatically striptmp-when matching guides to issues. When the feature ID is officially released upstream inweb-features, validator checks will automatically fail in CI to prompt updating the frontmatter to the official ID.
- Pending Features (
- draft (optional): Withholds the guide from all distribution without deleting it. Omit to publish. Must be one of:
stub: placeholder with outline/author notes; skips the H1 and Baseline checks.wip: being written.blocked: held back by the platform/spec situation. Requiresdraft-reason(one line, link the deciding issue/PR).
2. Tone and Formatting
- Formatting Directives: Use strict imperative directives (
MANDATORY:,DO,DO NOT) only when emphasis is strictly needed (e.g., for critical constraints, security, or common pitfalls). Do not overuse them for every single instruction. Coding agents respond best to rigid constraints when they are selectively applied. - Focus & Token Economy (Teach Only the Course-Correction Delta): Keep the guidance focused on the specific use case and short. No fluff or conversational text. Cut reference-style syntax enumeration and textbook explanations of Baseline Widely Available features that coding agents already know (e.g., how
<label>oraddEventListenerworks). Include a brief overview of the use case and explanation of why the solution outlined in the guide is the recommended approach. - Maintainer Notes vs. Agent Rationale (
{# ... #}vs. Prose/Comments):- Internal notes for human maintainers: Use
{# ... #}comments insideguide.md(which `stripComments()` strips out of the built guide served to agents) for upstream bug links, review history, or why an alternative/polyfill was rejected. Never commit separatereasoning.mdornotes.mdfiles in a guide directory. - Actionable rationale for coding agents: Put concise "why" explanations directly in
guide.mdprose or inline code comments whenever an agent might otherwise doubt or misapply a non-obvious pattern.
- Internal notes for human maintainers: Use
- Self-Contained: DO NOT include any external links in the markdown body (
[link text](url)), and DO NOT rely on internal{{ GUIDE_REF("...") }}cross-references to supply required implementation details. All required knowledge to use the feature MUST be fully synthesized into the markdown body (or transcluded at build time viaINCLUDE/FEATURE). Agents must not be slowed down or require additional retrievals to implement the guidance. - American English: Always author guidance in American English (
behavior,color,synchronize,center,optimize, etc.) for consistency across documentation, RAG tokens, and search embeddings. - Callouts: Use GitHub alert syntax (
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING],> [!CAUTION]), with the body on the following>lines. Validation rejects bold-label callouts (> **Note:** …) and other alert types; the devsite build converts alerts to DevSite notices.
3. Code Snippets
- No Full-Implementation Code Dumps: Include short, heavily commented code snippets where every snippet illustrates something the agent cannot infer from the prose above. Replace 50+ line boilerplate blocks with minimal, focused snippets and strip orthogonal details (such as inline SVG icons or arbitrary visual styling).
- Put directives directly in code comments so they are impossible to miss (e.g.,
<!-- Always use the required attribute -->). - Code comments MUST explain why a value or approach is chosen, not just what the code does. An agent that copies magic values without understanding them will apply them incorrectly. If a value is context-dependent (e.g., a threshold that should vary by use case), say so explicitly.
- Modern Standards: Exclusively use ES modules (
import/export) in JavaScript code examples; avoid CommonJS (require). - Clarifying Arbitrary Values: Explicitly identify placeholder values (like
2remor50ms) as example-only in comments to avoid them being mistaken for strict technical constraints.
4. Implementation Steps
- The implementation steps should assume any web feature can be used. Choose the best feature for the job, regardless of browser support.
- DO NOT suggest modern features just because they are modern. If a modern feature has no distinct user-visible advantage over a legacy feature for the given use case — but will require a more complex fallback implementation — use the legacy feature.
- Weigh tradeoffs across all users. A guide's output serves many groups: mouse and touch users, keyboard users, assistive technology users, users on slow networks or low-end devices, users in other locales, etc. DO NOT recommend an approach that degrades the experience for one group to improve it for another unless the gain clearly outweighs the loss (e.g. a negligible cost to one group for a large benefit to another), and never one that excludes a group from the use case entirely. These are case-by-case calls for the relevant ATLs; when a guide makes such a tradeoff, it must state it explicitly. Maintainability is a cost on the same scale: extra handling for any one group must justify the complexity it adds to the code with a proportionate user benefit.
- Platform-Native Composition: Prefer native platform primitives (
<dialog>,[popover],<details>) over manual re-implementations of top-layer or disclosure behavior (light dismiss,Escape, focus restoration,z-indexstacking). - DO NOT include cross-browser fallbacks in the implementation section. Those should only be mentioned in the fallback section.
- Only mark steps as
MANDATORYif they are truly required for the feature to function. Optional steps (e.g., adding scroll snap, adding an event listener for progressive enhancement) must be labeled as optional. Incorrect use ofMANDATORYcauses agents to implement unnecessary complexity. - The guide is the agent's only source of truth. DO NOT reference
demo.htmlor any other file — agents won't have access to them. Everything the agent needs to implement the use case must be inguide.md. - When listing alternatives, say how to choose between them (which use cases favor which). Optional improvements are alternatives too: the choice is between adding them or not, so say when they're worth adding. Don't invent criteria; if the choice genuinely depends on context you can't anticipate, leave it to the agent.
5. Fallback Strategies
If the primary implementation uses features that are not Baseline Widely Available, you MUST include a fallback recommendation in this section.
- Framing: Frame fallback necessity in terms of Baseline target (e.g., "If your Baseline target does not support X, use...").
- Assessment: Start with a broad assessment of the fallback's robustness. Recommend the modern approach if the fallback is robust; highlight complexity/caveats and suggest alternatives (like userland solutions) if it is not.
- Experience: MANDATORY: Explicitly describe the fallback experience (progressive enhancement vs. feature detection/graceful degradation).
- Feature Detection: Checks should be tightly scoped to the interface rather than the instance (e.g. use
Object.hasOwn(HTMLElement.prototype, 'onbeforematch')over'onbeforematch' in window) - Fallback Options (in order of preference):
- Custom Code: Short, reliable reimplementation (<50 lines) using widely available features.
- Polyfill: A robust, performant polyfill (see guidelines below).
- Abstraction: A well-tested userland library.
- Graceful Degradation: Baseline Newly Available features that degrade gracefully.
- Progressive Enhancement: Frame as progressive enhancement only if no robust fallback exists.
- Faithfulness: Fallbacks MUST be faithful to the use case. If the primary recommendation gracefully degrades but ultimately doesn't accomplish the core use case, suggest a different fallback if one is available. Graceful degradation IS acceptable for features that enhance, but are otherwise not core to the use case.
Baseline Status Macros
- MANDATORY: Include
{{ FEATURE_FALLBACKS("feature-id") }}or{{ BASELINE_STATUS("feature-id") }}as a standalone line for every non-widely available feature used.- When to use
FEATURE_FALLBACKSvs.BASELINE_STATUS:- Prefer
FEATURE_FALLBACKSwhen the fallback strategy is reusable across guides andfeatures/<feature-id>.mdexists with a non-empty## Fallbackssection (createfeatures/<feature-id>.mdif multiple guides share the feature). - Use
BASELINE_STATUSwhen nofeatures/<feature-id>.md#fallbacksentry exists:FEATURE_FALLBACKSrequiresfeatures/<feature-id>.mdwith a non-empty## Fallbackssection and throws aMacroError(failing validation/CI) if missing or empty. Use{{ BASELINE_STATUS("feature-id") }}directly when the fallback strategy is specific to a single guide (writing the fallback inline inguide.md), when you need the BCD-key second argument ({{ BASELINE_STATUS("feature-id", "bcd.key") }}), or when the feature is Baseline Widely Available and needs no fallback section.
- Prefer
- When to use
- Baseline Widely Available Features: While fallback strategies are not required for Baseline Widely Available features, you SHOULD include
{{ BASELINE_STATUS("feature-id") }}for features that became Baseline Widely Available (baseline_high_date) within the last 12 months (such assubgridor:has()), or that are commonly misjudged by coding agents as lacking support. This affirmatively reassures coding agents whose training data might predate wide availability that the feature is universally supported without needing defensive fallbacks. Do not conflatebaseline_low_date(Newly Available) withbaseline_high_date(Widely Available). - No Hard-Coded Browser Support Claims: Never hard-code browser versions, support matrices, or availability timelines in
guide.mdprose (e.g., "X is only supported in Chromium" or "until X is supported across major browsers"). Always render availability dynamically viaBASELINE_STATUSorFEATURE_FALLBACKSanchored to a validweb-feature-id(ortmp-*entry infeatures/pending-web-features.json). Brief factual notes explaining OS/UA integration mechanisms not captured by BCD (such as iOS/macOS Safari's@domain #codeSMS format forautocomplete="one-time-code") are allowed. - Placement: Use separate subsections with their own macros if multiple features are used. DO NOT use these macros outside the fallback section.
Polyfill Guidelines
- Conditional Loading: MANDATORY: ALWAYS conditionally load polyfills only when native support is missing. Prefer build-integrated conditional loading (code splitting) over CDNs.
- Performance: DO NOT recommend polyfills with significant performance tradeoffs, or those requiring fetching/parsing CSS. Prefer abstractions/userland solutions instead.
- Prohibited CDNs: DO NOT recommend polyfills from polyfill.io.
6. Build-time macros
| Macro | What it emits |
|---|---|
{{ BASELINE_STATUS("feature-id"[, "bcd.key"]) }} |
"Baseline status for <Feature>: Widely/Newly available..." or "Browser support for <Feature>: Limited availability". |
{{ INCLUDE("path[#section]") }} |
Whole markdown file (frontmatter + leading # H1 stripped) or one section (its heading dropped). Bare paths resolve from repo root; .//../ resolve relative to the calling file. |
{{ FEATURE("feature-id", "section") }} |
Sugar for INCLUDE("features/<feature-id>.md#<section>"). |
{{ FEATURE_FALLBACKS("feature-id") }} |
### Fallbacks & browser support for <Feature name> + BASELINE_STATUS + the #fallbacks section from features/<feature-id>.md (throws MacroError if the file or #fallbacks section is missing or empty). |
{{ FEATURE_ISSUES("feature-id") }} |
### Issues to be aware of when using <Feature name> + the #issues section. Returns "" if #issues is empty/missing. |
{{ GUIDE_REF("guide-slug") }} |
Cross-reference to another guide (\guide-slug` (via `npx -y modern-web-guidance@latest retrieve "guide-slug"`)inskills-cli; markdown link in devsite`). |
- Errors: invalid feature/guide ID or missing required argument →
MacroError(build fails loudly). Missing or empty referenced content (file or section) →MacroErrorforINCLUDE,FEATURE, andFEATURE_FALLBACKS, or falls back to""forFEATURE_ISSUES. - Section IDs: slugified heading text (
### Fallback strategies→fallback-strategies), or an explicit{#id}suffix on the heading. Avoid leaving an explicit{#section-id}suffix on a heading inguide.mdwhenslugify(heading)already matches#section-id. - Recursion: macros inside transcluded content expand normally. No cycle detection — don't write self-referential includes.
Cross-referencing other guides with GUIDE_REF
Coding agents mostly discover and batch-retrieve guides upfront (retrieve "a,b") from search or list results, and rarely follow cross-references after reading a guide.
- Never rely on
GUIDE_REFfor requirements of the current guide: Anything needed to implement this guide's use case — core rules, shared prerequisites, accessibility requirements, or fallbacks — must be inlined inguide.mdor transcluded at build time viaINCLUDE/FEATURE. - Only reference published guides: A published guide that uses
GUIDE_REFon a stub or draft fails validation, because the link would be dead. To plan a link to a guide that isn't written yet, park the full sentence in a marker comment:{# PENDING_GUIDE_REF: For X, see {{ GUIDE_REF("<slug>") }}. #}. Validation fails once<slug>is published, prompting you to delete the{# PENDING_GUIDE_REF:/#}wrapper so the link goes live. Drafts may reference unpublished guides directly. - Use
GUIDE_REFto point to a separate use case that is out of scope for the current guide:- Router / orientation hubs routing to specialized sub-guides (e.g.,
passkeysorweb-componentsrouting to specific use-case guides). - Disambiguating closely related sibling guides (place upfront before Section 1): Place disambiguation notes in the introductory overview before Section 1 and before any code snippets (e.g.,
progress-ringvs.spinnerfor determinate vs. indeterminate loading, orhovercardvs.interest-triggered-tooltips). Coding agents anchor heavily on the first code block they see; an upfront fork lets an agent that retrieved the wrong primitive pivot immediately without wasting context. - Referencing an adjacent use case (e.g.,
formspointing toime-safe-enter-submitforEnter-key submission during IME composition).
- Router / orientation hubs routing to specialized sub-guides (e.g.,
7. Reusing per-feature content via features/
When the same feature-level content (intro, fallback patterns, a11y, gotchas) applies to multiple guides, extract it into features/<feature-id>.md and pull it in with the macros above. Rule of thumb: extract if two or more guides cover the same web-feature-id and repeat the same advice. Standard section names: ## Fallbacks (used by FEATURE_FALLBACKS), ## Issues (used by FEATURE_ISSUES); add others as needed and pull them with FEATURE. Verify your include resolved by inspecting the build output (out/build/skills-cli/guides/<category>/<id>.md) after running pnpm build.
Authoring expectations.md and demo.html
Writing expectations.md
Write a natural-language, bulleted list of assertions that must be true if an agent implements guide.md correctly (e.g., "The input element is styled with a red border only AFTER a blur event"). Every completed non-stub, non-draft use-case guide must include a non-empty expectations.md.
- 1:1 with grader tests: Each bullet becomes a required must-pass test. Write one bullet per assertion; do not combine multiple checks into a single bullet.
- Plain declarative phrasing: Write each bullet as a plain statement of what is true of a correct implementation (e.g., "The dialog closes when the Escape key is pressed"). Strip imperative prefixes such as
MANDATORY:,OPTIONAL:,MUST,MUST NOT,DO, andDO NOT— those are aguide.mdconvention for steering coding agents, whereasexpectations.mddescribes verifiable outcomes. - **Concrete, deterministic criteria (ask "How can a grader know this?"):** Expectations must be verifiable DOM structures, stylesheet rules, or browser behaviors that a grader can check deterministically—statically (HTML DOM, CSSOM, JS AST) or in-browser (computed styles, accessibility tree, runtime behavior)—not factual statements about an API or criteria requiring human judgment (e.g., write "Every
<button>inside a<form>sets an explicittypeattribute" rather than referencing "non-submit buttons" or "decorative SVGs"). Pair any negative check ("X is not used") with a positive check that the target feature is present so an untouched page without the feature does not trivially pass. - Exercised in
demo.html: Ensure that every expectation written here is actively exercised in the accompanyingdemo.html. - Scoped to this use case: Only include expectations that apply to the specific use case being graded (roughly 5–10 bullets for a focused scenario; much longer files usually signal scope creep and should be split). Do not copy generic expectations from other guides if they describe behavior that won't appear in an implementation of this guide. Every bullet is a required must-pass test, so only include assertions that every correct implementation satisfies—do not include expectations for genuinely optional branches. In discipline guides, each bullet must name the element or feature it governs (forms, images, overlays, cookies, response headers) so its relevance to a given app can be judged.
- No external links: The grader generator cannot resolve them.
- Avoid over-constraining: Prefer observable outcomes over prescribing one syntax when several are valid, and name accepted alternatives explicitly (e.g., "
100%or a grid-based full-bleed layout"). Don't assert implementation details that don't affect correctness (e.g., don't require a direct child relationship if a descendant also works). Never upgrade guide "Prefer", "Optional", or conditional recommendations into unconditional must-pass assertions, never narrow guide phrasing (e.g., turning "preceding" into "immediately before"), never split "A or B" alternatives intoAND-ed tests, and avoid asserting arbitrary snippet example values (0.4s,ease-in-out) or overusing "such as" examples that cause tests to overfit. Never hardcode site-specific DOM locators (#id,.class) inguide.md's frontmatterdescriptionor inexpectations.md. - Separate native and fallback expectations: Write core expectations assuming all features in
guide.mdare natively supported. Whenguide.mdincludes## Fallback strategies, write each fallback requirement as a separate plain-English bullet that names the unsupported feature (e.g., "When<feature>is unsupported, ...") rather than combining native and fallback checks in the same bullet, sogd devcan scope fallback tests withskipUnless({ unsupported: '<feature>' })automatically.
Writing demo.html
- Reference implementation:
demo.htmlshould be a clean, working implementation of the use case (and its fallback strategy when the target feature is not Baseline Widely Available). Keep it self-contained with inline scripts and styles when possible. - Warning-free execution: Demos must run without browser console errors or warnings to ensure clean evaluation runs.