AGENTS.md: Add design system package guide

[jarekmorawski]

Description

Adds a "Design system package guide" section and two new common pitfalls to AGENTS.md, helping AI agents work correctly with WordPress Design System packages.

Design system package guide (new section)

• A package-to-role mapping table covering @wordpress/theme, @wordpress/ui, @wordpress/icons, @wordpress/admin-ui, @wordpress/dataviews, and @wordpress/components
• Key rules for token usage, package preference, and the relationship between the two styling systems
• Clarification of when to use --wp--preset--* (block rendering / front-end) vs. --wpds-* (admin UI / design system components) — two CSS custom property namespaces that coexist in Gutenberg

Common pitfalls (new bullets)

• @wordpress/dataviews registers a @wordpress/data store at import time; removing a <DataViews> usage without removing the import still ships the store registry
• @wordpress/ui and @wordpress/components use different styling systems (CSS Modules vs. Emotion) — contributors should match the styling approach of the package they're working in

Motivation

This addresses a recurring problem where AI agents working with Gutenberg:

• Pick components from @wordpress/components or @wordpress/ui at random, requiring manual cleanup
• Fabricate design tokens that sound plausible but don't exist, instead of referencing @wordpress/theme
• Confuse the two CSS custom property namespaces (--wp--preset--* vs. --wpds-*)
• Don't know when to fall back from /ui to /components (or when not to)

These patterns were observed across multiple prototyping projects that stress-tested the WPDS packages. The component lists in the table use "e.g." so they remain accurate as new components are added.

Part of #77205.

Testing Instructions

This is a documentation-only change to AGENTS.md. No code, tests, or build changes.

Pre-merge Checklist

• Change is documentation-only
• Component lists use "e.g." to stay future-proof
• New section placed after "Architectural decisions", before "Common pitfalls"
• New pitfall bullets match the style of existing ones
• Formatting matches the existing file style

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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: jarekmorawski <jarekmorawski@git.wordpress.org>
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.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @jarekmorawski! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Required label: Any label starting with [Type].
• Labels found: First-time Contributor.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[ciampo]

Should this information live in AGENTS.md? I'm always way of duplicating information across repos / documents / storybook / potential reference sites as it increases the changes of it getting out of sync/date and generating non-deterministic agent outputs.

IMO, information about what a package does and how to use its APIs shoud live as close as possible to the source (ie in the package's README, in each component docs, etc).

As for where wider "Design System orchestration" info should live, that's something to discuss and agree on: my take is that it should live on a reference site (either a dedicated site, or a section of Storybook), and agents should be pointed to fetch every time the latest version as the canonical source of information.

[aduth]

What's currently proposed here as a package summary might work well as a replacement or extension of the current design system introduction documentation in Storybook, and we could either summarize or redirect agents to that documentation (being mindful that agents tend to not always follow redirection, but also wary of the maintenance cost and drift potential of maintaining a duplicate summary copy).

There's been some concerns raised about the existence of this AGENTS file in the first place (related to Trac#63901 discussion), but I can see from my own experience with agents where this guidance may be helpful (e.g. preferring tokens over hardcoded values). With many of these, I do find myself asking:

• Should this be documented somewhere for both humans and agents to be referencing?
• At the very least, should it be more localized to the affected files? (e.g. package-specific AGENTS.md)
• Are they addressing shortcomings that should be eliminated altogether (e.g. the DataViews import logic is interesting and it's not clear to me if it's something we should be improving independently)

[aduth]

There's been some work to try to document status on a component-by-component basis.

Examples:

gutenberg/packages/components/src/h-stack/stories/index.story.tsx

Lines 77 to 81 in d5be89a

	componentStatus: {
	status: 'not-recommended',
	whereUsed: 'global',
	notes: 'Use `Stack` from `@wordpress/ui` instead.',
	},

gutenberg/packages/components/src/button/stories/index.story.tsx

Lines 54 to 58 in d5be89a

	componentStatus: {
	status: 'stable',
	whereUsed: 'global',
	notes: 'Will be superseded by `Button` in `@wordpress/ui`, but continue using for now.',
	},

I don't think we're at a point where we'd want to make a blanket statement to always prefer @wordpress/ui (related: #76135), but ideally we could and should be pointing towards these component-specific statuses if they're known.

[aduth]

This is a good reminder that we should ideally be considering these component statuses as part of an MCP offering; for example, maybe we should include some @wordpress/components components in the design system MCP responses if they're stable, i.e. there's not an equivalent in @wordpress/ui or it's not ready to be used.

[aduth]

This feels like something we're actively trying to avoid (i.e. @wordpress/components and @wordpress/ui should be expected to coexist without perceivable visual differences), so I'd be hesitant to document that this is expected, or that the components shouldn't be used together.

[mirka]

Right, and "can they coexist visually" is part of the criteria for adding a new @wordpress/ui component to the list of recommended components.