feat: add Tailwind v4 design-tokens foundation by georgewrmarshall · Pull Request #1117 · MetaMask/metamask-design-system

georgewrmarshall · 2026-04-27T22:21:55Z

Description

This PR is phase 1 of the larger Tailwind v4 migration effort and is split out from the original source-of-truth draft PR #842.

This phase is intentionally narrow. It introduces the new Tailwind v4 stylesheet surface from @metamask/design-tokens without pulling in the broader web component, Storybook, or repo-wide tooling migration yet.

What this PR does:

add packages/design-tokens/src/tailwind/theme.css
build and export @metamask/design-tokens/tailwind/theme.css
add package-level test coverage for the new theme surface in theme.test.ts
add migration guidance for Tailwind v3 preset consumers
link @metamask/design-system-tailwind-preset consumers to the new migration guidance

What this PR does not do:

migrate React components to Tailwind v4
update Storybook/web app Tailwind v4 wiring
cut over repo-wide Tailwind tooling
remove the existing Tailwind v3 preset

The goal is to make review smaller and clearer by separating the design-tokens foundation work from downstream adoption work that will continue in follow-up PRs from #842.

Related issues

Part of: https://consensyssoftware.atlassian.net/browse/DSYS-554

References #842

Manual testing steps

Check out this branch.
Run yarn install.
Run yarn build.
Confirm packages/design-tokens/dist/tailwind/theme.css is generated.
Confirm packages/design-tokens/package.json exports ./tailwind/theme.css.
Run yarn constraints.
Run yarn lint.
Run yarn workspace @metamask/design-tokens test.

Screenshots/Recordings

Not applicable. This PR introduces token, packaging, and migration-documentation changes rather than user-facing UI changes.

Before

Not applicable.

After

yarn build:css:tailwind script

Screen.Recording.2026-04-28.at.12.17.45.PM.mov

generates theme.css available from dist/

Pre-merge author checklist

I've followed MetaMask Contributor Docs
I've completed the PR template to the best of my ability
I’ve included tests if applicable
I’ve documented my code using JSDoc format if applicable
I’ve applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Medium Risk
Adds a new distributed CSS artifact and build/test pipeline changes in @metamask/design-tokens, which could affect package publishing/build output and consumer integration if misconfigured.

Overview
Introduces a new Tailwind CSS v4 consumption surface by adding @metamask/design-tokens/tailwind/theme.css, which centralizes token variables via @theme, provides explicit .light/.dark overrides, and defines @utility shortcuts for common color and typography classes.

Updates @metamask/design-tokens packaging to build and export this new stylesheet (new build:css:tailwind step using PostCSS import processing, plus new exports entry) and adds Jest coverage (theme.test.ts) to assert parity with the existing Tailwind v3 preset (colors/typography/shadow sizes) and with the source light/dark theme CSS.

Documentation is updated to guide v3 preset consumers toward the v4 theme.css path, including a new Tailwind v3→v4 migration section and a pointer from the v3 preset README.

^{Reviewed by Cursor Bugbot for commit 82cb7d1. Bugbot is set up for automated code reviews on this repo. Configure here.}

socket-security · 2026-04-27T22:22:56Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	postcss-cli@11.0.1
	postcss-import@16.1.1

View full report

socket-security · 2026-04-27T22:22:59Z

Warning

MetaMask internal reviewing guidelines:

Do not ignore-all
Each alert has instructions on how to review if you don't know what it means. If lost, ask your Security Liaison or the supply-chain group
Copy-paste ignore lines for specific packages or a group of one kind with a note on what research you did to deem it safe.
@SocketSecurity ignore npm/PACKAGE@VERSION

Action	Severity	Alert (click "▶" to expand/collapse)
Warn		Potential code anomaly (AI signal): npm `yaml` is 100.0% likely to have a medium risk anomaly Notes: The code presents a standard, non-malicious NodeBase component used in YAML/JS conversion. The primary risk surface is the optional reviver and onAnchor callbacks provided by the user: if untrusted, these can execute arbitrary code or influence the transformed representation via applyReviver or the reviver itself. This is expected behavior for extensible YAML libraries; ensure callbacks come from trusted sources and sandbox or validate revivers where possible. Confidence: 1.00 Severity: 0.60 From: `?` → `npm/@metamask/create-release-branch@4.2.0` → `npm/tailwindcss@3.4.16` → `npm/postcss-cli@11.0.1` → `npm/yaml@2.8.3` ℹ Read more on: This package \| This alert \| What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/yaml@2.8.3`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

Ignoring alerts on:

postcss-import@16.1.1

View full report

github-actions · 2026-04-27T22:23:21Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall · 2026-04-27T22:34:09Z

@@ -1,7 +1,5 @@
-/* eslint-disable import-x/no-nodejs-modules */


Moved out to separate PR #1118

georgewrmarshall · 2026-04-27T22:34:21Z

@@ -1,7 +1,5 @@
-/* eslint-disable import-x/no-nodejs-modules */


Moved out to separate PR #1118

github-actions · 2026-04-28T18:15:51Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-04-28T18:22:22Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-04-28T18:50:38Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall · 2026-04-28T18:56:20Z

@SocketSecurity ignore npm/postcss-import@16.1.1

Reviewed this publisher-change alert. postcss-import@16.1.1 still points to the official postcss/postcss-import repository on npm, and the npm registry now lists both the previous publisher (ryanzim) and the new publisher (romainmenke) as maintainers for the package. This dependency is only used as a build-time devDependency in packages/design-tokens/package.json to inline CSS imports when producing dist/tailwind/theme.css, so the blast radius for this PR is limited to build tooling. Ignoring this alert as manageable risk.

georgewrmarshall · 2026-04-28T19:10:29Z

+@import '../css/typography.css';
+@import '../css/shadow.css';
+
+@theme {


These resets intentionally carry forward the old Storybook v3 config behavior that removed Tailwind default colors, font sizes, and font weights:

metamask-design-system/apps/storybook-react/tailwind.config.js

Lines 13 to 27 in 619b463

theme: {

// Keep essential semantic colors, remove default palette colors.

// We want to rely on the colors provided by @metamask-previews/design-system-tailwind-preset

colors: {

inherit: 'inherit',

current: 'currentColor',

transparent: 'transparent',

black: '#000000',

white: '#ffffff',

},

// This removes all default Tailwind font sizes and weights.

// We want to rely on the design system font sizes and enforce use of the Text component

fontSize: {},

fontWeight: {},

},

. In v4 we do that inside @theme so consumers get the MetaMask token contract instead of a mix of framework defaults and preset values.

georgewrmarshall · 2026-04-28T19:10:29Z

+  --color-shadow-error: #ff758433;
+}
+
+/* Color Shortcut Utilities - Enable shorter class names */


These shortcut utilities preserve the ergonomics from the v3 preset textColor, backgroundColor, and borderColor extensions in src/index.ts: https://github.com/MetaMask/metamask-design-system/blob/619b46301f01ec8d94ecad2fe01a7d392c2d0d3d/packages/design-system-tailwind-preset/src/index.ts. Without them, consumers would have to switch back to longer class names like text-text-default and bg-background-default.

georgewrmarshall · 2026-04-28T19:10:29Z


 Design System Tailwind CSS preset for MetaMask projects

+> This package is the Tailwind CSS v3 preset. For Tailwind CSS v4 consumers, use `@metamask/design-tokens/tailwind/theme.css` instead.


This note is here because existing web consumers are still most likely to discover the v3 preset package first. Redirecting them to the v4 stylesheet keeps the migration entrypoint close to the old integration surface without changing v3 behavior.

georgewrmarshall · 2026-04-28T19:10:29Z

+  border-color: var(--color-border-muted);
+}
+
+/* Legacy typography classnames parity with the old preset */


These typography utilities intentionally keep the class-name surface from the v3 preset typography map: https://github.com/MetaMask/metamask-design-system/blob/619b46301f01ec8d94ecad2fe01a7d392c2d0d3d/packages/design-system-tailwind-preset/src/typography.ts. Phase 1 is moving the integration surface to a stylesheet first, not forcing downstream consumers to rename typography classes at the same time.

georgewrmarshall · 2026-04-28T19:10:29Z

+  /* Background default should be the darkest shade, 0 elevation.
+  Section is +1 elevation, subsection is +2 elevation.
+  Alternative should be deprecated. */
+  --color-background-default: var(--brand-colors-grey-grey000);


This color block is the @theme replacement for the semantic color map from the v3 preset: https://github.com/MetaMask/metamask-design-system/blob/619b46301f01ec8d94ecad2fe01a7d392c2d0d3d/packages/design-system-tailwind-preset/src/colors.ts. The goal is to preserve the same token names while letting Tailwind v4 generate bg-, text-, and border-* utilities directly from CSS variables.

georgewrmarshall · 2026-04-28T19:13:28Z

+    );
+  });
+
+  describe('Completeness: every @utility traces to v3 preset', () => {


The completeness checks are here to catch silent drift when tokens or utility mappings change later. Spot checks alone would miss newly added @utility or --color-* entries that never get wired back to the old preset surface.

georgewrmarshall · 2026-04-28T19:13:28Z

+    });
+  });
+
+  describe('Theme-scope overrides: .light block matches light-theme-colors.css', () => {


These light and dark comparisons make sure the stylesheet is not only exporting token names but also preserving the existing runtime theme-variable behavior from the source CSS files. That gives reviewers confidence that web consumers can adopt the new artifact without re-deriving theme overrides elsewhere.

georgewrmarshall · 2026-04-28T19:13:28Z

+  darkVars: Map<string, string>;
+};
+
+function parseThemeCss(): ParsedTheme {


These tests parse the final theme.css file rather than only asserting against token objects. That is deliberate because the review surface for this PR is the published stylesheet contract, so we want failures when the generated CSS shape drifts even if the source token data still looks correct.

georgewrmarshall · 2026-04-28T19:15:47Z

 - [From version 3.0.0 to 4.0.0](#from-version-300-to-400)
 - [From version 2.1.1 to 3.0.0](#from-version-211-to-300)

+## Tailwind CSS v3 to v4


This new section is the canonical migration path for web consumers moving from the v3 preset to the v4 stylesheet export. Keeping the setup steps here, rather than split across package READMEs, gives downstream teams one place to review the contract change introduced by this phase.

georgewrmarshall · 2026-04-28T19:15:47Z

+| ----------- | -------------- | ---------------------------------------------------------------------------- |
+| `font-sans` | `font-default` | v4 uses `font-default` instead of overriding Tailwind's built-in `font-sans` |
+
+### React Native


This scope note is important because the larger Tailwind v4 migration is intentionally split by platform. Web consumers get the new stylesheet in this phase, while React Native remains on the existing twrnc-based Tailwind v3 path for now.

georgewrmarshall · 2026-04-28T19:15:47Z

+| Shadow colors     | `--color-shadow-default` / `primary` / `error` in `@theme` only (no `shadow-default` etc. utilities; v3’s color-stack pattern had no adoption) |
+| Light/dark themes | `[data-theme='light']`/`.light` and `[data-theme='dark']`/`.dark` selector blocks                                                              |
+
+### Shadow utility changes


The shadow section is called out separately because this is one of the few intentional non-parity areas in phase 1. Size utilities stay available, but the old color-stacking shorthand is documented as a migration change instead of being silently dropped.

georgewrmarshall · 2026-04-28T19:16:21Z

    "./package.json": "./package.json",
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./tailwind/theme.css": "./dist/tailwind/theme.css"


This export is the main package contract introduced by phase 1. The follow-up Tailwind v4 adoption work can happen in separate PRs because downstream consumers only need this stable package path to start wiring the new stylesheet.

georgewrmarshall · 2026-04-28T19:16:21Z

@@ -37,7 +38,8 @@
  ],
  "scripts": {
    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references && yarn build:css",


This build split keeps the phase scoped to publishing a concrete CSS artifact instead of changing repo-wide Tailwind tooling. The package resolves and emits theme.css itself so downstream apps can adopt Tailwind v4 wiring later without this PR needing to own that cutover.

georgewrmarshall · 2026-04-28T19:16:21Z

@@ -56,6 +58,8 @@
    "clean-css-cli": "^5.6.3",
    "jest": "^29.7.0",
    "postcss": "^8.4.47",


These new devDependencies are intentionally limited to the CSS build path for this package. We removed the earlier parity-script wiring so phase 1 does not force broader Tailwind v4 assumptions into unrelated workspace test and lint flows.

github-actions · 2026-04-28T19:21:03Z

📖 Storybook Preview

View PR Storybook

github-actions · 2026-05-01T22:12:26Z

📖 Storybook Preview

View PR Storybook

## Release 38.0.0 This release updates the shared, web, native, tokens, and Tailwind packages with new cross-platform input and avatar-group contracts, new modal building blocks for React, a breaking React Native Toast API redesign, and Tailwind CSS v4 support for web consumers. ### 📦 Package Versions - `@metamask/design-system-shared`: **0.16.0** - `@metamask/design-system-react`: **0.21.0** - `@metamask/design-system-react-native`: **0.23.0** - `@metamask/design-system-tailwind-preset`: **0.7.0** - `@metamask/design-tokens`: **8.4.0** ### 🔄 Shared Type Updates (0.16.0) #### Input and AvatarGroup shared contracts ([#1043](#1043), [#1067](#1067)) **What Changed:** - Added shared `Input` contracts for controlled `value`, `isReadOnly`, and `isStateStylesDisabled` - Added shared `AvatarGroup` size, variant, and prop contracts - Added the shared `Merge` icon export ([#1155](#1155)) **Impact:** - React and React Native consumers can build against one aligned input and avatar-group API surface - Cross-platform wrappers can depend on `@metamask/design-system-shared` instead of maintaining platform-specific type assumptions ### 🌐 React Web Updates (0.21.0) #### Added - Added `ModalOverlay`, `ModalBody`, `ModalFocus`, and `ModalFooter` to support Extension modal migrations into `@metamask/design-system-react` ([#1120](#1120), [#1121](#1121), [#1128](#1128), [#1132](#1132)) - Added the `Merge` icon to the React icon set ([#1155](#1155)) #### Changed - Updated `Input` to follow the shared controlled input API and use `isReadOnly` as the public readonly prop name ([#1043](#1043)) - Updated `AvatarGroup` to use shared cross-platform size and variant contracts ([#1067](#1067)) ### 📱 React Native Updates (0.23.0) #### Added - Added the `Merge` icon to the React Native icon set ([#1155](#1155)) #### Changed - **BREAKING:** Redesigned `Toast` to use a single mounted `<Toast />` plus static `Toast.show(...)` and `Toast.hide()` methods for application usage ([#1104](#1104)) - Removed `ToastContext`, `ToastContextWrapper`, and `ToastContextParams` from the public export surface - Renamed `ToastVariants` to `ToastVariant`, changed icon-only close buttons to `ToastCloseButtonVariant.Icon`, and renamed `customBottomOffset` to `bottomOffset` - `Toast.show()` and `Toast.hide()` now throw a descriptive error if called before `<Toast />` mounts - See the [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0220-to-0230) - Updated `Input` to follow the shared controlled input API and rename `isReadonly` to `isReadOnly` ([#1043](#1043)) - Updated `AvatarGroup` to use shared cross-platform size and variant contracts ([#1067](#1067)) ### 🎨 Tokens and Tailwind Updates #### `@metamask/design-tokens` 8.4.0 - Added `@metamask/design-tokens/tailwind/theme.css` for Tailwind CSS v4 consumers, providing a single import for token variables, theme values, typography, fonts, and shadow utilities ([#1117](#1117)) #### `@metamask/design-system-tailwind-preset` 0.7.0 - Added a `fade-in` animation utility so consumers can use `animate-fade-in` for simple opacity entrance transitions, including the new `ModalOverlay` web migration path ([#1120](#1120)) - Clarified that Tailwind CSS v3 consumers should keep using this preset, while Tailwind CSS v4 consumers should migrate to `@metamask/design-tokens/tailwind/theme.css` ([#1117](#1117)) ### ⚠️ Breaking Changes #### Toast API redesign (React Native) **What Changed:** - `Toast` application usage moved from context/service patterns to static `Toast.show(...)` and `Toast.hide()` methods - `ToastContext`, `ToastContextWrapper`, and `ToastContextParams` were removed from the public API - `ToastVariants` was renamed to `ToastVariant` - Icon-only close buttons now use `ToastCloseButtonVariant.Icon` - `customBottomOffset` was renamed to `bottomOffset` **Impact:** - Existing `@metamask/design-system-react-native` consumers using the old Toast context flow need import, root-mount, and call-site updates - Existing app code must ensure `<Toast />` is mounted before invoking `Toast.show()` / `Toast.hide()` See migration guides for complete instructions: - [React Native Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0220-to-0230) ### ✅ Checklist - [x] Changelogs updated with human-readable descriptions - [x] Changelog validation passed (`yarn workspace <package> changelog:validate`) - [x] Version bumps follow semantic versioning - [x] design-system-shared: minor (`0.15.0` → `0.16.0`) - new shared `Input`, `AvatarGroup`, and icon exports - [x] design-system-react: minor (`0.20.0` → `0.21.0`) - new modal components, icon, and shared API alignment - [x] design-system-react-native: minor (`0.22.0` → `0.23.0`) - breaking Toast redesign, icon, and shared API alignment - [x] design-system-tailwind-preset: minor (`0.6.1` → `0.7.0`) - new `fade-in` utility and Tailwind CSS v4 migration guidance - [x] design-tokens: minor (`8.3.0` → `8.4.0`) - Tailwind CSS v4 `theme.css` export - [x] Breaking changes documented with migration guidance - [x] Migration guides updated with before/after examples (if breaking changes) - [x] PR references included in changelog entries ## **Pre-merge author checklist** - [ ] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [ ] I've reviewed the [Release Workflow](./.cursor/rules/release-workflow.md) cursor rule - [ ] All tests pass (`yarn build && yarn test && yarn lint`) - [x] Changelog validation passes (`yarn changelog:validate`) ## **Pre-merge reviewer checklist** - [ ] I've reviewed the [Reviewing Release PRs](./docs/reviewing-release-prs.md) guide - [ ] Package versions follow semantic versioning - [ ] Changelog entries are consumer-facing (not commit message regurgitation) - [ ] Breaking changes are documented in MIGRATION.md with examples - [ ] All unreleased changes are accounted for in changelogs

## Release 39.0.0 This release adds Tailwind CSS v4 integration via `@metamask/design-tokens/tailwind/theme.css`, ships extension migration UI on React web (`Modal`, `ModalContent`, `Skeleton`, `HeaderBase`), adds Tailwind preset animations (`animate-slide-up`, `animate-skeleton-pulse`), and refreshes the shared icon set (`ListArrow`, `Musd`, `MusdFilled`, `Group`, `PieChart`, `Predictions`, refreshed `Candlestick`, `Musd` SVG fix) across `@metamask/design-system-shared`, React, and React Native. **React Native** also ships a **breaking** Toast follow-up ([#1143](#1143)): root **`Toaster`**, imperative **`toast`** / **`toast.dismiss()`**, and flat **`ToastSeverity`** options. The TWRNC preset widens its React peer range for newer React Native / React stacks. ### 📦 Package Versions - `@metamask/design-tokens`: **8.4.0** - `@metamask/design-system-shared`: **0.17.0** - `@metamask/design-system-react`: **0.22.0** - `@metamask/design-system-react-native`: **0.24.0** - `@metamask/design-system-tailwind-preset`: **0.8.0** - `@metamask/design-system-twrnc-preset`: **0.4.2** ### 🎨 Design Tokens (8.4.0) #### Added (#1117) **What changed** - Added `@metamask/design-tokens/tailwind/theme.css` for Tailwind CSS v4 so consumers can import MetaMask token variables, theme values, typography, font, and shadow utilities in one place. **Impact** - Web apps on Tailwind v4 can adopt the token theme without hand-rolling CSS variables; see [Tailwind CSS v3 to v4](./packages/design-tokens/MIGRATION.md#tailwind-css-v3-to-v4). ### 🪶 `@metamask/design-system-tailwind-preset` (0.8.0) #### Added - **`animate-slide-up`** (and `slide-up` keyframes) for the same dialog entrance motion as `ModalContent` ([#1139](#1139)) - **`animate-skeleton-pulse`** (and `skeleton-pulse` keyframes) for loading placeholders used with `Skeleton` ([#1146](#1146)) ### 📲 `@metamask/design-system-twrnc-preset` (0.4.2) #### Changed (#844) - Expanded the `react` peer dependency range to `>=18.2.0` so the preset installs cleanly alongside React Native 0.76 and React 19 app stacks. ### 🔄 Shared Type Updates (0.17.0) #### Shared icon set (#1157, #1161, #1162, #1163) **What changed** - Extended the shared icon set with `ListArrow`, `Musd`, `MusdFilled`, `Group`, `PieChart`, and `Predictions`, refreshed the `Candlestick` icon, and corrected the `Musd` asset to use a single SVG path. **Impact** - Keeps `IconName` and assets aligned for `@metamask/design-system-react` and `@metamask/design-system-react-native`. ### 🌐 React Web Updates (0.22.0) #### Added - Added `Modal` and `ModalContent` for dialogs, `Skeleton` for loading placeholders, and `HeaderBase` for header layouts—supporting the MetaMask extension migration into the design system ([#1136](#1136), [#1139](#1139), [#1146](#1146), [#1142](#1142)) - Added icons `ListArrow`, `Musd`, `MusdFilled`, `Group`, `PieChart`, and `Predictions`, and updated the `Candlestick` icon ([#1157](#1157), [#1161](#1161), [#1162](#1162)) #### Fixed - Corrected the `Musd` icon asset so it renders from a single SVG path ([#1163](#1163)) ### 📱 React Native Updates (0.24.0) #### Added - Added icons `ListArrow`, `Musd`, `MusdFilled`, `Group`, `PieChart`, and `Predictions`, and updated the `Candlestick` icon ([#1157](#1157), [#1161](#1161), [#1162](#1162)) #### Changed - **BREAKING:** Toast API follow-up ([#1143](#1143)): mount **`<Toaster />`** once at the root; use **`toast(...)`** / **`toast.dismiss()`** instead of **`Toast.show(...)`** / **`Toast.hide()`**; content-first options with **`ToastSeverity`** and **`iconAlertProps`** (renamed from **`iconProps`**). See [Migration Guide](./packages/design-system-react-native/MIGRATION.md#from-version-0230-to-0240). #### Fixed - Corrected the `Musd` icon asset so it renders from a single SVG path ([#1163](#1163)) ### ⚠️ Breaking Changes #### React Native — Toast (#1143) **What changed** - Imperative API moves from **`Toast.show`** / **`Toast.hide`** on **0.23.x** to **`toast`** / **`toast.dismiss()`** with a root **`<Toaster />`**. - Options flatten to **`title`**, **`description`**, **`severity`** (**`ToastSeverity`**), accessories, and **`iconAlertProps`**; map **`ToastVariant`**-style payloads from **0.23.0** using the migration guide. **Migration** - See [From version 0.23.0 to 0.24.0](./packages/design-system-react-native/MIGRATION.md#from-version-0230-to-0240) (and [Toast Component](./packages/design-system-react-native/MIGRATION.md#toast-component) for component-library migration context). ### ✅ Checklist - [x] Changelogs updated with human-readable descriptions - [x] Changelog validation passed (`yarn changelog:validate`) - [x] Version bumps follow semantic versioning - [x] design-tokens: minor (8.3.0 → 8.4.0) — Tailwind v4 `theme.css` entry point - [x] design-system-shared: minor (0.16.0 → 0.17.0) — shared icon set additions and asset fixes - [x] design-system-react: minor (0.21.0 → 0.22.0) — extension migration components and icons - [x] design-system-react-native: minor (0.23.0 → 0.24.0) — **breaking Toast follow-up (#1143)**, icons, `Musd` fix - [x] design-system-tailwind-preset: minor (0.7.0 → 0.8.0) — `animate-slide-up` and `animate-skeleton-pulse` for ModalContent / Skeleton - [x] design-system-twrnc-preset: patch (0.4.1 → 0.4.2) — wider `react` peer range - [x] Breaking changes documented with migration guidance (React Native Toast — see MIGRATION.md link above) - [x] Migration guides updated with before/after examples (Toast **0.23 → 0.24**; Tailwind v4 consumers — design-tokens migration link above) - [x] PR references included in changelog entries ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [x] I've reviewed the [Release Workflow](./.cursor/rules/release-workflow.md) cursor rule - [x] All tests pass (`yarn build && yarn test && yarn lint`) - [x] Changelog validation passes (`yarn changelog:validate`) ## **Pre-merge reviewer checklist** - [ ] I've reviewed the [Reviewing Release PRs](./docs/reviewing-release-prs.md) guide - [ ] Package versions follow semantic versioning - [ ] Changelog entries are consumer-facing (not commit message regurgitation) - [ ] Breaking changes are documented in MIGRATION.md with examples (**React Native Toast** — [0.23.0 → 0.24.0](./packages/design-system-react-native/MIGRATION.md#from-version-0230-to-0240)) - [ ] All unreleased changes are accounted for in changelogs  --- > [!NOTE] > **Medium Risk** > Primarily a release/version bump, but it changes published package versions and updates peer dependency requirements, which can affect downstream installs. React Native release notes include a breaking `Toast` API change that consumers must account for when upgrading. > > **Overview** > Bumps the monorepo release to `39.0.0` and increments package versions for `@metamask/design-system-react` (`0.22.0`), `@metamask/design-system-react-native` (`0.24.0`), `@metamask/design-system-shared` (`0.17.0`), and `@metamask/design-system-tailwind-preset` (`0.8.0`), updating corresponding changelogs and compare links. > > Updates `@metamask/design-system-react` to require `@metamask/design-system-tailwind-preset@^0.8.0` (and aligns `yarn.lock`). Changelogs capture the release contents, including new modal/skeleton/header additions on web, icon set updates across packages, and a **breaking** React Native `Toast` API tightening for `Toaster`/`toast(...)` usage. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 4e3ea63. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

georgewrmarshall commented Apr 27, 2026

View reviewed changes

georgewrmarshall force-pushed the phase1/design-tokens-tailwind-v4 branch from 144f5a2 to d2b2457 Compare April 28, 2026 18:14

georgewrmarshall marked this pull request as ready for review April 28, 2026 18:58

georgewrmarshall requested a review from a team as a code owner April 28, 2026 18:58

georgewrmarshall commented Apr 28, 2026

View reviewed changes

georgewrmarshall added 4 commits April 28, 2026 12:19

feat(design-tokens): add Tailwind v4 theme.css foundation

6d15c0b

chore: unblock phase 1 branch checks

aeab1ca

docs: clarify shadow migration for tailwind v4

759b0bd

chore: narrow design tokens phase 1 scope

acb57b0

georgewrmarshall added 3 commits April 28, 2026 12:19

chore: reduce phase 1 storybook doc changes

f6ec426

chore: fix yarn.lock

7bbb138

chore: fix yarn.lock

6c5eecb

georgewrmarshall force-pushed the phase1/design-tokens-tailwind-v4 branch from 619b463 to 6c5eecb Compare April 28, 2026 19:19

georgewrmarshall self-assigned this Apr 28, 2026

georgewrmarshall changed the title ~~Phase 1: add Tailwind v4 design-tokens foundation~~ feat: Phase 1 - add Tailwind v4 design-tokens foundation Apr 28, 2026

georgewrmarshall changed the title ~~feat: Phase 1 - add Tailwind v4 design-tokens foundation~~ feat: add Tailwind v4 design-tokens foundation Apr 28, 2026

brianacnguyen approved these changes May 1, 2026

View reviewed changes

georgewrmarshall enabled auto-merge (squash) May 1, 2026 22:10

Merge branch 'main' into phase1/design-tokens-tailwind-v4

82cb7d1

georgewrmarshall merged commit 90248a5 into main May 1, 2026
44 checks passed

georgewrmarshall deleted the phase1/design-tokens-tailwind-v4 branch May 1, 2026 22:14

georgewrmarshall mentioned this pull request May 5, 2026

Release 38.0.0 #1156

Merged

20 tasks

brianacnguyen mentioned this pull request May 8, 2026

Release/39.0.0 #1167

Merged

20 tasks

brianacnguyen mentioned this pull request May 15, 2026

Release/40.0.0 #1173

Merged

17 tasks

		@@ -1,7 +1,5 @@
		/* eslint-disable import-x/no-nodejs-modules */

	theme: {
	// Keep essential semantic colors, remove default palette colors.
	// We want to rely on the colors provided by @metamask-previews/design-system-tailwind-preset
	colors: {
	inherit: 'inherit',
	current: 'currentColor',
	transparent: 'transparent',
	black: '#000000',
	white: '#ffffff',
	},
	// This removes all default Tailwind font sizes and weights.
	// We want to rely on the design system font sizes and enforce use of the Text component
	fontSize: {},
	fontWeight: {},
	},


		Design System Tailwind CSS preset for MetaMask projects

		> This package is the Tailwind CSS v3 preset. For Tailwind CSS v4 consumers, use `@metamask/design-tokens/tailwind/theme.css` instead.

Uh oh!

Conversation

georgewrmarshall commented Apr 27, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

socket-security Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 27, 2026

📖 Storybook Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

georgewrmarshall commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 28, 2026

📖 Storybook Preview

Uh oh!

github-actions Bot commented May 1, 2026

📖 Storybook Preview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

georgewrmarshall commented Apr 27, 2026 •

edited by cursor Bot

Loading

socket-security Bot commented Apr 27, 2026 •

edited

Loading

socket-security Bot commented Apr 27, 2026 •

edited

Loading

georgewrmarshall commented Apr 28, 2026 •

edited

Loading

georgewrmarshall Apr 28, 2026 •

edited

Loading