Skip to content

Create/update skills to support migration and document a plan - #14332

Draft
andrewscfc wants to merge 2 commits into
WS-AI-TOOLSfrom
WS-AI-TOOLS_migration-skills
Draft

Create/update skills to support migration and document a plan#14332
andrewscfc wants to merge 2 commits into
WS-AI-TOOLSfrom
WS-AI-TOOLS_migration-skills

Conversation

@andrewscfc

@andrewscfc andrewscfc commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

I'm part way through this but thought I'd drop an AI summary below to aid review.

I've been prompting and refining a migration plan geared around AI automation. I've heavily refined .github/skills/convert-webcore-component/SKILL.md and docs/SCSS-Modules-Migration.mdx but .github/skills/migrate-component-to-scss-modules/SKILL.md is still a work in progress

I haven't carefully reviewed this summary, will do it again before full review

Summary

Adds the AI tooling to carry out the SCSS Modules migration, plus a plan for how the work is sequenced.

Stacked on #14073 — its changes appear in this branch but belong to that PR.

Changes

.github/skills/migrate-component-to-scss-modules/SKILL.md (new)
The step-by-step process for taking a component off Emotion: an Emotion-to-SCSS value lookup, triage checks for components that can't be migrated by a styling change alone, and per-batch verification steps.

.github/skills/convert-webcore-component/SKILL.md (updated)
This skill told agents to produce index.styles.ts files and Emotion css props. Left unchanged it would work against the standards merged in #14280, so the styling half is rewritten for SCSS Modules. TypeScript guidance is untouched.

docs/SCSS-Modules-Migration.mdx (new)
Sequencing plan for engineers — scope, batching principles, blocked components, and a dated starting batch order. Published to Storybook, and deliberately outside the paths agents read so it can hold planning detail without consuming their context.

Worth discussing: should we add clsx?

Emotion's css={[base, cond && modifier]} silently drops falsy entries. className doesn't, so the direct translation renders class="link false" — a silent bug. This shape appears in 11 components.

The skills currently require a ternary with an empty-string fallback and say not to add a dependency, following our "avoid new dependencies" rule. I lean towards adding clsx instead — ~200 bytes, and it removes the footgun across ~30 migrations rather than relying on everyone getting the ternary right. If we agree, both skills need updating.

Notes

The blocked-component list and batch ordering were derived from the codebase rather than assumed. That turned up two components which look like easy early wins but aren't: MostRead/Label passes a css prop into a psammead component and uses a palette value as a runtime prop, and RelatedContentSection imports a legacy Emotion styles file directly.

---
name: migrate-component-to-scss-modules
description: Migrates an existing Emotion-styled React component in src/app/components to SCSS Modules. Use when asked to migrate, convert or batch-migrate components off Emotion (index.styles.ts / css prop) to index.module.scss, or when removing Emotion from a component.
---

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not really reviewed this file properly yet

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant