studio-engine 0.114.1.rc1 → 0.114.2.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3cff8f80942f244b718fc77cc30b887f2b2e7ebc7442ed37f9654ef6868759e
-  data.tar.gz: 0773c555963a091e9dc6b0a7379d196a90b1bc2ea64e8aafde5200e99de14e45
+  metadata.gz: d8f4151d1230d0b856b6960e64b6cb4d1c95a6a84c7a699b564c1517cf79342b
+  data.tar.gz: 3b558ba4c1c1338ed7079de81b4ed014f8b2ca77f340b2c70916aaa86b1742ba
 SHA512:
-  metadata.gz: 1a3eb7cb288a08e0def13629d0ba7bf38c5bfd4a480497f8077cb0be549844b80ce215eee870eae180abdb95811cb01123bd32b33ff4894a6e20ace30df0dedb
-  data.tar.gz: 3fc4b9eef2fbf8239d990ae88fa30599f7a0d85543e8b9642f9702dcdaa3cd4a2ab6209a8d66442bf959ea75a614636fbbb5e1f75b3bae0eacb7cc7dcbe9e14d
+  metadata.gz: f5d15fd2275e519d42ba93342499ddb304a3383a7e8029f7aa611826b5d8e7a542924cba6f863f48db6ae8784f8b3c40706742c21a593c05a731239d15661b3a
+  data.tar.gz: 03eef31def9eb2e19ec1e7a7b3c18f5c0e36b85efcab9544674609533265c5e2caf580d12c26d6a09d5dd07bb91046ab597af6afe8f64a476a09005c4a9f2999

data/CHANGELOG.md

@@ -4,6 +4,83 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.114.2 — 2026-10-26
+
+### Changed
+
+- **The Tailwind layer is CSS-first; a host's whole adoption is `@import
+  "../builds/tailwind/studio_engine";`.** That entry now imports the new
+  `host.css` (`Studio::TailwindEntry` rewrites it right after
+  tailwindcss-rails' `Tailwindcss::Engines.bundle` writes it), which brings
+  `engine.css`, `@source` lines for every engine directory that emits a class
+  (views, components, helpers, `app/javascript` and `app/assets/javascripts`,
+  the vendored third-party bundles excluded by name) and `engine-motion.css`.
+  `engine.css` imports `theme.css` (the design tokens as `@theme inline
+  reference`, and the class-based `dark:` variant) and otherwise stays the
+  narrow component layer: its `@source "../../../components"` line moved to
+  `host.css`, so a build importing `engine.css` by path (the hub's client kit)
+  compiles only what it names. A host needs no `@config`, no
+  content glob over the gem found by a bundler call from Node, no safelist,
+  and no motion rake task. The recipe for a host still on `@config`:
+  README, "Tailwind". Hosts adopt on their own cards. A host that only bumps
+  the gem still builds, with no class lost, but its CSS grows by the motion
+  layer (about 44 KB unminified; McRitchie Industries, Cyvasse and Moms App
+  get it for the first time) and the classes the new `@source` lines find.
+- **Engine classes are spelled whole, so the scan finds them.** The modal
+  blocks' `icon_color:` and `color:` tones (`_card_header`, `_success_card`,
+  `_processing_card`) are literal maps rather than `bg-<%= tone %>/15`, which
+  compiled only in a host whose safelist or markup spelled the same name; an
+  unknown token now paints as primary. Their check icon's `success` and
+  `warning` tones use `text-success-ink` and `text-warning-ink`: the bare
+  `text-success` the old interpolation produced is deliberately uncompilable,
+  so the "green check" painted the inherited colour in every host. The style
+  page's button specimens are keyed by whole class. `admin_model_table`'s
+  `min_width:` is an inline `min-width` style instead of an arbitrary
+  `min-w-[Npx]` class. Visible: a table given any width but 940 (which a host
+  happened to compile) gets its minimum width for the first time, so on a phone
+  it scrolls sideways instead of squeezing.
+- **A host's build now carries five engine classes it could miss before**
+  (`ring-primary`, `ring-red-500`, `ring-2`, `opacity-30`, `!visible`), written
+  only in the engine's helpers and scripts, which no host scanned. Visible: a
+  rejected drag on the board shows its red ring, and in a host that defines
+  `theme-transition` (the hub) a theme switch now animates.
+
+### Deprecated
+
+- **`tailwind/studio.tailwind.config.js`** is a shim for one release, so a host
+  still on `@config` builds unchanged; `test/integration/tailwind_preset_parity_test.rb`
+  holds it to the same utilities as `theme.css`. It is removed once every host
+  has adopted. Until a host migrates it gets the motion layer twice (through
+  `host.css` and through its own generated `studio_engine_motion` import);
+  the duplicate is harmless, and step 3 of the recipe removes it.
+  **Removing the shim will break, at build time or at runtime, everything that
+  still reads it:** every host's `config/tailwind.config.js` (hub, Turf
+  Monster, McRitchie Industries, Cyvasse, Moms App and any newer app built from
+  the old `NEW_APP_SETUP.md`), the hub's production code
+  `app/services/client_apps/studio_kit/css.rb` (`ENGINE_CONFIG` and its own
+  `SAFELIST`, which build the client kit CSS at request time), and the tests
+  that read the preset's text (hub `test/views/status_colour_tokens_test.rb`,
+  Turf `test/views/error_text_contrast_test.rb`). Each moves to `theme.css` on
+  its host's adoption card first.
+
+### Tests
+
+- `test/support/engine_tailwind_build.rb` builds the engine the CSS-first way
+  (no `@config`), with `motion:`, `sources:` and `with_variant` for controls.
+- `tailwind_probe_build_test.rb`: the tokens compile from `@theme` (and the
+  bare `text-<role>` still does not), the motion layer arrives through
+  `host.css`, and dropping the views, components or JavaScript `@source`
+  line loses classes only that directory emits.
+- `component_tailwind_source_test.rb`: every class the five emitting
+  directories name, read independently of Tailwind's scanner, is in a
+  host-shaped build with no safelist; every emitting directory has an
+  `@source` line; exclusions name only vendored files.
+- `test/views/dynamic_tailwind_class_guard_test.rb` refuses a Tailwind class
+  assembled at render time.
+- `test/integration/tailwind_entry_test.rb` runs the real
+  `Tailwindcss::Engines.bundle` and reads the entry: `host.css`, and in the
+  control without the wrap, `engine.css`.
+
 ## 0.114.1 — 2026-10-25
 
 ## 0.114.0 — 2026-10-25

data/README.md

@@ -45,6 +45,91 @@ resolved.
 - **Booking**: a simple scheduler on Google Calendar appointment schedules, with or without the footer. With `config.booking_url`, `studio_booking_frame` embeds Google's booking page, `studio_booking_link` opens it in a popup, and `config.draw_booking_routes = true` draws `/schedule` (or name the app's own page with `config.booking_path`). `config.booking_crop` crops the frame to the slot picker at rest, from numbers `bin/booking-crop-measure` reads off the app's own schedule. See [`docs/BOOKING.md`](docs/BOOKING.md).
 - **Surveys**: define a survey in app code (`config/surveys/*.rb`, `Studio.define_survey`) with six question types — emoji scale, 1–5 rating, single and multiple choice, short and long text — and the engine serves it at `/surveys/:slug`: one question per screen, autosave, resume, keyboard shortcuts, and a no-JavaScript fallback. `config.on_survey_completed` and `config.survey_ref_resolver` let the app fire its own goals and attribute email arrivals. An admin panel at `/admin/surveys` breaks results down per question and exports CSV. Opt in with `config.draw_survey_routes = true` and `config.draw_admin_survey_routes = true`. See [`docs/SURVEYS.md`](docs/SURVEYS.md).
 
+## Tailwind
+
+The engine's Tailwind 4 layer is CSS-first. A host's whole adoption is two
+lines in `app/assets/tailwind/application.css`:
+
+```css
+@import "tailwindcss";
+@import "../builds/tailwind/studio_engine";
+```
+
+tailwindcss-rails writes `app/assets/builds/tailwind/studio_engine.css` from
+Ruby on every build and watch (`bin/rails tailwindcss:engines` by hand), as an
+absolute `@import` of the gem's `engine.css`. The engine then points that entry
+at `app/assets/tailwind/studio_engine/host.css` (`Studio::TailwindEntry` wraps
+the contract's `bundle`), and that one import brings everything a host used to
+wire by hand:
+
+| What | Where it lives | What it replaced |
+|------|----------------|------------------|
+| The design tokens (surfaces, inks, the primary ladder, brand palettes, `text-2xs`/`text-3xs`, Montserrat) and the class-based `dark:` variant | `theme.css`, `@theme inline reference` | `tailwind/studio.tailwind.config.js` and the host's `@config` |
+| The scan of every engine directory that emits a class (views, components, helpers, both JavaScript trees) | `host.css`, `@source` | the host's content glob over the gem's views, found with a bundler call from Node |
+| Every engine class, with no safelist | the scan above; no class is assembled at render time | the host's primary-colour safelist (about 240 classes) |
+| The motion, effect and leveling primitives (`.spinner`, `.hold-btn`, `.level-badge-*`, ...) | `engine-motion.css`, imported last by `host.css` | `lib/tasks/tailwindcss_engine_motion.rake` and its `studio_engine_motion` import |
+
+`test/integration/tailwind_probe_build_test.rb` and
+`test/integration/component_tailwind_source_test.rb` build the engine exactly as
+a host does and hold all four; `test/integration/tailwind_entry_test.rb` runs
+the real `Tailwindcss::Engines.bundle` and reads the entry it leaves.
+
+`engine.css` on its own stays the narrow layer: the theme and the component
+`@utility` definitions, with no `@source` and no motion. A build that imports it
+by path, such as the hub's client kit (`ClientApps::StudioKit::Css`, held to
+100 KB), compiles only the classes it names.
+
+### Migrating a host from `@config`
+
+Hosts adopt on their own cards (hub, Turf Monster, Rolio, chain-ops, Rantly,
+McRitchie Industries, Cyvasse, Moms App). Until each one does, it keeps
+building unchanged: `tailwind/studio.tailwind.config.js` stays one release as a
+deprecated shim, and `test/integration/tailwind_preset_parity_test.rb` holds it
+to the same utilities as `theme.css`. A host that has bumped the gem but not
+yet migrated gets the motion layer twice (once through `host.css`, once
+through its own generated import). The duplicate is harmless and goes with
+step 3.
+
+1. **Bump** `studio-engine` to the release that carries this section.
+2. **`application.css`**: delete the `@config` line. Keep `@import
+   "tailwindcss";` and `@import "../builds/tailwind/studio_engine";` first.
+3. **Motion**: delete `@import "../builds/tailwind/studio_engine_motion";`,
+   `lib/tasks/tailwindcss_engine_motion.rake` and the generated
+   `app/assets/builds/tailwind/studio_engine_motion.css`.
+4. **`config/tailwind.config.js`**: delete it, moving only what is the host's
+   own into `application.css`:
+   - **`content:`** goes. Tailwind 4 detects the app's own sources from the
+     project root and skips what `.gitignore` names; the engine scans itself.
+     If CI or Heroku installs gems into `vendor/bundle` inside the app, exclude
+     only their Markdown: `@source not "../../../vendor/bundle/**/*.md";`.
+     Never exclude the whole directory: the gem lives under it there, and the
+     hub's build once lost every engine class that way. A file the default scan
+     misses (say `config/initializers/studio.rb` carrying navbar word classes)
+     takes its own `@source` line.
+   - **`safelist`** goes. The engine's own classes no longer need it. If a host
+     class is genuinely data-driven, spell its variants whole in source; as a
+     last resort, `@source inline()` takes brace expansion. The hub's whole
+     safelist is
+     `@source inline("{bg,text,border}-primary{,-{50,{100..900..100}}}{,/{5,10,20,30,40,50}}");`
+     (231 classes).
+   - **`theme` extensions** become `@theme inline { ... }` after the engine
+     import: a screen is `--breakpoint-pill-narrow: 530px;`, a palette is
+     `--color-warning-500: #FF7C47;`, and a text-only colour is
+     `--text-color-violet-ink: var(--color-violet-ink);` (the same name
+     overrides the engine's, as Turf's `text-primary` does with
+     `--text-color-primary: rgb(var(--color-primary-ink-rgb));`).
+   - **`darkMode: 'class'`** goes; `theme.css` declares it.
+5. **Verify** with `bin/rails tailwindcss:build`, then compare the class set of
+   `app/assets/builds/tailwind.css` before and after. It may only grow (the
+   engine now also scans its helpers and scripts). Spot-check one class from
+   each column above: `.text-heading`, `.btn-primary`, `.spinner`.
+
+When every host has adopted, the shim and the parity test are deleted in one
+engine change. Before that, every reader of the preset has to move, not only
+the build: the hub's `app/services/client_apps/studio_kit/css.rb` reads it at
+runtime to build the client kit CSS, and a few host tests read its text
+(CHANGELOG, Deprecated).
+
 ## Configuration
 
 Each consuming app configures the engine in `config/initializers/studio.rb`:
@@ -503,8 +588,8 @@ Two things that will bite you:
   tick *after* the stack empties, so a bare `.id` throws on every close.
 
 The scoped host takes its animations from `engine-motion.css` rather than an
-inline copy, so a consumer bundling that layer gets the same spring as the shared
-host.
+inline copy, so every host (the layer rides the engine's one Tailwind import)
+gets the same spring as the shared host.
 
 It carries the store API below with three deliberate differences: there is no
 `advance()`; `swap()` replaces the top entry immediately rather than running the
@@ -971,14 +1056,12 @@ config.navbar_z_tier = true      # the live header at z-[var(--z-nav)], not z-50
   truncating span with the host's class and nothing else. `navbar_wordmark`
   wins when both are set. Rules: `lib/studio/navbar_brand.rb`.
 - **The word classes live in the host's initializer**
-  (`config/initializers/studio.rb`), which a host's Tailwind scan does not
-  read by default (Turf Monster's `content:` lists `app/views`,
-  `app/helpers`, `app/javascript` and the engine's views). A utility named
-  only there, `text-heading` say, compiles only if some view also uses it.
-  Add the initializer to the scan (`content:`, or `@source` under Tailwind 4),
-  or give the word a class the host's CSS defines (`tm-wordmark`). The same
-  rule as the engine's views glob:
-  [NEW_APP_SETUP.md, section 14](docs/NEW_APP_SETUP.md#14-css-component-classes).
+  (`config/initializers/studio.rb`), which a host's Tailwind scan may not
+  read (a host still on `@config` lists only its `content:` globs). A utility
+  named only there, `text-heading` say, compiles only if some view also uses
+  it. Add the initializer to the scan (`@source "../../../config/initializers/studio.rb";`),
+  or give the word a class the host's CSS defines (`tm-wordmark`). See
+  [Tailwind](#tailwind).
 - `navbar_root_hook` and `navbar_z_tier` are booleans, `false` by default.
 
 ### The account row

data/app/assets/tailwind/studio_engine/engine-motion.css

@@ -36,30 +36,19 @@
     .seeds-bar-continuous 5-segment lockstep progress fill    (ported, TM)
 
   ─────────────────────────────────────────────────────────────────────────────
-  OPT-IN — this layer does NOT auto-bundle.
-
-  tailwindcss-rails' `tailwindcss:engines` task (Tailwindcss::Engines.bundle)
-  generates a `builds/tailwind/<engine>.css` entry ONLY for the file named
-  exactly `engine.css`. This file is `engine-motion.css`, so that matcher skips
-  it BY CONSTRUCTION — it never rides the auto-generated `studio_engine.css`
-  entry that `engine.css` uses, and consumers must adopt it deliberately.
-
-  Adopt with ONE line in the consuming app's app/assets/tailwind/application.css,
-  AFTER `@import "tailwindcss";` (and after your `../builds/tailwind/studio_engine`
-  import so the theme role vars are in scope):
-
-      @import "STUDIO_ENGINE_PATH/app/assets/tailwind/studio_engine/engine-motion.css";
-
-  Resolve STUDIO_ENGINE_PATH the same way config/tailwind.config.js already
-  resolves the shared preset — `bundle show studio-engine`. A one-time helper the
-  app-side de-fork task can wire (mirrors the engines contract):
-
-      # config/tailwind.config.js already computes this:
-      #   const studioPath = execSync('bundle show studio-engine').toString().trim()
-      # emit an absolute @import into your app CSS (or a tiny generated entry).
-
-  App-side wiring + removing the forked local copies lands in the follow-up
-  adoption task; until then the MS/TM local copies stay canonical.
+  HOW IT REACHES A HOST — through host.css, which imports this file last.
+
+  A host's one line, `@import "../builds/tailwind/studio_engine";`, resolves to
+  host.css (Studio::TailwindEntry) and so brings this layer with the rest of
+  the engine. engine.css itself does not import it. It used to be OPT-IN: tailwindcss-rails'
+  engines contract (Tailwindcss::Engines.bundle) writes a builds entry only for
+  the file named exactly `engine.css`, so each host carried a rake task
+  (lib/tasks/tailwindcss_engine_motion.rake) that generated a second entry,
+  `builds/tailwind/studio_engine_motion.css`, plus a matching @import. Both are
+  retired: a host deletes the task and the import (README, "Tailwind"). A host
+  that keeps them for a release gets this layer twice, which is harmless —
+  every rule below is a plain class, keyframe or @property, so the duplicate
+  resolves to the same values.
 
   ─────────────────────────────────────────────────────────────────────────────
   DESIGN RULES

data/app/assets/tailwind/studio_engine/engine.css

@@ -11,12 +11,17 @@
   (or manually: `bin/rails tailwindcss:engines`) because this file lives at the
   Rails-engines contract path: app/assets/tailwind/<engine_name>/engine.css.
 
+  That line resolves to host.css, not to this file: studio-engine writes the
+  builds entry itself (Studio::TailwindEntry) so it can carry, beside this
+  component layer, the @source scan of the engine's own markup and the motion
+  layer. See host.css. This file stays the NARROW layer: the theme (theme.css,
+  imported below, emits nothing on its own) and the component @utility
+  definitions, with no sources and no motion, so a build that imports it by
+  path (the hub's client kit) compiles only the classes it names.
+
   Requirements:
   - Tailwind v4 (this file uses @utility, so classes sort/override correctly
     in the utilities layer and take variants like `md:card`).
-  - The consumer's tailwind config spreads the engine preset
-    (tailwind/studio.tailwind.config.js) — it defines the surface / heading /
-    subtle / primary token utilities @apply'd below.
 
   Colors resolve through the 7-role theme CSS custom properties (--color-cta,
   --color-surface, ...) emitted by studio_theme_css_tag, so themed apps restyle
@@ -28,13 +33,7 @@
   their local copies for this import.
 */
 
-/* -- Components: in every host's class scan --------------------------------
-   The engine's ViewComponent classes (app/components) carry their colour
-   classes in Ruby, and a host's Tailwind config scans only the engine's
-   app/views. This adds app/components to the scan of every host that imports
-   this file, with no host edit. The path is relative to this file.
-   test/integration/component_tailwind_source_test.rb proves it compiles. */
-@source "../../../components";
+@import "./theme.css";
 
 /* -- Layer scale ------------------------------------------------------------
    The ONE stacking order every Studio app shares. Read the ORDER, not the

data/app/assets/tailwind/studio_engine/host.css

@@ -0,0 +1,56 @@
+/*
+  studio-engine HOST ENTRY — what a host's one Tailwind line resolves to.
+
+      @import "tailwindcss";
+      @import "../builds/tailwind/studio_engine";
+
+  tailwindcss-rails' engines contract (Tailwindcss::Engines.bundle) writes
+  app/assets/builds/tailwind/studio_engine.css as an @import of the gem's
+  engine.css. Studio::TailwindEntry (lib/studio/tailwind_entry.rb) rewrites
+  that entry, right after the bundle runs, to import THIS file instead, so a
+  host gets, from the same line and with nothing of its own:
+
+    - engine.css: the theme (theme.css, the tokens that replaced the JS
+      preset and the host's `@config`) and the component @utility layer;
+    - the @source scan below, so no host lists the gem in a content glob or
+      safelists its classes;
+    - engine-motion.css, the motion / effect / leveling layer, which used to
+      need a per-host rake task (lib/tasks/tailwindcss_engine_motion.rake).
+
+  The path is resolved by Ruby from the gem's root, so Node never runs bundler
+  to find the gem. engine.css stays importable on its own as the narrow layer.
+  Recipe: README, "Tailwind".
+*/
+@import "./engine.css";
+
+/* -- Sources: every engine directory that emits a class --------------------
+   Tailwind v4 compiles only the classes it SEES, so every directory whose
+   files put a utility class on the page is scanned here, relative to this
+   file, in every host that imports it, with no host edit: views and
+   partials, the ViewComponents (their colour classes live in Ruby), the
+   helpers that build markup (admin_model_table), and both JavaScript trees
+   (classes added at runtime).
+
+   The exclusions are NARROW on purpose: the vendored, minified third-party
+   bundles (Stimulus, Alpine, Leaflet, Sortable, canvas-confetti) are not
+   engine markup, and scanning them mints junk utilities from their
+   identifiers. Never exclude a whole directory: the hub's
+   `@source not "../../../vendor/bundle"` once dropped every one of these
+   lines in CI, because the gem itself lives under vendor/bundle there.
+
+   test/integration/component_tailwind_source_test.rb proves every class these
+   directories emit compiles, and that dropping any one line turns it red. A
+   class built by interpolation (`bg-<%= tone %>`) is invisible to the scan;
+   test/views/dynamic_tailwind_class_guard_test.rb refuses one. */
+@source "../../../views";
+@source "../../../components";
+@source "../../../helpers";
+@source "../../../javascript";
+@source not "../../../javascript/studio/vendor";
+@source "../../javascripts";
+@source not "../../javascripts/studio/{alpine,canvas_confetti,leaflet,sortable}.js";
+
+/* -- Motion / effect / leveling layer ---------------------------------------
+   Last, so the theme and component layer it reads are in scope, as when hosts
+   imported it after engine.css themselves. */
+@import "./engine-motion.css";

data/app/assets/tailwind/studio_engine/theme.css

@@ -0,0 +1,139 @@
+/*
+  studio-engine THEME — the shared Tailwind v4 design tokens, CSS-first.
+
+  This file replaced tailwind/studio.tailwind.config.js (the JS preset every
+  consumer spread through `@config`, after shelling out to bundler from Node to
+  find the gem). engine.css imports it (and host.css imports engine.css), so a
+  consumer gets these tokens from the same one line that brings the component
+  layer:
+
+      @import "tailwindcss";
+      @import "../builds/tailwind/studio_engine";
+
+  No `@config`, no bundler call from Node, no generated motion entry.
+
+  WHY `@theme inline`. Every runtime token here (surface, heading, the primary
+  ladder, the status inks) is a CSS custom property that studio_theme_css_tag
+  writes per app and per theme. A plain `@theme` would ALSO declare
+  `--color-surface: var(--color-surface)` on :root — a self-reference, which is
+  invalid — and would put Tailwind's copy in a cascade race with the theme tag.
+  `inline` makes each utility carry the value itself (`bg-surface` compiles to
+  `background-color: var(--color-surface)`, exactly what the JS preset
+  compiled to) and declares nothing on :root.
+
+  WHY THE PER-UTILITY NAMESPACES. The status roles are deliberately NOT plain
+  colours. A bare role colour as text (text-danger, text-warning, text-success)
+  fails WCAG AA on one theme or the other, so it must stay uncompilable; the
+  text inks (*-ink, derived per theme by ThemeResolver#contrast_ink) are the
+  text spelling. Tailwind v4 reads `--text-color-*`, `--background-color-*` and
+  `--border-color-*` for ONLY that utility family, so registering a fill there
+  cannot mint the text utility, the same split the preset's textColor /
+  backgroundColor / borderColor keys made.
+*/
+
+/* darkMode: 'class' — the theme tag toggles .dark on <html>. */
+@custom-variant dark (&:is(.dark *));
+
+@theme inline reference {
+  /* fontFamily — REPLACED, not extended (the preset set theme.fontFamily). */
+  --font-*: initial;
+  --font-sans: Montserrat, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, monospace;
+
+  /* Sub-xs type scale for dense UI (badges, meta rows, tick labels). Bare
+     sizes, no line-height, so text-2xs / text-3xs are drop-in replacements for
+     the text-[11px] / text-[10px] arbitrary values. */
+  --text-2xs: 0.6875rem; /* 11px */
+  --text-3xs: 0.625rem;  /* 10px */
+
+  /* Theme-aware semantic surfaces (studio_theme_css_tag). */
+  --color-page: var(--color-page);
+  --color-surface: var(--color-surface);
+  --color-surface-alt: var(--color-surface-alt);
+  --color-inset: var(--color-inset);
+
+  /* The dynamic primary palette, from the theme's primary role. The -rgb
+     triples are space lists, so `rgb(var(--x-rgb))` is valid and Tailwind's
+     opacity modifier (bg-primary/20) mixes it. */
+  --color-primary: rgb(var(--color-primary-rgb));
+  --color-primary-50: rgb(var(--color-primary-50-rgb));
+  --color-primary-100: rgb(var(--color-primary-100-rgb));
+  --color-primary-200: rgb(var(--color-primary-200-rgb));
+  --color-primary-300: rgb(var(--color-primary-300-rgb));
+  --color-primary-400: rgb(var(--color-primary-400-rgb));
+  --color-primary-500: rgb(var(--color-primary-500-rgb));
+  --color-primary-600: rgb(var(--color-primary-600-rgb));
+  --color-primary-700: rgb(var(--color-primary-700-rgb));
+  --color-primary-800: rgb(var(--color-primary-800-rgb));
+  --color-primary-900: rgb(var(--color-primary-900-rgb));
+
+  /* Brand palettes. */
+  --color-mint: #06D6A0;
+  --color-mint-50: #e6faf4;
+  --color-mint-100: #b3f0de;
+  --color-mint-200: #80e6c8;
+  --color-mint-300: #4ddcb2;
+  --color-mint-400: #1ad29c;
+  --color-mint-500: #06D6A0;
+  --color-mint-600: #05b888;
+  --color-mint-700: #049a70;
+  --color-mint-800: #037c58;
+  --color-mint-900: #025e40;
+
+  --color-navy: #1A1535;
+  --color-navy-50: #e8e7ed;
+  --color-navy-100: #b8b5c8;
+  --color-navy-200: #8883a3;
+  --color-navy-300: #58517e;
+  --color-navy-400: #3a3359;
+  --color-navy-500: #1A1535;
+  --color-navy-600: #16122e;
+  --color-navy-700: #120f27;
+  --color-navy-800: #0e0c20;
+  --color-navy-900: #0a0919;
+
+  --color-violet: #8E82FE;
+  --color-violet-50: #f0eeff;
+  --color-violet-100: #EAE8FF;
+  --color-violet-200: #b2aafe;
+  --color-violet-300: #C5C0FE;
+  --color-violet-400: #8E82FE;
+  --color-violet-500: #8E82FE;
+  --color-violet-600: #6558e5;
+  --color-violet-700: #6558E0;
+  --color-violet-800: #3b2cb3;
+  --color-violet-900: #3D2FB5;
+
+  --color-mist: #F7F6FF;
+  --color-lavender: #E8E6F0;
+  --color-slate: #6B6580;
+  --color-charcoal: #2D2648;
+  --color-midnight: #120F28;
+  --color-ember: #FF8C69;
+  --color-gold: #FFD166;
+  --color-magenta: #F72585;
+
+  /* Text-only tokens. */
+  --text-color-heading: var(--color-text);
+  --text-color-body: var(--color-text-body);
+  --text-color-secondary: var(--color-text-secondary);
+  --text-color-muted: var(--color-text-muted);
+  /* The status roles as TEXT, held to AA on every surface. There is
+     deliberately NO text-danger, text-warning or text-success. */
+  --text-color-danger-ink: var(--color-danger-ink);
+  --text-color-warning-ink: var(--color-warning-ink);
+  --text-color-success-ink: var(--color-success-ink);
+  /* The primary role as chip text; text-primary stays the brand colour. */
+  --text-color-primary-ink: var(--color-primary-ink);
+
+  /* The status-role FILLS, for backgrounds and borders ONLY. */
+  --background-color-success: var(--color-success);
+  --background-color-warning: var(--color-warning);
+  --background-color-danger: var(--color-danger);
+
+  --border-color-subtle: var(--color-border);
+  --border-color-strong: var(--color-border-strong);
+  --border-color-success: var(--color-success);
+  --border-color-warning: var(--color-warning);
+  --border-color-danger: var(--color-danger);
+}

data/app/helpers/studio/admin_models_table_helper.rb

@@ -12,6 +12,11 @@ module Studio
   #     <td class="px-4 py-3"><%= time_ago_in_words(user.created_at) %> ago</td>
   #   <% end %>
   #
+  # min_width is an inline style, not an arbitrary min-width class: Tailwind compiles
+  # only class names it can read in source, and a width interpolated at render
+  # time is never in source, so the class painted only in a host whose own
+  # markup happened to spell the same width.
+  #
   # The block yields each record and returns that row's <td> cells. Output matches
   # the long-standing markup (id="models-<key>-table", overflow wrapper, hover
   # rows, colspan empty state) so existing view assertions keep passing.
@@ -34,7 +39,7 @@ module Studio
       table = content_tag(:table,
         content_tag(:thead, header_row, class: "bg-surface-alt text-muted text-xs uppercase tracking-wide") +
           content_tag(:tbody, body, class: "divide-y divide-subtle"),
-        id: "models-#{key}-table", class: "w-full min-w-[#{min_width}px] text-sm")
+        id: "models-#{key}-table", class: "w-full text-sm", style: "min-width: #{min_width.to_i}px")
 
       content_tag(:div, table, class: "overflow-x-auto")
     end

data/app/views/studio/modals/_scoped_host.html.erb

@@ -30,8 +30,8 @@
   Animations come from the shared motion layer
   (app/assets/tailwind/studio_engine/engine-motion.css) — the .modal-card-* and
   .modal-backdrop-* classes — rather than an inline copy, so this stays small.
-  A consumer that does not bundle engine-motion.css still gets a working modal,
-  just without the spring.
+  every host's engine import brings that layer (host.css); a page built without it
+  still gets a working modal, just without the spring.
 
   Locals:
     store      — REQUIRED. Alpine store name, e.g. "emailModals". Must be unique

data/app/views/studio/modals/blocks/_card_header.html.erb

@@ -34,6 +34,20 @@
 %>
 <%
   icon_color = local_assigns[:icon_color] || 'primary'
+  # Each tone is spelled out WHOLE, never assembled from "bg-" + icon_color:
+  # Tailwind compiles only the class names it can read in this file, so an
+  # assembled one painted only in a host that happened to use or safelist it.
+  # The text half is the AA ink, not the bare role colour, which the theme
+  # leaves uncompilable on purpose (theme.css). An unknown token paints as
+  # primary. test/views/dynamic_tailwind_class_guard_test.rb refuses a
+  # rebuilt interpolation.
+  icon_tones = {
+    'primary' => { pill: 'bg-primary/15', ink: 'text-primary' },
+    'success' => { pill: 'bg-success/15', ink: 'text-success-ink' },
+    'warning' => { pill: 'bg-warning/15', ink: 'text-warning-ink' },
+    'mint'    => { pill: 'bg-mint/15',    ink: 'text-mint' }
+  }
+  icon_tone  = icon_tones.fetch(icon_color.to_s) { icon_tones['primary'] }
   size       = local_assigns[:size] || :md
   pill_class = size == :lg ? 'w-14 h-14' : 'w-12 h-12'
   svg_class  = size == :lg ? 'w-7 h-7'   : 'w-6 h-6'
@@ -56,8 +70,8 @@
       </svg>
     </div>
   <% elsif local_assigns[:icon] == :external_tab %>
-    <div class="mx-auto <%= pill_class %> rounded-full bg-<%= icon_color %>/15 flex items-center justify-center mb-4">
-      <svg class="<%= svg_class %> text-<%= icon_color %>" fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24">
+    <div class="mx-auto <%= pill_class %> rounded-full <%= icon_tone[:pill] %> flex items-center justify-center mb-4">
+      <svg class="<%= svg_class %> <%= icon_tone[:ink] %>" fill="none" stroke="currentColor" stroke-width="2.5" viewBox="0 0 24 24">
         <path stroke-linecap="round" stroke-linejoin="round" d="M4.5 19.5l15-15m0 0H8.25m11.25 0v11.25"/>
       </svg>
     </div>
@@ -66,8 +80,8 @@
   <% elsif local_assigns[:icon_emoji] %>
     <div class="text-5xl mb-4 leading-none"><%= icon_emoji %></div>
   <% else %>
-    <div class="mx-auto <%= pill_class %> rounded-full bg-<%= icon_color %>/15 flex items-center justify-center mb-4">
-      <svg class="<%= svg_class %> text-<%= icon_color %>" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
+    <div class="mx-auto <%= pill_class %> rounded-full <%= icon_tone[:pill] %> flex items-center justify-center mb-4">
+      <svg class="<%= svg_class %> <%= icon_tone[:ink] %>" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
         <path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/>
       </svg>
     </div>

data/app/views/studio/modals/blocks/_processing_card.html.erb

@@ -37,6 +37,16 @@
     'lg' => 'w-16 h-16 border-4'
   }
   spinner_class = sizes[size] || sizes['md']
+  # Each tone is spelled out WHOLE, never assembled from "border-" + color:
+  # Tailwind compiles only the class names it can read in this file. An
+  # unknown token spins in primary.
+  # test/views/dynamic_tailwind_class_guard_test.rb refuses a rebuilt one.
+  tones = {
+    'primary' => 'border-primary/30 border-t-primary',
+    'success' => 'border-success/30 border-t-success',
+    'warning' => 'border-warning/30 border-t-warning'
+  }
+  tone_class = tones.fetch(color.to_s) { tones['primary'] }
   # min_duration mirrors StudioModals.MIN_LOAD_MS (the JS default) so the Ruby and
   # JS sides of the convention agree on the same floor.
   min_duration = local_assigns[:min_duration] || 1400
@@ -62,7 +72,7 @@
     end
 %>
 <div class="text-center py-6"<%= resolve_attrs %>>
-  <div class="mx-auto <%= spinner_class %> rounded-full border-<%= color %>/30 border-t-<%= color %> animate-spin mb-5"></div>
+  <div class="mx-auto <%= spinner_class %> rounded-full <%= tone_class %> animate-spin mb-5"></div>
   <% if local_assigns[:title_key] %>
     <p class="text-base font-bold text-heading mb-1" x-text="<%= title_key %>"></p>
   <% elsif local_assigns[:title] %>

data/app/views/studio/modals/blocks/_success_card.html.erb

@@ -80,6 +80,20 @@
 %>
 <%
   icon_color    = local_assigns[:icon_color] || 'primary'
+  # Each tone is spelled out WHOLE, never assembled from "bg-" + icon_color:
+  # Tailwind compiles only the class names it can read in this file, so an
+  # assembled one painted only in a host that happened to use or safelist it.
+  # The text half is the AA ink, not the bare role colour, which the theme
+  # leaves uncompilable on purpose (theme.css). An unknown token paints as
+  # primary. test/views/dynamic_tailwind_class_guard_test.rb refuses a
+  # rebuilt interpolation.
+  icon_tones = {
+    'primary' => { pill: 'bg-primary/15', ink: 'text-primary' },
+    'success' => { pill: 'bg-success/15', ink: 'text-success-ink' },
+    'warning' => { pill: 'bg-warning/15', ink: 'text-warning-ink' },
+    'mint'    => { pill: 'bg-mint/15',    ink: 'text-mint' }
+  }
+  icon_tone  = icon_tones.fetch(icon_color.to_s) { icon_tones['primary'] }
   redirect_secs = local_assigns[:auto_redirect_seconds] || 5
   has_redirect  = !!local_assigns[:auto_redirect_url_key]
   fire_confetti = !!local_assigns[:confetti]
@@ -182,8 +196,8 @@
   <% if local_assigns[:icon_emoji] %>
     <div class="text-5xl mb-4 leading-none"><%= icon_emoji %></div>
   <% else %>
-    <div class="mx-auto w-14 h-14 rounded-full bg-<%= icon_color %>/15 flex items-center justify-center mb-4">
-      <svg class="w-7 h-7 text-<%= icon_color %>" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
+    <div class="mx-auto w-14 h-14 rounded-full <%= icon_tone[:pill] %> flex items-center justify-center mb-4">
+      <svg class="w-7 h-7 <%= icon_tone[:ink] %>" fill="none" stroke="currentColor" stroke-width="3" viewBox="0 0 24 24">
         <path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7"/>
       </svg>
     </div>

data/app/views/style/_modals.html.erb

@@ -28,8 +28,8 @@
      Free Entry Earned reward, gated by :leveling).
 
      The modal motion (modal-card-* / modal-backdrop-* keyframes + studio-modal-
-     drain + body.modal-open) ships in engine-motion.css, so a consumer that
-     bundles it animates these for real. %>
+     drain + body.modal-open) ships in engine-motion.css, which every host's
+     engine import brings (host.css), so every consumer animates these for real. %>
 <%
   web3_on     = Studio.feature?(:web3)
   leveling_on = Studio.feature?(:leveling)

data/app/views/style/_tricks.html.erb

@@ -4,7 +4,8 @@
      rendered primitive, its class name (one-click copy), and a copyable usage
      snippet. Every class here is a REAL engine class (engine.css component layer
      or engine-motion.css motion/effect/leveling layer), so a consumer that
-     bundles both styles the specimens for real.
+     imports the engine's Tailwind entry (host.css brings both) styles the
+     specimens for real.
 
      The Leveling group renders the REAL .level-badge tiers ported into the engine
      from Turf Monster, capability-gated by Studio.feature?(:leveling). When a host
@@ -15,15 +16,17 @@
      The color tokens/swatches now live in the Theme section (the landing section
      owns "the colors"); this section is the trick board. %>
 <%
+  # Keyed by the WHOLE class, never "btn-" + a name: Tailwind compiles only the
+  # @utility names it can read in source.
   button_variants = {
-    "primary"   => "Primary",
-    "secondary" => "Secondary",
-    "success"   => "Success",
-    "danger"    => "Danger",
-    "warning"   => "Warning",
-    "neutral"   => "Neutral",
-    "outline"   => "Outline",
-    "google"    => "Continue with Google"
+    "btn-primary"   => "Primary",
+    "btn-secondary" => "Secondary",
+    "btn-success"   => "Success",
+    "btn-danger"    => "Danger",
+    "btn-warning"   => "Warning",
+    "btn-neutral"   => "Neutral",
+    "btn-outline"   => "Outline",
+    "btn-google"    => "Continue with Google"
   }
 
   leveling_on = Studio.feature?(:leveling)
@@ -51,9 +54,9 @@
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
       <% button_variants.each do |name, label| %>
         <%= render layout: "style/specimen",
-              locals: { klass: ".btn .btn-#{name}",
-                        usage: %(<button class="btn btn-#{name}">#{label}</button>) } do %>
-          <button type="button" class="btn btn-<%= name %>"><%= label %></button>
+              locals: { klass: ".btn .#{name}",
+                        usage: %(<button class="btn #{name}">#{label}</button>) } do %>
+          <button type="button" class="btn <%= name %>"><%= label %></button>
         <% end %>
       <% end %>
 

data/app/views/style/index.html.erb

@@ -21,8 +21,9 @@
      app/views/style/_host.html.erb.
 
      Specimens use ONLY the engine's own classes (engine.css component layer plus
-     engine-motion.css motion/effect/leveling layer), so a consumer that bundles
-     engine.css and imports engine-motion.css styles them for real. The primitive
+     engine-motion.css motion/effect/leveling layer), so a consumer that imports
+     the engine's Tailwind entry (host.css: engine.css and engine-motion.css)
+     styles them for real. The primitive
      CSS is NOT inlined here - the consumer's Tailwind build provides it. Page
      chrome uses the engine's own .card / .label-upper / theme tokens. %>
 <%

data/lib/studio/engine.rb

@@ -330,6 +330,13 @@ module Studio
     # Studio.survey_definitions_path, loaded on boot and again on each
     # development reload so an edited definition takes effect without a restart.
     # Surveys defined in an initializer instead stay registered either way.
+    # The host's Tailwind entry for this engine imports host.css, not the bare
+    # engine.css (Studio::TailwindEntry says why). Rake's tailwindcss:engines
+    # runs after :environment, so every initializer has run by then.
+    initializer "studio.tailwind_entry", after: :load_config_initializers do
+      Studio::TailwindEntry.install!
+    end
+
     config.to_prepare do
       dir = Studio.survey_definitions_path
       Studio::Survey.load_definitions!(Rails.root.join(dir)) if dir.present? && Rails.root

data/lib/studio/tailwind_entry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Studio
+  # Points a host's Tailwind entry for this engine at host.css.
+  #
+  # tailwindcss-rails' engines contract (Tailwindcss::Engines.bundle, run by
+  # `tailwindcss:engines`, a prerequisite of tailwindcss:build, :watch and so
+  # of assets:precompile) writes app/assets/builds/tailwind/studio_engine.css as
+  # an @import of the gem's app/assets/tailwind/studio_engine/engine.css. That
+  # file has to stay the NARROW component layer, because a build may import it
+  # by path and want only the classes it names (the hub's client kit, held to a
+  # 100 KB budget). So right after the bundle runs, this rewrites the entry to
+  # import host.css instead: engine.css plus the engine's @source scan and the
+  # motion layer. A host's `@import "../builds/tailwind/studio_engine";` then
+  # brings all three, with no `@config`, no safelist and no rake task of its
+  # own, and the gem's path is resolved here in Ruby, never by Node running
+  # bundler.
+  #
+  # Prepended rather than added as a rake action: a second action on
+  # `tailwindcss:engines` runs in task-load order, and one that ran BEFORE the
+  # bundle would be deleted by it (the bundle removes and rewrites the file).
+  # super-then-write is ordered by construction.
+  module TailwindEntry
+    HOST_CSS = "app/assets/tailwind/studio_engine/host.css"
+    ENTRY    = "app/assets/builds/tailwind/studio_engine.css"
+
+    module_function
+
+    def entry_path(app_root) = Pathname(app_root).join(ENTRY)
+
+    def contents(engine_root)
+      <<~CSS
+        /* DO NOT MODIFY THIS FILE, it was auto-generated by studio-engine (Studio::TailwindEntry) */
+
+        @import "#{Pathname(engine_root).join(HOST_CSS)}";
+      CSS
+    end
+
+    # Writes the entry. Only when the bundle wrote one: an app whose engines
+    # contract found no engine.css gets nothing it did not ask for.
+    def write!(app_root:, engine_root:)
+      path = entry_path(app_root)
+      return false unless path.file?
+
+      File.write(path, contents(engine_root))
+      true
+    end
+
+    # Wraps Tailwindcss::Engines.bundle.
+    module Bundle
+      def bundle(...)
+        result = super
+        Studio::TailwindEntry.write!(app_root: Rails.root, engine_root: Studio::Engine.root)
+        result
+      end
+    end
+
+    # Idempotent. A host without tailwindcss-rails' engines contract is left
+    # alone: it never had the entry this rewrites.
+    def install!
+      require "tailwindcss/engines"
+      singleton = ::Tailwindcss::Engines.singleton_class
+      singleton.prepend(Bundle) unless singleton.ancestors.include?(Bundle)
+      true
+    rescue LoadError
+      false
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.114.1.rc1"
+  VERSION = "0.114.2.rc1"
 end

data/lib/studio.rb

@@ -21,6 +21,7 @@ require "studio/geo"
 require "studio/geo/lookup"
 require "studio/link_preview"
 require "studio/engine"
+require "studio/tailwind_entry"
 require "studio/color_scale"
 require "studio/environment_banner"
 require "studio/theme_resolver"

data/tailwind/studio.tailwind.config.js

@@ -1,3 +1,17 @@
+// DEPRECATED — kept for ONE release so consumers can adopt on their own cards.
+//
+// The engine's Tailwind layer is CSS-first: the tokens below now live in
+// app/assets/tailwind/studio_engine/theme.css (@theme), and every host gets
+// them, the engine's @source scan and the motion layer from its one
+// `@import "../builds/tailwind/studio_engine";` line. Nothing in the engine
+// reads this file any more. A host still on `@config` + this preset builds
+// exactly as before; test/integration/tailwind_preset_parity_test.rb holds it
+// to the same utilities as theme.css until it goes.
+//
+// Migration (README, "Tailwind"): drop the host's `@config` line,
+// config/tailwind.config.js, its safelist and lib/tasks/tailwindcss_engine_motion.rake.
+// This file is removed in the release after every consumer has adopted.
+//
 // Shared Tailwind config for all Studio apps
 // Apps spread from this in their own tailwind.config.js
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.114.1.rc1
+  version: 0.114.2.rc1
 platform: ruby
 authors:
 - Alex McRitchie
@@ -371,6 +371,8 @@ files:
 - app/assets/stylesheets/studio/sticky_table_header.css
 - app/assets/tailwind/studio_engine/engine-motion.css
 - app/assets/tailwind/studio_engine/engine.css
+- app/assets/tailwind/studio_engine/host.css
+- app/assets/tailwind/studio_engine/theme.css
 - app/components/previews/studio/badge_component_preview.rb
 - app/components/previews/studio/badge_component_preview/schemes.html.erb
 - app/components/previews/studio/badge_component_preview/tones.html.erb
@@ -790,6 +792,7 @@ files:
 - lib/studio/survey.rb
 - lib/studio/survey/breakdown.rb
 - lib/studio/survey/export.rb
+- lib/studio/tailwind_entry.rb
 - lib/studio/theme_resolver.rb
 - lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb