Add CSS @custom-media at-rule

[ramiy]

Description

Firefox 146 added support for @custom-media at-rule, enabling developers to use custom media variables inside @media at-rules.

I already updated BCD, and created a web feature on web platform. This PR adds an article to MDN explaining how and when to use Custom Media Queries.

Additional details

Over a year ago I tried to add this article but it was denied as no browser implemented this feature.

Now, with Firefox implementing it, we can add an article, explaining how to use this feature.

[github-actions]

Preview URLs (9 pages)

• /en-US/docs/Mozilla/Firefox/Experimental_features
• /en-US/docs/Mozilla/Firefox/Releases/146
• /en-US/docs/Web/API/CSSStyleSheet/insertRule
• /en-US/docs/Web/CSS/Guides/Media_queries/Using
• /en-US/docs/Web/CSS/Guides/Media_queries
• /en-US/docs/Web/CSS/Reference/At-rules/@custom-media
• /en-US/docs/Web/CSS/Reference/At-rules/@media
• /en-US/docs/Web/CSS/Reference/At-rules
• /en-US/docs/Web/CSS/Reference/Values/rule-list

Flaws (9)

Note! 7 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/CSS/Reference/At-rules/@custom-media
Title: @custom-media
Flaw count: 7

• broken_links:
  • Can't resolve /en-US/docs/Web/CSS/extension-name
  • /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#brackets is a redirect
  • Can't resolve /en-US/docs/Web/CSS/media-query-list
  • /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
  • /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
  • and 2 more flaws omitted

---

URL: /en-US/docs/Web/CSS/Reference/At-rules/@media
Title: @media
Flaw count: 2

• broken_links:
  • Can't resolve /en-US/docs/Web/CSS/media-query-list
  • Can't resolve /en-US/docs/Web/CSS/rule-list

External URLs (2)

URL: /en-US/docs/Mozilla/Firefox/Experimental_features
Title: Experimental features in Firefox

• https://bugzil.la/1744292 (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Mozilla/Firefox/Releases/146
Title: Firefox 146 release notes for developers (Beta)

• https://bugzil.la/1744292 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-12-02 16:35:43)

[chrisdavidmills]

Hi there @ramiy! Some really nice work here, thank you! I've got a bunch of comments, but nothing too serious — this is definitely going in the right direction.

[ramiy]

@chrisdavidmills I have a question about the following flaws:

They are not part of my content. They are caused by:

## Formal syntax

{{csssyntax}}

which generates:

Nevertheless, I create an article for rule-list, but the {{csssyntax}} macro is still displayed as a broken link.

It links to:

• /en-US/docs/Web/CSS/rule-list

Instead of:

• /en-US/docs/Web/CSS/Reference/Values/rule-list

I tried to look for a way to redirect to the links, but I found only the docs explaining how to move pages, which didn't work.

[chrisdavidmills]

I have a question about the following flaws:

@ramiy I wouldn't worry about this. This is something we really need to fix/improve in the platform.

[chrisdavidmills]

@ramiy much better, and so very nearly there. Just a handful of minor comments on the new additions.

[dipikabh]

Thank you @ramiy for taking on this work! 🏆
Thanks @chrisdavidmills for helping out with the review 🙌

[chrisdavidmills]

Awesome work, @ramiy! I think this is ready to merge now.

[yisibl]

This requires adding a live demo to the documentation.
#42201 (comment)