How A2UI Handles Different Screen Sizes: CSS Media Queries, Container Queries, and Design Tokens

A2UI handles different screen sizes by combining CSS media queries for global breakpoints, container queries for component-level responsiveness, and design-token-driven scaling that ensures components adapt automatically to their container dimensions.

The google/A2UI repository provides a responsive UI framework that adapts across phones, tablets, and desktops without requiring manual breakpoint handling in every component. By leveraging modern CSS features alongside runtime renderer controls, A2UI creates layouts that respond to both viewport dimensions and individual container sizes.

CSS Media Queries for Global Breakpoints

A2UI uses standard CSS media queries to adjust global layout structures when the viewport crosses specific thresholds. In tools/inspector/inspector.ts, the inspector UI implements a height-based breakpoint that switches to a taller-screen layout when the viewport exceeds 960 pixels:

@media (min-height: 960px) {
  #main #controls-container {
    grid-template-rows: 32px 1fr 42px;
    gap: var(--bb-grid-size-5);
  }
}

Source: [inspector.ts line 93](https://github.com/google/A2UI/blob/main/tools/inspector/inspector.ts#L93)

This pattern allows the overall application chrome to restructure its major regions—such as control panels and navigation areas—based on the available screen real estate.

Container Queries for Component-Level Responsiveness

While media queries handle global changes, A2UI relies primarily on CSS container queries for fine-grained component adaptation. The splitter component in both the inspector and editor declares itself as a size container using the container-type property:

:host {
  container-type: size;
  contain: strict;
}

Source: [splitter.ts line 74](https://github.com/google/A2UI/blob/main/tools/inspector/ui/splitter.ts#L74) (identical in tools/editor/ui/splitter.ts)

By setting container-type: size, each UI element establishes its own queryable context. This enables child components to adapt their internal layouts based solely on the space they actually receive, independent of the overall viewport size. According to the A2UI theming documentation, this is the recommended primary mechanism for component-level responsiveness.

Design Tokens and Responsive-By-Default Components

All core A2UI components—including Row, Column, Card, and Text—use flexible CSS grid and flex layouts paired with design tokens such as --bb-grid-size. These tokens scale proportionally with container size, ensuring that spacing, typography, and element sizing adjust automatically as components grow or shrink.

The theming guide in docs/guides/theming.md explicitly states that components are responsive by default:

"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"

Source: [theming.md lines 16-22](https://github.com/google/A2UI/blob/main/docs/guides/theming.md#L16)

Because design tokens like --bb-grid-size, --bb-grid-size-2, and --bb-grid-size-5 are calculated from container dimensions, any change in the parent container—whether triggered by media queries, container queries, or user resizing—propagates proportionally to all nested components.

Runtime Responsiveness in Renderers

A2UI does not impose a single responsive strategy on third-party integrations. Instead, individual renderers can enable library-specific responsiveness while benefiting from the surrounding container-query infrastructure. For example, when integrating Chart.js in the Angular sample catalog, the component activates the chart library's native responsive mode:

protected chartOptions: ChartOptions = {
  responsive: true,
  // …
};

Source: [chart.ts line 64](https://github.com/google/A2UI/blob/main/samples/client/angular/projects/rizzcharts/src/a2ui-catalog/chart.ts#L64)

This flexibility allows developers to leverage existing chart or visualization library behaviors while the A2UI layout system handles the surrounding container sizing.

Practical Implementation Examples

Adding a Component-Level Container Query

To make a custom card component responsive to its container rather than the viewport, implement size containment and container query rules:

/* my-card.css */
:host {
  display: block;
  container-type: size;   /* enables container queries */
}

/* When the container is < 400 px wide, shrink padding and font size */
@container (max-width: 400px) {
  .content {
    padding: var(--bb-grid-size-1);
    font-size: var(--bb-grid-size-3);
  }
}

/* When the container is ≥ 800 px wide, expand layout */
@container (min-width: 800px) {
  .content {
    padding: var(--bb-grid-size-6);
    font-size: var(--bb-grid-size-5);
    display: flex;
    gap: var(--bb-grid-size-4);
  }
}

This component automatically selects a compact layout on narrow containers and an expanded layout on wide containers without querying the global viewport.

Using Global Media-Query Breakpoints

For application-level layout shifts, apply standard media queries that mirror the inspector pattern:

/* global.css */
@media (min-width: 960px) {
  .toolbar {
    flex-direction: row;
    justify-content: space-between;
  }
}
@media (max-width: 959px) {
  .toolbar {
    flex-direction: column;
    align-items: stretch;
  }
}

This adjusts a toolbar's orientation based on overall screen width, matching the approach found in tools/inspector/inspector.ts.

Enabling Library-Level Responsiveness

When embedding third-party charts within A2UI, enable their responsive flags to ensure they fill their containers:

import { ChartOptions } from 'chart.js';

export class MyChartComponent {
  chartOptions: ChartOptions = {
    responsive: true,           // let Chart.js resize with its container
    maintainAspectRatio: false // optional: fill height as well
  };
}

The chart will now grow and shrink with its parent container, which is itself controlled by A2UI's container-query layout system.

Summary

• A2UI uses CSS media queries in tools/inspector/inspector.ts for global viewport breakpoints such as the 960px height threshold.
• Container queries are the primary mechanism for component-level responsiveness, implemented via container-type: size in components like splitter.ts.
• Design tokens such as --bb-grid-size enable proportional scaling of spacing and typography across all core components.
• Components are responsive by default according to docs/guides/theming.md, requiring no additional configuration for basic adaptive behavior.
• Renderers maintain autonomy over third-party library responsiveness, as demonstrated by the Chart.js integration in samples/client/angular/projects/rizzcharts/src/a2ui-catalog/chart.ts.

Frequently Asked Questions

Does A2UI use media queries or container queries for responsive design?

A2UI uses both: media queries handle global layout changes based on viewport dimensions (as seen in inspector.ts), while container queries handle component-level adaptations based on individual container sizes (implemented in splitter.ts). The framework recommends container queries as the primary method for fine-grained responsiveness because they allow components to react to their allocated space rather than the entire screen.

How do I make a custom A2UI component responsive?

Add container-type: size to your component's host element and define @container rules that adjust layout, padding, or typography based on the container's width or height. Use A2UI design tokens like var(--bb-grid-size-3) instead of fixed pixel values to ensure your component scales consistently with the rest of the system.

Are A2UI components responsive by default?

Yes. According to the theming documentation in docs/guides/theming.md, all core A2UI components use flexible grid and flex layouts with responsive design tokens. They automatically adjust spacing and sizing as their containers change, requiring no additional responsive configuration unless you need specific breakpoint behavior.

How does A2UI handle third-party libraries like Chart.js?

A2UI allows individual renderers to control third-party responsiveness independently. When integrating a chart library, you can enable its native responsive flag (such as responsive: true in Chart.js options) while the surrounding A2UI container manages the available space through container queries. This pattern appears in samples/client/angular/projects/rizzcharts/src/a2ui-catalog/chart.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}