Recommended tooling

Recommended tools

• PostCSS
• Lightning CSS
• Stylelint
• Browserslist
• Astro, 11ty (Eleventy, now Build Awesome), or another static-first build system

Choose a baseline first

• Minimum baseline: native CSS layers and Stylelint.
• Expanded baseline: add PostCSS or Lightning CSS when you need transforms or broader compatibility.
• Team baseline: keep one shared pipeline across projects to avoid divergent CSS behavior.

Custom media queries

Named breakpoints make media queries easier to read and easier to change. Breakpoints should describe layout needs, not specific devices. Component CSS should say what breakpoint it targets, not ask every developer to remember what a number means.

@custom-media --mobile (width < 768px);
@custom-media --from-tablet (width >= 768px);
@custom-media --tablet (768px <= width < 1280px);
@custom-media --until-desktop (width < 1280px);
@custom-media --desktop (width >= 1280px);
@custom-media --large-desktop (width >= 1680px);
@custom-media --reduced-motion (prefers-reduced-motion: reduce);

Directional helpers such as --from-tablet and--until-desktop are often more useful than rigid device labels. Accessibility queries such as--reduced-motion should be treated as first-class breakpoints too.

Authors write @custom-media in the settings layer; the build emits normal @media rules browsers understand. No major engine ships custom media natively yet—when the build step is worth the cost, and how it fits browserslist, is covered underCustom media queries and the build step.

Compatibility caveat: do not ship CSS that still contains@media (--name) if any delivery path skipped the expand step.

.product-card {
    /* Shared styles */

    @media (--desktop) {
        /* Desktop-only changes */
    }

    @media (--reduced-motion) {
        transition: none;
    }
}

Avoid scattering raw breakpoint numbers through component files.

.product-card {
    @media (min-width: 1024px) {
        /* What does 1024px mean here? */
    }
}

Browserslist and feature support

Tooling should follow a written browser support strategy. Use browserslist where your tools support it, and prefer feature-based support decisions over guessing browser versions by habit. The Apply pageBrowser support walks through config files, printing the resolved browserslist, and how prefixes and transpilation stay aligned.

Browser support choices should be documented, reviewed, and based on the project. They should not live as unwritten assumptions in old build config.

Compatibility caveat: if one package or app in a monorepo has a different browserslist target, verify that shared CSS outputs stay aligned across those builds.

Linting

Stylelint should support the methodology. It should catch avoidable mistakes, not force a naming system the project does not use or paper over unclear architecture with automatic formatting.

• Disallow styling with IDs.
• Discourage unnecessary !important.
• Flag unknown custom properties where possible.
• Enforce layer and ownership rules where Stylelint can express them.
• Allow the project’s chosen naming style.

Layer support

The build should preserve cascade layers and process imports in a way that keeps layer order predictable.

@layer legacy, settings, base, utilities,
layout, components, theme, hacks;

Read the media query organisationguidance alongside this page. Tooling only helps when the CSS rules are clear first.

Compatibility caveat: imported CSS from third-party libraries may not declare layers. Assign @import … layer(thirdparty) orlayer(legacy) so vendor styles stay in a dedicated low bucket and do not bypass your intended layer order — seelegacy and third-party layers.