Lumen UI

View saved version →

---
name: lumen-migrate
description: Plan and implement an explicitly requested Lumen version upgrade, including version-specific migration diagnostics and consumer verification. Use when updating an application's Lumen dependencies or replacing older Lumen contracts.
---

# Migrate a Lumen consumer

Resolve the installed versions from package metadata and lock files, the requested target, the
framework/platform, and the application's integration boundaries. Preserve existing user changes.
Do not infer an upgrade request from ordinary UI work or pick a newer major than the user requested.

Compare target contracts with MCP metadata using `lumen_check_compatibility`. A latest catalog is
not the installed API. For another version, use a matching published MCP package or installed public
types and release documentation. Verify target publication independently of workspace package metadata.

Read the migration guide and release notes for the requested source and target versions. Determine
which preview/apply commands the target CLI actually supports; do not assume every major has the
same automation. Read [references/v4.md](references/v4.md) for Lumen 4 or
[references/v5.md](references/v5.md) for Lumen 5. When MCP
is connected, read the migration contract without a package filter before narrowing to affected
packages so cross-package changes are not missed. If shell execution is unavailable, inspect a
supplied target-CLI preview and report remaining commands as unverified.

Apply only the reviewed migration scope. Use `--apply` for supported deterministic edits; inspect
their diff. Use the target release manifest for individual package pins and update the lock file with the
consumer's package manager. V5 companions can remain on v4; never assign one version to the family.
Review the changed public contracts and affected consumer workarounds. Keep ambiguous expressions
and application-owned policy for explicit review.
Never remove a workaround until the equivalent target behavior is verified. For changed setup,
read only the matching target from [framework contracts](../lumen-ui/references/frameworks.md).

Run the consumer's relevant types, tests, lint, build, and rendered interaction checks. Include
phone/desktop and keyboard/focus for web changes; use native compilation and accessibility checks
for native adapters. Re-run the supported preview to establish idempotence. Read
[the interaction checklist](../lumen-ui/references/verification.md) for affected UI behavior.
Report remaining manual findings and local versus published/deployed evidence accurately.

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

View saved version →

---
name: lumen-review
description: Review an existing Lumen interface or proposed UI change for component contracts, setup, semantic tokens, accessibility, and responsive behavior. Use for requested Lumen UI audits and reviews.
---

# Review a Lumen interface

Review the requested surface and return actionable findings with file locations, observable
consequences, and suggested fixes. Preserve the user's explicit review scope. A review request
does not authorize edits or dependency upgrades.

Identify the framework and resolved installed Lumen versions. Compare them with `lumen_get_meta`
and `lumen_check_compatibility` when MCP is connected. Read installed public types and documentation
when versions differ; a healthy server is not proof that its catalog matches the application.
Without MCP, use installed types, package READMEs, and `lumen show <component>`.

Inspect public component imports and props, theme/style ownership, and the framework's setup:
Astro runtime once, React hooks/controllers, Elements registration, or native providers/themes.
Read only the matching setup reference from
[framework contracts](../lumen-ui/references/frameworks.md) when checking adapter-specific details.
For v5, check component CSS coverage, await Astro enhancement, and account for lazy first
interactions and navigation cleanup. Full stylesheet usage is supported, not automatically a defect.
Keep source-only setup findings separate from measured route requests.
Look for duplicate primitive implementations, incorrect compound children, raw palettes,
application CSS that breaks public slots, and unsupported adapter APIs.

Review actual interactions and states: keyboard/focus and dismissal, accessible names, validation,
loading/error/empty feedback, touch targets, reduced motion, and phone/desktop layout. Use existing
project checks and rendered evidence when permitted; distinguish source findings from verified
behavior. Native reviews use platform semantics and supported target availability. Use
[the interaction checklist](../lumen-ui/references/verification.md) for the reviewed behavior;
report unavailable checks without treating source inspection as rendered verification.

For visualization, check that the encoding answers the product question, the selected chart exists
in the installed adapter, and its data shape preserves unique identities, missing values, and real
zeros. Verify localized context, readable exact data, and supported keyboard inspection. Applications
own aggregation, conversion rates, binning, and statistical policy; charts must not invent them.

Use `lumen doctor --json` or `lumen doctor-native --json` for existing diagnostics when installed.
Explain applicability instead of treating every advisory as a defect. Do not upload private
source, credentials, or user data to the public catalog service.

Report only evidence-backed issues in priority order. Say when no actionable findings remain,
list the checks performed, and identify any unverified behavior. Do not claim WCAG certification
from an automated accessibility scan.

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

View saved version →

---
name: lumen-ui
metadata:
  guidance-version: "5.1.0"
description: Build or restyle product interfaces with Lumen UI for Astro, React, Web Components, React Native, SwiftUI, or Jetpack Compose. Use for implementation requests using Lumen packages, components, or tokens, including accessible interfaces composed from Lumen primitives. Use lumen-review for requested audits and lumen-migrate for version upgrades.
---

# 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,
   resolved installed Lumen versions, 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:
   - Start discovery with `limit: 5` and the requested `framework` or native `platform`. Add
     `kind: "component"` or `kind: "native-component"` when choosing primitives; use
     `kind: "recipe"` for a complete composition. Widen the search only when those results do not
     cover the requirement. Read `detail: "usage"` for the selected contracts; request source only
     to resolve a specific missing detail. Reuse retrieved contracts within the same matching
     catalog version instead of listing the full catalog for every component.
   - For Astro, React, and Elements, when Lumen MCP is connected, read snapshot metadata and diagnostics, read agent rules,
     compare resolved installed versions with `lumen_check_compatibility`, 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.
   - On a version mismatch, use a matching published MCP version or installed public types and package documentation. Do not apply a newer catalog as the installed API or silently upgrade the app.
   - For a requested upgrade, use the `lumen-migrate` workflow; for a requested audit, use `lumen-review`. Ordinary UI changes retain their requested scope.
   - 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.
   For charts or analytics, read [references/data-visualization.md](references/data-visualization.md)
   to choose the encoding and verify its data and accessibility contract.
5. Read only the matching setup and runtime reference:
   [Astro](references/astro.md), [React](references/react.md),
   [Elements](references/elements.md), [React Native / Expo](references/react-native.md),
   [SwiftUI](references/swiftui.md), or [Compose](references/compose.md).
   Keep Tailwind optional, use public named imports, and retain state in the host application.
6. Implement with Lumen components and platform-native semantics. Follow the installed version's
   style contract: v5 Astro imports component CSS automatically; React/Elements load the foundation
   once and selected component CSS. Full styles.css remains supported. Preserve the app's state, navigation, data, a

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

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