For block theme developers, there is more to theme.json color settings than just look and feel. Yes they are partly for establishing the ~vibes~ but they also have consequences for theme development that extend beyond pure aesthetics. Here are a few key things to consider when you’re setting up your colors.
naming
Because the naming of your colors is in part communication between yourself, the user(s), and any developers who modify or extend your theme, it’s important to establish some norms and to be deliberate in the naming of your colors, gradients, and duotones.
One convention is to name, if not also label, the main colors in your palette “Primary”, “Secondary”, “Tertiary”, etc. It is also common to include a “White”, “Black”, and a “Gray”. Similarly gradients and duotones are often named in a way that makes it clear which colors are being used (and in the case of gradients, in what direction).
Take care not to collide with existing, default Gutenberg color settings slugs. For example there is already a “grayscale” duotone filter.
contrast
WCAG set a standard for contrast between text and background colors. Use this as a guide when building your palettes, and as you are establishing default styles and settings.
When possible, use per-block settings for colors to limit user choice and “validate” their color combinations to maintain adequate foreground/background contrast. Helpfully, the block editor will also warn users if they make selections for background and text colors that do not have sufficient contrast.
usage
While setting up a cover block based on a specification provided by a designer, I found that the mock-up included a 0 degree black to transparent gradient background. Text positioned at the bottom of the block would stay readable thanks to the additional contrast it provided. When I tried to recreate this design in the block editor, I couldn’t because I hadn’t added any gradients to our block theme.
Gradients in particular have a range of uses that are not purely aesthetic. They can and should be used to provide flair as a background for blocks, but they also have more functional applications like the one described above. Keep this in mind when selecting and naming gradients for your theme.
other considerations
For the most part you can reference your colors in the rest of your theme.json as CSS custom properties of the form --wp--preset--color--{slug}, but one area where this is not true (yet) is your duotone definitions. When setting the highlight and shadow colors for a duotone you must use a HEX or RGB value.
A higher level theming consideration is how color settings will cascade throughout your theme. While it is common practice to create a theme color palette and reference those values directly in the style settings for blocks and elements, adding an additional layer of abstraction through a three-tiered design token architecture affords you an opportunity to organize custom properties in a way that makes generating additional theme and block styles less of a hassle.