Visual Parity: Lit and React Renderers

This document describes the approach used to achieve visual parity between the Lit (Shadow DOM) and React (Light DOM) renderers.

Structural Mirroring

The Challenge

Lit components use Shadow DOM, where each component has an encapsulated DOM tree with its own scoped styles. The typical structure is:

#shadow-root
  <section class="theme-classes">
    <slot></slot>    ← children projected here
  </section>

The shadow host element (the custom element itself) acts as the :host and can have its own styles.

React uses Light DOM where everything exists in the global DOM. To achieve parity, we mirror Lit's two-element structure.

The Solution

Each React component renders a wrapper div (representing :host) plus a section (the internal element):

// React component structure
<div className="a2ui-card">
  <section className="theme-classes">
    {children}
  </section>
</div>

This mirroring allows CSS selectors to target the same conceptual elements in both renderers.

CSS Selector Transformation

Shadow DOM to Light DOM

Lit's Shadow DOM selectors need transformation for React's global CSS:

Example: Card Component

Lit's card.ts static styles:

:host {
  display: block;
  flex: var(--weight);
  min-height: 0;
  overflow: auto;
}

section {
  height: 100%;
  width: 100%;
  min-height: 0;
  overflow: auto;
}

section ::slotted(*) {
  height: 100%;
  width: 100%;
}

React's componentSpecificStyles equivalent:

.a2ui-surface .a2ui-card {
  display: block;
  flex: var(--weight);
  min-height: 0;
  overflow: auto;
}

.a2ui-surface .a2ui-card section {
  height: 100%;
  width: 100%;
  min-height: 0;
  overflow: auto;
}

.a2ui-surface .a2ui-card section > * {
  height: 100%;
  width: 100%;
}

CSS Specificity Matching

The Problem

Shadow DOM provides natural style encapsulation with low specificity. A selector like h2 inside Shadow DOM has specificity (0,0,0,1).

In React's global CSS, we need contextual selectors to scope styles:

.a2ui-surface .a2ui-text h2 { ... }

This has specificity (0,0,2,1) — much higher than Lit's (0,0,0,1).

Why It Matters

Utility classes like .typography-w-500 have specificity (0,0,1,0). In Lit:

• h2 { font: inherit; } = (0,0,0,1) — loses to utility class
• .typography-w-500 = (0,0,1,0) — wins, font-weight: 500 applied

In React (without fix):

• .a2ui-surface .a2ui-text h2 { font: inherit; } = (0,0,2,1) — wins
• .typography-w-500 = (0,0,1,0) — loses, font-weight reset to 400

The Solution: :where()

The :where() pseudo-class has zero specificity contribution. Wrapping contextual selectors in :where() matches Lit's low specificity:

/* Before: specificity (0,0,2,1) — too high */
.a2ui-surface .a2ui-text h1,
.a2ui-surface .a2ui-text h2 { ... }

/* After: specificity (0,0,0,1) — matches Lit */
:where(.a2ui-surface .a2ui-text) h1,
:where(.a2ui-surface .a2ui-text) h2 { ... }

Now utility classes can override element resets, just like in Lit.

When to Use :where()

Use :where() when the Lit component has element selectors that should be overridable by utility classes:

• Use :where(): Element resets like h1, h2 { font: inherit; }
• Don't use :where(): Structural styles on :host or section that define component behavior

File Organization

• ../src/styles/index.ts: Contains structuralStyles (from Lit) and componentSpecificStyles (React-specific)
• ../src/components/: Component files that render the mirrored structure with appropriate class names
• injectStyles(): Injects both structural and component-specific styles into the document
• ./fixtures/: Test fixtures for visual parity testing
• ./tests/: Playwright test specs

Troubleshooting

Vite Cache Issues (504 Outdated Optimize Dep)

If you see errors like:

Failed to load resource: the server responded with a status of 504 (Outdated Optimize Dep)
Uncaught TypeError: Failed to fetch dynamically imported module

This happens when Vite's dependency optimization cache becomes stale, typically after:

• Switching git branches
• Updating dependencies
• Rebuilding the React renderer

Fix: Clear the Vite cache and restart:

# From renderers/react/visual-parity/
rm -rf node_modules/.vite react/node_modules/.vite lit/node_modules/.vite ../node_modules/.vite
npm run dev:react  # or dev:lit

React Renderer Changes Not Picked Up

If you edit files in renderers/react/src/ but the visual parity app doesn't reflect the changes, this is because the visual parity app imports from the built @a2ui/react package, not directly from source.

Why this happens:

1. Source changes are in renderers/react/src/
2. Visual parity app imports from @a2ui/react/styles (workspace package)
3. Vite pre-bundles workspace dependencies into node_modules/.vite
4. The pre-bundled cache still has the old built version

Fix: Rebuild the package and clear Vite's cache:

# From renderers/react/visual-parity/

# 1. Rebuild the React renderer
cd ../
npm run build

# 2. Clear Vite cache and restart
cd visual-parity
rm -rf react/node_modules/.vite node_modules/.vite
npm run dev:react

Note: Vite's HMR works for changes within the visual parity app, but changes to workspace dependencies require rebuilding + cache clearing.

Testing Parity

This directory contains the visual parity test suite:

# Run all tests
npm test

# Run specific component tests
npm test -- --grep "button"

# Run dev servers for manual inspection
npm run dev

The tests:

1. Load the same fixture in both Lit (localhost:5002) and React (localhost:5001)
2. Take screenshots of both renderers
3. Compare pixel differences using pixelmatch
4. Fail if difference exceeds 1%

See README.md for detailed usage instructions.

Component CSS Checklist

Each Lit component with static styles needs a corresponding entry in componentSpecificStyles. Below is the complete list with implementation status:

✅ Implemented (0% pixel diff in visual parity tests)

⚠️ Lit Renderer Issues

Special Cases

Implementation Hints

Attribute Selectors (Column, Row, List)

Lit uses :host([attribute="value"]) for attribute-based styling. In React, use data attributes:

// React component
<div className="a2ui-column" data-alignment={alignment} data-distribution={distribution}>

/* componentSpecificStyles */
.a2ui-surface .a2ui-column[data-alignment="center"] section {
  align-items: center;
}

CSS Variables (Image)

Pass CSS variables via inline style:

// React component
<div className="a2ui-image" style={{ '--object-fit': fit }}>

/* componentSpecificStyles — use :where() so utility classes (e.g. layout-el-cv) can override */
:where(.a2ui-surface .a2ui-image) img {
  object-fit: var(--object-fit, fill);
}

Nested Selectors (Modal)

For complex nested styles, maintain the hierarchy:

/* Lit */
dialog section #controls button { ... }

/* React componentSpecificStyles */
.a2ui-surface .a2ui-modal dialog section #controls button { ... }

Form Elements

Form inputs already have some shared styles. Component-specific overrides use :where() so theme utility classes can override them:

/* DateTimeInput specific — :where() keeps specificity at (0,0,1) to match Lit's bare `input` selector */
:where(.a2ui-surface .a2ui-datetime-input) input {
  border-radius: 8px;
  padding: 8px;
  border: 1px solid #ccc;
}