| name | modern-web-guidance |
| description | Search tool for modern web development best practices. MANDATORY: Execute first for all HTML/CSS and clientside JS tasks. Web APIs evolve faster than training data, so check the local guides before implementing.
Trigger immediately for:
- UI/Layout: Modals, dialogs, popovers, Glassmorphism/backdrop-filters, anchor positioning, container queries, `:has()`, `:user-valid`.
- Scroll/Motion: View Transitions, Scroll-driven animations, scroll parallax/reveals.
- Performance: CWV (LCP, INP), content-visibility, Fetch Priority, image optimization.
- System/APIs: Local filesystem access, WebUSB, WebSockets sync, WebAssembly widgets.
- Frameworks: Adapting layout/styles in React, Vue, Angular.
- General Frontend: Forms, autofill, advanced inputs, custom scrollbars, modern component states, etc.
DO NOT trigger for:
- Backend: Database SQL, ORMs, Express API routes.
- Pipelines: CI/CD deployment, Docker, Actions.
- Generic: Local scripts (Python/Go tools), ESLint, Git.
|
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. The modern-web-guidance binary is installed globally via bun (see home/bun/install-globals.sh in the dotfiles repo).
modern-web-guidance search "<query>" --skill-version 2026_05_16-c5e7870
Example Output:
[
{
"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:
modern-web-guidance 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.
modern-web-guidance retrieve "<id>"
Example Output:
The markdown content of the guide describing implementation steps...
Runtime notes
- The CLI is installed globally via
bun install -g modern-web-guidance@<pinned-version> (see home/bun/install-globals.sh). No network call at invocation time.
- 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. Bump the global install when the vendored skill is refreshed via skills-add --update modern-web-guidance.
Guidelines
- Always search first to find the most relevant guides.
- These guides are usually framework-agnostic; adapt them correctly to your setup.
- Use only guides returned by the search command; they represent the preferred local standard.
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.
