System

System-level providers and layout/surface primitives for app scaffolding.

Stable direction
@lattice-ui/system

Part of the stable direction toward v1.0.

What It Is For

Use @lattice-ui/system for app-level UI context, density-aware theme resolution, and layout primitives like Stack, Row, Grid, and Surface.

It is the structural companion to style: style defines the visual language, while system applies that language across screens and layouts.

Preview size

Live demo is experimental and may contain bugs.

Install

Global CLI command: lattice add system

Monorepo local script

Use your package manager wrapper when running the local lattice command.

pnpm lattice add system

npm package: @lattice-ui/system

Peer dependencies

  • @rbxts/react
  • @rbxts/react-roblox

Public Exports

  • DensityProvider
  • useDensity
  • applyDensity
  • density
  • Grid
  • Row
  • Stack
  • surface
  • Surface
  • SystemProvider
  • useSystemTheme

State Model

  • SystemProvider owns two coordinated values: the raw baseTheme and the current density token.
  • useSystemTheme exposes the density-resolved theme for reading, plus setters for baseTheme and density.
  • Layout primitives are stateless views over spacing and layout rules; they read theme and density context but do not create their own global model.

Key API

SystemProvider

Use theme, defaultTheme, density, and their change callbacks when the app root should own global UI context.

useSystemTheme

Read the resolved theme and update setBaseTheme or setDensity when runtime appearance should react to user choice or screen context.

Stack / Row / Grid

Use these primitives for token-aware layout instead of hand-authoring repetitive padding, gap, and auto-size wiring.

Surface / surface

Use Surface for decorated containers and surface() when you only need host props for a given tone.

Composition Patterns

App root scaffolding

Wrap the top-level UI in SystemProvider, then build screens with Stack, Row, Grid, and Surface so density changes propagate cleanly.

Adaptive settings panels

Use useSystemTheme to switch theme or density in response to player settings without bypassing the shared UI model.

Cautions / Limits

  • system assumes you want one coherent app-wide UI context; if you skip the provider, density-aware behavior and theme coordination disappear.
  • Density is intentionally constrained to compact, comfortable, and spacious rather than an open-ended arbitrary scale.