Wpds

What Is This?

Overview

The WordPress Design System (WPDS) is a structured collection of UI components, design tokens, and interaction patterns maintained by the WordPress project. It provides a unified visual and functional language for building interfaces that align with the WordPress ecosystem, ensuring consistency across themes, plugins, and block-based editors. WPDS defines everything from color palettes and typography scales to button variants and form controls, all expressed through reusable tokens and documented components.

When working with WPDS in a development environment, the system integrates with the WPDS MCP (Model Context Protocol) server, which exposes design system documentation, token lists, and component references directly to your tooling. This allows developers to query available tokens, look up component usage patterns, and apply design system conventions without switching between documentation tabs and code editors. The skill targets WordPress 6.9 and later, running on PHP 7.2.24 or higher.

WPDS is not simply a component library. It is a living specification that governs how WordPress interfaces should look and behave. Adopting it means your UI work stays aligned with platform updates, accessibility standards, and the broader WordPress contributor community.

Who Should Use This

• Block developers building custom Gutenberg blocks who need consistent spacing, color, and typography tokens
• Plugin authors creating admin interfaces that should match the WordPress dashboard visual language
• Theme developers working within Full Site Editing (FSE) contexts where design token alignment is critical
• Frontend engineers contributing to WordPress core or Gutenberg who must follow established component patterns

Why Use WPDS?

Problems It Solves

• Visual inconsistency across plugins and themes: Without a shared token system, each plugin invents its own spacing and color values, leading to fragmented admin experiences.
• Redundant component work: Developers rebuild buttons, modals, and form inputs repeatedly instead of consuming tested, accessible components from a central source.
• Accessibility gaps: Custom-built components often miss ARIA attributes, focus management, or contrast requirements that WPDS components handle by default.
• Token drift during WordPress updates: Hard-coded color or size values break when WordPress updates its design language, while token-based implementations update automatically.

Core Highlights

• Access to the full WPDS token vocabulary including color, spacing, typography, and elevation
• Pre-built, accessible UI components aligned with WordPress core design standards
• MCP server integration for real-time documentation and token queries inside your editor
• Compatibility with WordPress 6.9 and the block editor architecture
• Consistent naming conventions that map directly to CSS custom properties
• Pattern library covering common UI layouts and interaction flows
• Support for both light and dark mode through semantic token usage

How to Use WPDS?

Basic Usage

After configuring the WPDS MCP server, you can query available tokens and components directly. A typical workflow starts with identifying the correct token for a design property.

/* Using a WPDS spacing token */
.my-block-wrapper {
  padding: var(--wp--custom--spacing--medium);
  color: var(--wp--preset--color--primary);
}

// Using a WPDS Button component in a block
import { Button } from '@wordpress/components';

const MyBlockControls = () => (
  <Button variant="primary" onClick={handleSave}>
    Save Settings
  </Button>
);

Specific Scenarios

Scenario 1: Building a custom admin settings page. Use WPDS form components and spacing tokens to match the native WordPress admin UI. Query the MCP server for the current input and card component specifications before writing markup.

Scenario 2: Creating a Gutenberg sidebar panel. Reference WPDS panel and typography tokens to ensure your inspector controls align visually with core block controls.

Real-World Examples

• A plugin settings screen using PanelBody, TextControl, and WPDS color tokens to match the core editor appearance
• A custom block toolbar built with ToolbarGroup and ToolbarButton components sourced from WPDS specifications

When to Use WPDS?

Use Cases

• Building any UI that will appear inside the WordPress admin or block editor
• Contributing components or patterns back to WordPress core
• Auditing an existing plugin for design system compliance
• Migrating a legacy plugin UI to match modern WordPress visual standards
• Creating documentation or Storybook stories for WordPress-adjacent component libraries
• Prototyping new block editor features that need to match platform conventions
• Enforcing design token usage in a team codebase through linting or code review

Important Notes

Requirements

• WPDS MCP server must be installed and running before using this skill
• WordPress 6.9 or later is required for full token and component compatibility
• PHP 7.2.24 or higher on the server environment
• Node.js environment for consuming @wordpress/components in JavaScript-based UIs