While Modern Web Guidance aims to move your development toward a "correct-by-default" approach, you may occasionally encounter issues with agent activation, implementation accuracy, or feature discovery. This section provides diagnostic steps to help you resolve common challenges, such as ensuring the Modern Web skill is properly triggered by your prompts or verifying that code fallbacks align with your project's established Baseline status. If you encounter persistent technical hurdles or identify outdated guidance, we encourage you to file an issue to help us keep these resources accurate and effective.
Diagnose Modern Web Guidance not being used by your agent
When Modern Web Guidance is installed, agents are instructed to use it for any web development tasks. However, agents sometimes ignore these instructions.
You can explicitly instruct the agent to use Modern Web Guidance by appending a phrase like "use modern-web-guidance" to the end of your prompt.
Some agents also support direct invocation of a skill using specific syntax, such as /modern-web-guidance or $modern-web-guidance, depending on the agent.
Refer to your agent's documentation, or ask your agent how to directly invoke the modern-web-guidance skill if unsure.
Diagnose "hallucinated" code or guessed implementations
This is a common occurrence where the LLM fills in knowledge gaps without warning. To prevent the agent from inventing information, we have found that appending the following instruction to your prompts is very helpful:
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
Diagnose failure to trigger specific guidance
If you are targeting a specific feature use case and you are not seeing it being discovered by the agent, ensure that your prompts include specific keywords and anchor requirements for proper discoverability. It helps the agent to identify the relevant guidance track (for example: "view transitions", "LCP optimization").
Track the agent's thought process:
- Check the output to see if it invoked the
modern-web-guidanceskill. - Locate the search call—for example,
npx -y modern-web-guidance@latest search "carousel scroll snap"—and identify if the keywords and resulting guides were the ones you expected. - Check that the retrieve call requested the relevant guide, for example:
npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync".
Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(npx -y modern-web-guidance@latest search "carousel scroll snap" --skill-version 2026_05_16-c5e7870)
⎿ [{"id":"carousel-snap-highlights","description":"Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden
content.","category":"user-experience","featuresUsed":["Container scroll-state queries"],"tokenCount":1442,"similarity":0.7783},
{"id":"carousel-slide-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller,
etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"],"tokenCount":2105,"similarity":0.6625},
{"id":"scroll-snap-state-sync","description":"Synchronize navigation indicators, linked content panels, and analytics tracking with the actively snapped item in a scrollable container.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1053,"similarity":0.6166},
{"id":"scroll-snap-realtime-feedback","description":"Provide real-time visual feedback in linked UI elements while a user scrolls through snap-aligned content, before the scroll gesture completes.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1886,"similarity":0.5664},
{"id":"navigation-drawer","description":"Create a navigation drawer component that, when triggered from a menu button, slides in from the side overlayed on top of existing page content, and slides out when dismissed (by swiping away, tapping outside, or pressing
escape).","category":"user-experience","featuresUsed":["inert","Intersection observer","Popover","Registered custom properties","Scroll-driven animations","scroll-initial-target","Scroll snap"],"tokenCount":4317,"similarity":0.5099}]
● Bash(npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync")
⎿ <output +158 lines>
}, undefined);
if (topEntry) setSelectedParagraph(topEntry.id);
},
{ root: main, threshold: 0.9 // Adjust based on your use case },
);
// Observe all snap targets (e.g., section headers)
document.querySelectorAll('h2').forEach(header => observer.observe(header));
}
- You can also run the search commands yourself in the terminal to see what guides match your search query.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
Feedback
If you have any additional questions or feedback on these new features, first read about how to contribute to Modern Web Guidance before filing an issue in our GitHub repository. While creating the issue, provide the initial agent prompts, screenshots and logs of the agent's thought process, and the final code change recommended based on that thinking.