Wrap responsive image styles in `@layer astro.images` to respect CSS cascade layers by astrobot-houston · Pull Request #17141 · withastro/astro · GitHub
Skip to content

Wrap responsive image styles in @layer astro.images to respect CSS cascade layers#17141

Merged
matthewp merged 1 commit into
mainfrom
flue/fix-17139
Jun 23, 2026
Merged

Wrap responsive image styles in @layer astro.images to respect CSS cascade layers#17141
matthewp merged 1 commit into
mainfrom
flue/fix-17139

Conversation

@astrobot-houston

Copy link
Copy Markdown
Contributor

Closes #17139

Changes

  • Wraps all CSS generated by generateImageStylesCSS() in @layer astro.images { … }. Per the CSS cascade spec, unlayered styles always beat layered styles regardless of specificity — so the previous unlayered :where([data-astro-image=constrained]){max-width:100%} was silently overriding any user max-width defined inside a @layer, even though :where() has zero specificity. Putting these defaults into a named layer restores the original intent of :where(): Astro's image styles should always be easy for users to override.
  • The layer name astro.images uses a dotted namespace to avoid collisions with user-defined layer names while remaining valid for CSS processors (e.g. lightningcss).
  • Note for users: to guarantee astro.images sits below your own layers, declare the order explicitly: @layer astro.images, layout, page, components;. Without an explicit order declaration, the first-seen layer wins — which may or may not be astro.images depending on stylesheet load order.

Testing

  • Updated assertions in packages/astro/test/units/assets/utils.test.ts to expect the @layer astro.images { … } wrapper around the generated CSS output.

Docs

  • No docs update needed. image.responsiveStyles is already documented as producing overridable defaults; this fix makes that promise actually true when users write CSS layers.

@astrobot-houston astrobot-houston added the fix verified Reporter confirmed the triage bot fix works label Jun 22, 2026
@changeset-bot

changeset-bot Bot commented Jun 22, 2026

Copy link
Copy Markdown

@github-actions github-actions Bot added the pkg: astro Related to the core `astro` package (scope) label Jun 22, 2026
@Daniel15

Copy link
Copy Markdown

I tried this and can confirm it works as expected.

@codspeed-hq

codspeed-hq Bot commented Jun 22, 2026

Copy link
Copy Markdown

@matthewp matthewp merged commit d785b9d into main Jun 23, 2026
31 checks passed
@matthewp matthewp deleted the flue/fix-17139 branch June 23, 2026 12:07
@astrobot-houston astrobot-houston mentioned this pull request Jun 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fix verified Reporter confirmed the triage bot fix works pkg: astro Related to the core `astro` package (scope)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Responsive image CSS overrides CSS from layers

3 participants