From 0001cbbe409c0bd139660bc4bc941acf38f42e6d Mon Sep 17 00:00:00 2001 From: Stephanie Hobson Date: Wed, 9 Sep 2026 12:01:10 -0700 Subject: [PATCH 1/2] Update browser support matrix to Firefox ESR, Safari 15.6+, evergreen Replaces the stale "defaults, IE 8" browserslist query in package.json with an explicit matrix: Firefox ESR, current Firefox, Safari/iOS >= 15.6, and the last 2 versions of Chrome, Edge, Opera, and Samsung Internet. This query is read by cssnano (via css-minimizer-webpack-plugin) for the shipped, minified CSS, and now drives Babel's compile target directly -- removed the hardcoded targets: { ie: '10' } override from all four babel-loader configs (docs site JS, Fractal theme JS, npm package JS, and the test bundle) so @babel/preset-env reads the browserslist config instead. Verified the compiled package JS now retains ES2015+ syntax (arrow functions) that was previously downleveled for IE10. Also updates docs and comments that assumed IE/legacy browser support: - New docs/02-usage/03-browser-support.md documenting the matrix - CHANGELOG.md: filled in the v23 placeholder, expanded Browser Support - AGENTS.md: corrected the stale "target IE10" JS description - Removed the now-false claim in themes.md that Protocol still ships a Sass-variable fallback theme for browsers without CSS custom properties (removed separately when _themes-sass.scss's Sass color variables were deleted) - Removed now-moot 'older browsers' caveats about
, CSS grid, and inline SVG support in three component readmes Part of the v23 browser-support workstream (#1084). CSS/JS dead-code removal for the new matrix follows in separate stacked PRs. Verified: npm run lint, npm test (47 specs, Firefox + Chrome), and npm run build-package all pass. --- AGENTS.md | 2 +- CHANGELOG.md | 4 ++- .../00-basic-elements/details/readme.md | 8 +++-- components/button/button--with-icon.readme.md | 2 +- components/layout/02-columns/readme.md | 5 +-- docs/01-fundamentals/02-themes.md | 3 -- docs/02-usage/03-browser-support.md | 33 +++++++++++++++++++ package.json | 11 +++++-- webpack.docs.build.config.js | 18 ++-------- webpack.package.build.config.js | 9 +---- webpack.test.config.js | 9 +---- 11 files changed, 57 insertions(+), 47 deletions(-) create mode 100644 docs/02-usage/03-browser-support.md diff --git a/AGENTS.md b/AGENTS.md index 2869cd9d..366311a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ A single component is spread across **three parallel trees**, by file type, that **Theming:** Two brands — **Mozilla** (default) and **Firefox**. Themes are CSS Custom Properties declared on `:root` in `includes/themes/` (`_mozilla.scss`, `_firefox.scss`). For any themeable property (foreground/background/link colors, heading & body font families) use `var(--...)` (e.g. `var(--background-color)`, `var(--theme-heading-text-color)`). **Exception: text sizing** — use the type-scale mixins (`@include text-heading-lg;`), never custom properties, because the mixins bake in responsive media queries. -**JavaScript:** Plain ES (target IE10 via Babel in tests), `module.exports`, no framework. Each module is an object named `Mzp` (e.g. `MzpDetails`, `MzpModal`) exposing `init()`/`destroy()` and exported as a **UMD global** named in `webpack.entrypoints.js`. Modules feature-detect via `MzpSupports` and lean on `MzpUtils` helpers. +**JavaScript:** Plain ES (targets the `browserslist` matrix in `package.json` — Firefox ESR, Safari 15.6+, evergreen — via Babel), `module.exports`, no framework. Each module is an object named `Mzp` (e.g. `MzpDetails`, `MzpModal`) exposing `init()`/`destroy()` and exported as a **UMD global** named in `webpack.entrypoints.js`. Modules feature-detect via `MzpSupports` and lean on `MzpUtils` helpers. ## Build, Test, and Development Commands diff --git a/CHANGELOG.md b/CHANGELOG.md index b3653e01..e1bd371e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # HEAD -This version introduces some major modernization changes around CSS and drops browser support for XXXX ( to be defined before V23 is published). +This version introduces some major modernization changes around CSS and updates the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers (Chrome, Edge, Opera, Samsung Internet). See [Browser Support](https://protocol.mozilla.org/docs/usage/browser-support) for the full matrix. The good news is we don't expect many visible changes in modern browsers and you should be able to do some automated visual regression testing to help with the migration. @@ -10,6 +10,8 @@ Introducing theme variables! CSS variables beginning with `--theme-` will adjust ### Browser Support +* (breaking) Updated the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers (`browserslist` in `package.json`). Drops the previous `IE 8` target. +* (breaking) Removed the Babel `targets: { ie: '10' }` override in every webpack config (docs site, npm package, and test bundle). The compiled JS now targets the `browserslist` matrix above instead of IE10. * (breaking) Remove support for vendor prefixing (#957) * (breaking) Replace deprecated CSS properties with their standard equivalents: `clip` → `clip-path` in the `visually-hidden` mixin, `word-wrap` → `overflow-wrap` in Menu Item. Drops functional support in legacy IE. diff --git a/components/00-basic-elements/details/readme.md b/components/00-basic-elements/details/readme.md index 3a9fc187..1eb67d95 100644 --- a/components/00-basic-elements/details/readme.md +++ b/components/00-basic-elements/details/readme.md @@ -1,7 +1,9 @@ The `
` element was introduced in HTML5 to provide a native collapsible -“accordion” widget that previously required JavaScript. However, older browsers -don’t support the newer elements, so Protocol includes a JavaScript polyfill to -improve backwards compatibility. +“accordion” widget that previously required JavaScript. It's natively supported +across Protocol's [supported browsers](https://protocol.mozilla.org/docs/usage/browser-support), so no +polyfill is needed. If you need more control over the open/close behavior than +the native element provides, use the JS-driven Protocol +[Details component](details-component) instead. The `
` element requires a ``, which you can combine with headings to convey hierarchy, if appropriate. diff --git a/components/button/button--with-icon.readme.md b/components/button/button--with-icon.readme.md index 9e0cdba9..1a49c8ff 100644 --- a/components/button/button--with-icon.readme.md +++ b/components/button/button--with-icon.readme.md @@ -16,7 +16,7 @@ consistency and reliability, use an image. - Prefer embedded SVG over an external `img` (whether SVG or other format). An inline SVG icon can more easily change color for the different button states - and style variants. Be aware that very old browsers don’t support SVG. + and style variants. - Consider the text direction of the page language. Arrows in particular indicate a specific orientation that may be confusing in text that flows the opposite diff --git a/components/layout/02-columns/readme.md b/components/layout/02-columns/readme.md index d1b8b909..4ce2f2c8 100644 --- a/components/layout/02-columns/readme.md +++ b/components/layout/02-columns/readme.md @@ -15,10 +15,7 @@ two columns in one-third/two-thirds proportions. If you need that kind of layout you’ll need to use an alternative method. This uses [CSS grid](https://developer.mozilla.org/docs/Web/CSS/CSS_Grid_Layout), -which is [well supported in modern browsers](https://caniuse.com/css-grid) but -not supported in any browsers release prior to 2018. Older browsers will ignore -the column layout and content will be linearized by default. If you need a -multi-column layout in older browsers you’ll need to use an alternative method. +which is well supported across Protocol's supported browsers. The contents of each column should be in its own container element that must be a _direct child_ of the multi-column container, as shown in the examples. The diff --git a/docs/01-fundamentals/02-themes.md b/docs/01-fundamentals/02-themes.md index 38f5c562..2ab34ec0 100644 --- a/docs/01-fundamentals/02-themes.md +++ b/docs/01-fundamentals/02-themes.md @@ -13,9 +13,6 @@ Our CSS framework achieves the different themes by using [CSS Custom properties] set on the root element using the `:root` pseudo-class, and these custom properties will be changed depending on which brand is represented on the page. -(Note: Since CSS Custom Properties aren't supported by legacy browsers, -Protocol still uses a default theme with Sass variables for those browsers.) - Protocol defaults to the Mozilla brand “out of the box.” If you use the packaged, pre-compiled CSS, you’ll have everything you need for a Mozilla-branded website without needing to compile the Sass yourself. We still recommend doing your own diff --git a/docs/02-usage/03-browser-support.md b/docs/02-usage/03-browser-support.md new file mode 100644 index 00000000..cbe61168 --- /dev/null +++ b/docs/02-usage/03-browser-support.md @@ -0,0 +1,33 @@ +--- +title: Browser Support +label: Browser Support +--- + +Protocol supports: + +- **Firefox ESR** and current Firefox +- **Safari 15.6** and later (macOS and iOS) +- All evergreen browsers (Chrome, Edge, Opera, Samsung Internet — their two + most recent versions) + +This matrix is declared as the `browserslist` key in +[`package.json`](https://github.com/mozilla/protocol/blob/main/package.json), +which drives both the Sass build's CSS minification and the Babel target for +the compiled JavaScript. See [CHANGELOG.md](https://github.com/mozilla/protocol/blob/main/CHANGELOG.md) +for the version this matrix took effect. + +## What this means for your project + +If you compile Protocol's Sass yourself, your own build tooling should target +the same matrix (or a subset of it) to avoid re-introducing legacy CSS output. + +Protocol no longer ships vendor-prefixed fallbacks, `@supports` feature-query +fallbacks for older engines, or IE-era polyfills. If your project needs to +support browsers outside this matrix, you'll need to add your own fallback +styles and polyfills — Protocol won't provide them. + +## Testing + +Protocol's automated test suite (`npm test`) runs unit tests in Firefox and +Chrome. Safari is not currently covered by CI; if you rely on Safari support, +we recommend a manual smoke test of your integration. diff --git a/package.json b/package.json index d4d545c3..0768b5b6 100644 --- a/package.json +++ b/package.json @@ -58,7 +58,14 @@ "stylelint-config-standard-scss": "^17.0.0" }, "browserslist": [ - "defaults", - "IE 8" + "last 2 chrome versions", + "last 2 edge versions", + "last 2 firefox versions", + "last 2 opera versions", + "last 2 samsung versions", + "Firefox ESR", + "Safari >= 15.6", + "iOS >= 15.6", + "not dead" ] } diff --git a/webpack.docs.build.config.js b/webpack.docs.build.config.js index 1a4ffaf1..9649b09d 100644 --- a/webpack.docs.build.config.js +++ b/webpack.docs.build.config.js @@ -30,14 +30,7 @@ const protocolJSConfig = { loader: 'babel-loader', options: { presets: [ - [ - '@babel/preset-env', - { - targets: { - ie: '10' - } - } - ] + '@babel/preset-env' ] } } @@ -166,14 +159,7 @@ const fractalJSConfig = { loader: 'babel-loader', options: { presets: [ - [ - '@babel/preset-env', - { - targets: { - ie: '10' - } - } - ] + '@babel/preset-env' ] } } diff --git a/webpack.package.build.config.js b/webpack.package.build.config.js index bf173a00..272ba8f9 100644 --- a/webpack.package.build.config.js +++ b/webpack.package.build.config.js @@ -34,14 +34,7 @@ const jsConfig = { loader: 'babel-loader', options: { presets: [ - [ - '@babel/preset-env', - { - targets: { - ie: '10' - } - } - ] + '@babel/preset-env' ] } } diff --git a/webpack.test.config.js b/webpack.test.config.js index abf9def5..12c60338 100644 --- a/webpack.test.config.js +++ b/webpack.test.config.js @@ -36,14 +36,7 @@ module.exports = { loader: 'babel-loader', options: { presets: [ - [ - '@babel/preset-env', - { - targets: { - ie: '10' - } - } - ] + '@babel/preset-env' ] } } From 2439d04fc516e4d28208924258bb58a6538201d6 Mon Sep 17 00:00:00 2001 From: Stephanie Hobson Date: Thu, 10 Sep 2026 13:10:01 -0700 Subject: [PATCH 2/2] Address review feedback on browser support matrix (#1084) Answering the review question directly: no polyfill was removed here, because assets/js/protocol/details.js doesn't polyfill native
/ at all -- it's a separate, general-purpose "convert headings into an accordion" component (MzpDetails) that happens to also work on elements. The component readme's old claim that Protocol "includes a JavaScript polyfill" for native
was already inaccurate before this PR; the previous commit here corrected that framing. What I missed the first time: components/details-component/ (a *different* readme/demo than the one above) did contain a real, intentional polyfill *usage pattern* -- its example script checked `if (!MzpSupports.details) { MzpDetails.init('summary'); }`, using MzpDetails to retrofit accordion behavior onto elements in browsers lacking native
support. Since MzpSupports.details is unconditionally true across the new matrix (native
has been supported in Safari since 6, Firefox since 49, every evergreen browser for years), that branch can no longer execute for anyone following our documented support policy. Removed it from both the demo HTML and the readme's copy of the same snippet -- confirmed in the built docs output. Left MzpSupports.details itself untouched in supports.js: it's still a documented public API property, just with zero remaining internal consumers now (same "keep the public API, the internal usage is what was dead" shape as the matchMedia/classList cleanup in the JS PR). Removing the property itself is the same bigger, separate breaking-API call already deferred there. Also applied the other pending review suggestions on this PR: - Simplified the evergreen-browsers bullet in the new Browser Support doc page to match the styling of the other two bullets, and trimmed two sentences (the CHANGELOG cross-reference, the "Protocol won't provide them" clause). - Trimmed the CHANGELOG intro paragraph and Browser Support bullet to drop redundant detail now that the dedicated docs page covers it. - Copilot flagged the hardcoded protocol.mozilla.org domain in the
readme's link -- switched to a site-relative /docs/usage/browser-support.html path instead, so it resolves correctly on local Fractal dev and any alternate host too. Verified this is the real canonical path (matches the dist/ build output and CHANGELOG.md's own existing links), not one of the legacy /fundamentals/* paths that only work via netlify.toml redirects. Verified: npm run lint and npm run build-docs (524 items, no errors -- confirmed the details-component demo's rendered output no longer contains the removed polyfill branch). --- CHANGELOG.md | 4 ++-- components/00-basic-elements/details/readme.md | 2 +- components/details-component/details-component.html | 8 -------- components/details-component/readme.md | 8 -------- docs/02-usage/03-browser-support.md | 8 +++----- 5 files changed, 6 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e1bd371e..dcd87fd8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # HEAD -This version introduces some major modernization changes around CSS and updates the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers (Chrome, Edge, Opera, Samsung Internet). See [Browser Support](https://protocol.mozilla.org/docs/usage/browser-support) for the full matrix. +This version introduces some major modernization changes around CSS and updates the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers. The good news is we don't expect many visible changes in modern browsers and you should be able to do some automated visual regression testing to help with the migration. @@ -10,7 +10,7 @@ Introducing theme variables! CSS variables beginning with `--theme-` will adjust ### Browser Support -* (breaking) Updated the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers (`browserslist` in `package.json`). Drops the previous `IE 8` target. +* (breaking) Updated the supported browser matrix to Firefox ESR, Safari 15.6+, and evergreen browsers (`browserslist` in `package.json`). * (breaking) Removed the Babel `targets: { ie: '10' }` override in every webpack config (docs site, npm package, and test bundle). The compiled JS now targets the `browserslist` matrix above instead of IE10. * (breaking) Remove support for vendor prefixing (#957) * (breaking) Replace deprecated CSS properties with their standard equivalents: `clip` → `clip-path` in the `visually-hidden` mixin, `word-wrap` → `overflow-wrap` in Menu Item. Drops functional support in legacy IE. diff --git a/components/00-basic-elements/details/readme.md b/components/00-basic-elements/details/readme.md index 1eb67d95..33bb268d 100644 --- a/components/00-basic-elements/details/readme.md +++ b/components/00-basic-elements/details/readme.md @@ -1,6 +1,6 @@ The `
` element was introduced in HTML5 to provide a native collapsible “accordion” widget that previously required JavaScript. It's natively supported -across Protocol's [supported browsers](https://protocol.mozilla.org/docs/usage/browser-support), so no +across Protocol's [supported browsers](/docs/usage/browser-support.html), so no polyfill is needed. If you need more control over the open/close behavior than the native element provides, use the JS-driven Protocol [Details component](details-component) instead. diff --git a/components/details-component/details-component.html b/components/details-component/details-component.html index a96c926e..08b88ac9 100644 --- a/components/details-component/details-component.html +++ b/components/details-component/details-component.html @@ -18,14 +18,6 @@

Sub Heading