Foundations

Getting Started

Install Lunar Aurora via npm or include it via CDN — no build step required. Works with any HTML project out of the box.

ℹ

Lunar Aurora requires no dependencies. It runs purely on modern CSS features — OKLCH, CSS Nesting, Container Queries and @property.

shell

# Via npm
npm install lunar-aurora

# Via pnpm / yarn
pnpm add lunar-aurora
yarn add lunar-aurora

html

<!-- Import CSS -->
<link rel="stylesheet" href="node_modules/lunar-aurora/dist/aurora.css">

<!-- Import JS (headless components) -->
<script src="node_modules/lunar-aurora/dist/aurora.js" defer></script>

<!-- Apply a theme -->
<html data-theme="dark">

✦

All class names are prefixed with la- to avoid conflicts with other frameworks.

Foundations

Design Tokens

All visual values are exposed as CSS custom properties on :root — colors, spacing, radii, shadows, and typography scales.

Token	Value	Preview
--la-color-primary	oklch(52% 0.28 280)
--la-color-secondary	oklch(66% 0.2 200)
--la-color-accent	oklch(62% 0.28 340)
--la-surface-0	oklch(8% 0.02 280)
--la-radius-md	10px	—
--la-space-4	1rem (16px)	—
--la-font-body	'Space Grotesk', system-ui	—
--la-font-mono	'JetBrains Mono', monospace	—

css

/* Override tokens at root level */
:root {
  --la-color-primary: oklch(58% 0.3 270);
  --la-radius-md: 14px;
  --la-font-body: 'Inter', sans-serif;
}

Foundations

Typography

A fluid typographic scale with utility classes for size, weight, and font family. Uses clamp() for responsive sizing.

Preview

.la-text-5xl Display

.la-text-3xl Heading 1

.la-text-xl Heading 2

.la-text-base Body text — the quick brown fox jumps over the lazy dog.

.la-text-sm Caption text for secondary information

.la-font-mono const aurora = 'beautiful'

html

<h1 class="la-text-5xl la-font-display la-font-bold">Display</h1>
<h2 class="la-text-3xl la-font-semibold">Heading 1</h2>
<p  class="la-text-base la-text-muted">Body paragraph</p>
<code class="la-font-mono la-text-sm">Monospace</code>

Layout

Grid

A 12-column CSS Grid system with responsive column utilities. Combines with container queries for truly component-scoped layouts.

Preview

.la-col-12

.la-col-6

.la-col-4

html

<div class="la-grid">
  <div class="la-col-4">One third</div>
  <div class="la-col-4">One third</div>
  <div class="la-col-4">One third</div>
</div>

<!-- Columns: 1, 2, 3, 4, 6, 8, 9, 10, 12 -->
<!-- Responsive: la-col-sm-6, la-col-md-4 -->

Layout

Flexbox

Utility classes for flex layouts — direction, alignment, gap, wrapping. Combine freely for quick one-line layouts.

Preview — .la-flex .la-items-center .la-gap-3 .la-justify-between

Left Center flex item Right

html

<div class="la-flex la-items-center la-gap-3 la-justify-between">
  <span>Left</span>
  <span>Center</span>
  <span>Right</span>
</div>

<!-- Directions: la-flex-col, la-flex-row -->
<!-- Align: la-items-start, center, end, stretch -->
<!-- Justify: la-justify-start, center, end, between, around -->
<!-- Gap: la-gap-1 … la-gap-16 -->

Layout

Container Queries

Lunar Aurora leverages CSS Container Queries to make components responsive to their parent's size — not the viewport. Add la-container to any wrapper.

ℹ

Container Queries are supported in all modern browsers (Chrome 105+, Firefox 110+, Safari 16+).

html

<!-- Mark a container -->
<div class="la-container">
  <div class="la-card la-cq-md:la-flex">
    <!-- Switches to flex when container > 640px -->
  </div>
</div>

css

/* Generated internally by Lunar Aurora */
.la-container {
  container-type: inline-size;
}

@container (min-width: 640px) {
  .la-cq-md\:la-flex { display: flex; }
}

Components

Buttons & Badges

Accessible, themeable button variants and badge components. All transitions use cubic-bezier easing for polish.

Button variants

Button sizes

Badges

Aurora Cyan Pink Green

html

<!-- Buttons -->
<button class="la-btn la-btn-primary">Primary</button>
<button class="la-btn la-btn-secondary">Secondary</button>
<button class="la-btn la-btn-ghost">Ghost</button>
<button class="la-btn la-btn-primary la-btn-sm">Small</button>
<button class="la-btn la-btn-primary la-btn-lg">Large</button>

<!-- Badges -->
<span class="la-badge la-badge-violet">Aurora</span>
<span class="la-badge la-badge-cyan la-badge-dot">Live</span>

Components

Cards

Versatile card component with optional header, body, and footer slots. Hover state elevates the card with a subtle glow.

Preview

Mooncat Card New

A clean card component with header, body, and footer slots. Uses glass morphism by default.

🌙

Simple Card

No header or footer needed — body-only works great too.

html

<div class="la-card">
  <div class="la-card-header">
    <span class="la-card-title">Title</span>
    <span class="la-badge la-badge-violet">New</span>
  </div>
  <div class="la-card-body">
    Content goes here.
  </div>
  <div class="la-card-footer">
    <button class="la-btn la-btn-primary la-btn-sm">Action</button>
  </div>
</div>

Components

Forms

Form controls styled to match the dark aesthetic — inputs, selects, checkboxes, and textareas. Focus rings use OKLCH colors for accessibility.

Preview

Email address

Theme

html

<div class="la-form-group">
  <label class="la-label" for="email">Email</label>
  <input class="la-input" id="email" type="email" placeholder="...">
</div>

<div class="la-form-group">
  <label class="la-label">Select</label>
  <select class="la-select">
    <option>Option 1</option>
  </select>
</div>

<!-- Also available: la-textarea, la-checkbox, la-radio, la-toggle -->

Components

Modals

Headless modal dialogs powered by data-la-modal attributes. Supports keyboard navigation, focus trap, and backdrop click to close.

Preview (static)

html

<!-- Trigger -->
<button class="la-btn la-btn-primary"
        data-la-modal-open="my-modal">
  Open Modal
</button>

<!-- Dialog -->
<dialog class="la-modal" id="my-modal">
  <div class="la-modal-box">
    <h2 class="la-modal-title">Title</h2>
    <div class="la-modal-body">Content</div>
    <div class="la-modal-footer">
      <button data-la-modal-close>Close</button>
    </div>
  </div>
</dialog>

Components

Tabs & Accordions

Accessible tab and accordion components driven by aria-* attributes. No JS configuration needed — the framework handles state automatically.

Tabs

Lunar Aurora components are headless — they provide structure and behavior, not style. Customize freely with utility classes.

Accordion

What browsers are supported? ▼

All modern browsers: Chrome 105+, Firefox 110+, Safari 16+, Edge 105+. IE is not supported.

Can I use it with React / Vue? ▼

Yes — Lunar Aurora is pure CSS + vanilla JS. Use the classes directly in JSX or templates.

html

<!-- Tabs -->
<div class="la-tabs">
  <div class="la-tabs-nav" role="tablist">
    <button class="la-tab" role="tab">Tab 1</button>
    <button class="la-tab" role="tab">Tab 2</button>
  </div>
  <div class="la-tab-panel" role="tabpanel">Content</div>
</div>

<!-- Accordion -->
<div class="la-accordion">
  <div class="la-accordion-item">
    <button class="la-accordion-trigger" aria-expanded="false">
      Question? <span class="chevron">▼</span>
    </button>
    <div class="la-accordion-content">
      <div class="la-accordion-body">Answer.</div>
    </div>
  </div>
</div>

Advanced

Themes

Apply any of 30+ themes with a single data-theme attribute on any element. Themes cascade — nest them for local overrides.

dark

cyberpunk

aurora

hacker

pastel

retro

slate

amber

html

<!-- Global theme -->
<html data-theme="dark">

<!-- Component-level override -->
<div data-theme="cyberpunk">
  <div class="la-card">Cyber card</div>
</div>

<!-- Switch theme with JS -->
<script>
  document.documentElement.dataset.theme = 'aurora';
</script>

<!-- Available: dark · light · cyberpunk · aurora · hacker
              pastel · retro · slate · amber · ocean · +20 more -->

Advanced

Utilities

A comprehensive set of utility classes for spacing, display, overflow, opacity, cursor, and more. All prefixed with la-.

.la-hidden display: none

.la-sr-only Visually hidden, screen reader visible

.la-truncate text-overflow: ellipsis

.la-rounded-full border-radius: 9999px

.la-overflow-hidden overflow: hidden

.la-pointer cursor: pointer

.la-opacity-50 opacity: 0.5

.la-glass Glassmorphism preset

.la-gradient-text Gradient fill on text

.la-m-{n} margin (0–16)

.la-p-{n} padding (0–16)

.la-w-full width: 100%

html

<!-- Spacing utilities -->
<div class="la-p-4 la-m-2">...</div>

<!-- Glassmorphism -->
<div class="la-glass la-rounded-full la-p-4">...</div>

<!-- Gradient text -->
<h1 class="la-gradient-text la-text-3xl la-font-bold">
  Glow Up
</h1>

Advanced

Icons

Inline SVG icons bundled as CSS classes. No external fonts, no external requests. Used via .la-icon-* or the <la-icon> web component.

🌙 moon

✦ star

⚡ zap

◉ circle

▭ rect

⬡ hex

✏ edit

⊞ grid

↔ arrows

≡ menu

⬆ arrow-up

✕ close

html

<!-- CSS class approach -->
<span class="la-icon la-icon-moon" aria-hidden="true"></span>

<!-- Web component approach -->
<la-icon name="moon" size="20"></la-icon>

<!-- Inside a button -->
<button class="la-btn la-btn-primary">
  <la-icon name="star"></la-icon>
  Favorite
</button>