[Draft] Respected Authored CSS Specificity

[jonathantneal]

Respected CSS Specificity Proposal

Astro should respect the authored specificity when generating scoped CSS.

Background

Astro component styles are scoped by default, meaning they only apply to items in the component.
These are exclusive styling boundaries that prevent styles from applying to items outside the component or within child components.

To accomplish this, Astro adds an additional class to all elements and selectors, increasing specificity from O+1 to O(1)+1.

See an example of the current behavior.

This specificity increase is perceptually inconsistent to authors, without a deeper knowledge of the Astro internals and Type, ID, add Class selector specificity.
This specificity increase makes it hard to combine with other CSS files or other styling libraries (Tailwind, CSS Modules, Styled Components, Stitches), as those systems would not include our additional side-effects.

Goals

• Allow authored styles to retain their specificity.
• Allow authored styles to retrain exclusive boundaries to the component.
• Allow authored styles to work consistently with other CSS files or other styling libraries.

Non Goals

• Browser support

  Browsers that would not support the proposed solution do not support existing features core to Astro, such as JavaScript modules. Authors wishing to avoid those other aspects could also avoid this aspect by using <style global>.

• Specificity increases on purpose

  Authors relying the specificity increase in our current implementation are still vulnerable to perceptually inconsistent and less unpredictable behavior when using CSS files or other styling libraries.

• Using classes vs data attributes

  The detailed design uses data-prefixed attributes to illustrate the current behavior and proposed solution. The current implementation uses classes. Both implementations share the same specificity behavior, and so either does not affect this proposal.

• Controlling the order of styles

  The order of CSS styles can impact which styles are applied to items. However, that is part of CSS cascade, not CSS specificity. The issues raised in this proposal would still impact the CSS cascade. Therefore, it is not a focus of this proposal.

Solution

Astro can prevent this specificity increase by wrapping the scoping mechanism in a :where() CSS pseudo-class.

By using :where(), styles would now:

• respect the specificity with which they were authored.
• work consistently alongside other CSS files or CSS libraries.
• preserve the exclusive boundaries that prevent styles from applying outside the component.

See an example of the proposed behavior.

---

Detailed Design

Example of the Current Behavior

<style>
p {
  color: blueviolet;
}

aside p {
  color: darkviolet;
}

:global(aside) p {
  text-decoration: underline;
}
</style>
<p>This is a paragraph.</p>
<aside>
  <p>This is a paragraph in an aside.</p>
</aside>

In this example, the HTML and CSS will generally transform into the following code:

<style>
p[data-astro-scope="OZV3B5RX"] {
  color: blueviolet;
}

aside[data-astro-scope="OZV3B5RX"] p[data-astro-scope="OZV3B5RX"] {
  color: darkviolet;
}

aside p[data-astro-scope="OZV3B5RX"] {
  text-decoration: underline;
}
</style>
<p data-astro-scope="OZV3B5RX">This is a paragraph.</p>
<aside data-astro-scope="OZV3B5RX">
  <p data-astro-scope="OZV3B5RX">This is a paragraph in an aside.</p>
</aside>

Authored Selector	Compiled Selector	Authored Specificity	Compiled Specificity
p	p[data-astro-scope="OZV3B5RX"]	0.0.1	0.1.1
aside p	aside[data-astro-scope="OZV3B5RX"] p[data-astro-scope="OZV3B5RX"]	0.0.2	0.2.2
:global(aside) p	aside p[data-astro-scope="OZV3B5RX"]	0.0.2	0.1.2

Example of the Proposed Behavior

<style>
p {
  color: blueviolet;
}

aside p {
  color: darkviolet;
}

:global(aside) p {
  text-decoration: underline;
}
</style>
<p>This is a paragraph.</p>
<aside>
  <p>This is a paragraph in an aside.</p>
</aside>

In this example, the HTML and CSS will generally transform into the following code:

<style>
p:where([data-astro-scope="OZV3B5RX"]) {
  color: blueviolet;
}

aside:where([data-astro-scope="OZV3B5RX"]) p:where([data-astro-scope="OZV3B5RX"]) {
  color: darkviolet;
}

aside p:where([data-astro-scope="OZV3B5RX"]) {
  text-decoration: underline;
}
</style>
<p data-astro-scope="OZV3B5RX">This is a paragraph.</p>
<aside data-astro-scope="OZV3B5RX">
  <p data-astro-scope="OZV3B5RX">This is a paragraph in an aside.</p>
</aside>

Authored Selector	Compiled Selector	Authored Specificity	Compiled Specificity
p	p:where([data-astro-scope="OZV3B5RX"])	0.0.1	0.0.1
aside p	aside:where([data-astro-scope="OZV3B5RX"]) p:where([data-astro-scope="OZV3B5RX"])	0.0.2	0.0.2
:global(aside) p	aside p:where([data-astro-scope="OZV3B5RX"])	0.0.2	0.0.2

Open Questions

Is there another way to increase the specificity of component styles without the unexpected behaviors that were mentioned?

No, not currently. It will only be possible once browsers widely support the @layer CSS At-rule.

[Ceres6]

This would be great. Maybe in the meantime we can update the Astro docs to make clear this gotcha (e.g. in the build a blog tutorial and the styling docs). In fact the docs seem to suggest this problem doesn't exist.

I also thought of modifying the astro plugin to inline the scoped style so that it's easier to calculate the specificity. I don't know how difficult would this be, but I'm happy to try if there is interest for this

[Princesseuh]

The docs does not mention this because this problem doesn't exist anymore. See https://docs.astro.build/en/reference/configuration-reference/#scopedstylestrategy for more information.