Skip to main content
196

Search Lumen

Find components, APIs, guides, and recipes.

GitHub
Web docs
Web documentation

Build once. Use Lumen everywhere.

Accessible primitives, shared tokens, and component-specific CSS. Pick a framework below; use its native behavior and load the components your product needs.

196components
3framework targets
1shared foundation

Glass system

Built from Lumen primitives
Live
AstroReference implementation@santi020k/lumen-astro
ReactAdapter primitives@santi020k/lumen-react
ElementsCustom elements@santi020k/lumen-elements
1

Install a runtime adapter

Choose Astro, React, or Elements. Add the optional Lumen CLI separately as a development dependency.

2

Load component styles

Astro v5 imports CSS automatically. React and Elements use the shared foundation plus selected component CSS.

3

Use framework behavior

Mount the Astro runtime once, use React controllers, or register the required custom elements.

Start here

Install and use

Upgrading an existing application? Follow the v4 → v5 migration guide before changing dependencies or removing full CSS.

pnpm

bash
pnpm add @santi020k/lumen-astro

npm

bash
npm install @santi020k/lumen-astro

yarn

bash
yarn add @santi020k/lumen-astro

V5 Astro components import their own CSS. Install @santi020k/lumen separately as a development dependency for CLI commands. Mount UIPrimitives once in your root layout only if you use interactive primitives; do not add it beside every component.

astro
---
import { Button, Card, Input, Label } from '@santi020k/lumen-astro'
---

<Card>
  <Label for="email">Email</Label>
  <Input id="email" type="email" placeholder="you@example.com" />
  <Button>Subscribe</Button>
</Card>

Framework contracts

Framework-specific guidance

Lumen keeps one visual contract, but each target has its own integration surface for behavior, local wrappers, and registration.

Astro

@santi020k/lumen-astro
  • Reference implementation for markup, props, automatic component CSS, and selective progressive enhancement.
  • In v5, await LumenInitUiPrimitives(scope); ui:ready follows completion and ui:runtime-error reports failed enhancement.
  • Mount UIPrimitives once in the root layout for interactive primitives and CustomEvents.
  • Use lumen add Component or lumen add recipe-name --target astro when you want local .astro starter files.

React

@santi020k/lumen-react
  • React components mirror the same ui-* classes, data attributes, and prop names where React naming allows it.
  • DataTable renders the same structured row contract and VirtualList provides built-in fixed-height windowing.
  • Use React hooks such as useDialog, usePopover, useDropdownMenu, useContextMenu, useTabs, useSelect, useFormValidation, useCalendar, useInputOTP, useDateRangePicker, useRichTextEditor, useSchedule, useKanban, useResizable, useThemeBuilder, useThemeToggle, useToast, and useTooltip for behavior-heavy primitives.
  • Use lumen add Component --target react or lumen add recipe-name --target react when you want local .tsx starter files.

Elements

@santi020k/lumen-elements
  • Custom elements expose the shared class and data contract through lumen-* tags that work in plain HTML or any framework.
  • Call defineLumenElements once before using the tags; behavior-backed elements include DataTable selection/sort, form validation, calendar grids, OTP segmentation, date range syncing, rich text commands, context menu triggers, schedule drag/drop and file drag/drop, tours, anchor scroll spy, transfer, mentions, cascader and tree selection, resizable pane sizing, ThemeBuilder export, VirtualList range events, overlays, tabs, tooltip, and toast.
  • For Badge, Button, and Card-only surfaces, use their @santi020k/lumen-elements/components/* entrypoints to avoid bundling the complete catalog.
  • Use lumen add Component --target elements or lumen add recipe-name --target elements when you want local Elements starter files.

Component CSS

Choose your style setup

Astro v5 imports component styles automatically. React and Elements load the foundation once and each used component stylesheet. Full CSS remains supported; Tailwind is optional.

Astro + Tailwind

Astro v5 components import their own CSS. Keep the layer order and optional Tailwind bridge in the shared entry.

css
@import "@santi020k/lumen-astro/layers.css";
@import "tailwindcss";
@import "@santi020k/lumen-astro/tailwind.css";

Selective component CSS

Load the foundation once and each used component stylesheet. Include conditional and compound content. Elements exposes the same CSS paths.

ts
import '@santi020k/lumen-react/styles/foundation.css'
import '@santi020k/lumen-react/styles/components/button.css'
import { Button } from '@santi020k/lumen-react/components/button'

Full CSS alternative

Full styles.css remains a supported convenience option in every adapter. Retain it during migration until every route has equivalent coverage.

ts
import '@santi020k/lumen-react/styles.css'

Token contract

Themes

Lumen includes light and dark schemes. Paper adds warm surfaces and serif article headings. Field uses sage and pine with rounded controls. Import thestylesheet for your chosen themeand select it on the whole page or a section.

Light · same components, different tokens
Workspace settingsActive
Dark · same components, different tokens
Workspace settingsActive

Illustrative previews · buttons do not save data. Try your own palette in the theme playground.

Default themes

Omit data-theme or set data-theme="light" for the default light theme; set data-theme="dark" for the built-in dark theme.

html
<html data-theme="light">
  <body>...</body>
</html>

<html data-theme="dark">
  <body>...</body>
</html>

Runtime switch

Switch themes by updating document.documentElement.dataset.theme; components read the CSS variables from the root element.

ts
const nextTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
  ? 'dark'
  : 'light'

document.documentElement.dataset.theme = nextTheme

santi020k website theme

Import the website appearance once, then set data-theme="santi020k-light" or data-theme="santi020k-dark" on html. Switch the docs theme family to santi020k to see the same card change.

css
@import "@santi020k/lumen-astro/styles/themes/santi020k.css";

Surface system

Glassmorphism surfaces

Glass is a surface treatment, not a theme: shared tokens control blur, saturation, borders, and highlights, with fallbacks for browsers without backdrop-filter support.

Workspace

Launch window

The same content on three surface treatments.

Solid surface<Card>
Workspace

Launch window

The same content on three surface treatments.

Subtle glass<Card glass="subtle">
Workspace

Launch window

The same content on three surface treatments.

Strong glass<Card glass="strong">

Astro card

Use the glass prop for standalone content surfaces.

astro
<Card glass>
  <h2>Launch window</h2>
  <p>Shared glass tokens.</p>
</Card>

Overlay surface

Use the same glass prop for overlays without changing their semantics.

astro
<Popover glass>
  <Button data-ui-trigger>
    Invite
  </Button>
  <div>
    <Input type="email" />
  </div>
</Popover>

Elements

Elements support glass with a boolean attribute.

html
<lumen-card glass>
  <h2>Production</h2>
  <p>Same class contract.</p>
</lumen-card>

Package map

Packages

Astro

Reference

@santi020k/lumen-astro

Reference implementation of the full primitive catalog, shared CSS, and progressive-enhancement runtime.

React

Full catalog

@santi020k/lumen-react

React implementation of the full primitive catalog using the shared class, token, and data contract.

Elements

Full catalog

@santi020k/lumen-elements

Standards-based implementation of the full primitive catalog using the shared class, token, and data contract.

Core

Shared foundation

@santi020k/lumen-core

Design tokens, component metadata, and utilities shared by every framework implementation.

Behavior layer

Progressive-enhancement runtime

Mount UIPrimitives once in your Astro root layout to wire every interactive primitive. Static components never need it, and component snippets assume the root layout already owns that runtime include.

Switch content

Try the tabs

Focus a tab and use the arrow keys to switch views.

Your workspace is ready.

No new activity today.

Tabs API and examples
Open an overlay

Try the dialog

Open help, press Escape to dismiss it, then check where focus returns.

Workspace help

Keep your team settings in one place.

Dialog API and examples
Native HTML behavior

Try the disclosure

Click the question or focus it and press Enter. This also works without JavaScript.

Does this need JavaScript?

Native details can open and close without the runtime.

Accordion API and examples

Copy a demo · Astro snippets assume styles and UIPrimitives are already mounted in your root layout.

astro
---
import { Tabs, TabsList, TabsPanel, TabsTrigger } from '@santi020k/lumen-astro'
---

<Tabs initialValue="overview">
  <TabsList aria-label="Workspace view">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
  </TabsList>
  <TabsPanel value="overview">
    <p>Your workspace is ready.</p>
  </TabsPanel>
  <TabsPanel value="activity">
    <p>No new activity today.</p>
  </TabsPanel>
</Tabs>
More runtime behaviors

Dialogs and sheets

Trigger, dismiss, escape-key, and focus behavior for modal surfaces.

Menus and popovers

Lightweight disclosure patterns for contextual actions and floating content.

Tabs and command lists

Progressively enhanced keyboard navigation and client-side filtering.

Toasts and carousel controls

Document-level behavior for transient feedback and slide navigation.

Next steps

Every component page includes a live preview plus code for all three targets.

Web docsFull catalog