Add DESIGN.md for agent-facing design system guidance

[jameskoster]

What

Adds a DESIGN.md file — a concise, agent-facing guide to the WordPress Design System (WPDS). It covers visual philosophy, package hierarchy, the component inventory, page-building patterns, accessibility expectations, and theming. AGENTS.md and CLAUDE.md are updated to reference it.

Why

AI coding agents are increasingly used to build admin UI in this repository. Without design guidance, agents make reasonable but inconsistent choices — wrong packages, hardcoded values instead of tokens, custom widgets where a component already exists, missed accessibility requirements.

Today, the relevant knowledge is scattered across package READMEs, Storybook, token docs, and tribal knowledge. DESIGN.md gives agents a single entry point that establishes the ground rules before they start writing code, reducing review friction and improving first-pass quality.

How

• DESIGN.md (~180 lines) — intentionally kept lean and resistant to drift:
  • Opening prose establishes the design philosophy (utility-first, native UI, restrained palette, system fonts).
  • Key characteristics as a scannable checklist.
  • Package hierarchy and import patterns so agents reach for the right package first (@wordpress/ui over @wordpress/components).
  • Component table for quick lookup.
  • Building pages pattern (Page + DataViews/DataForm + core-data hooks).
  • Accessibility, theming, and a minimal working example.
  • Specific values (pixel sizes, hex colors, weight numbers) are avoided where possible — the document points to tokens and package READMEs as the source of truth for implementation details.
• AGENTS.md — one new bullet under "Architectural decisions" directing agents to read DESIGN.md when building admin UI.
• CLAUDE.md — added @DESIGN.md so Claude Code automatically loads the full document into context.

Use of AI Tools

Created with Cursor and Claude Opus 4.6. I reviewed the output manually.

Note

I recognise some of the proposed content is aspirational, and potentially blocked by issues like #76135 and components in the UI package being marked as allowed (https://github.com/WordPress/gutenberg/blob/trunk/packages/eslint-plugin/rules/use-recommended-components.js#L11).

[jameskoster]

I recognise this list can easily drift. I wonder if there's a neat way to avoid that, maybe by refering to a canonical directory?

[github-actions]

Flaky tests detected in 238ff4a.
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.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/24089629284
📝 Reported issues:

• [Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
• [Flaky Test] should show correct homepage actions based on current homepage or posts page #68892 in /test/e2e/specs/site-editor/homepage-settings.spec.js

[mirka]

What would you say to building this file up item by item when we notice specific problems in PR review, and when the best solution to that problem is not a lint rule? A lot of times, the best solution (both in terms of enforceability and source of truth) is a lint rule. If we want to push it further, maybe the agent can be directed to follow the lint rules, and not disable lint rules haphazardly.

I'm not only concerned about the maintenance cost of these types of files, but also the actual effectiveness. Without comparison testing, there's no way to tell if having the agent file will be better than baseline in either token efficiency or output quality.

[jasmussen]

Thanks for starting this. I think it's a monumental effort we are undertaking with this, and one of the most important ones, so it's outstanding that this effort has been kicked off. The thing is, this doc is useful to create and agree on, so that all institutional and important knowledge gets captured in an easily portable document. IMO that's the first task this needs to accomplish, and this is a good start.

What Lena mentions above also resonates, though; she'll know more precisely the possible consequences, but it sounds like this is one of those files that ideally shouldn't change substantially or that often. Grow, yes definitely, but change, hopefully rarely.

You mention the word yourself, aspirational. I wonder if we can split this PR in two: one list of things that feel obviously true and are useful even today, make that the growing doc that Lena suggests. And one, perhaps a discussion, about the aspirational bits, so we can lock them in. That's not meant as disagreement (I happen to agree with at least 80% of what you outlined), but rather so we can massage it and lock it in, before we codify it. What do you think?

[jameskoster]

Thank you, I appreciate the scrutiny and skepticism. I agree there's potential for a file like this to overlap with automations and become a maintenance burden, which we certainly do not want. We could eliminate that by removing content with potential to go stale as suggested, but those are likely the pieces most useful to an agent, so I suspect the file would lose a lot of utility (although may still be useful to human readers).

building this file up item by item when we notice specific problems in PR review, and when the best solution to that problem is not a lint rule?

That seems like a sensible approach :)