Docs · Guide

Design principles

The rules every component follows — so the library stays predictable as it grows. Each one is enforced by automated contract tests, not just good intentions.

Principles

  • Zero JS by default. Components render on the server and ship no client runtime. A dozen interactive components (dialog, carousel, toast…) carry small scoped scripts; everything else is pure HTML + CSS. Each component page states its JavaScript requirement up front.
  • Tokens are the theming API. Every color, radius, space, and type size is a --ui-* custom property. There is no theme config — override a variable and every component that reads it follows, in light and dark mode. Try it in the token playground.
  • Accessibility is structural. Semantic elements first, WAI-ARIA patterns where natives fall short (tabs, dialogs), visible focus rings, and a screen-reader path for every chart. Accessibility notes ship on each component page.
  • Small composable primitives. One component per file, slots for structure, and a class prop on everything for escape hatches — instead of a prop for every CSS knob. Shared prop names (variant,size, disabled) mean learning one component teaches you the next.
  • Docs checked by tests. Props, tokens, SSR safety, and markup rules are asserted by contract suites, so documentation drift fails the build instead of rotting silently.
  • Framework-agnostic output. Plain.astro plus CSS — no React, Vue, or client framework bundled. Use components as Astro islands or plain server-rendered markup.

Deliberate differences

Two places where astro-ui consciously diverges from the common folder-per-component convention:

  • Category folders, not folders per component.Components live in general/,forms/, data-display/ and similar, exported from one root entry with per-component subpaths — one import style to learn, tree-shakable by construction.
  • Own naming. Classes use theaui- prefix and props follow a fixed vocabulary (variant, size,ariaLabel) rather than mirroring an external registry — so examples never silently depend on another system's conventions.