@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.
import { defaultDarkTheme, Text } from "@lattice-ui/style";
import {
Row,
Stack,
Surface,
SystemProvider,
useSystemTheme,
} from "@lattice-ui/system";
function SystemDemo() {
const { density, setDensity, theme } = useSystemTheme();
return (
<Surface tone="surface">
<Stack gap={12} padding={16}>
<Text
BackgroundTransparency={1}
Text={`System density: ${density}`}
TextColor3={theme.colors.textPrimary}
TextSize={theme.typography.bodyMd.textSize}
TextXAlignment={Enum.TextXAlignment.Left}
/>
<Row gap={8}>
{(["compact", "comfortable", "spacious"] as const).map(
(nextDensity) => (
<textbutton
key={nextDensity}
AutoButtonColor={false}
BackgroundColor3={
density === nextDensity
? theme.colors.accent
: theme.colors.surfaceElevated
}
BorderSizePixel={0}
Size={UDim2.fromOffset(108, 34)}
Text={nextDensity}
TextColor3={
density === nextDensity
? theme.colors.accentContrast
: theme.colors.textPrimary
}
TextSize={theme.typography.labelSm.textSize}
Event={{ Activated: () => setDensity(nextDensity) }}
>
<uicorner CornerRadius={new UDim(0, theme.radius.md)} />
</textbutton>
),
)}
</Row>
</Stack>
</Surface>
);
}
export function SystemExample() {
return (
<SystemProvider
defaultDensity="comfortable"
defaultTheme={defaultDarkTheme}
>
<SystemDemo />
</SystemProvider>
);
} 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 systemPublic Exports
-
DensityProvider -
useDensity -
applyDensity -
density -
Grid -
Row -
Stack -
surface -
Surface -
SystemProvider -
useSystemTheme
State Model
SystemProviderowns two coordinated values: the rawbaseThemeand the current density token.useSystemThemeexposes the density-resolvedthemefor reading, plus setters forbaseThemeanddensity.- 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
systemassumes 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, andspaciousrather than an open-ended arbitrary scale.