Statamic Bard Color Picker Laravel Package

Getting Started

This addon registers a Bard (TipTap) toolbar button that lets editors wrap selected text in a color mark, with a configurable swatch palette shown in a popover.

Minimal setup:

1. Install — composer require ndx/statamic-bard-color-picker. Check composer.json first to confirm Statamic 4/5 support; the addon is niche (11 stars, no dependents), so version constraints matter more than usual.
2. Publish config (optional) — php artisan vendor:publish --tag=statamic-bard-color-picker-config (confirm the tag in src/ServiceProvider.php's publishes() call). Defaults usually work for a first look.
3. Enable the button in the Bard field's buttons array in your fieldset/blueprint:

   -
     handle: body
     field:
       type: bard
       buttons:
         - bold
         - italic
         - color_picker   # use the exact handle registered in resources/js
   

4. Define your swatches — globally in config/statamic/bard-color-picker.php, or per-field if the field exposes a colors/swatches option.

First use case: open an entry, select a sentence in a Bard field, click the color button, pick a swatch, save, and inspect the rendered HTML. Confirm whether the mark serializes to <span style="color: #..."> or to a class — your entire frontend styling strategy depends on that answer.

Where to look first: README.md → composer.json (Statamic version) → src/ServiceProvider.php (how the Bard extension and JS/CSS assets are registered) → resources/js/ (button handle, mark name, serialization) → config/ (palette and options). The JS is the real source of truth if docs are thin.

Implementation Patterns

• Brand palette, not raw hex. Populate the swattches with your design-system tokens (primary, muted, accent, danger) so editors can't produce off-brand colors. Keep the list to ~6–10 swatches; long palettes overwhelm in the toolbar popover.
• Reuse across fieldsets via a shared partial. Put the color-enabled Bard field in a fieldset partial and include it in every blueprint that needs rich text, so the palette and button list stay in one place.
• Per-field overrides vs. global config. Use the global config for the default palette; override per field where a marketing page and a legal page need different palettes. If the addon doesn't support per-field overrides, wrap distinct fields with distinct config keys or duplicate the fieldset.
• Rendering on the frontend. If save_html: true is set on the Bard field, inline <span style="color:..."> flows straight into Antlers {{ body }}. If the field stores ProseMirror JSON, you must render through Bard's renderer — the mark has to be known to your schema or the color silently drops.
• Mark nesting. Color is an inline mark and normally wraps text nodes, so **bold inside color** and links inside a colored span typically round-trip. Verify both directions (edit → save → re-edit) before shipping, since mark ordering affects output.
• Transform to classes if you theme. If inline styles get stripped by your CSS pipeline, add a small Bard/HTML renderer step that maps style="color: #x" to class="text-x" so your Tailwind/config can control it.
• Editor UX. Place the button next to bold/italic plus a divider — it reads as a text-formatting control, not a block control. Keep the swatch popover to a single row if possible.

Gotchas and Tips

• Button handle is exact and silent. A typo in buttons: doesn't error — the button simply never appears. If nothing shows, diff the handle against the one in resources/js.
• Assets and caching. After install or upgrade, run php artisan cache:clear and php artisan config:clear, then hard-reload the Control Panel (cache-busted asset URLs are registered via the AddonServiceProvider $scripts/$styles arrays).
• HTML purifier can eat your colors. If content saves but the color disappears on render, check config/statamic/purifier.php. span must be allowed and style permitted on it, otherwise inline color is stripped.
• save_html decision is load-bearing. Switch between HTML and ProseMirror JSON storage and colors will disappear or reappear unpredictably — decide early and migrate content if you change it.
• Frontend sanitizers and Tailwind prose. Any sanitize-html call or prose/typography reset can strip or override inline color styles. Either whitelist style on span or convert to utility classes.
• Accessibility is your job. The picker does not enforce contrast; a light swatch on a light theme will ship as a WCAG failure. Provide a palette with tested contrast, and consider a secondary "background" variant only if the addon supports it.
• Low-maintenance signal. With 11 stars and no dependents, expect limited ongoing support. Pin the version in composer.json, watch the Statamic major line, and be prepared to read resources/js rather than rely on the README.
• Extension points. You can register an additional mark or swap the swatch source from your own service provider by extending the addon's Bard extension class — useful if you need dynamic palettes (e.g., per-site brand colors) that config files can't express.