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 UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility)—including when fixing UX symptoms (e.g., janky interactions, layout shifts).
• Before creating or updating a component, to check if a standardized modern web pattern already exists.
• To avoid implementing ad-hoc solutions or loading large dependencies unnecessarily.

Usage Instructions

Step 1. Search Use Cases

Run modern-web-guidance directly with npx using a 2–5 word action-oriented query for a single web platform capability or UI pattern:

• Keep queries focused and generic: Describe the user-visible capability (<verb> + <UI/platform object>, optionally paired with the target HTML/CSS/JS feature name if known). Omit framework/library names (React, Vue, Tailwind, etc.) and app/domain nouns (product, route, or component/file names). Split multi-feature tasks into separate search calls.
• Example: Search "light dismiss dialog" or "responsive data table", not "dialog" (too terse), "responsive table dark mode" (compound — split into two searches), or "close React settings modal on outside click" (framework/app noise).

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_10_16-6654652b

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: Judge results by their description fields (not raw similarity scores):

• Match found: Call retrieve directly—do not also run list.
• No match on a web UI/CSS/DOM behavior (or broad UI audit): If search returns [] or unrelated descriptions because your phrasing differed from the catalog (or your task spans multiple categories), run npx -y modern-web-guidance@latest list once to check if the pattern is covered under more general terminology.
• Topic not covered: If no guide description directly matches your task, proceed with your implementation without retry loops or retrieving unrelated guides.

Step 2. Retrieve Best Practices

Once you have relevant id(s) from the search results, call retrieve to get the full guide(s)—including both specific use-case guides that match your task and any broader discipline guide (e.g., html, css, forms, accessibility, color, performance, security) that applies. You can pass multiple IDs separated by commas.

npx -y modern-web-guidance@latest retrieve "<id>"

If the output is truncated, you must repeat the command but redirect to a file and read that file.

Example Output: The markdown content of the guide describing implementation steps...

Step 3. Verify Guidance Compliance

When generating or modifying code, cross-check the implementation against the retrieved guide before concluding:

• Applicable Guidance & Fallbacks: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly applied, without forcing unrequested features.
• Task Fulfillment: Confirm that the implementation fully satisfies the user's request.

Step 4. Disclose Skill Usage

When you consult modern-web-guidance for a task, end the response where you deliver those changes with a ### Modern Web Guidance section:

• When retrieved guides shaped your code: Write one bullet (1–2 sentences, ≤75 words) per newly applied <id> in first-person voice explaining the non-obvious implementation choices, CSS/API overrides, or fallbacks <id> required and the pitfall it prevented, anchored by a short verbatim quote of that specific rule or gotcha (never the guide's intro overview): - **\`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("").`
  • Never guess <id>s or quotes from memory after context compaction (re-run search/retrieve if needed), and credit only guide-backed changes from the current turn.
• When searched/listed in this turn but zero guides applied: Write one first-person sentence naming which topics or guides you checked in modern-web-guidance and why none applied (omit if any guide applied).

Using npx / pnpx

• Prefer pnpx over npx if pnpm is available (note: pnpx does not use the -y flag).
• When requesting tool permissions, allowlist npx -y modern-web-guidance@latest * specifically (or pnpx modern-web-guidance@latest *), never bare npx * or pnpx *.
• IMPORTANT: on Windows, using npx may fail. Use npx.cmd ... instead.
• Fetching and running modern-web-guidance requires outbound network access. If running in a sandboxed, permission-gated, or approval-based environment (e.g., Codex, Claude Code), proactively request approval/allowlisting for the command with network access BEFORE executing it the first time, avoiding sandbox network timeouts.
• In sandboxed environments where ~/.npm is read-only or restricted, set NPM_CONFIG_CACHE=/tmp/npm-cache.
• If the command hangs due to being 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 use vanilla HTML/CSS/JS; adapt them to your framework without dropping the modern feature:
  • Types: Spread/cast newly shipped HTML attributes ({...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}, [attr.*]) rather than removing them or merging @types/react.
  • SSR & Bundlers: Guard window/HTMLElement in SSR and load polyfills via bare import('<pkg>') in client effects (or set Vite build.target: 'esnext' for top-level await)—never copy files from node_modules.
  • DOM, IDs & CSS: Call showModal()/moveBefore() via refs on non-VDOM-managed nodes, generate per-instance IDs/anchor-names (useId()), and keep :root and @starting-style top-level/unscoped.
• 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.