The current layer model
foundation
This layer defines tokens, dark mode, presets, accent sets, radius, density, shadow, font, border, reset, element-level rules, and the default styling for raw HTML such as headings and code.
utilities
Use utilities for small adjustments after the main pattern and primitive decisions are already correct. Spacing, text sizing, alignment, color, and visibility helpers live here.
layout
This layer contains container, stack, cluster, split, grid, row/column, navbar, sidebar, and shell structure. It solves frame and flow, not button-level UI.
primitives + surfaces
Buttons, forms, tables, dropdowns, drawers, modals, and tabs are primitives. Cards, stats, callouts, lists, toolbars, filter bars, and empty states are surfaces. Public classification follows UI role, not folder name.
patterns
Patterns define real page jobs such as dashboard shell, auth shell, settings shell, content shell, and marketing surfaces.
icons
Icons are delivered as class-based assets and aliases in this guide. They support primitives and patterns rather than acting as a separate UI layer.
Build order matters
The package build order is intentional. Later layers rely on earlier layers already being present.
- foundation
- utilities
- layout
- primitives
- patterns
- icons
Do not flatten the layer model If a class primarily defines page structure, keep it in layout or patterns. If it is an atomic control, keep it in primitives. If it is a framed content region, treat it as a surface. If it only nudges spacing or text alignment, keep it in utilities.
What this site is not doing
No custom classes
Every class used in docs/ comes from the shipped package CSS.
No style scripts
Layout, spacing, and presentation are left to CSS. No JavaScript is added to fake CSS concerns.
No behavior CSS
Overlays, tabs, drawers, dropdowns, and theme switching rely on shipped JavaScript hooks instead of CSS hacks.