[6.x] Generate Tailwind utilities from the design tokens - #19494
Draft
brianjhanson wants to merge 9 commits into
Draft
[6.x] Generate Tailwind utilities from the design tokens#19494brianjhanson wants to merge 9 commits into
brianjhanson wants to merge 9 commits into
Conversation
📚 Storybook previews@craftcms/ui — open Storybook Changed components:
resources/js — open Storybook No changed components detected in this Storybook. |
brianjhanson
changed the title
Replaces the `@theme inline` mapping with prefixed `@utility` rules. Class names no longer repeat the token's role — the property implies it, so `--c-color-danger-fill-normal` is `c-bg-danger-normal` rather than `bg-danger-fill-normal`. Text takes both roles: `c-text-*` inks with the fill color, `c-text-on-*` with the color meant to stay legible on it. Tailwind's own `prefix()` applies to a whole build, and the CP writes plain Tailwind everywhere, so the prefix lives in the class names instead. That also means `tailwind.css` can no longer be imported into a layer — `@utility` is only valid at the top level of a stylesheet.
Puts an element in a color group with a class that matches the `c-` utility prefix, and an attribute that matches the class. The Craft 5 spellings (`.cp-color-*`, `[data-color]`) stay on the same rule, so existing markup and plugins keep working. `data-theme` was the obvious name but it's already the light/dark color-scheme attribute, which is a different axis entirely.
… shell Sets Tailwind's `prefix(cp)`, so Craft's token utilities and stock Tailwind land in one namespace — `cp:bg-loud` next to `cp:flex` — and anything unprefixed reads as a legacy class from the old SCSS bundle. The prefix is `cp` rather than `c` because `prefix(c)` renames Tailwind's own theme variables into `--c-*`, which is Craft's token namespace; eight of them (`--c-text-sm`, `--c-radius-sm`, `--c-font-mono`, …) would have landed on Craft tokens of the same name holding different values. The utilities move to a new `resources/css/utilities.css` entry — tokens, Tailwind, and Craft's utilities, with no preflight — which both shells now load. The legacy Twig shell renders its own document and never called `Cp::viteScripts()`, so it had neither the utilities nor the `--c-*` tokens its own compatibility aliases resolve against; `CpAsset` now pulls the entry in without re-resetting the page. `hidden` and `inline-flex` stay unprefixed: the legacy bundle defines both as bare rules that mean more than Tailwind's (an `!important`, and alignment plus a gap), so they are legacy classes that merely share a Tailwind name. The colorable class follows the CP's `.cp-*` convention as `.cp-palette-*`.
The gap utilities in _main.scss are the first to go now that both shells load the same utility stylesheet. The scales are named differently, so the mapping shifts by one step — legacy `--xs` aliases to `--c-spacing-sm`, not `-xs`. A name-for-name sweep would have quietly halved the spacing at every call site: gap-2xs -> cp:gap-xs gap-s -> cp:gap-md gap-l -> cp:gap-lg gap-xs -> cp:gap-sm gap-m -> cp:gap-lg gap-xl -> cp:gap-xl Verified in the built CSS that each replacement resolves to the same token the legacy alias did.
CP code only ever runs in the CP, where this is the only Tailwind there is, so there is no raw-Tailwind context to tell a Craft utility apart from — the prefix was ceremony at every call site for a distinction that never comes up. `bg-loud` now sits next to `flex`, `p-md` next to `p-4`. Tailwind's default theme keeps its own namespaces (`--spacing`, `--text-*`, `--radius-*`), which never overlapped Craft's `--c-*` tokens; `--color-*` is the one they share, and Craft's palette replaces Tailwind's there as it always has. Where the unlayered legacy bundle defines a name Tailwind also generates (`hidden`, `inline-flex`, `truncate`) the legacy rule still wins, which is the behaviour that predates this branch.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Republishes Craft's design tokens into the Tailwind namespaces that generate utility classes for them —
--color-*for the semantic colors,--spacing-*for the spacing scale.Colors
Each semantic color token gets a matching set of utility classes. The token name is the utility name — drop the
--c-color-prefix, and what's left is what you type:--c-color-neutral-border-quietborder-neutral-border-quiet,divide-…,ring-…--c-color-danger-fill-normalbg-danger-fill-normal--c-color-accent-on-loudtext-accent-on-loudThe generic tokens are mapped too, which is usually what you want inside a component:
bg-fill-quiet,border-border-normal, andtext-on-loudpaint with whatever the nearest[data-color]orvariantresolved to, rather than naming a color up front.Scope is deliberately narrow — the six semantic groups plus the generic set, 63 entries. The raw palette (
--c-color-red-*and friends) stays reachable from CSS and from[data-color], it just doesn't get utility classes.Spacing
The named steps on the spacing scale map into
--spacing-*, so they work everywhere a spacing utility does —p-sm,gap-md,mt-lg,-mx-xs,size-xl,space-y-2xl.--c-spacing-smp-sm,gap-sm,mx-sm, …--c-spacing-2xlp-2xl,mt-2xl, …--c-spacing-1pxp-1px,gap-1px, …The numeric scale is untouched —
p-4still resolves through Tailwind's own--spacingbase. That base is deliberately not mapped: in Tailwind v4 a bare--spacingis what generates the numeric utilities, so pointing it at--c-spacingwould rewrite every numeric spacing utility in the CP rather than adding to them.Generation
packages/craftcms-ui/tailwind.cssis now generated rather than hand-maintained, by a newscripts/generate-tailwind.jswired intobuild.jsandnpm run generate:colors. Colors come fromsrc/constants/colors.data.ts, the same sourcecolorable.cssalready used, so adding a semantic color there gives you its utilities for free. The sharedloadColorData()helper moved toscripts/utils.js.The mapping stays
@theme inline, so utilities reference the custom properties instead of snapshotting their values —[data-theme='dark']and[data-color]both keep working through them.Two corrections to the old hand-written file: it declared a whole
--color-brand-*block pointing at--c-color-brand-*variables that don't exist anywhere, and carriedborder-faint/border-subtle/border-default/border-strongaliases from the pre-rename vocabulary. Both are gone; the legacy aliases had no usages.Also fixes class names in the codebase that never had a matching variable and were rendering as nothing:
text-neutral-text-quiet→text-neutral-on-quiet(6 sites)border-neutral-quiet→border-neutral-border-quiettext-danger-text→text-danger-on-normal, matching what.error-listalready uses