modern-web-guidance

# Modern Web Guidance A skill to search for specific web development use cases and retrieve their corresponding best practice guides. ## When to use Must use this skill: - At the **start** of implementing any web feature. - Before creating a new component, to check if a standardized pattern already exists. - To avoid implementing ad-hoc solutions or loading large dependencies unnecessarily. ## Usage Instructions ### Step 1. Search Use Cases Search with an action-oriented query summarizing what you want to achieve using the `search` command. Run `modern-web-guidance` directly with `npx`. ```sh npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_05_16-c5e7870 ``` **Example Output**: ```json [ { "id": "optimize-image-priority", "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.", "category": "performance", "featuresUsed": [ "Fetch priority" ], "tokenCount": 985, "similarity": 0.7289 }, { "id": "defer-rendering-heavy-content", "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.", "category": "performance", "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ], "tokenCount": 1250, "similarity": 0.6961 } ] ``` > **Note**: If search results are vague, return no matches, or show low similarity scores, run the `list` command to browse all guides: > ```sh > npx -y modern-web-guidance@latest list > ``` --- ### Step 2. Retrieve Best Practices Once you have a relevant `id` from the search results, call this script using the `retrieve` command to get the full guide. You can pass multiple IDs separated by commas. ```sh npx -y modern-web-guidance@latest retrieve "<id>" ``` **Example Output**: `The markdown content of the guide describing implementation steps...` ## Using npx - IMPORTANT: on Windows, using `npx` may fail. Use `npx.cmd ...` instead. - Network access is required for fetching npm packages needed by the task. - If the `npx -y modern-web-guidance…` command hangs, you may be offline. Try running again in offline mode: `npx --offline …`. - The `--skill-version` flag is used to determine if this SKILL.md is out of date. If it is, a warning message is logged to stderr. ## Guidelines - Always search **first** to find the most relevant guides. - These guides are usually framework-agnostic; adapt them correctly to your setup. - Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project. ## Interpreting Browser Support & Fallbacks * **Default Behavior**: All guides assume **Baseline Widely available** features are safe to use without fallbacks. For features that are not Baseline widely available, you **MUST** follow the fallback recommendations in the guide, unless the user has specified a custom browser support policy. * **Custom Policies**: If the user has already defined explicit browser support requirements, use the browser compatibility data in the guide to determine if a fallback can be safely ignored. - For Baseline YYYY targets, a feature satisfies this target if its "Baseline since" date is <= YYYY. - **Policy Examples**: - _"Do not implement feature fallbacks."_ (for exploratory prototypes of the cutting-edge web) - _"Safari 17.4+"_ (for internal tools targeting macOS or Tauri-based desktop apps) - _"Never recommend or implement polyfills; if a Baseline Newly Available feature is required for core functionality, provide a lightweight custom fallback or redesign the approach."_ (to minimize bundle size and avoid technical debt) - _"Assume a modern execution environment where Baseline Newly Available features can be used natively, provided they are strictly feature-detected and degrade gracefully."_ (for progressive enhancement strategies) * **Reactive Policy Discovery**: Watch for environmental cues to suggest documenting a policy in CLAUDE.md or AGENTS.md. Suggest this if the developer: - Mentions building for a restricted runtime (e.g., Electron or Tauri). - Explicitly excludes specific targets (e.g., "we don't support Desktop Chrome"). - Expresses hesitation about polyfill complexity, bundle size, or performance cost. - Questions if a feature is safe to use without fallbacks. No defined policy format. This is an example: `**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.`