Statamic Editor Themes Laravel Package

Getting Started

• Install the addon with Composer and let Statamic discover it. Clear Statamic’s caches if the preference panel does not appear immediately.
• First place to look: Control Panel → Preferences → Themes. Pick a theme, save, and confirm the editor updates for your user.
• For command-line setup, use:
  • php please editor-themes:apply "Tokyo Night" — works with either the theme name or id.
  • php please editor-themes:remove — removes the user’s explicit theme and falls back to the applicable default.
• A good first use case is standardising the editor theme for a team during onboarding or deployment, then letting users override it from Preferences.

Implementation Patterns

• Per-user preference flow: Let users choose their own theme under Preferences → Themes. This is the lowest-friction path and preserves individual preference.
• Provisioning and onboarding: Use editor-themes:apply in setup scripts or internal docs to give new users a sensible starting theme. Because it accepts a theme name, scripts can be readable: "Gruvbox", "Solarized", etc.
• Removing customisation: Use editor-themes:remove when resetting a user to site/role defaults. On Statamic Pro, the user receives their role’s default theme or the site default, if one exists. Communicate that behaviour to users so removal is not mistaken for “no theme”.
• Theme definitions: Treat the grey ramp as part of the contract. A valid theme needs shades 100 and 950, and all colours must be six-digit hex. Validate custom or ported themes before rolling them out.
• Light and dark mode: The package measures light-mode contrast against the body surrounding content, not just the content surface. When adjusting custom themes, check links, status colours, and muted text in both modes rather than only checking the editor background.
• Accent handling: If an accent needs to go all the way to black or white to meet contrast, the package now applies that final step. Avoid hard-coding old accent values that assumed the last step was skipped.
• CLI and picker parity: Preferences written from the command line now match those saved from the picker, including leaving body-border at Statamic’s default. This makes CLI provisioning safe for users who later open Preferences.

Gotchas and Tips

• Offline theme list: If statamic.com is unreachable — offline, firewalled, DNS failure, refused connection — the theme list should remain populated. If you are debugging an empty Themes panel, confirm you are on a release that includes this fix and check network/proxy behaviour.
• Clear validation errors: Invalid themes are refused rather than silently ignored. If a theme fails, check for missing gray-100/gray-950 shades and malformed hex values first.
• Quote theme names with spaces: editor-themes:apply "Tokyo Night" is safer than relying on shell word splitting. Theme ids remain the most stable choice for automation.
• No-email command scope: When no email is supplied, the commands now count at most two users instead of loading every user. For bulk operations, pass an explicit email or scope the command deliberately; do not assume “no email” means “all users”.
• Pro fallback on removal: editor-themes:remove is not just a delete. On Pro, it resolves to a role or site default. Check those defaults before using removal in support workflows.
• Contrast changes are intentional: Dracula, Everforest, and Gruvbox gray-500, plus Solarized and Tokyo Night gray-600, are darker in light mode. If you have custom CSS or screenshots pinned to previous values, expect small visual diffs.
• Debugging commands: Run php please list to confirm the editor-themes:* commands are registered, then test with a single known user before applying changes broadly.
• Extension point: Keep custom theme definitions in the package’s theme registry/config and validate them against the same rules the package enforces: complete grey ramp, six-digit hex, and contrast-safe accents.