Install a runtime adapter
Choose Astro, React, or Elements. Add the optional Lumen CLI separately as a development dependency.
Accessible primitives, shared tokens, and component-specific CSS. Pick a framework below; use its native behavior and load the components your product needs.
Glass system
Built from Lumen primitives@santi020k/lumen-astro@santi020k/lumen-react@santi020k/lumen-elementsChoose Astro, React, or Elements. Add the optional Lumen CLI separately as a development dependency.
Astro v5 imports CSS automatically. React and Elements use the shared foundation plus selected component CSS.
Mount the Astro runtime once, use React controllers, or register the required custom elements.
Start here
Upgrading an existing application? Follow the v4 → v5 migration guide before changing dependencies or removing full CSS.
pnpm
pnpm add @santi020k/lumen-astronpm
npm install @santi020k/lumen-astroyarn
yarn add @santi020k/lumen-astroV5 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.
---
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>pnpm
pnpm add @santi020k/lumen-reactnpm
npm install @santi020k/lumen-reactyarn
yarn add @santi020k/lumen-reactInstall the runtime adapter; add @santi020k/lumen separately for the optional CLI. Load foundation and component CSS, or retain full styles.css. React ships the same styled markup and data contract, including data-display, overlay, form, rich text, and schedule attributes; use hooks for behavior-heavy primitives.
import '@santi020k/lumen-react/styles/foundation.css'
import '@santi020k/lumen-react/styles/components/card.css'
import '@santi020k/lumen-react/styles/components/input.css'
import '@santi020k/lumen-react/styles/components/label.css'
import '@santi020k/lumen-react/styles/components/button.css'
import { Button, Card, Input, Label } from '@santi020k/lumen-react'
export function SubscribeForm() {
return (
<Card>
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" placeholder="you@example.com" />
<Button>Subscribe</Button>
</Card>
)
}pnpm
pnpm add @santi020k/lumen-elementsnpm
npm install @santi020k/lumen-elementsyarn
yarn add @santi020k/lumen-elementsInstall the runtime adapter; add @santi020k/lumen separately for the optional CLI. Load foundation and component CSS and register each used element. This example imports the registration catalog and registers only the listed elements. Use public components/<name> registrations where available to reduce the dependency graph; registration scope alone does not prove selective JavaScript delivery.
<script type="module">
import '@santi020k/lumen-elements/styles/foundation.css'
import '@santi020k/lumen-elements/styles/components/card.css'
import '@santi020k/lumen-elements/styles/components/label.css'
import '@santi020k/lumen-elements/styles/components/input.css'
import '@santi020k/lumen-elements/styles/components/button.css'
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements(['Card', 'Label', 'Input', 'Button'])
</script>
<lumen-card>
<lumen-label id="email-label">Email</lumen-label>
<lumen-input aria-labelledby="email-label" id="email" type="email" placeholder="you@example.com"></lumen-input>
<lumen-button>Subscribe</lumen-button>
</lumen-card>Framework contracts
Lumen keeps one visual contract, but each target has its own integration surface for behavior, local wrappers, and registration.
Component CSS
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 v5 components import their own CSS. Keep the layer order and optional Tailwind bridge in the shared entry.
@import "@santi020k/lumen-astro/layers.css";
@import "tailwindcss";
@import "@santi020k/lumen-astro/tailwind.css";Load the foundation once and each used component stylesheet. Include conditional and compound content. Elements exposes the same CSS paths.
import '@santi020k/lumen-react/styles/foundation.css'
import '@santi020k/lumen-react/styles/components/button.css'
import { Button } from '@santi020k/lumen-react/components/button'Full styles.css remains a supported convenience option in every adapter. Retain it during migration until every route has equivalent coverage.
import '@santi020k/lumen-react/styles.css'Token contract
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.
Illustrative previews · buttons do not save data. Try your own palette in the theme playground.
Omit data-theme or set data-theme="light" for the default light theme; set data-theme="dark" for the built-in dark theme.
<html data-theme="light">
<body>...</body>
</html>
<html data-theme="dark">
<body>...</body>
</html>Switch themes by updating document.documentElement.dataset.theme; components read the CSS variables from the root element.
const nextTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
? 'dark'
: 'light'
document.documentElement.dataset.theme = nextThemeImport 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.
@import "@santi020k/lumen-astro/styles/themes/santi020k.css";Selected work · Design systems
Surface system
Glass is a surface treatment, not a theme: shared tokens control blur, saturation, borders, and highlights, with fallbacks for browsers without backdrop-filter support.
The same content on three surface treatments.
<Card>The same content on three surface treatments.
<Card glass="subtle">The same content on three surface treatments.
<Card glass="strong">Use the glass prop for standalone content surfaces.
<Card glass>
<h2>Launch window</h2>
<p>Shared glass tokens.</p>
</Card>Use the same glass prop for overlays without changing their semantics.
<Popover glass>
<Button data-ui-trigger>
Invite
</Button>
<div>
<Input type="email" />
</div>
</Popover>Elements support glass with a boolean attribute.
<lumen-card glass>
<h2>Production</h2>
<p>Same class contract.</p>
</lumen-card>Package map
@santi020k/lumen-astro
Reference implementation of the full primitive catalog, shared CSS, and progressive-enhancement runtime.
@santi020k/lumen-react
React implementation of the full primitive catalog using the shared class, token, and data contract.
@santi020k/lumen-elements
Standards-based implementation of the full primitive catalog using the shared class, token, and data contract.
@santi020k/lumen-core
Design tokens, component metadata, and utilities shared by every framework implementation.
Behavior layer
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.
Focus a tab and use the arrow keys to switch views.
Your workspace is ready.
No new activity today.
Open help, press Escape to dismiss it, then check where focus returns.
Dialog API and examplesClick the question or focus it and press Enter. This also works without JavaScript.
Native details can open and close without the runtime.
Copy a demo · Astro snippets assume styles and UIPrimitives are already mounted in your root layout.
---
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>---
import { Button, Dialog } from '@santi020k/lumen-astro'
---
<Button data-ui-dialog-trigger="workspace-help">Open workspace help</Button>
<Dialog id="workspace-help" aria-labelledby="workspace-help-title">
<h2 id="workspace-help-title">Workspace help</h2>
<p>Keep your team settings in one place.</p>
<footer>
<Button data-ui-dialog-close>Close help</Button>
</footer>
</Dialog>---
import { Accordion } from '@santi020k/lumen-astro'
---
<Accordion>
<details>
<summary>Does this need JavaScript?</summary>
<p>Native details can open and close without the runtime.</p>
</details>
</Accordion>Trigger, dismiss, escape-key, and focus behavior for modal surfaces.
Lightweight disclosure patterns for contextual actions and floating content.
Progressively enhanced keyboard navigation and client-side filtering.
Document-level behavior for transient feedback and slide navigation.
Every component page includes a live preview plus code for all three targets.