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

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

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:

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

   Example: samples/TT5/extraction.json

2. AI Synthesis — Uses LLM providers (OpenAI, Anthropic Claude, Azure OpenAI) to analyze, deduplicate, and synthesize tokens into a coherent design system

   Example:

   • samples/TT5/design-system.md
   • samples/TT5/tokens.json
   • samples/TT5/figma-tokens.json
   • samples/TT5/styleguide.html

• 🎨 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

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

# 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 require soderlind/ps-design-system

1. Navigate to Design System → Settings
2. 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
3. Save settings

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

┌─────────────────────────────────────────────────────────────┐
│                      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           │
└─────────────────────────────────────────────────────────────┘

• PHP 8.3+
• Composer
• Node.js 20+
• npm

# Install PHP dependencies
composer install

# Install JavaScript dependencies
npm install

# Run PHP tests (Pest)
composer test

# Run JavaScript tests (Vitest)
npm test

# Run all tests
composer test && npm test

# Check PHP code style
composer phpcs

# Fix PHP code style
composer phpcbf

# Lint JavaScript
npm run lint

// 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 );

// 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 );

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": [...]
}

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

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

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

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

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation
• 🧾 Changelog