Update project-guide skill guidelines

[philipwalton]

Summary:

This PR updates the project-guides skill guidelines to provide clearer, more detailed instructions for authoring implementation steps and fallback strategies in web guidance.

Changes:

• Implementation Steps: Added guidance to prioritize the most appropriate feature for the job rather than defaulting to modern features if a legacy feature works just as well and has simpler fallbacks. Clarified that cross-browser fallback logic must be excluded from this section and kept strictly in the fallback section.
• Expanded Fallback Strategies: Revamped the fallback guidance to include an ordered preference of fallback approaches (custom code, robust polyfills, userland abstractions, or progressive enhancement). Requires authors to assess the robustness of the fallback approach and frame necessity in terms of the developer's Baseline target.
• Baseline Status Practices: Created a dedicated subsection for BASELINE_STATUS macro rules. It clarifies that macros must be included for every non-widely available feature, recommending separate subsections for each if multiple features are used.
• Polyfill Best Practices: Added a new subsection detailing strict rules for polyfills. It emphasizes conditional loading, integrating polyfills into the build process over CDNs, and strictly prohibiting polyfills that cause significant performance tradeoffs or require fetching/parsing CSS.
• Formatting: Minor markdown formatting and spacing improvements for readability.

[philipwalton]

@atopal FYI

[paulirish]

really appreciate the thought you put into this fallback policy.

[paulirish]

maybe numbered bullets for this nested list?

[paulirish]

this looks like a lot of text and I was having a hard time parsing it myself. i prompted my agent with "Is it repeating itself? And is there a more concise way to make the same additions to this policy?"

and it returned back this:

### 5. Fallback Strategies

If the primary implementation uses features that are not Baseline Widely Available, you **MUST** include a fallback recommendation in this section.

* **Framing:** Frame fallback necessity in terms of Baseline target (e.g., "If your Baseline target does not support X, use...").
* **Assessment:** Start with a broad assessment of the fallback's robustness. Recommend the modern approach if the fallback is robust; highlight complexity/caveats and suggest alternatives (like userland solutions) if it is not.
* **Experience:** **MANDATORY:** Explicitly describe the fallback experience (progressive enhancement vs. feature detection/graceful degradation).
* **Feature Detection:** Prefer checking `HTMLElement.prototype` (e.g., `'onbeforematch' in HTMLElement.prototype`) over `window` or `document`.
* **Fallback Options (in order of preference):**
    1.  **Custom Code:** Short, reliable reimplementation (**<50 lines**) using widely available features.
    2.  **Polyfill:** A robust, performant polyfill (see guidelines below).
    3.  **Abstraction:** A well-tested userland library.
    4.  **Graceful Degradation:** Baseline Newly Available features that degrade gracefully.
    5.  **Progressive Enhancement:** Frame as progressive enhancement only if no robust fallback exists.
* **Faithfulness:** Fallbacks MUST be faithful to the use case. If the primary recommendation gracefully degrades but ultimately doesn't accomplish the core use case, suggest a different fallback if one is available. Graceful degradation **IS** acceptable for features that enhance, but are otherwise not core to the use case.

#### Baseline Status Macros
* **MANDATORY:** Include `{{ BASELINE_STATUS("feature-id") }}` for *every* non-widely available feature used.
* **Placement:** Use separate subsections with their own macros if multiple features are used. **DO NOT** use macros outside the fallback section.
* **BCD Keys:** **OPTIONAL:** Use `{{ BASELINE_STATUS("feature-id", "bcd.key") }}` if a sub-feature's status differs.

#### Polyfill Guidelines
* **Conditional Loading:** **MANDATORY:** ALWAYS conditionally load polyfills only when native support is missing. Prefer build-integrated conditional loading (code splitting) over CDNs.
* **Performance:** **DO NOT** recommend polyfills with significant performance tradeoffs, or those requiring fetching/parsing CSS. Prefer abstractions/userland solutions instead.
* **Prohibited CDNs:** **DO NOT** recommend polyfills from polyfill.io.

it does looks good to me.. my agent said

Zero loss of information: All new policy points from the PR are preserved.

Reduced Redundancy: Conditional loading and performance expectations for polyfills are stated exactly once.

Better Scanability: Clear separation between meta-rules (framing, assessment, experience) and the ordered list of fallback options.

and.. sure.

anyway.. bikeshedding text with models. lol.

[paulirish]

and here's a ~neutral comparison of the two: https://gemini.google.com/share/dc979d042b89

edit: i incorporated its two pieces of feedback into the above revision.

[philipwalton]

I'm fine with this rewording. I agree with Gemini's assessment that this version don't quite capture the "philosophy" of it as well, but I trust that the LLM can properly interpret both and if so then shorter is better.

The only thing that stands out to me in this version (which was a problem in the previous one as well, just not as obvious), is this line

• Feature Detection: Prefer checking HTMLElement.prototype (e.g., 'onbeforematch' in HTMLElement.prototype) over window or document.

While this is a good best practice, it's a bit weird to have this specific example as the only example rather than having a general rule. What about updating to this?

• Feature Detection: Checks should be tightly scoped to the interface rather than the instance (e.g. use Object.hasOwn(HTMLElement.prototype, 'onbeforematch') over 'onbeforematch' in winow)

[LeaVerou]

Nice!

Ideas for potential improvements, take them or leave them:

• Recommend that fallbacks/polyfills for each feature should be independent, i.e. if you need to provide fallbacks for 2 features, don't assume that if feature A is using the fallback, feature B is also using a fallback, unless we have validated with data that the browsers that support B are a subset of those that support A. Concrete example: style-parent-with-has where the fallback for :has() was also assuming a polyfill for :user-invalid was being used.
• That (at least in CSS and HTML that fail gracefully) non-fallback CSS code can use features whose browser support is a superset of the feature. E.g. there was a discussion a couple weeks ago that @starting-style can use CSS nesting, because the browsers that support nesting are a strict superset of those that support @starting-style.

[jamesnw]

I don't disagree, but as an example of how this will play out, this will apply to the anchor positioning polyfill, and all anchor positioning use cases will not have reasonable non-duplicative fallbacks.

[paulirish]

Yup true. That's deliberate. And unfortunate. But it's the state of things until Bramus gets his way. :)

[jamesnw]

+1 to Bramus getting his way 😄

[LeaVerou]

Seeing @jamesnw's comment got me thinking around polyfills/fallbacks. I wonder if it may make sense to encode a decision framework taking into account:

1. How badly does it fail when the feature is not supported? (which varies both by feature and by use case)
2. How critical is it that the functionality is present? (which varies even within the same use case)
3. What % of users are in browsers that don't support the feature?

Basically trying to quantify total impact as the usual Scale (# of people affected) × Depth (impact per person).

E.g. a heavy polyfill or a complex but high fidelity fallback may make sense for a cutting edge feature where a substantial proportion of users will see the fallback, or when the feature is critical. But e.g. for a feature that's almost Widely Available, especially if not critical, it's not justifiable.

Currently, we don't have a good estimate of 3 so the agent can't make informed decisions, except to the extent it can be inferred from Baseline status, but I've heard @paulirish is working on some improvements around that.

[philipwalton]

I do think it would make sense to have a more nuanced decision tree for fallbacks, and the bar should definitely be higher for limited availability features than it is a feature that is 6 months away from being Baseline widely available.

That said, my biggest concern with CSS polyfills in particular (that require fetching/parsing the CSS and reimplementing the entire cascade logic in JS), isn't just with the size and performance. My biggest concern is that there are just so many limitations and caveats that it's very risky to offer them as a blanket recommendation. The agent just doesn't have enough context about the site to always be able to determine whether or not the polyfill can be safely used—even if the guide documents all of the polyfill limitations.

For example, the anchor positioning polyfill cannot be used on web.dev because web.dev hosts its CSS on the gstatic.com domain, but the agent probably wouldn't know that, because it doesn't have access to the build pipeline for web.dev (which is managed elsewhere in Google infrastructure). In this case the agent would recommend the polyfill and then it would silently fail.

So my point is not that I would never recommend the anchor positioning polyfill (or other CSS polyfills). I'm sure there are many, many situations where it would totally make sense to use. The problem is I just don't think we can safely make that recommendation to every single web developer using modern web guidance.