# Theming and Tailwind

> How Lexsis standardizes brand tokens, Tailwind utilities, and compiled page CSS

Canonical URL: https://fa7e86e3d553:3005/pages/theming

Lexsis uses one styling pipeline:

1. `theme_css` defines page-wide brand tokens and intentional custom rules.
2. Tailwind CSS 4.3 utilities define layout, spacing, sizing, responsive
   behavior, state, and most visual styling.
3. Scoped section CSS handles the small set of rules that are clearer as
   authored CSS.
4. The compiler combines all three into one immutable
   `compiled_page_css` artifact.

There is no runtime Tailwind CDN and no separate Tailwind installation per
section.

## Styling ownership

| Concern | Preferred mechanism |
|---|---|
| Grid, flex, spacing, sizing | Tailwind utilities |
| Breakpoints and mobile behavior | Tailwind responsive variants |
| Hover, focus, active, group state | Tailwind state and arbitrary variants |
| Brand colors, fonts, radii | `--lx-*` variables in `theme_css` |
| Reusable complex selector | Scoped section CSS |
| Commerce interaction | Island props and island CSS hooks |
| Local behavior | Scoped section JavaScript |

Avoid building a second layout system in custom CSS. If a value can be
expressed clearly with Tailwind, use Tailwind.

## Theme variables

```css
:root {
  --lx-accent-color: #2d5016;
  --lx-accent-color-hover: #203c10;
  --lx-text-color: #171a14;
  --lx-text-muted: #66705f;
  --lx-text-inverse: #ffffff;
  --lx-bg-color: #ffffff;
  --lx-bg-surface: #f7f8f2;
  --lx-surface-alt: #eef1e8;
  --lx-border-color: #dfe3d8;
  --lx-font-heading: "Cormorant Garamond", serif;
  --lx-font-body: "Inter", sans-serif;
}
```

Always wrap page theme variables in `:root`.

Use variables from Tailwind arbitrary values:

```html
<section class="bg-[var(--lx-bg-color)] text-[var(--lx-text-color)]">
  <h1 class="font-[var(--lx-font-heading)] text-4xl lg:text-6xl">
    Thoughtful essentials
  </h1>

  <a
    class="inline-flex rounded-[var(--lx-button-radius,9999px)] bg-[var(--lx-accent-color)] px-6 py-3 text-[var(--lx-text-inverse,#fff)] transition-colors hover:bg-[var(--lx-accent-color-hover)]"
    href="/collections/all"
  >
    Shop now
  </a>
</section>
```

Inline `style` attributes remain valid for dynamic CSS custom-property values,
but they should not replace Tailwind for ordinary structural layout.

## Standard responsive layout

```html
<div class="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-4">
  ...
</div>
```

If a row must remain four columns at every supported width:

```html
<div class="grid grid-cols-4 gap-2 sm:gap-4">
  ...
</div>
```

`grid-cols-4` is a normal Tailwind utility. Lexsis generates its CSS because
the compiler scans the authored HTML and includes every referenced utility in
`compiled_page_css`.

## Island media hover effects

Use native media islands and their stable styling parts instead of authoring a
raw image tag:

```html
<section id="featured-product" class="overflow-hidden rounded-2xl">
  <lx-island name="MediaCarousel">
    <script type="application/json">
      {
        "media": [
          {
            "type": "image",
            "src": "https://cdn.example.com/product.jpg",
            "alt": "Featured product"
          }
        ],
        "aspect": "1:1"
      }
    </script>
  </lx-island>
</section>

<style>
  #featured-product [data-part="image"] {
    transition: transform 500ms ease;
  }

  #featured-product:hover [data-part="image"] {
    transform: scale(1.045);
  }
</style>
```

Raw image and video tags produce `native_media_island_recommended` compiler
warnings. Native islands own responsive sources, loading, media controls,
accessibility, and reduced-motion behavior.

## Compiled CSS order

The page compiler emits styles in deterministic order:

```text
1. Lexsis theme (`theme_css`)
2. Generated Tailwind utilities
3. Section CSS in page-section order
```

The resulting page contains:

```typescript
{
  compiled_page_css: string;
  style_manifest: {
    engine: "tailwindcss";
    compiler_version: "4.3.0";
    input_version: number;
    input_sha256: string;
    candidate_count: number;
    css_bytes: number;
  };
}
```

`input_sha256` identifies the complete style input: theme CSS plus every
section's HTML and CSS.

## Missing utilities

Compilation returns `missing_candidates` and a
`missing_tailwind_utility` error when a class:

- Produces no Tailwind CSS
- Is not defined in `theme_css`
- Is not defined in section CSS
- Is not an accepted behavior-only marker

Do not publish while `missing_candidates` is non-empty.

## Theme updates

Theme edits on source-backed pages must trigger full-page recompilation. Use
`lexsis_drafts` action `page_update_head` with the complete `theme_css`; the MCP
recompiles the stored source and commits it through the atomic source
replacement path. A direct backend head-only patch cannot safely rebuild the
complete Tailwind artifact.

## Fonts

Load approved web fonts through `head.fonts`:

```json
{
  "head": {
    "title": "Mulberry Silk Collection",
    "fonts": [
      "https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@600;700&family=Inter:wght@400;500;600&display=swap"
    ]
  }
}
```

Then reference the theme variables in Tailwind:

```html
<h2 class="font-[var(--lx-font-heading)] text-3xl lg:text-5xl">
  Naturally refined
</h2>
```

## Section CSS

Section CSS is appropriate for:

- Complex pseudo-elements
- Named keyframes
- Island CSS hooks
- Browser behavior not represented by a readable utility
- A reusable local component selector

Scope selectors to the section:

```html
<!-- section: product-story -->
<section id="product-story" class="py-16 lg:py-24">
  ...
</section>

<style>
  #product-story .story-rule {
    background: linear-gradient(
      90deg,
      transparent,
      var(--lx-border-color),
      transparent
    );
  }
</style>
```

Do not use `!important` as the default way to fight Tailwind. Remove the
conflicting utility or express the intended rule directly.

## Visual verification

Compilation proves that CSS exists; it does not prove that the composition is
visually correct. The calling agent must verify:

- 390px mobile
- 768px tablet
- 1280px desktop
- Computed grid/flex layout
- Horizontal overflow
- Text clipping
- Hover and focus states
- Broken images
- Unexpected section height

The MCP returns preview URLs but does not run a shared browser-automation
service.

## Related

- [Brand & Theme Tools](/tools/brand-design)
- [Page Source Contract](/pages/schema)
- [Styling Issues](/troubleshooting/styling-issues)