# Theme.json Design Manager

A lean, core-aligned WordPress plugin for managing design tokens — colors, spacing, typography, border radius, and shadows — that integrate directly with WordPress Global Styles via `theme.json`.

No code editing required. Fully reversible.

## Features

- **Color Palette** — Define semantic color tokens with live contrast previews. Generates `--wp--preset--color--{slug}` CSS custom properties.
- **Spacing Scale** — Create spacing tokens with drag-to-reorder support. Generates `--wp--preset--spacing--{slug}` CSS custom properties.
- **Typography Scale** — Set font size tokens with optional fluid `clamp()` support. Generates `--wp--preset--font-size--{slug}` CSS custom properties.
- **Border Radius** — Define radius presets with live corner previews. Generates `--wp--custom--border-radius--{slug}` CSS custom properties.
- **Shadow Presets** — Create box-shadow tokens with live previews. Generates `--wp--preset--shadow--{slug}` CSS custom properties.
- **Hide Defaults** — Optionally hide theme/core default presets from the editor for a clean, curated design system. CSS custom properties are preserved.
- **Reserved Slug Protection** — Automatically detects and renames color slugs (e.g. "text", "link") that conflict with WordPress core CSS marker classes, preventing color override issues in the editor.
- **Diagnostics Tab** — View runtime data including stored tokens, merged palette by origin, generated CSS variables, preset classes, and settings at a glance.

## How It Works

The plugin stores design tokens in the WordPress database (`wp_options`) and merges them into the theme's Global Styles via the [`wp_theme_json_data_theme`](https://developer.wordpress.org/reference/hooks/wp_theme_json_data_theme/) filter. Tokens use WordPress's native slug-based merge system — matching slugs are replaced, new slugs are appended.

Deactivating the plugin restores your theme's original styles. Token data is preserved in the database until the plugin is deleted (uninstalled).

## Requirements

- WordPress 6.1 or later
- PHP 7.4 or later
- A block theme or classic theme with `theme.json` support

## Installation

1. Download or clone this repository into your `/wp-content/plugins/` directory:
   ```bash
   cd /path/to/wordpress/wp-content/plugins
   git clone https://github.com/YOUR_USERNAME/theme-json-design-manager.git
   ```
2. Activate the plugin through **Plugins → Installed Plugins** in the WordPress admin.
3. Navigate to **Appearance → Design Manager** to start managing your design tokens.

## Usage

After activation, go to **Appearance → Design Manager** in the WordPress dashboard. The interface provides tabbed sections for each token type:

| Tab           | What it manages      | CSS variable pattern                  |
| ------------- | -------------------- | ------------------------------------- |
| Colors        | Color palette tokens | `--wp--preset--color--{slug}`         |
| Spacing       | Spacing scale tokens | `--wp--preset--spacing--{slug}`       |
| Typography    | Font size tokens     | `--wp--preset--font-size--{slug}`     |
| Border Radius | Radius presets       | `--wp--custom--border-radius--{slug}` |
| Shadows       | Box-shadow presets   | `--wp--preset--shadow--{slug}`        |
| Settings      | Hide default presets | —                                     |
| Diagnostics   | Runtime token data   | —                                     |

Reference any token in your CSS or block styles using its generated CSS custom property:

```css
.my-element {
  color: var(--wp--preset--color--primary);
  padding: var(--wp--preset--spacing--md);
  font-size: var(--wp--preset--font-size--large);
  border-radius: var(--wp--custom--border-radius--lg);
  box-shadow: var(--wp--preset--shadow--soft);
}
```

## Developer Hooks

The plugin provides extensibility hooks for developers building on top of it:

### Filters

- **`gdtm_tokens_before_merge`** — Modify tokens before they are merged into `theme.json`. Useful for Pro add-ons (e.g., dark mode token sets).

  ```php
  add_filter( 'gdtm_tokens_before_merge', function( $tokens ) {
      // Transform or extend tokens.
      return $tokens;
  } );
  ```

- **`gdtm_admin_tabs`** — Register additional tabs in the admin UI.
  ```php
  add_filter( 'gdtm_admin_tabs', function( $tabs ) {
      $tabs['my-custom-tab'] = 'My Tab';
      return $tabs;
  } );
  ```

### Actions

- **`gdtm_after_save`** — Fires after tokens are saved to the database.
- **`gdtm_after_tab_content`** — Render custom content after a tab's default output.

## Plugin Structure

```
theme-json-design-manager/
├── theme-json-design-manager.php   # Main plugin bootstrap
├── uninstall.php                   # Clean removal of plugin data
├── assets/
│   ├── admin.css                   # Admin UI styles
│   └── admin.js                    # Admin UI scripts (color picker, sortable, previews)
└── includes/
    ├── class-gdtm-admin.php        # Admin page registration, rendering, and form handling
    ├── class-gdtm-storage.php      # Token persistence, validation, and sanitization
    └── class-gdtm-theme-json.php   # theme.json integration via wp_theme_json_data_theme
```

## FAQ

**Does this require a specific theme?**
No. It works with any block theme or classic theme that supports `theme.json`.

**Will my tokens override the theme's existing values?**
Tokens with matching slugs replace the theme's values. New slugs are appended alongside existing ones. This is WordPress's native slug-based merge behavior.

**What happens when I deactivate the plugin?**
All plugin-managed tokens are removed from the Global Styles pipeline and your theme's original `theme.json` values are restored. Your data is preserved in the database.

**What happens when I delete (uninstall) the plugin?**
All token data is removed from the database for a clean uninstall.

**Can I use fluid typography?**
Yes. On the Typography tab, enable the "Fluid" toggle and set min/max values. WordPress generates a responsive `clamp()` function automatically.

## Changelog

### 1.0.0

- Initial release.
- Color palette, spacing scale, typography scale, border radius, and shadow preset management.
- Live previews for colors, radius, and shadows.
- Fluid typography with clamp() support.
- Drag-to-reorder for spacing tokens.
- Settings tab with toggles to hide default presets from the editor.
- Reserved slug protection — auto-renames color slugs that collide with WordPress core marker classes.
- Diagnostics tab — runtime view of stored tokens, merged palette, CSS variables, and preset classes.
- Base color fallback — ensures `--wp--preset--color--base` stays defined when replacing the theme palette.
- Full theme.json integration via `wp_theme_json_data_theme` filter.
- Extensibility hooks for developers.

## License

GPLv2 or later — [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html)

## Author

**Sulaiman Dauda**