Architecture

WebBlocks UI is intentionally layered so that tokens, structure, visible building blocks, and full-screen compositions do not blur together.

The current layer model

foundationtokens and theme axes
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.
utilitiessmall helper classes
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.
layoutcontainers and structural flow
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 + surfacescontrols and framed content regions
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.
patternsscreen-level compositions
Patterns define real page jobs such as dashboard shell, auth shell, settings shell, content shell, and marketing surfaces.
iconsasset layer
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.

  1. foundation
  2. utilities
  3. layout
  4. primitives
  5. patterns
  6. 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.