/design-system-synthesizer

name: design-system-synthesizer
description: "Use when the user says 'build a design system for my site', 'extract design tokens', 'capture my brand', or 'build my style guide', or after a rebrand. Reads representative pages, theme files, and media to extract logo, colors, typography, spacing, and components, then writes a visible style-guide page."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.4.2
  mcp-server: respira-wordpress
  category: intelligence

Design System Synthesizer

**Version:** 1.4.2 **Updated:** 2026-08-13 **Freshly updated:** v1.4.0 persists to the Design Direction owner layer. The synthesized system is now saved as a schema-validated draft direction via `respira_save_design_direction` (readiness reported in the response), with the legacy `respira_update_option('respira_design_system', ...)` write kept only as a fallback for plugins that predate the direction tools. The final step offers activation via `respira_activate_design_direction` — activation refuses a direction that is not ready, so nothing goes live half-synthesized. Any token you could not observe and had to guess must carry `inferred: true`. **Previous:** v1.3.0 caught up with the design-token surface. Builder global palettes and typography are now written through first-class token tools (`respira_list_design_tokens`, `respira_create_design_token`, `respira_update_design_token`, `respira_delete_design_token`), replacing v1.2.0's describe-it-in-plain-words guidance. HTML/design conversions register the colors and typography they carry as named tokens in the builder's own global styles automatically, and converted pages reference those tokens instead of carrying value copies — so the synthesizer reads what is already registered before synthesizing, reuses those names instead of re-inlining values, and reports token registration in its summary. **Category:** intelligence **Status:** stable **Requires:** Respira for WordPress plugin 7.1+ + MCP server

---

Description

Read a WordPress site's representative pages, theme files, and media library to extract a complete, reusable **design system** — logo, color palette, typography, spacing scale, component patterns. Persist it to the site so every future content-creation skill references it, and every new page Claude builds matches the existing brand.

This is the foundation for on-brand AI-generated content. Without a design system, the agent guesses at colors, fonts, and spacing — and the result looks like every other AI-generated WordPress page. With a design system, the agent has explicit tokens to use, and new pages snap to the brand.

---

What it produces

A structured `design_system` artifact stored at the site level. Schema:

{
  "version": "1.2.0",
  "synthesized_at": "2026-05-24T14:30:00Z",
  "synthesized_from": ["/", "/about/", "/services/web-design/", "/blog/sample-post/", "/contact/"],
  "brand": {
    "logo_url": "https://example.com/wp-content/uploads/2025/logo.svg",
    "logo_dark_url": null,
    "favicon_url": "https://example.com/favicon.ico",
    "social_card_url": "https://example.com/wp-content/uploads/2025/og-default.jpg",
    "wordmark_text": "Acme Studio"
  },
  "colors": {
    "primary": "#2563EB",
    "secondary": "#0F172A",
    "accent": "#F59E0B",
    "neutral_900": "#0F172A",
    "neutral_700": "#334155",
    "neutral_500": "#64748B",
    "neutral_300": "#CBD5E1",
    "neutral_100": "#F1F5F9",
    "background": "#FFFFFF",
    "background_alt": "#F8FAFC",
    "text_primary": "#0F172A",
    "text_secondary": "#475569",
    "link": "#2563EB",
    "success": "#10B981",
    "warning": "#F59E0B",
    "error": "#EF4444"
  },
  "typography": {
    "heading_family": "Söhne, ui-sans-serif, system-ui, sans-serif",
    "heading_weight": 700,
    "h1_size": "3.5rem",
    "h2_size": "2.5rem",
    "h3_size": "1.875rem",
    "h4_size": "1.5rem",
    "h5_size": "1.25rem",
    "h6_size": "1rem",
    "body_family": "Söhne, ui-sans-serif, system-ui, sans-serif",
    "body_weight": 400,
    "body_size": "1rem",
    "body_line_height": 1.65,
    "mono_family": "JetBrains Mono, ui-monospace, monospace",
    "letter_spacing_heading": "-0.02em",
    "letter_spacing_body": "0"
  },
  "spacing": {
    "scale_base": 4,
    "scale_steps": [4, 8, 12, 16, 24, 32, 48, 64, 96, 128],
    "section_padding_y": "96px",
    "section_padding_x": "24px",
    "container_max_width": "1280px"
  },
  "components": {
    "button_primary": {
      "background": "primary",
      "color": "#FFFFFF",
      "padding": "12px 24px",
      "border_radius": "8px",
      "font_weight": 600
    },
    "button_secondary": { /* ... */ },
    "card": {
      "background": "background",
      "border": "1px solid neutral_300",
      "border_radius": "12px",
      "padding": "32px",
      "shadow": "0 1px 3px rgba(0,0,0,0.05)"
    },
    "hero_pattern": "centered_with_kicker_h1_subtitle_2cta",
    "section_pattern": "wide_two_column_image_left"
  },
  "voice_hints": {
    "person": "we",
    "formality": "approachable_professional",
    "sentence_length_avg_words": 14,
    "avoids": ["exclamation marks", "marketing superlatives"]
  }
}

The artifact is persisted through the Design Direction owner layer via `respira_save_design_direction` (see Step 8). On plugins that predate the direction tools, fall back to `respira_update_option('respira_design_system', ...)` — the plugin's first-run migration lifts that option into a draft direction automatically once it updates.

---

When to Use

• First time setting up an AI workflow for an existing site — generate the design system so future content is on-brand
• Site rebrand — re-synthesize after the new brand lands so the AI catches the new tokens
• Before running content-creation skills (`build_page`, page generators) so the new pages match the brand
• Quarterly refresh — re-synthesize to capture brand drift

---

Trigger Phrases

• "build a design system for my