PS Design System

A PoC and still in early development — use at your own risk!

Extract design systems from WordPress themes using deterministic parsing and AI synthesis.

Description

PS Design System is a WordPress plugin that extracts design tokens and patterns from any WordPress theme, producing a structured design system document. It uses a two-step process:

Deterministic Extraction — Parses CSS files, theme.json, and template files to extract raw design tokens (colors, typography, spacing, etc.)

Example: samples/TT5/extraction.json
AI Synthesis — Uses LLM providers (OpenAI, Anthropic Claude, Azure OpenAI) to analyze, deduplicate, and synthesize tokens into a coherent design system

Example:

Features

🎨 Design Token Extraction — Colors, typography, spacing, shadows, borders, and more
📄 theme.json Support — Full support for WordPress block theme configuration
🤖 Multi-Provider LLM — Choose between OpenAI, Anthropic Claude, or Azure OpenAI
🔐 Secure API Keys — Sodium encryption for stored API credentials
⚡ Background Processing — Action Scheduler for chunked extraction of large themes
📊 Progress Tracking — Real-time job status updates in the admin UI
📥 Multiple Outputs — Export as JSON tokens, full design system, HTML styleguide, or Figma Tokens Studio file
🎯 Figma Integration — Import tokens directly into Figma via Tokens Studio plugin

Requirements

PHP 8.3 or higher
WordPress 6.8 or higher
Sodium PHP extension (included in PHP 7.2+)
Composer (for development)

Installation

From Source

# Clone the repository
git clone https://github.com/soderlind/ps-design-system.git

# Install dependencies
cd ps-design-system
composer install --no-dev

# Copy to your WordPress plugins directory
cp -r ps-design-system /path/to/wp-content/plugins/

Composer

composer require soderlind/ps-design-system

Configuration

Navigate to Design System → Settings
Enter your API key for at least one provider:
- OpenAI — Get your key at platform.openai.com
- Anthropic — Get your key at console.anthropic.com
- Azure OpenAI — Configure endpoint, deployment, and API key
Save settings

Usage

Go to Design System → Generate
Select the theme to analyze
Choose extraction scope:
- Tokens Only — Just design tokens (fastest)
- Tokens + Components — Tokens and UI component patterns
- Full System — Complete design system with templates
Select your LLM provider
Click Generate Design System
Download the results when complete

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      WordPress Admin                         │
├─────────────────────────────────────────────────────────────┤
│  Generate Page  │  History Page  │  Settings Page           │
├─────────────────────────────────────────────────────────────┤
│                      Job Manager                             │
│  (Action Scheduler for background processing)                │
├──────────────┬──────────────────┬───────────────────────────┤
│   Extractor  │    Normalizer    │      LLM Client           │
│  (CSS/JSON)  │  (Dedupe/Score)  │  (AI Synthesis)           │
├──────────────┴──────────────────┼───────────────────────────┤
│                                 │    Figma Generator        │
│                                 │  (Tokens Studio format)   │
├─────────────────────────────────┴───────────────────────────┤
│                      Providers                               │
│    OpenAI    │    Anthropic     │    Azure OpenAI           │
└─────────────────────────────────────────────────────────────┘

Development

Prerequisites

PHP 8.3+
Composer
Node.js 20+
npm

Setup

# Install PHP dependencies
composer install

# Install JavaScript dependencies
npm install

Testing

# Run PHP tests (Pest)
composer test

# Run JavaScript tests (Vitest)
npm test

# Run all tests
composer test && npm test

Code Style

# Check PHP code style
composer phpcs

# Fix PHP code style
composer phpcbf

# Lint JavaScript
npm run lint

Hooks

Filters

// Modify extracted tokens before normalization
add_filter( 'ps_ds_extracted_tokens', function( $tokens, $theme, $job_id ) {
    // Modify $tokens
    return $tokens;
}, 10, 3 );

// Modify the system prompt sent to LLM
add_filter( 'ps_ds_system_prompt', function( $prompt, $scope ) {
    return $prompt . "\n\nAdditional instructions...";
}, 10, 2 );

// Modify final design system output
add_filter( 'ps_ds_design_system', function( $design_system, $job_id ) {
    // Add custom properties
    return $design_system;
}, 10, 2 );

Actions

// Fired when extraction starts
add_action( 'ps_ds_extraction_started', function( $job_id, $theme ) {
    // Log or notify
}, 10, 2 );

// Fired when job completes
add_action( 'ps_ds_job_complete', function( $job_id, $outputs ) {
    // Post-processing
}, 10, 2 );

// Fired on job failure
add_action( 'ps_ds_job_failed', function( $job_id, $error ) {
    // Error handling
}, 10, 2 );

Output Format

The generated design system follows a structured JSON schema:

{
  "version": "1.0",
  "theme": "theme-name",
  "generated_at": "2026-02-04T12:00:00Z",
  "tokens": {
    "colors": {
      "primary": { "value": "#007bff", "usage": "primary-actions" },
      "secondary": { "value": "#6c757d", "usage": "secondary-elements" }
    },
    "typography": {
      "fontFamilies": [...],
      "fontSizes": [...],
      "lineHeights": [...]
    },
    "spacing": {
      "scale": [4, 8, 16, 24, 32, 48, 64],
      "unit": "px"
    }
  },
  "components": [...],
  "patterns": [...]
}

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the GPL v2 or later — see the LICENSE file for details.

Credits

Per Soderlind — Author
PHP CSS Parser — CSS parsing library
Action Scheduler — Background processing
Brain Monkey — WordPress mocking for tests

Support

📦 Source: soderlind/ps-design-system · Edit on GitHub