agentleFS
OutThisLifeOutThisLife/brooklyn-skills/skills/modern-web-guidance/SKILL.md

modern-web-guidance

Skill215 starsChanged 4 months agoMITView on GitHub

Search tool for modern web development best practices. MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip — web APIs evolve rapidly and training weights contain obsolete patterns. Trigger immediately for: modals/dialogs/popovers, tables, dark mode, anchor positioning, container queries, view transitions, scroll-driven animations, parallax/reveals, forms, validation, autofill, accessibility, custom selects, scrollbars, CWV (LCP, INP, CLS), content-visibility, fetch priority, image optimization, security, passkeys, HTML sanitization, web components, dates/timezones, built-in AI, WebAssembly, standard HTML/CSS/DOM in frameworks, etc. DO NOT trigger for: backend (SQL, ORMs, API routes), infra/scripts (CI/CD, Docker, Actions, Python/Go, Git), or tooling/trivial (Vite, tsconfig, ESLint, tests, copy/renames, 3P docs), etc.

23 other projects use a version of this, 13 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use chrome-extensions, code-review-and-quality and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • thistleknotSkill

    chrome-extensions

    Build, install and verify a personal Chrome extension that does something on the local machine (write a file, run a script) when its toolbar button is clicked. Covers the Manifest V3 extension + native-messaging host pattern, pinning the extension ID with a "key", registering the host under HKCU (no admin), the one manual "Load unpacked" step and why automation cannot do it, and how to test the real Chrome round trip yourself without clicking the toolbar. Trigger on "chrome extension", "browser button that saves to a file", "native messaging", "clip the page to a file", "load unpacked", "extension shows a red !".

    Also in 4 projects that use this

  • LLl0k0laDSkill

    code-review-and-quality

    Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.

    Also in 3 projects that use this

  • VercelSkill

    find-skills

    Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 2 are common, 3 are distinctive, and 11 are very specific to this project.

  • 2

    Common

    Most of the 20 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search and retrieve standardized modern web best practices at the start of implementing or updating any web UI, CSS layout/animation, or …

    line 11
  2. Very specific:

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

    line 17
  3. Very specific:

    Example: Search "light dismiss dialog" or "responsive data table", not "dialog" (too terse), "responsive table dark mode" (compound — split …

    line 20
  4. Very specific:

    If retrieve saves large output (> 9.5 KB) to a temporary file to prevent truncation, read that file path in full using your file-reading …

    line 39
  5. Distinctive:

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

    line 43
  6. Distinctive:

    Applicable Guidance & Fallbacks: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly …

    line 44
  7. Very specific:

    Do not run legacy-scan; it's for detecting legacy patterns to modernize, not this.

    line 46
  8. Very specific:

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

    line 50
  9. Very specific:

    When searched/listed in this turn but zero guides applied: Write one first-person sentence naming which topics or guides you checked in …

    line 54
  10. Very specific:

    Only: when asked for a broad, open-ended codebase modernization or legacy-pattern scan where no specific target feature or component is …

    line 58
  11. Very specific:

    Verify: Check each finding against its keepWhen / dropWhen rubric.

    line 67
  12. Very specific:

    Runner & Permissions: Prefer pnpx over npx if pnpm is available (pnpx does not use -y).

    line 74
  13. Very specific:

    Offline: If the command hangs due to being offline, retry with npx --offline ….

    line 76
  14. Common:

    Always search first to find the most relevant guides.

    line 80
  15. Very specific:

    DOM, IDs & CSS: Call showModal()/moveBefore() via refs on non-VDOM-managed nodes, generate per-instance IDs/anchor-names (useId()), and …

    line 84
  16. Common:

    Default Behavior: All guides assume Baseline Widely available features are safe to use without fallbacks.

    line 88

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Modern Web Guidance

Search and retrieve standardized modern web best practices at the start of implementing or updating any web UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility, UX fixes) before writing ad-hoc solutions or adding dependencies.

Primary Workflow

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.
  • Name implied UI primitives: When the user's prompt expresses intent without naming the UI primitive (e.g. "confirm first", "delete with confirmation", "pick a date"), translate the domain intent into the implied UI component or platform mechanism (e.g. search "confirmation modal dialog" or "confirm dialog" rather than "confirm destructive action", or "date picker input" rather than "pick a date").
  • 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_11_09-5bcc021b

Note: Returns [{ "id", "description" }, ...]. Judge results by their description fields:

  • Match found: Call retrieve directly—do not also run list.
  • Weak or empty results: If search returns [] or unrelated descriptions, rephrase search once using the concrete HTML/CSS/UI component noun or synonym (e.g., dialog, modal, popover, table, form) before falling back to list (or use list once for broad UI audits).
  • Topic not covered: If no description matches after rephrasing, proceed without 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 retrieve saves large output (> 9.5 KB) to a temporary file to prevent truncation, read that file path in full using your file-reading tool (reading remaining line ranges if needed)—do not use cat or head.

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.
  • Do not run legacy-scan; it's for detecting legacy patterns to modernize, not this.

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): - **\<id>`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("<short verbatim quote of the specific rule or gotcha>").`
    • 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).

Alternative flow: Modernize an existing codebase

Only when asked for a broad, open-ended codebase modernization or legacy-pattern scan where no specific target feature or component is named (do not run legacy-scan when asked to add, update, fix, or audit a specific feature or component), run the 4-step modernization flow:

Note: legacy-scan scans for a curated subset (~20% of the guidance corpus).

npx -y modern-web-guidance@latest legacy-scan <path> --json
  1. Scan: Run legacy-scan <path> --json to detect legacy web platform patterns across the project or directory.
  2. Verify: Check each finding against its keepWhen / dropWhen rubric; drop false positives (fallbacks, cross-file helpers, vendor code, lookalikes).
  3. Report: Summarize verified findings (and the modernization plan, if editing) for the user, noting that legacy-scan only checks the subset of guides (~20% of the catalog) that have deterministic legacy rules.
  4. Modernize (when the user asked to modernize rather than only audit/report): Retrieve each finding's guide (retrieve "<guide-id>" via Step 2), apply the replacement (keeping existing libraries as fallbacks where the guide requires one), and re-run legacy-scan <path> on the modified files to confirm resolution.
    • Dropped findings and kept fallbacks still match static scans; do not edit safe code or inspect legacy-scan.mjs to force 0 findings.

Using npx / pnpx

  • Runner & Permissions: Prefer pnpx over npx if pnpm is available (pnpx does not use -y); on Windows, use npx.cmd. When requesting tool permissions, allowlist npx -y modern-web-guidance@latest * (or pnpx modern-web-guidance@latest *) specifically, never bare npx * or pnpx *.
  • Sandboxes & Network: Fetching modern-web-guidance requires outbound network access. In sandboxed or approval-gated environments (e.g., Codex, Claude Code), proactively request approval/allowlisting with network access BEFORE the first execution to avoid timeouts, and set NPM_CONFIG_CACHE=/tmp/npm-cache if ~/.npm is read-only.
  • Offline: If the command hangs due to being offline, retry with npx --offline ….

Guidelines

  • Always search first to find the most relevant guides. Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.
  • 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.

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 defines explicit browser support requirements, use the guide's compatibility data to determine if a fallback can be ignored (for Baseline YYYY targets, a feature satisfies the target if its "Baseline since" date is <= YYYY). Examples: "Do not implement feature fallbacks", "Safari 17.4+", "Never implement polyfills; use a lightweight custom fallback or redesign", or "Allow Newly Available features if feature-detected with graceful degradation".
  • Reactive Policy Discovery: Suggest documenting a policy in AGENTS.md or CLAUDE.md (e.g., **Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and no external dependencies) if the developer targets a restricted runtime (Electron/Tauri), excludes specific browsers, hesitates over polyfill size/complexity, or asks if a feature is safe without fallbacks.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.