Skip to content

Theming & Styling

Customize the look and feel of A2UI components to match your brand.

The A2UI Styling Philosophy

A2UI follows a client-controlled styling approach:

  • Agents describe what to show (components and structure)
  • Clients decide how it looks (colors, fonts, spacing)

This ensures:

  • ✅ Brand consistency: All UIs match your app's design system
  • ✅ Security: Agents can't inject arbitrary CSS or styling
  • ✅ Accessibility: You control contrast, focus states, and ARIA attributes
  • ✅ Platform-native feel: Web apps look like web, mobile looks like mobile

Styling Layers

A2UI styling works in layers:

flowchart TD A["1. Semantic Hints
Agent provides hints
(e.g., usageHint: 'h1')"] B["2. Theme Configuration
You configure
(colors, fonts, spacing)"] C["3. Component Overrides
You customize
(CSS/styles for specific components)"] D["4. Rendered Output
Native platform widgets"] A --> B --> C --> D

Layer 1: Semantic Hints

Agents provide semantic hints (not visual styles) to guide client rendering:

{
  "id": "title",
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "usageHint": "h1"
    }
  }
}

Common usageHint values: - Text: h1, h2, h3, h4, h5, body, caption - Other components have their own hints (see Component Reference)

The client renderer maps these semantic hints to actual visual styles based on your theme and design system.

Layer 2: Theme Configuration

Each renderer provides a way to configure your design system globally, including:

  • Colors: Primary, secondary, background, surface, error, success, etc.
  • Typography: Font families, sizes, weights, line heights
  • Spacing: Base units and scale (xs, sm, md, lg, xl)
  • Shapes: Border radius values
  • Elevation: Shadow styles for depth

TODO: Add platform-specific theming guides:

Web (Lit): - How to configure theme via renderer initialization - Available theme properties

Angular: - Integration with Angular Material theming - Standalone A2UI theme configuration

Flutter: - How A2UI uses Flutter's ThemeData - Custom theme properties

See working examples: - Lit samples - Angular samples - Flutter GenUI docs

Layer 3: Component Overrides

Beyond global theming, you can override styles for specific components:

Web renderers: - CSS custom properties (CSS variables) for fine-grained control - Standard CSS selectors for component-specific overrides

Flutter: - Widget-specific theme overrides via ThemeData

TODO: Add detailed component override examples for each platform.

Common Styling Features

Dark Mode

A2UI renderers typically support automatic dark mode based on system preferences:

  • Auto-detect system theme (prefers-color-scheme)
  • Manual light/dark theme selection
  • Custom dark theme configuration

TODO: Add dark mode configuration examples.

Responsive Design

A2UI components are responsive by default. You can further customize responsive behavior:

  • Media queries for different screen sizes
  • Container queries for component-level responsiveness
  • Responsive spacing and typography scales

TODO: Add responsive design examples.

Custom Fonts

Load and use custom fonts in your A2UI application:

  • Web fonts (Google Fonts, etc.)
  • Self-hosted fonts
  • Platform-specific font loading

TODO: Add custom font examples.

Best Practices

1. Use Semantic Hints, Not Visual Properties

Agents should provide semantic hints (usageHint), never visual styles:

// ✅ Good: Semantic hint
{
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "usageHint": "h1"
    }
  }
}

// ❌ Bad: Visual properties (not supported)
{
  "component": {
    "Text": {
      "text": {"literalString": "Welcome"},
      "fontSize": 24,
      "color": "#FF0000"
    }
  }
}

2. Maintain Accessibility

  • Ensure sufficient color contrast (WCAG AA: 4.5:1 for normal text, 3:1 for large text)
  • Test with screen readers
  • Support keyboard navigation
  • Test in both light and dark modes

3. Use Design Tokens

Define reusable design tokens (colors, spacing, etc.) and reference them throughout your styles for consistency.

4. Test Across Platforms

  • Test your theming on all target platforms (web, mobile, desktop)
  • Verify both light and dark modes
  • Check different screen sizes and orientations
  • Ensure consistent brand experience across platforms

Next Steps