# Philosophy

> The core goals, principles, and mental model behind the Roadie Design System.

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](https://ticketsolutionsptyltd.github.io/roadie/foundations/colors.md)
and [Interactions](https://ticketsolutionsptyltd.github.io/roadie/foundations/interactions.md) 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](https://ticketsolutionsptyltd.github.io/roadie/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](https://base-ui.com/) 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](https://ticketsolutionsptyltd.github.io/roadie/foundations/accessibility.md) 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](https://ticketsolutionsptyltd.github.io/roadie/foundations/performance.md) 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](https://ticketsolutionsptyltd.github.io/roadie/foundations/colors.md).
- Emphasis presets set the visual weight (`strong`, `normal`, `subtle`,
  `raised`, `floating`, etc). See [Colors](https://ticketsolutionsptyltd.github.io/roadie/foundations/colors.md).
- Semantic tokens are purpose-based CSS custom properties for
  background, text, and border. See [Tokens](https://ticketsolutionsptyltd.github.io/roadie/tokens/).
- Layout is grid-first. `grid gap-*` is the default stack. `flex`
  is for content-driven rows. See [Layout](https://ticketsolutionsptyltd.github.io/roadie/foundations/layout.md).
- Interaction utilities are `is-interactive` for buttons and
  `is-interactive-field` for inputs. See
  [Interactions](https://ticketsolutionsptyltd.github.io/roadie/foundations/interactions.md).
- The shape scale sets consistent border-radius tiers from inline to
  full. See [Shape](https://ticketsolutionsptyltd.github.io/roadie/foundations/shape.md).

## Next steps

- [Installation](https://ticketsolutionsptyltd.github.io/roadie/overview/getting-started.md) shows how to install and
  configure Roadie in your project.
- [Components](https://ticketsolutionsptyltd.github.io/roadie/components.md) lets you browse the component library.
- [Foundations](https://ticketsolutionsptyltd.github.io/roadie/foundations/colors.md) goes deep into the design
  foundations.

Docs updated 23 Sept 2026.