You receive a report that the mobile layout is broken and open the CSS to fix the offending media query. You then find @media (max-width: 768px) scattered across dozens of locations throughout the file. Fixing just one spot leaves older values intact elsewhere, keeping the layout broken. In the end, you find yourself running a global search-and-replace for "768px" across all files, while also hunting for variations like 767px or 769px just in case. When taking over maintenance for sites built by other vendors in client web development, you encounter this scenario with alarming frequency. If breakpoint values are hardcoded and scattered throughout your CSS, every responsive fix turns into a high-stakes gamble where fixing one part risks breaking another.
The fundamental solution to this dispersion is @custom-media, which assigns names to media query conditions for centralized management. As highlighted in @custom-media (CSS-Tricks Almanac) published by CSS-Tricks in June 2026, this feature—which long relied on build tools like PostCSS—is steadily moving toward native browser implementation. In this article, we organize how to use @custom-media as a tool for creating resilient responsive designs in client web development and how to migrate existing sites.
Why hardcoding breakpoints leads to breakdown
Directly writing conditions like @media (max-width: 768px) in various places across your CSS poses no problems initially. The breakdown occurs as the site expands and the following three factors collide.
First is scattered values. Even when referring to the exact same tablet boundary, 768px is written independently across different components and files. If design requirements demand updating that boundary to 820px, missing even a single instance leaves that specific location running on the outdated behavior.
Second is loss of intent. Looking at a bare number like max-width: 768px, you cannot discern whether it was intended for mobile, portrait tablets, or the specific constraints of an isolated component. The next developer must modify it without knowing what the number was originally supposed to represent.
Third is inconsistent notations. When 768px and 767.98px or max-width and min-width coexist, styles can apply doubly around the boundary or leave gaps where no styles apply. These discrepancies cannot be reliably caught with search-and-replace, leading to prolonged debugging sessions.
@custom-media resolves all three issues through naming. By defining boundary values in a single location and referencing that name elsewhere, changing a value requires updating only one line of definition to take effect globally. Developers reading the code see an expressive name that conveys intent rather than an arbitrary number.
@custom-media basics — assigning names to conditions
Using it is as simple as assigning custom property-like names to media query conditions. First, organize your definitions at the top of the project or inside a dedicated file.
/* ブレークポイントの定義を一か所に集約 */
@custom-media --sp (max-width: 600px); /* スマホ */
@custom-media --tablet (max-width: 900px); /* タブレット以下 */
@custom-media --pc (min-width: 901px); /* PC */
@custom-media --reduce-motion (prefers-reduced-motion: reduce);Then, within each component, reference the name instead of raw numbers.
.card-grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
}
/* 「タブレット以下なら2列」が一読で分かる */
@media (--tablet) {
.card-grid { grid-template-columns: repeat(2, 1fr); }
}
@media (--sp) {
.card-grid { grid-template-columns: 1fr; }
}There are two key takeaways. First, reading @media (--tablet) instantly communicates the intent: "this adjustment applies to tablet viewports and below." Second, if you later decide to shift the tablet boundary from 900px to 820px, you only need to change a single line in the definition, and the change immediately propagates to every reference. Concerns over search-and-replace omissions and inconsistent notation disappear.
Beyond media queries, you can also assign names to feature queries like prefers-reduced-motion, allowing you to centralize accessibility conditions. This lets you reuse the intent of "targeting users who prefer reduced motion" across your codebase under the name --reduce-motion.
Designing breakpoints as part of design tokens
The true value of @custom-media emerges not when used in isolation, but when bundled as part of your design system tokens. If you already manage colors, spacing, and typography using custom properties, bringing breakpoints into that same central place formalizes responsive baselines as explicit design conventions, ensuring anyone touching the codebase adheres to the same boundaries.
However, keep in mind that @custom-media can only be used within the condition part of @media; it cannot be embedded as an arbitrary property value like var(). Conversely, standard CSS custom properties such as --color-primary cannot be used in media query conditions. Because their roles are distinct, take care not to confuse them. When designing tokens as reusable CSS functions, pairing this with the concept of encapsulating value generation logic within names—as covered in our article on CSS @function—will improve overall token clarity.
| How it works | What is named | Where it can be used |
|---|---|---|
| @custom-media | Media query conditions (boundaries, features) | Inside @media (...) |
| Custom properties (—x) | Values (colors, spacing, sizes) | Property values (var()) |
Tokenizing colors and spacing while leaving breakpoints hardcoded everywhere leaves a design system half-finished. Breakpoint boundaries should be managed with the same granularity—like --tablet—as colors are managed with --color-primary. The concept of maintaining color consistency connects directly to the principle discussed in the article on self-correcting color systems with contrast-color(): relying on mechanisms rather than hardcoding values.
How to introduce it to existing sites in client web development
On the corporate website of a home renovation company whose maintenance we took over (company name withheld), the "global search-and-replace for 768px" occurred during every single update. Inspecting the CSS revealed a mixture of 768px, 767px, 769px, and 48em, meaning four different values were being used for what was intended to be the same tablet boundary. Styles applied doubly around the threshold, triggering momentary layout breaks at specific screen widths.
Rather than a full rebuild, we chose a phased consolidation. First, we audited all breakpoint values used in the existing CSS and established a policy to consolidate them into three intentional categories: --sp, --tablet, and --pc. Next, we systematically replaced @media (max-width: 768px) with @media (--tablet) while normalizing variations into standard values. For environments where native browser support was still uncertain, we integrated a build plugin to transpile them into traditional @media syntax, keeping the compiled CSS functional in legacy browsers. We did not perform an elaborate platform rewrite; we simply assigned names to scattered boundaries and centralized them. As a result, subsequent responsive updates required editing just a single line in the definition, and overlapping style conflicts around breakpoints were eliminated.
The single most effective lesson from this project was never attempting to migrate everything all at once. Because traditional @media syntax and @custom-media can coexist, you can migrate to named references gradually starting with new or modified components, only replacing legacy hardcoded values when touching relevant code. Attempting a wholesale conversion leads to massive diffs, causing code reviews and regression testing to collapse. Deciding which syntax to deploy natively and where to supplement with build tools can be safely guided by interpreting Baseline, as detailed in our article on modern native CSS features.
Where to begin
If your responsive maintenance has degraded into a search-and-replace gamble each time, we recommend listing every breakpoint value currently used across your project. Seeing how many variations of the same conceptual boundary are scattered throughout will immediately highlight what needs consolidation.
The next step is defining a small set of names—such as --sp, --tablet, and --pc—and switching to named references whenever you work on new or updated components. By avoiding forced mass conversions and migrating legacy hardcoded values incrementally alongside regular updates, you can keep both diffs and verification overhead minimal.
If you are struggling with recurring responsive layout glitches or bloated CSS that developers hesitate to touch, please reach out via the GleamHub contact form. We can audit your current site's CSS, centralize breakpoints and design tokens, and reorganize your codebase into a maintainable structure.
