[ciampo]

What?

Refine the four Design System skills, the Emotion migration skill, and the package instructions for Components, UI, Theme, and token sources.

Why?

The guidance sometimes requires broad checks for small edits, treats the checkout as a review baseline regardless of its revision, and groups portals with separate documents. The package instructions also miss useful maintainer routes and repeat consumer guidance.

How?

Lead UI and package reviews with concrete checks for component reuse, public contracts, token usage, accessibility, and rendering setup. Keep contribution and Emotion migration steps focused on the affected behaviour and consumer overrides, and route package instructions directly to relevant documentation. Give agents explicit MCP lookup steps and keep version checks conditional. Rely on dependency coverage for behaviour it owns, and request local tests only for meaningful risks introduced by our code or integration. Keep shared compatibility and verification guidance in the public guide, including Veloria searches for external API usage. Existing Claude redirects remain intact.

Testing Instructions

Read the revised guidance against these scenarios:

1. Change an existing Button label. Keep the supported component and limit checks to the affected wording and semantics.
2. Review a menu migration that also changes Menu.Popup. Review both the application and package contracts, including plugin-supplied SlotFill children.
3. Fix a popup that loses a nested theme when portaled to document.body. Check its actual DOM destination and public customization options before changing document-level setup.
4. Rename a public token with the same default value as its replacement. Check semantic purpose, affected modes, external compatibility, and generated output.
5. Compare an unchanged dependency wrapper with one that transforms callbacks and owns new state. Avoid duplicating dependency tests; consider focused local coverage only for a concrete risk introduced by the latter.

Verification

• Full repository build passed.
• Markdown lint passed for all ten changed files.
• All five skill validators passed; all 100 local links and anchors resolved.
• Refreshed the generated Claude skill view.
• Independent scenario checks covered consumer and package work, dependency wrappers, token usage, Emotion cascade preservation, and proportionate verification; no actionable guidance issues were found.

Use of AI Tools

Codex audited and authored the changes, checked them against repository source and documentation, and ran verification. A separate Codex agent evaluated the review scenarios.

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

[aduth]

This feels much improved overall by listing specific things we're looking for. I left a few comments, particularly in the design-system-ui-composition, though some of the comments apply across skills.

I wondered if we really need dual skills for both the contribution and review, or if it would suffice to describe what a good contribution looks like once that could be used for both implementation and review. I think there's enough unique content that it could make senes to continue the split, but there's a risk of duplication and ongoing maintenance (sync) concern.

I also like the idea that the skill can be aware of circumstantial considerations: whether the implementation is happening inside Gutenberg or external consumer of the design system, and with or without the MCP server being available. As noted in a comment, I think we may eventually want to improve how these skills are actually delivered (some of this originally covered in #77209, and potentially related to #82984).

I'm interested to see if this performs any better for a second review on my test PR #83890 😄

[aduth]

I liked how the previous paragraph had a clear decision graph: "With the MCP server, do X. If you don't have the MCP server, do Y." I suspect this sentence is trying to communicate the same thing, but it feels less clear because there's no mention of "MCP", nor that the tokens reference would only be needed as a fallback if the MCP tool is not available (we wouldn't want someone to use both).

[ciampo]

Made the MCP/fallback choice explicit here and in the related skills and shared guide in d839e1d.

[aduth]

Similarly, I like that we're clear here about steps that would apply only to external consumers. I would wonder practically speaking how an external consumer would use this skill though, and if the way they're using the skill would be able to follow relative links like this. At the very least maybe it should be an absolute link in case someone copies only the skill? (I assume that would extend to any link in this document)

I think a separate step we'll want to explore is improving the distribution of these skills. I assume right now the only way someone would integrate these is by manually copying it into their own project. But in general I think it's a good idea for us to treat these skills as supporting both internal and external usage.

[ciampo]

Switched the links in all five changed skills to absolute GitHub URLs so they work when copied into another project. A distribution mechanism can follow separately.

[ciampo]

@aduth Actually, I remember we discussed this already. Using GH URLs has the risk of out of sync docs, in case, eg, an agent is working on an older working copy of the branch. Relative URLs are safer in this case, and we can add an explicit upstream fallback for skills copied outside of Gutenberg

[aduth]

we can add an explicit upstream fallback for skills copied outside of Gutenber

What would this look like?

[ciampo]

You can check e556f0e to see how I applied those feedback URLs. Happy to tweak those if necessary, in case.

[aduth]

I really struggle to understand what this section is meant to communicate.

[ciampo]

Rewrote this to say what to inspect before editing and when to keep the existing component. Removed the vague planning and runtime-setup wording.

[aduth]

What is a "control" in this context? Is "importing package-private source" even possible, or would linters catch that? I guess the main thing here would be to avoid creating duplicate copies of a component?

[ciampo]

Yes, the intent was to avoid duplicating existing components. Rewrote this around concrete examples and documented props and composition.

[aduth]

Is "content styling" in this sentence meant to be specifically contextualized within "theme" ? I feel like the phrasing could be ambiguous, and risks the agent trying to use --wp-preset--* for any content styling.

[ciampo]

Yes, this means content styled with the active theme's theme.json presets. Made that explicit in the composition skill, UI review skill, and shared guide.

[aduth]

What is this "nearby menu or dialog" sentence referring to?

[ciampo]

Removed that example; the instruction to choose the smallest composition that meets the interaction contract already covers the intent.

[aduth]

This doc is much improved 👍

[aduth]

It's a nit but also worth thinking about how we document for ourselves and AI: Should the spelling be the Americanized "behavior" and not "behaviour" (per documentation grammar guide)?

[ciampo]

Agreed, switched to American English throughout the guidance changed by this PR and updated the affected anchor links.

[ciampo]

@aduth I'm keeping the split because implementation and review need different instructions, with the shared contract and verification guidance in one guide. I agree distribution deserves a separate follow-up, though