Skip to content

Design System: Ship agent skills with the theme and UI packages - #86737

Open
simison wants to merge 8 commits into
trunkfrom
simison/design-system-agent-files-842d60
Open

simison wants to merge 8 commits into
trunkfrom
simison/design-system-agent-files-842d60

Conversation

@simison

@simison simison commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

What?

Ship agent skills with @wordpress/theme and @wordpress/ui, so tools that link skills from dependencies (such as pnpm 12.11+) give consumer projects' agents guidance on using the design system.

Package Skill What it does
@wordpress/theme wp-theme Guides choosing design tokens and replacing legacy color variables, with a bundled token reference.
@wordpress/theme wp-theme-setup Sets up token loading, the Stylelint and ESLint token rules, and build-time fallback values.
@wordpress/ui wp-ui Guides building interfaces by choosing and composing components.
@wordpress/ui wp-ui-migration Guides moving from @wordpress/components to @wordpress/ui, including gradual migration with lint suppressions.
@wordpress/ui wp-ui-setup Sets up project styles and the ESLint rule that flags components to migrate.

The Storybook "Using with AI" docs are split into MCP and Skills pages, with install instructions for pnpm, npm and Yarn.

Why?

While we provide the design system MCP server to provide info and context for building with the design system, we rely on each individual developer working on a repo setting it up.

Agent files meanwhile can be automated within the entire repo, so anyone working on that repo then ends up using them.

Tooling doing PR reviews (such as CodeRabbit) also cannot very easily use MCP server in the reviews; while they support it, consumer (or we) would need to ship a hosted version of it and ensure that every versioned package is supported. Files meanwhile can be committed to the repo where review tool can see them, and they can be version controlled with NPM and Git.

How?

Adds agent skills to @wordpress/theme and @wordpress/ui, so package managers that link skills from dependencies (for example pnpm 12.11+) can copy them into consumer projects.

  • Skills live in packages/<package>/skills/<name>/SKILL.md and are published through files: wp-theme and wp-theme-setup in @wordpress/theme, wp-ui, wp-ui-migration and wp-ui-setup in @wordpress/ui.
  • The wp-theme skill bundles references/tokens.md. The token build generates it as a second output of the existing token docs plugin, so it stays in sync with docs/tokens.md.
  • The Storybook "Using with AI" docs are split into MCP and Skills pages. The Skills page has install instructions for pnpm, npm and Yarn. The MCP page keeps the previous content and its in-repo links now point to it.
  • The design-system-contribution skill documents how to maintain the published skills.
  • Changelog entries for both packages.

pnpm links skills natively after pnpm approve. npm and Yarn don't link skills from dependencies yet, so the docs use the community skills CLI.

Testing Instructions

  • Run npm run storybook:dev to test Design System / Using with AI page. See screenshot below.
  • Running npm pack --dry-run -w @wordpress/theme -w @wordpress/ui 2>&1 | grep skills/ should list the files at skills/ to see how skills are included in the tarballs.
  • In a test project, install the packages from a local pack with pnpm 12.11+, run pnpm approve, and check the skills appear in .claude/skills. Example PRs in Woocommerce and Jetpack.

Testing Instructions for Keyboard

Screenshots or screencast

image

Use of AI Tools

yes

@github-actions github-actions Bot added [Package] Theme /packages/theme [Package] UI /packages/ui labels Nov 12, 2026
@simison simison added the [Type] Developer Documentation Documentation for developers label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 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: simison <simison@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.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

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

📦 Bundle size

Size Change: 0 B

Total Size: 8.68 MB

fb08fd2 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric f9a72ae trunk % Change
timeToFirstByte 44 ms +9.43% -2.95% 45.2 ms +7.74% -5.42% -2.65%
largestContentfulPaint 70 ms +8.57% -2.86% 68 ms +5.88% -2.94% 2.94%
lcpMinusTtfb 25.3 ms +14.43% -5.14% 23.45 ms +5.54% -6.82% 7.89%
wpBeforeTemplate 22.91 ms +8.34% -1.27% 23.55 ms +8.03% -5.44% -2.72%
wpTemplate 17.66 ms +4.98% -6% 17.13 ms +7.41% -1.87% 3.09%
wpTotal 40.77 ms +9.86% -3.85% 40.81 ms +10.24% -3.7% -0.1%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric f9a72ae trunk % Change
timeToFirstByte 36.5 ms +9.04% -1.64% 36.25 ms +8.28% -2.62% 0.69%
largestContentfulPaint 68 ms +5.88% -5.88% 66 ms +3.03% -3.03% 3.03%
lcpMinusTtfb 29.15 ms +9.61% -3.95% 28.5 ms +11.23% -4.04% 2.28%
wpBeforeTemplate 19.97 ms +9.76% -2.25% 19.63 ms +7.64% -0.92% 1.73%
wpTemplate 13.58 ms +4.12% -2.72% 13.57 ms +3.61% -4.42% 0.07%
wpTotal 33.62 ms +6.72% -1.55% 33.44 ms +7.03% -2.42% 0.54%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric f9a72ae trunk % Change
mediaProcessingJpeg 327.65 ms +1.5% -1.52% 325.59 ms +0.84% -0.57% 0.63%
mediaProcessingAvif 4852.52 ms +0.56% -0.23% 4889.76 ms +0.51% -0.2% -0.76%
mediaProcessingJpegToAvif 3414.72 ms +0.26% -0.57% 3425.75 ms +0.25% -0.46% -0.32%

media-upload

Metric f9a72ae trunk % Change
jpegUploadProcessing 1471.11 ms +2.42% -1.36% 1466.26 ms +1.11% -1.53% 0.33%
pngUploadProcessing 241.5 ms +6.16% -4.47% 250.18 ms +5.62% -5.02% -3.47%
largeJpegUploadProcessing 1444.43 ms +1.06% -0.4% 1433.14 ms +0.48% -0.27% 0.79%
multipleImageUploadProcessing 1504.7 ms +0.9% -0.18% 1520.93 ms +0.31% -0.27% -1.07%

post-editor

Metric f9a72ae trunk % Change
serverResponse 476.05 ms +0.88% -8.67% 462.35 ms +2.41% -8.31% 2.96%
firstPaint 443.99 ms +1.32% -10.17% 393.08 ms +11.51% -1.45% 12.95%
domContentLoaded 819.38 ms +4.69% -1.88% 801.45 ms +0.56% -0.36% 2.24%
loaded 820.46 ms +4.67% -1.88% 802.56 ms +0.53% -0.38% 2.23%
firstContentfulPaint 469.04 ms +7.94% -4.1% 446.43 ms +2.47% -1.61% 5.06%
firstBlock 2166 ms +8.88% -1.37% 2139.18 ms +2.41% -0.64% 1.25%
type 17.63 ms +7.32% -7.77% 17.38 ms +7.77% -4.2% 1.44%
typeWithoutInspector 17.37 ms +3.86% -9.33% 17.81 ms +1.57% -14.21% -2.47%
typeWithTopToolbar 22.4 ms +5.94% -5.4% 22.32 ms +8.87% -3.41% 0.36%
typeContainer 8.39 ms +5.6% -19.67% 8.4 ms +6.67% -12.74% -0.12%
focus 120.33 ms +3.18% -1.76% 117.45 ms +6.77% -4.96% 2.45%
firstFocus 256.66 ms +0% -0% 268.22 ms +0% -0% -4.31%
selectAll 447.09 ms +1.73% -8.23% 404.22 ms +1.12% -3.78% 10.61%
undo 27.47 ms +6.19% -2.69% 27.63 ms +8.61% -3.11% -0.58%
listViewOpen 82.05 ms +6.03% -18.9% 79.3 ms +7.77% -16.56% 3.47%
inserterOpen 42.49 ms +11.46% -13.6% 41.86 ms +10.97% -5.83% 1.51%
inserterHover 11.63 ms +6.96% -5.25% 10.87 ms +11.59% -11.41% 6.99%
inserterSearch 8.06 ms +11.79% -5.58% 8.34 ms +7.43% -8.87% -3.36%
loadPatterns 611.37 ms +8.24% -1.8% 622.9 ms +7.61% -2.39% -1.85%
wpTotal 466.16 ms +0.97% -8.81% 452.57 ms +2.52% -8.47% 3%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric f9a72ae trunk % Change
serverResponse 480.41 ms +2.95% -7.18% 489.87 ms +0.56% -1.43% -1.93%
firstPaint 444.88 ms +8.18% -10.18% 469.53 ms +2.85% -14.53% -5.25%
domContentLoaded 851.34 ms +1.45% -1.2% 852.8 ms +2.12% -0.34% -0.17%
loaded 852.47 ms +1.44% -1.18% 854 ms +2.1% -0.36% -0.18%
firstContentfulPaint 477.57 ms +4.41% -1.3% 481.72 ms +1.68% -1.27% -0.86%
firstBlock 2635.24 ms +4.22% -0.29% 2677.77 ms +0.51% -2.11% -1.59%
type 18.83 ms +4.62% -8.18% 18.88 ms +7.73% -0.85% -0.26%
navigate 122.98 ms +8.7% -6.51% 113.83 ms +5.46% -1.99% 8.04%
loadPatterns 1467.65 ms +12.18% -14.56% 1478.94 ms +3.12% -3.48% -0.76%
loadPages 992.34 ms +4.27% -1.44% 1006.53 ms +8.31% -3.9% -1.41%
wpTotal 470.92 ms +2.96% -7.33% 480.17 ms +0.58% -1.45% -1.93%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

fb08fd2 Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Navigates the list via UP/DOWN arrow keys from action buttons in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' }) with timeout 5000ms
  - waiting for getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
    14 × locator resolved to <button type="button" tabindex="-1" class="components-button is-small" id="view-list-0-169-primary-action-edit-post">Edit</button>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js:243:5

Should duplicate the widgets in /test/e2e/specs/widgets/editing-widgets.spec.js, passed after 1 failed attempt.

should select synced pattern in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]') with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
    14 × locator resolved to <div tabindex="0" role="document" draggable="true" data-title="Pattern" data-type="core/block" data-is-drop-zone="true" aria-label="Block: Pattern" id="block-4edd0b9d-8507-47e6-9f95-9380c16ea6c3" data-block="4edd0b9d-8507-47e6-9f95-9380c16ea6c3" class="block-editor-block-list__block wp-block is-selected is-reusable block-library-block__reusable-block-container wp-block-block block-editor-block-list__layout">…</div>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1464:5

fb08fd2 Run

@simison simison added the Storybook Storybook and its stories for components label Nov 12, 2026
@simison
simison force-pushed the simison/design-system-agent-files-842d60 branch from bdbf4ed to 38bd7c4 Compare November 12, 2026 12:40
@aduth

aduth commented Nov 12, 2026

Copy link
Copy Markdown
Member

Related (closes?): #85972

Excited to see this 🙏

package managers that link skills from dependencies (such as pnpm 12.11+) can copy them into consumer projects

I'm not sure how much this will catch on in other package managers, but I wonder if we should generally lead with the use-case of other, more conventional package managers like npm, putting the skills integration first.

As a first use-case: Could we integrate this in Gutenberg itself? And possibly remove or trim some of the other existing skills in the process? That could happen as a separate follow-on as well.

@simison

simison commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

I'm not sure how much this will catch on in other package managers, but I wonder if we should generally lead with the use-case of other, more conventional package managers like npm, putting the skills integration first.

True, I think that's valid point.

As a first use-case: Could we integrate this in Gutenberg itself? And possibly remove or trim some of the other existing skills in the process? That could happen as a separate follow-on as well.

Yeah; let's do it in a follow-up. It'll need more thought on what to leave to "contributing" docs and what was generic enough to package to NPM package skills. One guide where I found a lot of overlap was copy writing guidance #86741

Later in follow-ups we should also consider if we can package skills about data layer which have a lot of common pitfalls, and some UX quirks guidance for DataViews/DataForms, etc.

@simison
simison force-pushed the simison/design-system-agent-files-842d60 branch 2 times, most recently from cd49819 to 9544577 Compare November 18, 2026 13:15
@simison
simison marked this pull request as ready for review November 18, 2026 13:27
@simison
simison requested a review from a team as a code owner November 18, 2026 13:27
@github-actions
github-actions Bot requested review from aduth and ciampo November 18, 2026 13:28
@simison

simison commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

This would be good for a review; it includes a few skills (setting up, migrating, working) with Theme and UI. Later this could expand to Admin UI, DataViews/DataForms, WP Build, Data and more. I'm also looking into UI copy skill separately.

I can pull this back to just simpler skill to mostly scaffold the structure and PR skills separately if we need more time finetuning them; I've built them based on lots of the reviewing I've done in products from actual component usage & migrations.

My initial approach was to add some scripts for simple tasks like analysing the repo before setup , but I pulled them back for now to keep starting point simpler.

I'm also testing the setup in practise in PRs in woocommerce/woocommerce#70299 and Automattic/jetpack#55018

@simison
simison force-pushed the simison/design-system-agent-files-842d60 branch from 9544577 to 967e8eb Compare November 19, 2026 09:01
Add `wp-theme`, `wp-theme-setup`, `wp-ui`, `wp-ui-migration` and `wp-ui-setup` skills under each package's `skills/<name>/SKILL.md` and publish them via `files`, so package managers that link skills from dependencies (such as pnpm 12.11+) can copy them into consumer projects. The token reference is bundled with `wp-theme` and generated by the token build.

Split the Storybook "Using with AI" docs into MCP and Skills pages, with install instructions for pnpm, npm and Yarn. Document maintaining the published skills in the design-system-contribution skill.
…skills

Add a `tokens.mjs` script to the `wp-theme` skill that searches and checks design tokens against the installed `@wordpress/theme`, and suggests the closest tokens for an unknown name. Add a read-only `inspect-project.mjs` script to the `wp-theme-setup` and `wp-ui-setup` skills that reports the package manager, linter and build configuration, installed WordPress packages, and which setup steps already look done.

Add a step to the `wp-ui-migration` skill that builds the migration inventory from ESLint's JSON output of `use-recommended-components`, with links to each component's migration guide. Document in the contribution skill how to maintain the scripts.
Remove the `tokens.mjs` and `inspect-project.mjs` scripts from the agent skills. The `wp-theme` skill now searches the bundled token reference with grep and checks tokens with the project's Stylelint and ESLint rules, and the setup skills describe how to inspect a project in plain instructions.

Run linters through the project's installed binaries instead of a bare `npx`, which downloads packages that are not installed.
@simison
simison force-pushed the simison/design-system-agent-files-842d60 branch from 7e320d9 to fb08fd2 Compare November 19, 2026 14:08

This branch has not been deployed

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

Labels

[Package] Theme /packages/theme [Package] UI /packages/ui Storybook Storybook and its stories for components [Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants