Contribute to the WordPress Design System

Contribute to the WordPress Design System

In a Gutenberg checkout, read the relative links below from the checked-out revision. Outside a checkout, resolve them from .agents/skills/design-system-contribution/ in Gutenberg on GitHub.

Read the affected package's AGENTS.md and the relevant package contribution guidance.

Choose the smallest change

Start from the consumer's need. For a bug fix, reproduce the failure and identify the behavior to restore. For a refactor, identify the behavior to preserve. A new capability needs a concrete use case and an explanation of why existing public composition is insufficient.

When choosing a component or token, use the Design System MCP server's get_components, get_component_details, and get_design_tokens as appropriate when available. Without MCP, use the guide's recommendation sources and the token reference. Check the current source before adding an API that appears to be missing.

Keep product-specific behavior in the consuming package and use design-system-ui-composition for that work. For unresolved public design decisions, follow Contributing to the Design System before implementation; continue work that does not depend on that decision.

Preserve the affected contracts

• Follow the package's component, prop/ref, state, and styling conventions. Reuse existing composition and helpers instead of rebuilding behavior already provided by a dependency.
• For removals, replacements, or behavior changes, compare the affected old and new contracts using the compatibility guidance. Include plugin and npm consumers, even when all Gutenberg callers have been migrated.
• For token changes, choose by semantic purpose and affected modes, then follow the token source guide and build procedure. For Emotion migrations, use emotion-to-scss-modules.
• Use package-runtime-compatibility only when changing a contract between independently updated package and WordPress versions.

Verify what changed

Start with existing tests and stories. Add coverage only for a concrete regression risk introduced by our code or integration that existing coverage does not address. Rely on dependency tests for behavior the dependency owns; avoid speculative edge cases and exhaustive combinations. Use the guide's verification choices for checks that need a browser.

When changing component recommendations, follow the component status guidance to update Storybook status, curated manifest tags, ESLint recommendation lists, migration guidance, and generated manifest snapshots together.

Follow the completion checks for affected exports, documentation, generated files, and changelogs, along with the repository's required checks. State any material verification gap without claiming visual parity from snapshots or class assertions.