Guidelines

How we build interfaces with Flux UI — match these rules and your screens will feel native to the system.

Design tokens

Prefer semantic utilities: bg-background, text-muted-foreground, border-border, bg-primary. They map to CSS variables (--background, --primary, …) so light and dark stay consistent. Avoid hard-coded hex in primitives unless you are defining a token.

Tailwind v4

Use @import "tailwindcss"; and @theme inline to bridge variables to utilities. Point @source at @flux/ui src/**/*.tsx so classes inside the package are generated.

Composition

Build forms with Field, FieldLabel, and FieldError; wrap inputs with InputGroup when you need prefixes or actions. Use Dialog and overlay primitives for focus-heavy tasks.

Accessibility

Keep labels associated with controls, preserve focus rings (token --ring), and test keyboard paths for dialogs, menus, and selects. Tooltips require a TooltipProvider ancestor.

Dark mode

Use class="dark" on the root (e.g. via next-themes) with the .dark variable overrides. Every primitive on this site is checked in both themes.