From 902d0cc8322fa7507a93c231e075fe4565de9bff Mon Sep 17 00:00:00 2001
From: Kleber Rocha <kleber.rocha@cora.com.br>
Date: Mon, 11 May 2026 13:07:57 -0300
Subject: [PATCH 1/2] fix(styles): isolate module's Tailwind utilities in a
 lower cascade layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Modules generated from this template were silently breaking the
Backoffice Shell sidebar: when the module was active, clicking the
sidebar trigger flipped the `data-state` to `expanded` but the sidebar
element stayed at `display: none`. Reproduced live in
`front-scholarship-funds` (fix shipped there as well).

Root cause: cascade order on `.hidden`. The shell uses `hidden md:block`
(shadcn sidebar) and emits both `.hidden` and `.md\:block` in its
stylesheet. The module does not use `md:block`, so Tailwind 4 emits
only `.hidden` for the module. `vite-plugin-css-injected-by-js`
appends the module's <style> after the shell's stylesheet, and inside
the shared `@layer utilities` the later-source rule wins — so the
module's `.hidden` defeats the shell's `.md\:block`, even on a wide
viewport.

Fix: declare the module's auto-generated utilities in a dedicated
`module-utilities` layer that sits below the global `utilities` layer
the shell occupies. The shell's `.md\:block` now wins by layer
priority regardless of <style> injection order. Manual utilities a
module adds later via `@layer utilities { ... }` keep the
high-priority layer, so module-specific visuals still apply where
intended. `@theme` gets the same treatment (`module-theme`) for
symmetry — module theme tokens point at shell tokens via `var(...)`,
so shell `theme` rules winning on conflicts is the desired behavior.

This is the same family of bug as the existing Preflight gotcha
already documented at the top of globals.css; the comment is expanded
to cover both.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/styles/globals.css | 44 +++++++++++++++++++++++++++++-------------
 1 file changed, 31 insertions(+), 13 deletions(-)

diff --git a/src/styles/globals.css b/src/styles/globals.css
index 43e7d61..88f9313 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -1,19 +1,37 @@
 /*
- * We intentionally DO NOT import the full "tailwindcss" entry, because
- * it includes Preflight in the `base` layer. Preflight contains a
- * global reset with `*, ::before, ::after { border:0 solid; margin:0;
- * padding:0; box-sizing:border-box }` — and since the module's CSS is
- * injected into the shell's page via css-injected-by-js, that reset
- * would apply to every element on the page, including the shell's
- * own chrome. Symptom: sidebar/header borders disappear, layout shifts.
+ * Two gotchas with the module's Tailwind import — read both before
+ * touching the lines below.
  *
- * Import only the theme and utilities layers. The shell already runs
- * Preflight once for the whole page at its own startup — the module
- * just needs the utility classes on top.
+ * 1) Preflight. The full `tailwindcss` entry includes Preflight in the
+ *    `base` layer. Preflight is a global reset (`*, ::before, ::after
+ *    { border:0 solid; margin:0; padding:0; box-sizing:border-box }`).
+ *    Since the module's CSS is injected into the shell's page via
+ *    css-injected-by-js, that reset would apply to every element on
+ *    the page — including the shell's chrome. Symptom: sidebar/header
+ *    borders disappear, layout shifts. Fix: import only `theme` and
+ *    `utilities`, never the full `tailwindcss` entry. The shell ships
+ *    its own Preflight once for the whole page.
+ *
+ * 2) Cascade order on shared utilities (`.hidden`, `.flex`, `.block`).
+ *    Tailwind 4 emits only the utilities each project actually uses.
+ *    The shell uses `hidden md:block` (shadcn sidebar) but a module
+ *    typically does not — so the shell's stylesheet contains BOTH
+ *    `.hidden` and `.md\:block`, while the module's stylesheet
+ *    contains ONLY `.hidden`. css-injected-by-js appends the module's
+ *    <style> after the shell's stylesheet, and within a shared
+ *    `@layer utilities` the later-source rule wins. Result: the
+ *    module's `.hidden` defeats the shell's `.md\:block` even on wide
+ *    viewports, the shell sidebar stays `display:none`, and clicking
+ *    the trigger appears to do nothing. Fix: route the module's
+ *    auto-generated utilities into a lower-priority layer
+ *    (`module-utilities`) declared before `utilities`. Manual
+ *    utilities the module defines via `@layer utilities { ... }`
+ *    below stay in the high-priority `utilities` layer so they still
+ *    apply where the module needs them.
  */
-@layer theme, base, components, utilities;
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/utilities.css" layer(utilities);
+@layer module-theme, module-utilities, theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(module-theme);
+@import "tailwindcss/utilities.css" layer(module-utilities);
 @import "tw-animate-css";
 
 @custom-variant dark (&:is(.dark *));

From 7b13594f332fa38b55b6c1da66cd510b3410bd42 Mon Sep 17 00:00:00 2001
From: Kleber Rocha <kleber.rocha@cora.com.br>
Date: Mon, 11 May 2026 14:06:51 -0300
Subject: [PATCH 2/2] docs(styles): use full vite-plugin-css-injected-by-js
 name in comment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses Copilot review on PR #17 — the comment referred to the
plugin as `css-injected-by-js` while the actual package is
`vite-plugin-css-injected-by-js`. Standardizes on the full name so
the comment is greppable against package.json / vite.config.ts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/styles/globals.css | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/styles/globals.css b/src/styles/globals.css
index 88f9313..73889ec 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -6,20 +6,20 @@
  *    `base` layer. Preflight is a global reset (`*, ::before, ::after
  *    { border:0 solid; margin:0; padding:0; box-sizing:border-box }`).
  *    Since the module's CSS is injected into the shell's page via
- *    css-injected-by-js, that reset would apply to every element on
- *    the page — including the shell's chrome. Symptom: sidebar/header
- *    borders disappear, layout shifts. Fix: import only `theme` and
- *    `utilities`, never the full `tailwindcss` entry. The shell ships
- *    its own Preflight once for the whole page.
+ *    `vite-plugin-css-injected-by-js`, that reset would apply to every
+ *    element on the page — including the shell's chrome. Symptom:
+ *    sidebar/header borders disappear, layout shifts. Fix: import
+ *    only `theme` and `utilities`, never the full `tailwindcss` entry.
+ *    The shell ships its own Preflight once for the whole page.
  *
  * 2) Cascade order on shared utilities (`.hidden`, `.flex`, `.block`).
  *    Tailwind 4 emits only the utilities each project actually uses.
  *    The shell uses `hidden md:block` (shadcn sidebar) but a module
  *    typically does not — so the shell's stylesheet contains BOTH
  *    `.hidden` and `.md\:block`, while the module's stylesheet
- *    contains ONLY `.hidden`. css-injected-by-js appends the module's
- *    <style> after the shell's stylesheet, and within a shared
- *    `@layer utilities` the later-source rule wins. Result: the
+ *    contains ONLY `.hidden`. `vite-plugin-css-injected-by-js` appends
+ *    the module's <style> after the shell's stylesheet, and within a
+ *    shared `@layer utilities` the later-source rule wins. Result: the
  *    module's `.hidden` defeats the shell's `.md\:block` even on wide
  *    viewports, the shell sidebar stays `display:none`, and clicking
  *    the trigger appears to do nothing. Fix: route the module's