Migrate Emotion styles to SCSS Modules

SkillDev tools

Use when planning or implementing an Emotion-to-SCSS-Modules migration in @wordpress/components, including styled wrappers, css/useCx composition, and migration-related cascade fixes.

Available today. Use it from your connected AI after setup.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the Migrate Emotion styles to SCSS Modules skill

What this skill tells your AI

The instructions your AI receives, as published by wordpress/gutenberg in .agents/skills/emotion-to-scss-modules/SKILL.md and read by ahel’s review.

Establish the scope

  1. Read the migration guide and the package's styling conventions before editing.
  2. Identify the requested component or dependency cluster and the baseline revision. Search for imports of its wrappers/style fragments and consumers of its public classes, including outside packages/components.
  3. Record the contract and the states at risk using the guide's contract audit. Select a relevant merged example, then check its lesson against current source.

Implement and compare

  1. Capture baseline behavior for the affected states and at least one relevant composed consumer. For a reported regression, establish a failing test or browser reproduction first.
  2. Apply the guide's translation rules. Reuse the underlying component or shared polymorphic utility according to the existing contract. Classify values as static, conditional, or genuinely dynamic before choosing Sass, module classes, or custom properties.
  3. Audit the winning declarations after removing the wrapper. Check consumer overrides, remaining Emotion composition, shorthand/longhand precedence, and nested instances. Explain any required specificity adjustment with the conflicting declaration.
  4. Use the guide's verification choices, starting with existing coverage. Private module-class assertions prove wiring only. Check actual styles in a browser, including RTL or root/iframe differences when applicable. Keep fixture-CSS tests limited to the registration or composition mechanism they exercise.
  5. Keep intentional API, interaction, or visual changes explicit and within the requested scope. An older migration's exception does not authorize the same change here.

Finish

Follow the guide's completion checks, including scoped cleanup, whole-repository snapshot review, type checking, builds, generated-file checks, and the current migration changelog convention.

Recheck affected consumers after the last selector edit or rebase. Report the preserved behavior, any agreed change, the real-style evidence, and any unverified case. Do not report visual parity from mocked styles or passing snapshots alone.

Signals

GitHub stars
12k
Forks
5k
Last commit
Sep 2026
Advanced
Catalog kind
skill
Gateway key
emotion-to-scss-modules
Source
github.com/wordpress/gutenberg