Styling Aurora UIX in a Host Application

Aurora UIX renders all of its generated components against a set of --auix-* CSS custom properties. This guide shows how to align those properties with your host application's design system — either by remapping them through a style bridge file or by overriding individual tokens directly — without touching any library source.

The five files and their cascade layers

Running mix auix.gen.stylesheet writes the following files and declares the layer order auix.baseline → auix.variables → auix.bridge → auix.rules:

The library regenerates auix-variables.css and auix-rules.css on every mix auix.gen.stylesheet run. The bridge, custom, and baseline files are host-owned: the task copies or creates them on first run (each behind its own opt-in flag where applicable) and skips them on subsequent runs unless --force is passed.

Choosing an integration path

Variables + rules only. Import auix-variables.css and auix-rules.css directly (or the auix-stylesheet.css shim). The components render using Aurora UIX's built-in defaults with no host-theme integration. This is the fastest path to a working UI.

Non-Tailwind hosts: add auix-baseline.css. Plain CSS apps, vanilla Phoenix apps, and Web Component hosts have no preflight to normalise html, body, and a. Generate the opt-in baseline stylesheet with mix auix.gen.stylesheet --baseline, then import it before auix-variables.css. Tailwind v4 hosts already ship a preflight and must skip this file — see Hosts without Tailwind below.

Bridge. Add the daisyUI bridge (auix-bridge-daisyui.css) or write your own. The bridge maps your framework's semantic tokens onto --auix-* variables so every component follows theme changes (dark mode, brand tokens, etc.) automatically. See Writing a Style Bridge for authoring guidance.

Recommended: style bridge + auix-custom.css. For hosts that already use a style bridge but need a few additional per-project tweaks, an auix-custom.css file provides a safe override layer that sits at the same cascade level as the style bridge. Token overrides written here take effect without modifying either library file. Run mix auix.gen.stylesheet --custom to scaffold the stub on first use.

Escape hatch: semantic class overrides. When a desired visual change cannot be expressed with a token override (e.g. restructuring flex layout), you can override .auix-* class rules directly. This is intentionally last-resort; see Escape hatch: semantic class overrides.

Recommended path: variable overrides

Import order

@import "auix-variables.css";
@import "auix-bridge-daisyui.css";  /* or your custom bridge */
@import "auix-custom.css";          /* host customizations (opt-in via --custom) */
@import "auix-rules.css";

Scaffolding auix-custom.css

Run the following to create the stub on first use:

mix auix.gen.stylesheet --custom

The file is treated as host-owned and will not be overwritten on subsequent runs. Pass --force together with --custom to regenerate it from the current theme defaults:

mix auix.gen.stylesheet --custom --force

Without --custom, the task never creates this file, so hosts that do not need it stay clean.

Wrapping pattern

All overrides must live inside @layer auix.bridge to win over auix.variables but lose to auix.rules (which provides the final component rules):

@layer auix.bridge {
  :root, :host {
    --auix-border-radius-default: 0.75rem;
    --auix-color-focus-ring: #7C3AED; /* violet-600 */
  }
}

Worked example: rounder corners + custom focus color

/* assets/css/auix-custom.css */
@layer auix.bridge {
  :root, :host {
    /* Round all component borders */
    --auix-border-radius-default: 0.75rem;
    --auix-border-radius-small:   0.375rem;
    --auix-border-radius-large:   1.25rem;

    /* Use a violet focus ring instead of the default indigo */
    --auix-color-focus-ring: #7C3AED;
  }
}

Both changes take effect for every generated form, table, and modal without modifying any library file.

Hosts without Tailwind

Tailwind v4 ships a preflight that resets html, body, a, and form elements. Plain CSS apps, vanilla Phoenix apps, and Web Component hosts have no such reset — without one, links render with browser-default purple+underline, body gets its default margin, and html loses the --auix-* font stack.

Scaffolding auix-baseline.css

auix-baseline.css is opt-in. Run:

mix auix.gen.stylesheet --baseline

The file is host-owned. Subsequent runs without --force leave it untouched. Pass --force together with --baseline to regenerate it from the current theme defaults:

mix auix.gen.stylesheet --baseline --force

Import order

Add one extra import before auix-variables.css:

@import "auix-baseline.css"; /* non-Tailwind hosts only */
@import "auix-variables.css";
@import "auix-bridge-daisyui.css";  /* or your custom bridge */
@import "auix-custom.css";          /* host customizations (opt-in via --custom) */
@import "auix-rules.css";

The reset uses the same --auix-* variables a bridge maps, so a style bridge still controls colours and typography — the baseline and style bridge complement each other. The reset sits in @layer auix.baseline, the lowest layer in the cascade, so both the style bridge and any rules-level overrides win over it.

Tailwind hosts: do not pass --baseline and do not import this file. Tailwind's preflight already normalises the same selectors, and double-resetting can produce subtle border and spacing regressions.

Variable reference

Sizes & dimensions

Typography

Opacity

Shadows & rings

Colors

Colors are theme-dependent. The defaults shown here are from the white_charcoal theme in light mode (the library default). Dark-mode variants are applied automatically via --dark--auix-* intermediate variables when the host sets up a dark-mode selector.

Backgrounds

Text

Borders & Focus

Icons

Shadows (color tokens)

Component aliases (derived from primitives above)

Recipe table

Common visual adjustments and the minimal set of variables to override:

Rule: one color class per element

An element may carry multiple CSS classes, but at most one of them may set color, background-color, or border-color. The classes ending in a BEM modifier (--alt, --errors, --iconized) and the named full-variant classes (.auix-index-all-action-button) are the color-bearing classes. Structural bases like .auix-button-default and size utilities like .auix-icon-size-5 are color-neutral and safe to combine freely with a color class.

When adding a brand variant, mirror the same pattern — declare a single class that sets color rules only (no padding, border-width, font-*, etc.) and let the component's structural base handle the rest:

/* ✅ Color-only variant — safe to layer on top of .auix-button-default */
.my-host-app .auix-button--promo {
  background-color: var(--my-brand-promo);
  color: var(--my-brand-promo-text);
}

Escape hatch: semantic class overrides

When a variable override cannot express the desired structural change — for example, switching a component's flex direction or inserting an additional layout layer — you can override the .auix-* class rules directly.

Warning: The class names listed below are a semi-public API. They may be renamed, split, or removed in any release without prior deprecation. Changes will be called out in CHANGELOG.md under a dedicated CSS class changes subsection. If you override these classes, you are accepting that responsibility. Prefer variable overrides whenever they can express the change.

Class reference

Scoping example

Scope overrides to a specific host section to avoid leaking into unrelated components:

/* Overrides the primary color variant only; sibling variants (.auix-button--alt,
   .auix-index-all-action-button) are unaffected and need their own override if
   matching brand color is desired there. */
.my-host-app .auix-button {
  background-color: var(--my-brand);
}

Verifying your overrides

• Inspect computed values. Open DevTools → Elements → Computed and search for --auix- to see the resolved values in context.
• Confirm layer precedence. In Chrome DevTools Styles pane, each rule shows its @layer. Check that your override is in auix.bridge and is not crossed out by a higher-specificity rule in auix.rules.
• Visual smoke-test. Navigate to a generated index, form, or show page in the dev server and verify the change is visible across components.
• For non-Tailwind hosts: confirm auix-baseline.css is imported by checking for @layer auix.baseline rules in the DevTools Styles pane on <html> or <body>. If absent, link styling will fall back to browser defaults; if you never generated the file, re-run mix auix.gen.stylesheet --baseline.