Project Use Cases

Stage 1: Identifying use cases for a feature (Needs use cases)

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:

1. Stage 1: Identifying use cases for a feature (you are here)
2. Stage 2: Authoring guidance for a use case
3. Stage 3: Evaluating guidance for a use case

Identifying action-oriented tasks

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.

• Action-oriented thinking: Frame every use case as a task, and make sure it starts with a verb. Instead of "Scroll-driven animations support horizontal scrolling," use something like "Synchronize an animation's progress with the horizontal scroll distance of a container."
• Bridge the knowledge gap: Assume the developer knows what they want to build (e.g., "I need a sticky header that shrinks on scroll") but might not know which modern web feature is the best solution (e.g., scroll-driven animations). Your use cases should facilitate this discovery by focusing on the desired outcome.
• Balance Generality and Distinctness: The use case description should be general enough to capture the overall intent and match a wide range of user prompts. However, to leverage the vector search effectively, ensure the guide uses clear, descriptive headings. The RAG system chunks content by heading, making specific parts of your guide discoverable for specific prompts. The implementation details within those chunks must remain distinct and specific to ensure the agent receives an unambiguous solution. For example, instead of saying "Fade an image in/out..." in the description, say "Smoothly hide/show a component...".
• Focus on the WHAT not the HOW: Do not mention the solution in the use case description. NEVER mention the specific API methods, properties, or the target feature name in the description itself. For example, avoid phrases like "...by doing..." or "...through the use of...". Ideally, the use case description should remain constant, even if the recommended features or best practices for implementing it change over time.
• Scope: Aim for 2-5 distinct use cases per feature. Each use case should represent a distinct implementation pattern or a significant variation in how the feature is applied. IMPORTANT: Not every sub-feature or feature variation needs a use case.
• MANDATORY: Drop niche use cases: Every guide must solve a tangible, high-priority developer need. Do not document niche features or visual tricks with negligible practical impact. Omit use cases unlikely to match real developer prompts.
• Merge rather than split: If two proposed use cases would result in guides that are 99% identical, combine them into one, more general use case. Duplicate guides bloat context windows and create confusing contradictions.
• Break down complex features: Conversely, do not cram multi-step, intricate features (like passkeys) into a single generic guide. Split them into logical, detailed use cases.
• UX-Driven, Not Feature-Driven: Do not simply list every method, property, or option of an API as a separate use case. A use case must represent a distinct user experience goal or a distinct developer problem, not just a variation in API usage. If the implementation across proposed use cases is 90% identical, consolidate them.
• Avoid Forcing Use Cases on Low-Level Utilities: If a feature is a low-level utility (like a new Promise method or a general object cloning function) that primarily acts as a drop-in replacement for legacy patterns, avoid forcing it into multiple outcome-oriented use cases. Instead, consider recommending a single 'Fundamental Guide' (e.g., "Deep cloning complex objects") or placing it in a top-level discipline skill file.
• Granular Guide Decomposition (Avoid Monoliths): For discipline-level guides, ensure the guidance is broken down into granular "subskills" (i.e., smaller, focused guides) rather than a single monolithic guide. Monolithic guides are too complex to evaluate in the harness, as they present too many best practices to test simultaneously. The primary discipline-level guide (e.g., guides/css/css/guide.md or guides/performance/performance/guide.md) should serve as a conceptual "hub" that establishes the agent's mental model for the discipline, explaining when and how to reference each granular subskill guide, and linking them via the {{ GUIDE_REF("guide-slug") }} macro.

Minimizing overlap

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.

• Check existing guides: Before creating a new use case, review existing guides in the same discipline.
• Search by web-feature-id: Each guide lists the web features it relies on in the web-feature-ids metadata field. Search for the ID of the feature you're writing about in existing guides and open PRs to see how it's being used.
• Merge or differentiate: If your proposed use case is substantially similar to an existing one, do not create a duplicate. Instead, consider how the existing guide should be updated to include your new scenario as a variation or a specific directive.
• Distinct value proposition: Every new guide must offer a distinct solution to a distinct problem.

Implementation and scaffolding

The following steps are REQUIRED for creating a new use case:

• 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 expectations.md stub

  Create an expectations.md file in the new subdirectory outlining the must-pass verification criteria for any application implementing this guidance.

• Step 6: Generate base-app evaluation capsules

  Once guide.md and expectations.md are authored, run gd dev guides/<category>/<guide> to automatically generate and calibrate the evaluation capsules across SUPPORTED_BASE_APPS under targets/<base_app>/.

• Step 7: Validate the use case

  Run pnpm --filter guides test to validate the use case structure and target integrity.

• Step 8: Get the use case approved

  Submit the use case for review by creating a Pull Request containing the authored guide.md and expectations.md along with the generated targets/ directory.

After the use case is approved, you can proceed to refining the guidance and expectations as needed. Additional guidance for these stages is provided by the project-guides and project-evals skills.