@santi020k/lumen-astro

Production-ready Astro primitives for Lumen UI. The stylesheet is standalone CSS, so no Tailwind configuration is required to render the components.

Install

pnpm add @santi020k/lumen-astro

The adapter also exposes Lumen's discovery and diagnostics CLI:

pnpm exec lumen show Tabs
pnpm exec lumen doctor

Import the CSS once in your root layout and mount UIPrimitives once in that same app shell if you use interactive components such as dialogs, menus, popovers, tabs, carousels, toggles, command lists, or toasts. Do not add UIPrimitives beside each component instance; one root include enhances all matching Lumen markup on the page.

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

Applications using the essential forms, feedback, tabs, dialogs, calendar, and data-table surface can instead load @santi020k/lumen-astro/styles/critical.css. The generated entry is about 50 KiB raw versus 170 KiB for the complete catalog; switch to styles.css when using components outside that documented critical set.

The stylesheet defaults --ui-font to "Montserrat", "Avenir Next", "Segoe UI", sans-serif. It declares the family stack but does not bundle or load font files. Load Montserrat once through your preferred delivery path, or override --ui-font in application CSS.

With Tailwind, keep the Lumen import in the same shared CSS entry:

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

---
import UIPrimitives from '@santi020k/lumen-astro/runtime'
---

<UIPrimitives />
<slot />

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

<Card>
  <label for="email">Email</label>
  <Input id="email" type="email" placeholder="[email protected]" />
  <Button>Subscribe</Button>
</Card>

Input and NativeSelect preserve the native numeric size attribute. Use visualSize="sm" or visualSize="lg" for presentation so native behavior and visual styling remain separate.

<Input size={32} visualSize="sm" />
<NativeSelect size={8} visualSize="lg" />

PhoneInput generates localized country names, supplementary flags, and calling codes when custom countries are not provided. Mount UIPrimitives once to enable as-you-type formatting, metadata-backed validation, automatic country detection for pasted international numbers, and the ui:phone-change event with a LumenPhoneNumber detail.

The phone metadata and normalization controller are selector-loaded only when a rendered page contains PhoneInput; pages without the component do not evaluate or download that controller.

<PhoneInput countryValue="CO" locale="en-US" name="hospitalPhone" />

Compound interactive components

Popover, dropdown menu, tabs, and tooltip parts expose the DOM and ARIA contracts consumed by the shared progressive-enhancement runtime. Prefer these parts over recreating roles and data-ui-* attributes by hand.

Tabs keep the selected trigger visible when a narrow tab list scrolls horizontally and emit a typed ui:tabs-change event. Import LumenTabsChangeDetail or LumenTabsChangeEvent from this package when application behavior follows the selected value.

---
import {
  Button,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  Popover,
  PopoverPanel,
  PopoverTrigger,
  Tabs,
  TabsList,
  TabsPanel,
  TabsTrigger,
  Tooltip,
  TooltipContent
} from '@santi020k/lumen-astro'
---

<DropdownMenu>
  <DropdownMenuTrigger>Download</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>macOS</DropdownMenuItem>
    <DropdownMenuItem>Windows</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem disabled status="Soon">Android</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

<Popover>
  <PopoverTrigger>Filters</PopoverTrigger>
  <PopoverPanel>Filter controls</PopoverPanel>
</Popover>

<Tabs initialValue="preview">
  <TabsList aria-label="Workspace view">
    <TabsTrigger value="preview">Preview</TabsTrigger>
    <TabsTrigger value="code">Code</TabsTrigger>
  </TabsList>
  <TabsPanel value="preview">Rendered result</TabsPanel>
  <TabsPanel value="code">Source code</TabsPanel>
</Tabs>

<Tooltip>
  <Button aria-label="Save changes">Save</Button>
  <TooltipContent>Save changes</TooltipContent>
</Tooltip>

Context navigation

Use ContextNavigation below a primary header when the available links change with a selected platform, product, or workspace. Put the stable selector or identity in the context slot and one independently named NavigationMenu in the default slot. Long link sets scroll horizontally.

---
import { ContextNavigation, NativeSelect, NavigationMenu } from '@santi020k/lumen-astro'
---

<ContextNavigation>
  <NativeSelect slot="context" aria-label="Documentation platform" visualSize="sm">
    <option>Web</option>
    <option>Apple</option>
    <option>Android</option>
  </NativeSelect>
  <NavigationMenu aria-label="Web documentation" variant="unstyled">
    <a href="/docs/web" aria-current="page">Overview</a>
    <a href="/docs/components">Components</a>
    <a href="/docs/web/playground">Playground</a>
  </NavigationMenu>
</ContextNavigation>

Forms and Astro Actions

Form renders a semantic form and preserves native method, action, enctype, autocomplete, reset, and no-JavaScript submission. Compose it with Field, Label, FieldError, and ErrorSummary.

Astro Actions remain application-owned. Use accept: 'form', read the result with Astro.getActionResult(), and pass ActionInputError to normalizeAstroActionErrors() so field errors receive stable control IDs.

---
import { actions, isInputError } from 'astro:actions'
import { ErrorSummary, Form, normalizeAstroActionErrors } from '@santi020k/lumen-astro'

const result = Astro.getActionResult(actions.updateProfile)
const errors = result?.error && isInputError(result.error)
  ? normalizeAstroActionErrors(result.error)
  : normalizeAstroActionErrors(result?.error)
---

<Form action={actions.updateProfile} method="POST">
  <ErrorSummary {errors} />
  <!-- fields -->
</Form>

See the Astro Actions form guide.

Error states

Use ErrorState when a page or region cannot show its primary content. Pass recovery controls through the actions slot; the application still owns retry and logging behavior. Static states are not live regions by default, so set announce="polite" only when a newly rendered failure needs an announcement.

<ErrorState title="Could not load projects" description="Check your connection and try again.">
  <Button slot="actions">Try again</Button>
</ErrorState>

See the repository Astro error-handling guide for the complete example, retry ownership, announcement behavior, and verification guidance.

Use Icon for Lucide icons by name across framework adapters.

---
import { Button, Icon } from '@santi020k/lumen-astro'
---

<Button variant="secondary">
  <Icon name="wand-sparkles" decorative />
  Generate
</Button>
<Icon name="search" label="Search" />

Long-form navigation

Anchor accepts heading depth, index, and description metadata plus an activationOffset. Its current link stays synchronized on click and scroll, including at the end of the document. ScrollProgress derives reading progress from the document and pins the indicator to the top or bottom viewport edge. Both use the single root UIPrimitives runtime.

---
import { Anchor, CopyButton, ScrollProgress } from '@santi020k/lumen-astro'
---

<ScrollProgress aria-label="Article reading progress" />
<Anchor items={[
  { depth: 2, href: '#install', label: 'Install' },
  { depth: 3, href: '#astro', label: 'Astro' }
]} />

Progress can be updated after hydration by dispatching ui:progress-change from its root with { value, max? }. Use CopyButton to copy arbitrary text or a referenced element without giving non-code content Code semantics.

<p id="invite">Join the Lumen workspace</p>
<CopyButton size="sm" target="#invite" toast variant="default">
  Copy invite
  <span slot="copied">Invite copied</span>
  <span slot="error">Copy failed</span>
</CopyButton>

CopyButton accepts the same presentation variant and size vocabulary as Button. Its stable copy-idle, copy-copied, and copy-error slots keep visible feedback in sync with the accessible label; free-form default children remain the idle presentation.

Data visualization

Use Sparkline beside a metric, BarChart for categorical comparison, LineChart for ordered trends, PieChart for a small part-to-whole breakdown, ScatterChart for numeric relationships, Heatmap for a matrix, RangeChart for intervals, and ComboChart for a shared-domain mix of bars, lines, and areas. The chart components accept already-aggregated series, use Lumen data-color tokens, and include a revealable semantic data table by default.

---
import { LineChart } from '@santi020k/lumen-astro'

const series = [{
  id: 'views',
  label: 'Views',
  data: [{ x: 'Mon', y: 42 }, { x: 'Tue', y: 68 }]
}]
---

<LineChart aria-label="Views by day" heading="Website traffic" {series} />

PieChart accepts one LumenChartSeries; its data points become slices. It defaults to variant="donut" and also supports variant="pie".

Every chart includes a factual screen-reader summary by default and accepts summary for more useful domain context. See data visualization for selection, missing-data, live-data, and accessibility guidance.

Lucide intentionally excludes brand marks. For GitHub and other project-specific icons, put the SVG in the default slot instead of passing an unsupported name; Astro warns about unknown named icons during development.

Code tabs

Use CodeTabs for related install commands, language variants, or configuration examples. Each item supplies a stable value, visible label, code string, and optional language. A shared storageKey keeps matching instances synchronized and remembers the reader's selection.

---
import { CodeTabs } from '@santi020k/lumen-astro'

const installCommands = [
  { value: 'pnpm', label: 'pnpm', code: 'pnpm add @santi020k/lumen-astro', language: 'bash' },
  { value: 'npm', label: 'npm', code: 'npm install @santi020k/lumen-astro', language: 'bash' }
]
---

<CodeTabs
  ariaLabel="Package manager"
  items={installCommands}
  storageKey="preferred-package-manager"
/>

Optimized images

Lumen's Astro Image delegates to astro:assets, so imported image metadata, responsive layouts, generated srcset values, output formats, quality, and remote-size inference stay available. It loads lazily by default. Use loading="eager" and fetchpriority="high" only for the single image that is likely to be the page's LCP image.

---
import { Image } from '@santi020k/lumen-astro'
import hero from '../assets/hero.jpg'
---

<Image
  alt="Team collaborating around a table"
  layout="full-width"
  quality="high"
  src={hero}
/>

For monochrome artwork whose pixels were authored for a light background, add invertOnDark. Colorful photography should keep the default so its colors remain unchanged.

AnimatedLogo accepts your own inline SVG rather than imposing brand artwork. Put the accessible name on the SVG itself.

---
import { AnimatedLogo } from '@santi020k/lumen-astro'
---

<AnimatedLogo style="height: 3rem">
  <svg aria-label="Acme" role="img" viewBox="0 0 120 32">
    <!-- Your logo artwork -->
  </svg>
</AnimatedLogo>

For a choreographed logo, set animation="sequence" and mark individual SVG layers with data-ui-logo-pop, data-ui-logo-draw, or data-ui-logo-reveal. Timing can be adjusted per layer with --ui-logo-delay.

The package ships the complete Astro primitive catalog plus a small progressive-enhancement runtime for dialogs, popovers, tabs, menus, command filtering, carousels, and toasts.

Kanban boards

Compose KanbanBoard and KanbanColumn with ordinary Card items. Give every item a stable data-ui-kanban-item and add a dedicated button with data-ui-kanban-handle. UIPrimitives emits the cancellable ui:kanban-move-request event for keyboard, mouse, and touch movement without changing the DOM. Keep persistence, pending state, rollback, and status rules in the application. Use Empty variant="compact" inside empty columns and Skeleton cards while loading.

Motion

Use the shared fast, standard, and slow duration vocabulary across motion primitives. ScrollReveal handles one entrance, RevealGroup staggers direct children, and AnimatedNumber animates a formatted metric while preserving a stable accessible value. All three keep their final content readable without JavaScript and honor reduced-motion preferences.

<ScrollReveal animation="slide-up" as="section" duration="slow">
  <h2>Release highlights</h2>
</ScrollReveal>

<RevealGroup as="ul" stagger={80}>
  <li><Card>Plan</Card></li>
  <li><Card>Build</Card></li>
  <li><Card>Ship</Card></li>
</RevealGroup>

<AnimatedNumber decimals={1} suffix="%" value={99.8} />

Glass surfaces

Lumen includes glassmorphism tokens and reusable classes in the shared stylesheet. Cards use a boolean prop, and overlays or navigation primitives use the same prop while preserving semantic variants. The older variant="glass" form remains supported for cards.

<Card glass>Glass card</Card>
<Dialog glass>Glass dialog</Dialog>
<Popover glass>Glass popover</Popover>
<DatePicker glass="subtle" />
<Select glass="strong" options={['Astro', 'React']} />

Semantic stat roots

Stat renders a div by default. Use as="article" when the metric and its supporting content form a standalone item, or as="section" when it is a labeled region in a larger view.

<Stat as="article" label="Active workspaces" value="1,234" variant="accent">
  <p>Across all production organizations.</p>
</Stat>

Use variant="default" for the original neutral surface, variant="accent" for a featured metric, or variant="glass" for selective translucency.