The primary goal of this stage is to translate a technical web platform feature into a carefully selected set of its most common and important use cases. This is the first of three stages in creating guidance:
A "use case" in this project is not a description of a feature; it's a task that the user is trying to implement, or a problem they're trying to solve. The feature is only relevant in the sense that it's part of the recommended solution for the use case.
This guidance is ultimately served through a RAG (Retrieval-Augmented Generation) search system. If multiple guides have significant overlap, coding agents may struggle to select the most relevant one, leading to confusing or contradictory advice.
-
Step 1: Describe the use case
You MUST choose a short (max 1024 characters), action-oriented description of the problem the feature solves. The description must be a single sentence, start with a verb, and answer the question: "What is the user trying to DO?"
For example, a use case of the fetch-priority feature is "Deprioritize background data fetches made with the Fetch API to prevent network contention with user-initiated requests."
-
Step 2: Choose a category
Use cases MUST live under the guides/ directory, organized into a single, high-level category such as motion or performance. List the current subdirectories under guides/ and choose the most appropriate one.
Categorize by the use case, not the implementation. This is the "WHAT not HOW" principle applied to taxonomy: a category should name the user's goal (motion, overlays, datetime, typography), not the technology used to achieve it. Quick test: could someone who understands the use case but can't write the code file it correctly? If the only way to know where a guide belongs is to know which API it uses, the category is implementation-shaped. Two guides solving the same goal with different tech (e.g. a tab underline that morphs via anchor positioning vs. view transitions) belong in the same category.
Some categories are named after a technology domain (css, html, canvas) because they are anchored by a comprehensive reference guide for that technology (e.g. html/html/guide.md). These are valid homes for use cases genuinely about that technology, or that don't yet have enough siblings to form a use-case cluster.
File by primary goal; cover cross-cutting concerns inline. Performance, accessibility, privacy, security, and UX are verticals nearly every guide touches. File a guide by what it is primarily trying to accomplish and address secondary concerns in the guide.md body, not via category. A scroll-driven animation with a rendering cost still belongs in motion or scroll, with its performance notes in the guide, not in performance. (This is why the catch-all user-experience category was removed: UX is a vertical every guide addresses, not a bucket of its own.)
-
Step 3: Create the use case subdirectory
Create a subdirectory under guides/<category>/ for your use case. The subdirectory name MUST be a short, slugified version of the action-oriented use case. For example, for the use case in Step 1, the subdirectory name is deprioritize-background-fetches.
DO NOT prefix the slug with action verbs like create-, build-, or add-. Slugs are directory names scanned in lists—action verbs just add noise and make it harder to find what you're looking for.
-
Step 4: Create the guide.md stub
Create a guide.md file in the new subdirectory. For now, the guide should only contain metadata about the use case. The actual content of the guide will be filled in later after peer review.
The required YAML frontmatter fields are:
- name: Short, slugified name of the use case.
- description: Action-oriented description of the use case.
- web-feature-ids: List of web feature IDs that the use case relies on. These can be found in the
web-features package or via webstatus.dev.
For example:
---
name: deprioritize-background-fetches
description: Deprioritize background data fetches made with the Fetch API to prevent network contention with user-initiated requests.
web-feature-ids:
- fetch-priority
- fetch
---
-
Step 5: Create the demo.html file
Create a demo.html file in the new subdirectory. This file is eval infrastructure — it is used by grader.ts to verify that a correct implementation passes all tests. Real-world coding agents never see this file.
Because it is not shown to agents, demo.html does not need to be a polished or production-ready example. It just needs to be a correct, minimal implementation of the use case. Keep it self-contained with inline scripts and styles. Use placeholder URLs for any subresources like images or videos.
Quality Rules for Demos:
- Identifiable Test Targets: Make target elements in HTML demos explicitly identifiable using clear data attributes like
data-testid and specific class names to aid in grading.
See demo.html for an example from the deprioritize-background-fetches use case.
-
Step 6: Validate the use case
Run pnpm --filter guides test to validate the use case.
-
Step 7: Get the use case approved
Submit the use case for review by creating a Pull Request containing only the files created in steps 1-6. This allows for early feedback on the selection and naming of the use cases.
After the use case is approved, you can proceed to writing the guidance and expectations. Additional guidance for these stages is provided by the project-guides and project-evals skills.
