Overview

• The display uses additive light. An unlit pixel provides the background; the interface does not paint a conventional page surface. App applies var(--uit-color-background-window) and var(--uit-color-text-primary) to its subtree. Keep that window background instead of adding a light or application-defined page background, which would illuminate pixels unnecessarily and reduce legibility.
• Input uses directional navigation. A user does not aim a pointer. One element owns focus, arrow input moves focus to the nearest eligible element in that direction, and confirm activates the focused element. Compose routes so every intended action is reachable through that model.

• Route chrome: Page, SubNavigationPager, Header, and SubNavigation.
• Actions: Button, ButtonGroup, ButtonRail, ButtonDivider, QuickReplyButton, and ActionHint.
• Rows and sections: ListItem, SwipeToReveal, ContainerHeader, and Divider.
• Tiles: ControlTile, AppControlTile, and WebAppIcon.
• Input and value controls: InputTextView, Switch, RadioButton, SliderBar, IsolatedControl, and Scrubber.
• Identity and labels: Avatar, AppBadge, NotificationBadge, Tag, Chip, and ReadMoreTextView.
• Progress: ProgressIndicator, ProgressRing, CircularProgressBar, and IndeterminateLoader.
• Inline panels: Modal.
• Overlays: ContextMenu, ContextMenuItemView, VerticalMenu, VerticalMenuButton, Tooltip, TooltipContainer, Toast, and Scrim.
• Status indicators: PaginationIndicator, SwipeIndicator, VolumeIndicator, and ZoomIndicator.

• Derive layout from available space. Use the viewport, content, and semantic tokens to determine dimensions. Avoid encoding a device resolution or branching on a particular viewport size so the interface remains responsive.
• Assign one scroll owner per axis and route. A route, or one page in a pager, has one vertical scroll container. A nested same-axis scroller breaks focus scrolling and the fading edges that communicate remaining distance.
• Dock actions below the content they affect. Keep the action region at the bottom of the display and outside the scroller. The scroller then ends above the actions, so content does not pass behind them.
• Design around focus. Give every control a useful neighbor in each expected direction. Choose one intended initial-focus target and keep it fully visible in the first settled frame so the route is ready to use immediately.
• Compose with the most specific toolkit component. Prefer an existing component that matches the interaction instead of recreating it from rounded rectangles. Avoid styling component internals or depending on DOM structure and generated class names; the toolkit owns those details to preserve behavior and consistency.
• Keep material-owning components separate. Do not nest Container, StaticContainer, Surface, Button, Chip, Tag, or the page Header inside another component in that set. Each owns its material, corner radius, and content inset, so nesting duplicates all three.

• Application structure explains the shell, route skeletons, and bottom action dock.
• Navigation and focus covers directional navigation, initial focus, Back, overlays, and restoration.
• Screen layout describes insets, edge-to-edge regions, scroll ownership, and intrinsic sizing.