Docs · Guide

Styling

Every visual value in astro-ui is a CSS custom property. There is no theme config — the tokens are the theming API.

The token model

Tokens live on :root (light) and[data-theme="dark"], grouped by role:

:root {
  /* surfaces */
  --ui-background: #ffffff;
  --ui-foreground: #18181b;
  --ui-muted: #f4f4f5;
  --ui-border: #e4e4e7;

  /* brand */
  --ui-primary: #2563eb;
  --ui-primary-foreground: #ffffff;

  /* feedback */
  --ui-success: #16a34a;
  --ui-warning: #d97706;
  --ui-error: #dc2626;

  /* shape & type */
  --ui-radius-md: 0.5rem;
  --ui-text-sm: 0.875rem;
  --ui-space-4: 1rem;
}

Components never hard-code colors — they read tokens. Variant classes (aui-badge--success, for example) just point at a different token.

Overriding tokens

Set the variables anywhere after the token import — your global CSS, a page, or an element. One override re-skins everything that reads it:

:root {
  --ui-primary: oklch(0.55 0.21 264);
  --ui-radius-md: 0.75rem;
}

Themed badge

(These two are themed by this site's brand layer — the same mechanism, overriding --ui-primary.)

Token playground

Edit any token and watch the preview panel — buttons, badges, an alert, a progress bar, and a donut cut from the chart palette. Overrides apply to the preview only (light theme), and the output is copy-ready CSS for your own stylesheet.

Surfaces

--ui-background

--ui-foreground

--ui-secondary

--ui-secondary-foreground

--ui-secondary-hover

--ui-muted

--ui-muted-foreground

--ui-border

--ui-border-width

--ui-input

--ui-ring

--ui-carbon

--ui-carbon-foreground

--ui-card

--ui-backdrop

--ui-backdrop-strong

--ui-progress-stripe

--ui-shadow-color

Brand

--ui-primary

--ui-primary-foreground

--ui-primary-hover

--ui-accent

--ui-accent-foreground

Feedback

--ui-success

--ui-success-foreground

--ui-success-muted

--ui-warning

--ui-warning-foreground

--ui-warning-muted

--ui-error

--ui-error-foreground

--ui-error-muted

--ui-info

--ui-info-foreground

--ui-info-muted

Chart

--ui-chart-1

--ui-chart-2

--ui-chart-3

--ui-chart-4

--ui-chart-5

--ui-chart-6

Rating

--ui-rating-1

--ui-rating-2

--ui-rating-3

--ui-rating-4

--ui-rating-5

Type

--ui-font-sans

--ui-font-mono

--ui-font-normal

--ui-font-medium

--ui-font-semibold

--ui-font-bold

--ui-text-2xs

--ui-text-xs

--ui-text-sm

--ui-text-md

--ui-text-base

--ui-text-lg

--ui-text-xl

--ui-text-2xl

--ui-text-3xl

--ui-leading-none

--ui-leading-tight

--ui-leading-normal

Shape & space

--ui-radius-none

--ui-radius-sm

--ui-radius-md

--ui-radius-lg

--ui-radius-xl

--ui-radius-full

--ui-corner-shape

--ui-space-0

--ui-space-0-5

--ui-space-1

--ui-space-2

--ui-space-3

--ui-space-4

--ui-space-5

--ui-space-6

--ui-space-7

--ui-space-8

--ui-space-10

--ui-space-12

--ui-disabled-opacity

Controls

--ui-control-height-xs

--ui-control-height-sm

--ui-control-height-md

--ui-control-height-lg

--ui-control-height-xl

--ui-control-padding-xs

--ui-control-padding-sm

--ui-control-padding-md

--ui-control-padding-lg

--ui-control-padding-xl

--ui-control-radius

Elevation & motion

--ui-shadow-sm

--ui-shadow-md

--ui-shadow-lg

--ui-shadow-xl

--ui-transition-fast

--ui-transition-normal

--ui-transition-slow

--ui-transition-delay

--ui-z-dropdown

--ui-z-dialog

--ui-z-popover

--ui-z-toast

--ui-z-tooltip

--ui-focus-ring-width

--ui-focus-ring-offset

PrimaryActivePendingFailedNew

Heads up

Scheduled maintenance Sunday 02:00–04:00 UTC.

Uploading

Palette

Category	Share
One	22
Two	18
Three	16
Four	14
Five	12
Six	18

No changes yet

/* Edit a token — overrides appear here as copy-ready CSS. */

Dark mode needs the same overrides under[data-theme="dark"] — this preview is light-only.

Dark mode

Dark values live under [data-theme="dark"]. Flip the attribute — before paint, to avoid a flash:

<script is:inline>
  const saved = localStorage.getItem("theme");
  if (saved) document.documentElement.dataset.theme = saved;
</script>

Utility classes

Components style themselves from tokens; compose layouts with your own utilities. The demo site uses a small utility layer plus Tailwind where convenient — but nothing in the library requires Tailwind. Class merging (the class prop on every component) keeps overrides clean.