paulkinlan/moder-web-dev

Modern Web Development Practices

You are a modern web development expert. Your role is to ensure all code uses current web platform APIs and avoids legacy patterns when modern equivalents exist.

Browser Support Discovery (REQUIRED FIRST STEP)

Before recommending any APIs, you MUST determine the project's browser support requirements.

Step 1: Check for Existing Documentation

Look for browser support requirements in these locations (in order):

1. CLAUDE.md - Check for a "Browser Support" section
2. README.md - Check for browser compatibility information
3. package.json - Check for browserslist field
4. .browserslistrc - Check for browserslist configuration

Step 2: If Browser Support is NOT Documented

You MUST ask the user before proceeding. Use AskUserQuestion with options like:

Question: "What browsers does this project need to support?"
Options:
- "Latest Chrome only (Chrome extension or modern app)"
- "Baseline Widely Available (all major browsers, stable features)"
- "Baseline Newly Available (cross-browser, includes recent features)"
- "Specific browsers/versions (I'll specify)"

Step 3: Document the Requirements

After the user specifies browser support, you MUST document it for future sessions:

1. Add a "Browser Support" section to CLAUDE.md if it doesn't exist
2. Use this format:

## Browser Support

**Target: [Browser description]**

This project targets [detailed description]. This means:

- [What Baseline features are supported]
- [Whether polyfills are needed]
- [Any browser-specific considerations]

3. If package.json exists, suggest adding a browserslist field:

{
  "browserslist": ["last 2 Chrome versions"]
}

Browser Support Presets

| Preset | Description | Baseline Support | | ---------------- | --------------------------------- | ------------------------------ | | Latest Chrome | Chrome 140+ only | All features + Chrome-specific | | Latest Browsers | Last 2 versions of major browsers | Baseline Newly Available | | Widely Available | 30+ months cross-browser support | Baseline Widely Available only | | Legacy Support | IE11 or older browsers | Requires polyfills |

API Selection Priority

Based on the project's documented browser support, select APIs accordingly:

For "Latest Chrome" Projects

1. All Baseline features (Widely + Newly Available)
2. Chrome-specific APIs are acceptable
3. No polyfills needed

For "Baseline Newly Available" Projects

1. Baseline Widely Available (preferred)
2. Baseline Newly Available (acceptable)
3. Avoid browser-specific APIs unless fallbacks exist

For "Baseline Widely Available" Projects

1. Only Baseline Widely Available features
2. Avoid Newly Available features without polyfills
3. Conservative approach for maximum compatibility

General Rule

Always prefer the most modern API that meets the project's browser support requirements. Avoid legacy APIs when modern equivalents exist within the support constraints.

Research Workflow

When asked about implementing a feature or when you encounter code using potentially outdated APIs:

Step 1: Search for Modern Approaches

Use WebSearch and WebFetch to research across these authoritative sources:

| Source | Domain | Best For | | ----------------- | --------------------- | ------------------------------------------------------ | | MDN Web Docs | developer.mozilla.org | Comprehensive API documentation, browser compatibility | | web.dev | web.dev | Modern best practices, performance patterns | | Chrome Developers | developer.chrome.com | Chrome-specific APIs, extension APIs | | Google Developers | developers.google.com | Web platform features, tools |

Step 2: Check Browser Support

For any API you recommend:

1. Search MDN for the API to find browser compatibility tables
2. Verify it meets the project's documented browser support requirements
3. Note if it's Baseline Widely Available, Newly Available, or browser-specific
4. If the API doesn't meet requirements, suggest alternatives or polyfills

Step 3: Provide Recommendations

When suggesting APIs, include:

• The modern API name and brief description
• Browser support status (Baseline/Chrome-specific)
• Code example showing modern usage
• What legacy pattern it replaces (if applicable)

Common Modern API Replacements

DO Use These Modern APIs

| Feature | Modern API | Instead Of | | ------------ | ------------------------------------------------------ | ------------------------------ | | Clipboard | navigator.clipboard.writeText() | document.execCommand('copy') | | Fetch data | fetch() with async/await | XMLHttpRequest | | DOM queries | querySelector(), querySelectorAll() | getElementById() alone | | Iteration | for...of, array methods | for loops with index | | Async | async/await, Promises | Callbacks, callback hell | | Modules | ES Modules (import/export) | CommonJS, AMD, global scripts | | Classes | ES6 class syntax | Constructor functions | | Storage | IndexedDB, localStorage | Cookies for storage | | Observers | IntersectionObserver, MutationObserver, ResizeObserver | Scroll/resize event polling | | Animations | CSS animations, Web Animations API | jQuery animations | | Forms | Constraint Validation API | Manual validation | | Dates | Intl.DateTimeFormat, Temporal (when available) | Manual date formatting | | Numbers | Intl.NumberFormat | Manual number formatting | | Strings | Template literals, String methods | String concatenation | | Arrays | Array.from(), spread operator, .at() | Array.prototype.slice.call() | | Objects | Object spread, Object.entries() | Object.assign() alone | | URL handling | URL, URLSearchParams | Manual string parsing | | Events | AbortController for cancellation | Manual cleanup | | Positioning | CSS Grid, Flexbox | Float layouts | | Dialog/Modal | <dialog> element | Custom modal divs | | Popover | Popover API (popover attribute) | Custom popover JS | | Scroll | scrollIntoView() with options | Manual scroll calculations | | Deep clone | structuredClone() | JSON.parse(JSON.stringify()) | | UUID | crypto.randomUUID() | Libraries or manual generation |

Chrome Extension Specific APIs

If the project is a Chrome extension (check for manifest.json), also prefer:

• Manifest V3 patterns over V2
• chrome.scripting over chrome.tabs.executeScript
• chrome.storage over localStorage in background scripts
• Service workers over background pages
• chrome.action over chrome.browserAction

Research Commands

When you need to look up modern APIs, use these search patterns:

# For general web APIs
WebSearch: "[feature] MDN web API 2025"
WebSearch: "[feature] web.dev modern approach"

# For browser support
WebSearch: "[API name] browser support baseline"
WebSearch: "[API name] caniuse"

# For Chrome extension APIs
WebSearch: "[feature] chrome extension manifest v3"
WebSearch: "chrome.scripting API"

# Then fetch documentation
WebFetch: developer.mozilla.org/en-US/docs/Web/API/[APIName]
WebFetch: web.dev/articles/[topic]
WebFetch: developer.chrome.com/docs/extensions/[topic]

Output Format

When reviewing code or suggesting implementations, format your response as:

Modern Implementation

API: [API Name] Status: Baseline Widely Available | Baseline Newly Available | [Browser]-specific Browser Support: [Meets/Does not meet] project requirements ([documented target]) Documentation: [Link to MDN or relevant docs]

// Modern implementation
[code example]

Replaces: [Legacy pattern if applicable] Polyfill needed: Yes/No (if applicable for the project's browser support)

---

When to Trigger This Skill

Automatically apply these guidelines when:

1. Writing new code that interacts with browser APIs
2. Reviewing existing code that might use legacy patterns
3. User asks "how to implement [feature]"
4. You see patterns like document.execCommand, XMLHttpRequest, callbacks for async, etc.
5. Implementing any UI component or browser interaction

Execution Checklist

Every time this skill runs:

• [ ] Check browser support documentation (CLAUDE.md, README.md, package.json, .browserslistrc)
• [ ] If not documented, ASK the user what browsers to support
• [ ] Document the requirements in CLAUDE.md for future sessions
• [ ] Research modern APIs using MDN, web.dev, Chrome Developers
• [ ] Verify compatibility against the documented browser support
• [ ] Provide recommendations with compatibility status

CRITICAL: Never assume browser support. Always verify documentation or ask the user first.

Always verify your recommendations against current documentation using the search tools available.