Philosophy

Roadie is the design system for Oztix applications. It exists to make building consistent, accessible, and beautiful UI the path of least resistance. Teams ship faster without sacrificing quality.

Core principles

Tailwind-native

Roadie is not a styling abstraction on top of Tailwind. It is Tailwind. Custom @utility directives extend Tailwind v4 with semantic color, emphasis, and interaction utilities. You write the same classes you already know, with a design-system vocabulary layered on top.

Intent and emphasis

This is the most important concept in Roadie.

Intent sets the color context. It picks what palette to use. Apply intent-accent, intent-danger, or intent-success to a container and every child inherits that palette automatically.

Emphasis sets the visual weight. It decides how prominent an element should be. emphasis-strong is a solid fill, emphasis-subtle is a light tint, emphasis-raised floats with a shadow.

Together they form a two-axis system: intent controls which color, emphasis controls how much color. See Colors and Interactions for full details.

Semantic over literal

You won't find bg-gray-100 or text-blue-500 in Roadie code. Instead, utilities like bg-normal, text-subtle, and border-subtle describe purpose, not appearance. These resolve differently depending on the active intent, light/dark mode, and theme. No conditional classes are needed.

See Tokens for the full set of semantic values.

CSS cascade, not prop drilling

Intent flows through the DOM via CSS custom properties. Wrap a section in intent-accent and every button, badge, and input inside it picks up the accent palette. There are no props to pass and no context providers to wire up. This keeps component APIs small and composable.

Accessible by default

Components are built on Base UI which provides keyboard navigation, focus management, and ARIA semantics out of the box. Roadie layers styling on top without breaking those guarantees. The foundation is always semantic HTML.

See Accessibility for guidelines and testing advice.

Fast by default

Theming is pure CSS. Colors, dark mode, and intent switching need zero JavaScript runtime. Components are tree-shakeable ESM. Typography scales fluidly with clamp() instead of breakpoint overrides.

See Performance for optimisation principles.

Key concepts

A quick map of the building blocks and where to learn more:

• Intent sets the color palette (neutral, brand, accent, danger, success, warning, info). See Colors.
• Emphasis presets set the visual weight (strong, normal, subtle, raised, floating, etc). See Colors.
• Semantic tokens are purpose-based CSS custom properties for background, text, and border. See Tokens.
• Layout is grid-first. grid gap-* is the default stack. flex is for content-driven rows. See Layout.
• Interaction utilities are is-interactive for buttons and is-interactive-field for inputs. See Interactions.
• The shape scale sets consistent border-radius tiers from inline to full. See Shape.

Next steps

• Installation shows how to install and configure Roadie in your project.
• Components lets you browse the component library.
• Foundations goes deep into the design foundations.