CSS-Library: use postcss to reorder media queries

[powellkerry]

Chromatic

https://6069-overwrite-media-query-ordering--65a6e2ed2314f7b8f98609d8.chromatic.com

Summary

Reorders media-queries on build and minify to be mobile first, resolves issue with medium breakpoints overwriting desktop

Description

USWDS appends custom media-queries to the end of the generated media-queries, since the css-library has a custom "medium" query, it was being added after other media-queries causing it to overwrite desktop and widescreen breakpoints. This fix adds postcss to re-order the media-queries after build.

Related tickets and links

Closes #6069

Screenshots

Before

After

Testing and review

Provide any testing instructions or review steps as needed.

Approvals

See the QA Checklists section below for suggested approvals. Use your best judgment if additional reviews are needed. When in doubt, request a review.

Approval groups

Add approval groups to the PR as needed:

• Engineering: platform-design-system-fe
• Accessibility: platform-design-system-a11y
• Design: platform-design-system-designer

QA checklists

Use the QA checklists below as guides, not rules. Not all checklists will apply to every PR but there could be some overlap.

In all scenarios, changes should be fully tested by the author and verified by the reviewer(s); functionality, responsiveness, etc.

✨ New Component Added

• The PR has the minor label
• The component matches the Figma designs.
• All properties, custom events, and utility functions have e2e and/or unit tests
• A new Storybook page has been added for the component
• Tested in all VA breakpoints.
• Chromatic UI Tests have run and snapshot changes have been accepted by the design reviewer
• Tested in vets-website using Verdaccio
• Engineering has approved the PR
• Design has approved the PR
• Accessibility has approved the PR

🌱 New Component Variation Added

• The PR has the minor label
• The variation matches its Figma design.
• Any new properties, custom events, or utility functions have e2e and/or unit tests
• A new story has been added to the component's existing Storybook page
• Any Chromatic UI snapshot changes have been accepted by a design reviewer
• Tested in vets-website using Verdaccio
• Engineering has approved the PR
• Design has approved the PR

🐞 Component Fix

• The PR has the patch label
• Any new properties, custom events, or utility functions have e2e and/or unit tests
• Any markup changes are evaluated for impact on vets-website.
  • Will any vets-website tests fail from the change?
• Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
• Engineering has approved the PR

♿️ Component Fix - Accessibility

• The PR has the patch label
• Any new properties, custom events, or utility functions have e2e and/or unit tests
• Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
• Engineering has approved the PR
• Accessibility has approved the PR

🚨 Component Fix - Breaking API Change

• The PR has the major label
• vets-website and content-build have been evaluated to determine the impact of the breaking change
• Any new properties, custom events, or utility functions have e2e and/or unit tests
• Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
• Tested in vets-website using Verdaccio
• Engineering has approved the PR

🔧 Component Update - Non-Breaking API Change

• The PR has the minor label
• Any new properties, custom events, or utility functions have e2e and/or unit tests
• Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
• Engineering has approved the PR

📖 Storybook Update

• The PR has the ignore-for-release label
• Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
• Engineering has approved the PR

🎨 CSS-Library Update

• The PR has the css-library label
• vets-website and content-build have been checked to determine the impact of any breaking changes
• Engineering has approved the PR

[powellkerry]

I attempted to resolve this by updating the _uswds-theme.scss config like this:

  $theme-utility-breakpoints: (
    "card": false,
    "card-lg": false,
    "mobile": false,
    "mobile-lg": false,
    "tablet": false,
    "tablet-lg": false,
    "desktop": false,
    "desktop-lg": false,
    "widescreen": false
  ),
  $theme-utility-breakpoints-custom: (
    "mobile": 320px,
    "mobile-lg": 480px,
    "tablet": 640px,
    "medium-screen": 768px,
    "desktop": 1024px,
    "desktop-lg": 1200px,
    "widescreen": 1440px,
  ),

But since we are not changing the names of the other breakpoints they they already exist in the USWDS map and the result was the same.

[powellkerry]

postcss-sort-media-queries consolidates media queries, which is an unexpected optimization. Here is what that means:

• No duplicate media queries
• Number of media-queries on main is 278, that is reduced in this branch to 14
• The number of CSS rules remained unchanged at 4,412 (all rules are preserved)
• A bundle size reduction of 2.6% or 14.9KB

[powellkerry]

USWDS PR to fix root issue here: uswds/uswds#6610

[Copilot]

Pull request overview

This PR updates the css-library build pipeline to reorder generated media queries to be mobile-first (addressing a breakpoint override issue caused by USWDS appending custom media queries at the end).

Changes:

• Add PostCSS tooling and configuration to sort media queries (postcss-sort-media-queries).
• Update css-library build scripts to run PostCSS after Sass compilation.
• Regenerate dist/ CSS outputs (and associated token timestamps/source maps) to reflect the new ordering.

Reviewed changes

Copilot reviewed 2 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
yarn.lock	Adds PostCSS-related dependencies to the repo lockfile.
packages/css-library/yarn.lock	Adds PostCSS-related dependencies to the css-library lockfile.
packages/css-library/postcss.config.js	New PostCSS config enabling mobile-first media query sorting.
packages/css-library/package.json	Updates build scripts to run PostCSS; adds PostCSS dependencies; bumps version.
packages/css-library/dist/tokens/scss/variables.scss	Regenerated token output (timestamp update).
packages/css-library/dist/tokens/css/variables.css	Regenerated token output (timestamp update).
packages/css-library/dist/stylesheets/uswds-typography.css.map	Regenerated stylesheet source map reflecting PostCSS processing.
packages/css-library/dist/stylesheets/uswds-typography.css	Regenerated stylesheet output (formatting/order updates).
packages/css-library/dist/stylesheets/shame.css.map	Regenerated stylesheet source map reflecting PostCSS processing.
packages/css-library/dist/stylesheets/shame.css	Media queries reordered/combined per mobile-first sort.
packages/css-library/dist/stylesheets/mobile-typography.css.map	Regenerated stylesheet source map reflecting PostCSS processing.
packages/css-library/dist/stylesheets/mobile-typography.css	Regenerated stylesheet output (formatting/order updates).
packages/css-library/dist/stylesheets/core.css.map	Regenerated stylesheet source map reflecting PostCSS processing.
packages/css-library/dist/stylesheets/core.css	Media queries reordered/relocated per mobile-first sort.

[jamigibbs]

This looks good although copilot brings up a question about generated source maps that we might want to verify when you test the release candidate.