A cross-platform UI system with 150+ web primitives and shared native foundations.
Documentation · Components · Figma library · Issues
Lumen gives applications a consistent visual language without tying them to one rendering model. Its packages share tokens, component contracts, styles, and interaction patterns while keeping each framework and platform's native authoring experience.
- Framework native: Astro components, React primitives, and standards-based custom elements.
- Native foundations: generated React Native, SwiftUI, and Jetpack Compose tokens plus the complete shared interface and namespaced brand icon catalogs preserve the same semantic roles and artwork without introducing DOM or CSS assumptions.
- Accessible by default: semantic markup, keyboard paths, focus management, and reduced-motion support are built into the primitives.
- Standalone CSS: no Tailwind configuration is required. Tailwind users get an explicit layer integration.
- Progressively enhanced: Astro interactions use a small client runtime instead of requiring an application framework.
- Ready for design and AI workflows: published Figma resources, a portable agent skill, an MCP
server,
llms.txt, a machine-readable registry, and a cross-platform release manifest ship alongside the component system. - Product-ready templates: five responsive dashboard and application families are available as live previews and installable Astro, React, and Elements recipes.
Explore the template gallery for complete analytics, SaaS admin, commerce, project workspace, and authentication/onboarding experiences. Each family uses public Lumen primitives and semantic tokens, includes responsive and accessibility coverage, and ships through the CLI for all three framework targets:
lumen add analytics-dashboard
lumen add commerce-dashboard --target react
lumen add auth-onboarding --target elementsInstall the package for your framework:
# Astro
pnpm add @santi020k/lumen-astro
# React
pnpm add @santi020k/lumen-react
# Web Components
pnpm add @santi020k/lumen-elementsImport the stylesheet and mount UIPrimitives once in your root layout. The runtime enhances all
interactive Lumen markup on the page.
---
import '@santi020k/lumen-astro/styles.css'
import UIPrimitives from '@santi020k/lumen-astro/runtime'
---
<html lang="en">
<body>
<slot />
<UIPrimitives />
</body>
</html>---
import { Button, Card, Input } from '@santi020k/lumen-astro'
---
<Card>
<label for="email">Email</label>
<Input id="email" name="email" type="email" placeholder="you@example.com" />
<Button>Subscribe</Button>
</Card>Load the stylesheet once from your app entry or global CSS:
import '@santi020k/lumen-react/styles.css'
import { Button, Card, Input } from '@santi020k/lumen-react'
export function SubscribeForm() {
return (
<Card>
<label htmlFor="email">Email</label>
<Input id="email" name="email" type="email" placeholder="you@example.com" />
<Button>Subscribe</Button>
</Card>
)
}Import the styles and register the elements once:
<style>
@import "@santi020k/lumen-elements/styles.css";
</style>
<script type="module">
import { defineLumenElements } from '@santi020k/lumen-elements/define'
defineLumenElements()
</script>
<lumen-card>
<label for="email">Email</label>
<lumen-input id="email" name="email" type="email" placeholder="you@example.com"></lumen-input>
<lumen-button>Subscribe</lumen-button>
</lumen-card>See the Web documentation for installation, theming, component examples, and API details.
For failure states, use the error-handling guide to choose between field
feedback, summaries, persistent alerts, transient toasts, and the ErrorState recovery surface.
Lumen owns presentation and accessibility; applications retain logging, retry, and exception policy.
For native applications, choose the React Native, Apple / SwiftUI, or Android / Compose guide. The shared foundations explain the cross-platform token and component contract; repository contributors can also use the cross-platform architecture and native component reference.
Native platform status for Lumen 2. React Native, SwiftUI, Compose, and Wear OS use the frozen supported contract. Package, migration, build, security, artifact, and stability checks gate the initial release. The incomplete external-consumer and physical-device matrices remain published as post-release qualification work; review them before choosing a production adapter.
The repository includes three searchable, interactive galleries built from the real native packages:
apps/playground-react-nativeruns through Expo on the web, iOS, and Android and includes EAS profiles for TestFlight, Android App Bundles, and APKs.apps/playground-appleis available on the App Store for iPhone, iPad, and Mac. It also builds as an iOS Xcode app or macOS Swift Package executable for local exploration.apps/playground-androidbuilds a native Compose application and a directly installable debug APK. Its Google Play release is awaiting approval.
See the playground workflow for run, capture, and distribution commands.
Keep the layer prelude, Tailwind import, and Lumen stylesheet in the same shared CSS entry. Replace
lumen-astro with the package for your framework.
@import "@santi020k/lumen-astro/layers.css";
@import "tailwindcss";
@import "@santi020k/lumen-astro/styles.css";This order places Tailwind base styles before Lumen components and Tailwind utilities above Lumen component defaults.
| Package | Purpose |
|---|---|
@santi020k/lumen-astro |
Reference implementation, Astro components, and progressive-enhancement runtime |
@santi020k/lumen-react |
React components and behavior hooks |
@santi020k/lumen-react-hook-form |
Optional React Hook Form adapters for composite controls |
@santi020k/lumen-elements |
Standards-based Web Components |
@santi020k/lumen-core |
Shared tokens, metadata, class helpers, and behavior contracts |
@santi020k/lumen-tokens |
Canonical platform-neutral design token source |
@santi020k/lumen-react-native |
React Native foundations and native primitives |
LumenUI |
Swift Package for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS foundations and native primitives |
LumenWidgetUI |
Focused WidgetKit-safe semantic text, icon, badge, and compact-stat foundations |
lumen-compose |
Android library for Jetpack Compose foundations and native primitives |
lumen-compose-wear |
Focused Wear OS primitives for at-a-glance round-screen actions, progress, status, metrics, and rows |
@santi020k/lumen-icons-brand |
Optional namespaced brand icons for web Icon adapters |
@santi020k/lumen |
Umbrella package, CLI, registry metadata, and public package map |
@santi020k/lumen-mcp |
MCP server for component discovery and source retrieval |
Install the portable Lumen skill in Codex, Claude Code, Cursor, Windsurf, and other compatible coding agents:
npx skills add santi020k/lumen --skill lumen-uiThe skill teaches agents how to select, compose, theme, and verify Lumen primitives. Pair it with
@santi020k/lumen-mcp when an agent needs to search the live catalog or retrieve
current source, props, tokens, and usage rules.
OpenAI Plugins Directory status: Lumen UI 1.0.0 has been submitted for review for Codex and ChatGPT. Until OpenAI approves it and the publisher completes publication, install the portable skill or connect the MCP server directly; directory availability is not yet guaranteed.
Additional machine-readable surfaces include:
llms.txtfor a concise project map.docs/ai-usage.mdfor downstream generation examples.docs/styling-contract.mdfor stable parts and component variables.docs/import-and-icon-performance.mdfor repeatable import and icon evidence.docs/graphics.mdfor portable decorative artwork across web and native platforms.docs/consumer-regression-fixtures.mdfor production-shaped local coverage.docs/project-adoption.mdfor the sibling-project audit and staged web and native migration strategy.registry/lumen.registry.jsonfor recipes and installable file groups.docs/figma.mdfor Figma variables and Code Connect workflows.plugins/lumen-uifor the packaged Codex and ChatGPT plugin, with its submission and review record..claude-plugin/marketplace.jsonfor the Claude Code marketplace, with its installation and submission guide.docs/cross-platform.mdfor the native architecture, support tiers, and component-parity policy.docs/native-patterns.mdfor developed native compositions and the boundary between Lumen presentation and platform-owned application structure.
Lumen is a pnpm workspace. Astro is the reference implementation; shared contracts belong in
packages/core, while framework-specific behavior stays in its adapter package.
pnpm install
pnpm run dev
pnpm run validateRead CONTRIBUTING.md before opening a pull request. User-visible package
changes require a changeset.
Lumen is free and MIT licensed while the project focuses on adoption, public examples, and real-world feedback.
- Explore task-oriented guides.
- Share a public project in the community showcase.
- Evaluate the system with the open team adoption path.
- Tell us what would improve your next build through the adoption survey.
Maintainers can use the exposure playbook for publishing cadence, campaign measurement, video scripts, and launch copy.
Lumen's original code and artwork are available under the MIT License. Generated
interface icons retain the Lucide ISC or Feather MIT terms, and generated brand icons retain Font
Awesome Free's CC BY 4.0 terms. The native packages include the required attribution and license
notices; see icons/THIRD_PARTY_NOTICES.md.