Lumen UI

View saved version →

---
name: lumen-ui
description: Build, restyle, review, or migrate product interfaces with Lumen UI for Astro, React, Web Components, React Native, SwiftUI, or Jetpack Compose. Use when a request mentions Lumen UI, Lumen packages or tokens, or asks an AI agent to create an accessible interface that should use Lumen instead of inventing primitives.
---

# Lumen UI

Build interfaces from Lumen's real component contracts, semantic tokens, and framework adapters.
Treat Astro as the reference surface, while following the user's existing stack.

## Workflow

1. Inspect the app before editing. Identify the framework, package manager, global style entry,
   existing Lumen packages, theme overrides, and local component conventions.
2. Choose the matching target:
   - Astro: `@santi020k/lumen-astro`
   - React: `@santi020k/lumen-react`
   - Web Components or framework-neutral HTML: `@santi020k/lumen-elements`
   - React Native or Expo: `@santi020k/lumen-react-native`
   - SwiftUI or Apple platforms: `LumenUI`
   - Jetpack Compose or Android: `lumen-compose`
3. Retrieve current contracts before guessing:
   - For Astro, React, and Elements, prefer connected Lumen MCP tools: read snapshot metadata and diagnostics, read agent rules,
     search with the target framework, then read the selected component's usage contract and tokens.
     Retain the catalog manifest when the client supports caching so a later catalog diff identifies
     only the contracts that changed.
   - For native targets, prefer `lumen_list_native_components` and `lumen_get_native_component`,
     then verify installed adapter source/types when the local package version may differ.
   - Otherwise inspect installed package types/source or use the Lumen CLI and online docs.
   - Never invent a component, prop, variant, event, or import path from memory.
4. Plan the interface as product structure and states, then map each part to the smallest suitable
   Lumen primitive. Read [references/component-selection.md](references/component-selection.md)
   when choosing components or composing a full screen.
5. Read [references/frameworks.md](references/frameworks.md) for setup and runtime rules for the
   selected target.
6. Implement with Lumen components and platform-native semantics. Import a stylesheet once only for
   web targets. Preserve the app's state, navigation, data, and domain logic.
7. Customize through Lumen tokens and public props. Read
   [references/design-system.md](references/design-system.md) when theming, polishing, or reviewing
   visual quality.
8. Verify the edited surface with the narrowest relevant typecheck, test, lint, and visual or
   browser check available in the project.

## Non-negotiable Rules

- Prefer existing Lumen primitives over hand-built replacements.
- Prefer Astro only for a new project with no requested framework; do not migrate an existing app
  merely because Astro is the reference implementation.
- Load the matching package stylesheet once at the app boundary for web targets; native adapters do
  not use CSS.
- Mount `UIPrimitives` once in an Astro root layout when interactive primitives are present.
- Use React behavior hooks for behavior-heavy React primitives; do not mount the Astro runtime.
- Register Lumen custom elements once before using `lumen-*` elements.
- Use `CodeTabs` for related commands, languages, or configuration examples instead of building a
  parallel tab controller.
- Use accessible names, native semantics, visible focus, keyboard paths, and meaningful empty,
  loading, error, success, disabled, and destructive states.
- Use Lucide names through web Lumen `Icon`; React Native accepts application-provided native icon
  components, SwiftUI uses SF Symbols, and Compose accepts `ImageVector`. Do not substitute emoji
  for interface icons.
- Use only the public semantic color vocabulary. Do not hardcode a second palette into component
  markup.
- Keep glass surfaces selective and legible. Decorative styling must not

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.