C2f Tailwind Css Architecture

---
name: c2f-tailwind-css-architecture
description: "MANDATORY READ before creating, modifying or migrating Tailwind CSS v4 screens, layouts, pages or components. Prevents cascade conflicts, stale compiled CSS, discarded runtime styles and broken builds."
user-invocable: false
---

# Governance and Architecture of Tailwind CSS v4 in Conn2Flow and Projects

## Diagnosis of CSS in runtime with Chrome DevTools MCP

After syncing through the pipeline, follow `c2f-agent-visual-inspection`: capture screenshot and snapshot on desktop/mobile and after switching dynamic states. Measure the node with `evaluate_script` (`getComputedStyle`, `getBoundingClientRect`) and correlate real classes, breakpoint, display, position and overflow with CSS delivered by SQL.

When `get_css_styles` is in the session catalog, use it to examine corresponding rules and computed styles. Compare overwritten rules, specificity, order and context flex/grid; an applied statement can be inactive by context incompatibility. Do not treat DevTools' inactive style visual indicator as a guaranteed MCP tool. Without this tool, combine measurements and inspection of the loaded sheets, recording the limitation.

Correlate with `c2f css:audit --url=<rota>` and rebuild derivatives by the authorised `c2f css:rebuild`. Do not use transitional changes in the DOM/CSS or direct updates in `css_compiled` as the final solution; re-validate the synchronized resource.

# ⚡ MANDATORY TRIGGER
- **TRIGGER**: Create, change, migrate or debug any layout, page, component or template with classes of Tailwind CSS v4.
- **SKIP ONLY IF**: Purely PHP backend tasks or APIs without visual rendering.
- **CONSEQUENCE OF IGNORING**: cascade CSS break (idebar hidden on desktop), code masking by database cache (`css_compiled`) and discard runtime styles.

---

## ⛔ Inviolable Rules
1. **NEVER execute manual commands via `npx`** (`npx tailwindcss`, etc.). Always use `./c2f resources:sync` (or `php atualizacao-dados-recursos.php`). When direct invocation is strictly required in local debugging, use **only local binaries in `node_modules/.bin/tailwindcss.cmd` and `node_modules/.bin/terser.cmd`** (Armadilla 17: absolute prohibition of `npx`).
2. **All HTML/CSS visual must reside in the Resource System**: `resources/<idioma>/<tipo>/<id>/<id>.html` and `<id>.json`.
3. **JSON Metadata**: All resource Tailwind MUST declare `"framework_css": "tailwindcss"` in your `<id>.json` metadata file.
4. **Runtime Dynamic Templates (Finding F2)**: Declare dynamic template dependencies in the `"tailwind_dependencies": ["id-1", "id-2"]` array of the parent resource JSON.
5. **Cascade and Media Queries**: Never use `.hidden` isolated on daughter pages that conflict with `lg:flex` or `md:block` of the parent layout; always use explicit breakpoint prefixes (e.g. `hidden lg:flex`).

---

## 🏗️ Author vs Derived (Manual Outline Elimination)

Conn2Flow CSS architecture strictly separates **author** fields (preserved) from **derivatives** fields (always recalculable):

|Field in Database|Classification|Description|
|---|---|---|
|`html`|**AUTHORITY**|Original HTML edited by the author. Preserved according to `user_modified` and `project`.|
|`css`|**AUTHORITY**|Original CSS edited by the author. Preserved according to `user_modified` and `project`.|
|`css_precompiled`|**Derivatives**|Intermediate CSS generated by the Tailwind compilation pipeline. Never edited manually.|
|`css_compiled`|**Derivatives**|Optimized end CSS served to visitor. Never edited manually.|

> [!CAUTION]
> **Hack Legacy Elimination Rule**: The old practice of zeroing `paginas.css_compiled = NULL` directly into database was a manual outline of a structural problem. This practice is **prohibited**. The correct procedure is to use `c2f css:rebuild` to recalculate the derived CSS from the current authorship.

---

## 🔧 CSS Measurement and Reconstruction Instruments

Instead of inferring blind code reading stylization, use audit commands:

### `c2f css:audit`
Audit the origin (`css_source_hash`), coverage of classes and classes Tailwind embedded in PHP/JS per table.
```bash
./c2f css:audit
```

### `c2f css:audit --url=<rota>`
Audit the actual composite page (with layout + components) and map orphan classes to the source resource.
```bash
./c2f css:audit --url=/transformamp/home
```

### `c2f css:rebuild`
Rebuilds the derivative CSS (`css_precompiled` and `css_compiled`) using the actual HTML of the database as source.
```bash
./c2f css:rebuild
./c2f css:rebuild --url=/transformamp/home
```

---

## ⚠️ Technical debt: `tailwind_sources` in PHP/JS

Point `tailwind_sources` to `.php` or `.js` files indicates Tailwind utilitarian classes mounted in running time via JavaScript or PHP. This violates the Conn2Flow architecture, where PHP/JS should not load marking or styles.

**Classification**: Technical debt to be eliminated.
**Corrective Action**: Move class generation to components/templates within the Resource System (`resources/`), where the Tailwind compiler can scan them statically.

---

## 📋 Required registration of `tailwind_sources` and `tailwind_sources_reason`

### Problem

Tailwind's previous compiler analyzes only the static HTML of resource. Dynamically mounted utilitarian classes in PHP (e.g. status badges), manipulated in JS (`classList.toggle('hidden')`) or configured in JSON of **do not enter the generated bundle** modules, causing silent visual failures.

### Normative Directive

For manager/site pages using Tailwind classes outside static HTML, declare the metadata in `<id>.json` resource:

```json
{
  "tailwind_sources": [
    "../../../../modulos/ecommerce/ecommerce-checkout.php"
  ],
  "tailwind_sources_reason": "Classes de badge de status (bg-green-100, text-red-600) são montadas em PHP com base no estado do pedido"
}
```

|Field|Mandatory|Description|
|---|---|---|
|`tailwind_sources`|Yes|Path array for PHP/JS files containing dynamic Tailwind classes|
|`tailwind_sources_reason`|**Yes**|Textual justification for inclusion — build **You're accusing fatal error.** if reason is omitted|

### Alternative in Core Libraries

For Core libraries that generate HTML with Tailwind classes, encapsulate the dynamic palette in a `<template>` element inert in the resource HTML component itself:

```html
<!-- Paleta de classes dinâmicas para o scanner Tailwind -->
<template data-tailwind-palette>
  <span class="bg-green-100 text-green-800 bg-red-100 text-red-800 bg-yellow-100 text-yellow-800"></span>
</template>
```

> [!CAUTION]
> Without registration of `tailwind_sources`, utility classes used exclusively in PHP/JS are **deleted from compiled CSS** in build. The error is silent — the renders page without the classes, causing visual breakage without error message.

---

## ⚙️ Local Binary Resolution and Modular Migration (`node_modules/.bin/`)

To ensure immunity to the NPM volatile cache and avoid PATH crashes in Windows (Armadile 17):
- Every pipeline or script that invokes the Tailwind compiler or miner Terser shall refer directly to local binaries in `node_modules/.bin/tailwindcss.cmd` (Windows) or `node_modules/.bin/tailwindcss` (Linux/macOS), without intermediating calls via `npx`.
- When migrating administrative modules from Fomantic-UI to Tailwind, see and apply the canonical skill `c2f-tailwind-module-migration`, respecting the order of bundles (`$_GESTOR['tailwind-page-bundle'] = true`), the `-tailwind` variants in `interface_componente_variante()` and the utilitarian classes isolated in the HTML of resource.

## Hooks on screens of other modules (BL-028)

Marking injected by hook on other screen uses own sheet and component specific classes. Do not inject generic bundle of utilities after the page package: this changes the cascade and can reverse host responsives. Validate the host screen on desktop/mobile and the actual order of sheets. CSS itself continues to be authored in resources/, synchronized by pipeline.

Rendered component in someone else's context may not resolve @[var]@ of your module. In this case use marker #x# explicitly replaced in PHP with value obtained in the correct scope via gestor_variaveis; escaping according to destination (text/attribute). Do not place marker in comment: the exchange may consume the first occurrence. Check that there are no markers left in the response and do not apply indiscriminate replacement to components whose contract already solves variables.