# Styling Issues

> Diagnose Tailwind compilation, theme tokens, responsive layout, and visual regressions

Canonical URL: https://fa7e86e3d553:3005/troubleshooting/styling-issues

Lexsis compiles page styling into one `compiled_page_css` artifact. It contains
the page theme, generated Tailwind utilities, and section CSS. There is no
runtime Tailwind CDN.

## A Tailwind class has no effect

### Diagnose

Run `lexsis_pages` action `compile` and inspect:

```typescript
{
  styles: {
    candidates: string[];
    tailwind_candidates: string[];
    custom_css_candidates: string[];
    missing_candidates: string[];
    style_manifest: {
      engine: "tailwindcss";
      compiler_version: string;
      candidate_count: number;
      css_bytes: number;
      input_sha256: string;
    };
  };
}
```

If a class is in `missing_candidates`, it produced no Tailwind CSS and was not
found in `theme_css` or section CSS.

### Fix

- Correct a misspelled utility.
- Replace a dynamically constructed class with a complete literal class.
- Define an intentional custom class in scoped CSS.
- Use a data attribute for a behavior-only JavaScript marker.
- Do not publish while missing candidates remain.

`grid-cols-4` is a normal Tailwind utility. The expected generated declaration
is a four-track grid when the element also uses `grid`.

## Compilation succeeds but the layout is wrong

CSS generation proves that a rule exists; it does not prove the visual
composition is correct.

Inspect the preview at 390px, 768px, and 1280px. Check:

- `display`
- `grid-template-columns`
- Flex direction and wrapping
- Element width and height
- Horizontal scroll width
- Overflow and clipping

For a fixed four-column row:

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

For a responsive one-to-four-column layout:

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

If computed `grid-template-columns` contains only one track, confirm that both
`grid` and `grid-cols-4` appear in `tailwind_candidates` and in
`compiled_page_css`.

## Media hover scale is not triggered

Use a native media island and target its documented image part:

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

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

Verify the part name against the current island schema. Raw media tags trigger
`native_media_island_recommended`.

## Theme colors do not apply

Use `--lx-*` variables in `theme_css`:

```css
:root {
  --lx-accent-color: #4b2e24;
  --lx-text-color: #231c18;
  --lx-bg-color: #fffaf5;
}
```

Apply them through Tailwind:

```html
<section class="bg-[var(--lx-bg-color)] text-[var(--lx-text-color)]">
  <a class="bg-[var(--lx-accent-color)] text-white" href="/collections/all">
    Shop
  </a>
</section>
```

Common causes:

- Missing `:root` wrapper
- Wrong token name
- A hardcoded utility overrides the token
- The page was not recompiled after a theme change
- The wrong workspace theme was loaded

Theme changes on source-backed pages should use `lexsis_drafts` action
`page_update_head` with the complete `theme_css`. The MCP recompiles the stored
source so `compiled_page_css` is rebuilt.

## Fonts fall back to the system font

Add a complete HTTPS stylesheet URL to `head.fonts`:

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

Then use the configured token:

```html
<p class="font-[var(--lx-font-body)]">Body copy</p>
```

Verify that the network request succeeds and the computed `font-family`
contains the intended font.

## Custom CSS conflicts with Tailwind

Avoid solving conflicts by increasing specificity or adding `!important`.

Preferred order:

1. Remove the conflicting Tailwind class.
2. Express the intended rule as a Tailwind utility or arbitrary value.
3. Use a uniquely scoped section selector when custom CSS is genuinely
   clearer.

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

The compiled order is theme CSS, generated Tailwind, then section CSS.

## Section CSS leaks into another section

Avoid generic selectors such as `.card`, `.title`, or `.button`.

```css
/* Risky */
.card { border-radius: 1rem; }

/* Scoped */
#product-story .story-card { border-radius: 1rem; }
```

## Mobile viewport does not change

Viewport handling belongs to the calling agent's browser capability, not the
MCP server.

After setting a mobile viewport:

1. Read back the actual viewport width.
2. Reload or re-evaluate responsive layout if required by the host.
3. Measure the document width and key section bounds.
4. Do not trust a mobile result that still reports a desktop width.

If screenshot capture fails, continue with DOM measurements, computed styles,
console errors, and broken-image checks.

## Unexpected overflow

Inspect:

```javascript
document.documentElement.scrollWidth > window.innerWidth
```

Common causes:

- Fixed pixel widths
- Unbreakable text
- Absolute-positioned decoration
- A four-column row with oversized minimum widths
- Images missing `max-w-full`
- Negative margins

Prefer a native `MediaCarousel`, `ProductGallery`, `ProductHero`, or
`HeroMedia` island with an appropriate `fit`/`objectFit` prop. Raw image and
video tags produce `native_media_island_recommended`.

## Transparent images appear black

The underlying PNG may still be valid. Some preview surfaces display
transparency against black.

- Inspect the image over a checkerboard or known light background.
- Check the actual alpha channel before converting it.
- Use `lexsis_assets` action `view` to inspect the stored asset.
- Do not add a white background unless the page design requires it.

## Structural integrity passes but visual QA fails

Integrity checks validate source and commerce invariants. They do not detect
all visual failures, including:

- Stacked columns
- Excessive section height
- Overlap
- Text clipping
- Poor contrast
- Broken hover behavior
- Unexpected responsive wrapping

Always perform browser QA at the standard breakpoints before publishing.

## Related

- [Theming and Tailwind](/pages/theming)
- [Page Source Contract](/pages/schema)
- [Publishing](/pages/publishing)