Lumen UI · Web Components

Custom elements · Browser-native composition · Shared styles

Documentation · npm · Source · Issues

` and `` with JSON arrays. `` emits `ui:chart-cursor-change` with `{ x }`. Set `annotations` to a JSON array. Set serializable `series` data through the JavaScript property for application data. The JSON attribute form is useful for static HTML and server output. ```html ``` `lumen-sparkline` also accepts comma-separated or JSON `values`. Every data chart includes a revealable semantic table unless `show-table="false"` is set. `lumen-pie-chart` uses the first serialized series and defaults to `variant="donut"`. ## Optimized images Image optimization belongs to the host framework or CDN. Keep its generated `picture`, `srcset`, and `sizes` output, and put Lumen's `ui-image` class on the final `img`. This works with optimized markup from Nuxt, SvelteKit, a CMS, an image CDN, or a static build pipeline without sending the image through a second component. ```html ``` Add `ui-image--invert-dark` only to monochrome artwork that needs inversion on dark themes. Elements emit the same `ui-*` classes and `data-ui-*` attributes as the Astro primitives. Astro remains the reference package, and the Web Components adapter now carries matching light-DOM behavior for DataTable, Dialog, Popover, DropdownMenu, ContextMenu, Tabs, Select, ThemeBuilder, Toast, Tooltip, forms, Calendar, InputOTP, DateRangePicker, RichTextEditor, Schedule, Resizable, VirtualList, FileUpload, Tour, Anchor, CopyButton, Progress, Transfer, Mentions, Cascader, and TreeSelect: selection, validation, calendar grids, OTP segmentation, date range syncing, rich text command, context menu, schedule and file drag/drop, anchored tours, scroll spy, collection transfer, mention insertion, hierarchical selection, resizable pane sizing, theme, and range events, ARIA state, keyboard navigation, Escape/outside dismissal, focus return/trapping, native form participation, and the document-level toast controller events. ## Interactive behavior Internal behavior methods use native JavaScript private members. Public properties, events and registration APIs retain their existing contracts. Disclosure keyboard navigation skips hidden or inert regions, invisible controls, and native disabled controls, including a disabled fieldset. Available controls in a fieldset's first legend retain their native keyboard behavior; removing `inert` makes a region available again. Enhanced DatePicker controls mirror native input `aria-invalid`, `aria-describedby`, and `aria-errormessage` onto the visible trigger, including dynamic changes. Valid updates and uncanceled form resets clear generated errors while preserving explicit application errors. `lumen-skeleton` and `lumen-spinner` are decorative (`aria-hidden="true"`) until they have an `aria-label` or `aria-labelledby`, then they become `role="status"`; explicit `aria-hidden` and `role` values are kept. `lumen-skeleton` and `lumen-progress` render as blocks. Skeleton `shape`, `width`, `height`, and `animation` attributes update and reset when changed or removed. A `loading` `lumen-button` also sets `aria-busy="true"`. Mentions keeps suggestion navigation on the textarea through `aria-activedescendant`; suggestion buttons are excluded from the Tab sequence while Enter and pointer selection still insert a mention. Select follows the Astro keyboard contract: Space opens the listbox or selects the focused option unless it continues an active typeahead query, and moving focus outside the field closes the listbox. The listbox shares the trigger's accessible name. Adding, removing, relabeling, or disabling native options re-renders the listbox while preserving focus on an available option. Toggling the native select's `disabled` state updates the trigger. React and Elements can share a page. React DatePicker, Calendar, and InputOTP render `data-ui-owner="react"` because React owns their behavior, so the document-wide Elements enhancers skip them whether elements are registered before or after the React island mounts. Standards-based `data-ui-*` markup without an owner, and `lumen-*` elements, are enhanced as before. Registering the elements wires behavior-heavy primitives without a framework runtime. DataTable, Dialog, Popover, DropdownMenu, ContextMenu, Tabs, Select, ThemeBuilder, Toast, Tooltip, forms, Calendar, InputOTP, DateRangePicker, RichTextEditor, Schedule, Resizable, and VirtualList track the Astro runtime's data event, validation, calendar grids, OTP segmentation, date range syncing, rich text command, context menu, schedule drag/drop, resizable pane sizing, theme export, ARIA, keyboard, Escape, dismissal, and toast controller semantics while keeping markup declarative and Declarative-Shadow-DOM friendly. Calendar attribute updates preserve the focused day in the owning document after iframe adoption. Calendar form resets restore the latest configured `value` attribute; interactive date selections do not replace that reset baseline. Form error summaries can focus associated native controls outside the form subtree when their `form` attribute names that form. FileUpload, Tour, Anchor, CopyButton, Progress, ScrollProgress, Transfer, Mentions, Cascader, and TreeSelect also run directly through their registered custom elements; no Astro runtime or host controller is required. Rich text controls may provide `data-ui-editor-value` for commands such as `formatBlock` and `createLink`; editable surfaces emit `ui:editor-change` with both HTML and plain text, support common formatting shortcuts, and keep toggle controls synchronized through `aria-pressed`. `lumen-tabs` keeps the selected trigger visible in narrow horizontal lists and emits `ui:tabs-change`; import `LumenTabsChangeDetail` or `LumenTabsChangeEvent` for its typed detail. Nested `lumen-tabs` and `lumen-code-tabs` keep independent selection and panel state. Keyboard navigation skips disabled triggers and stays within the active tab group. `` and `` provide the same controlled board contract. Mark ordinary card items with `data-ui-kanban-item` and put `data-ui-kanban-handle` on a dedicated button. The board emits the cancellable `ui:kanban-move-request` event for keyboard, mouse, and touch movement without moving DOM or application data. Use `` for column-level empty states. ```html

Join the Lumen workspace

Copy invite ``` ```html ``` You can also use the shared document events: dispatch `ui:toast` to create, `ui:toast-update` to update, and `ui:toast-dismiss` to dismiss runtime toasts. Toast actions emit `ui:toast-action` unless an action supplies a custom event name. Use `` when a region or page cannot show its primary content. Keep its visible heading, explanation, optional safe reference, and recovery actions in light DOM, label the region with `aria-labelledby`, and use the documented `data-slot="error-state-*"` hooks. Lumen presents the failure; application code owns exception capture, logging, and retry policy. See the repository [Web Components error-handling guide](https://github.com/santi020k/lumen/blob/main/docs/error-handling.md#web-components) for the complete light-DOM structure, ARIA ownership, retry boundary, and verification guidance. `lumen-anchor` uses the greater of `activation-offset` and the root `scroll-padding-top` plus heading `scroll-margin-top`, with one CSS pixel of rounding tolerance. It reads live styles for text resizing and responsive headers, and does not treat a non-scrolling page as the document end. `lumen-pill` wraps long text within its available width. A `.ui-pill__count` child stays together; plain text labels do not need a wrapper. This reflow behavior is shared by Astro and React `Pill`. ## Motion The elements adapter exposes the same motion vocabulary as Astro and React. Use `lumen-scroll-reveal` for one entrance, `lumen-reveal-group` for a short staggered sequence, and `lumen-animated-number` for meaningful metric changes. They honor reduced-motion preferences. ```html Plan Build Ship ``` ### Elements labels and dialogs `lumen-input` owns an internal native control. Name that control using `aria-labelledby` pointing at a visible label, or `aria-label` on the host. A native label's `for` pointing only at the custom host does not name the internal input. Use the public `lumen-label` for visible label styling. Do not type a custom host as `HTMLInputElement` or `HTMLButtonElement`; use its exported element class and runtime narrowing when accessing element-specific methods. Use `lumen-dialog` as the behavior owner. Its public methods are `show(trigger?)` and `close()`, not `showModal()` on the custom host. A native `dialog` child is its documented modal contract: ```html Edit profile

Profile settings

Display name Cancel

``` Register `Button`, `Dialog`, `Field`, `Input`, and `Label` through `defineLumenElements` before use. The dialog behavior focuses its first focusable control, handles Escape, traps focus, and returns focus to its trigger. Keep draft state in the form control or application; closing does not reset it. Do not replace this behavior with a parallel native-dialog controller. ## DatePicker accessibility DatePicker uses the positioned `ui-date-picker-field` host shell. It requires authored native input, control, trigger, and popover children with their `ui-date-picker__native`, `ui-date-picker__control`, `ui-date-picker__trigger`, and `ui-date-picker__popover` classes. Put `aria-invalid`, `aria-describedby`, and `aria-errormessage` on the input marked `data-ui-date-picker-native`. The enhancer mirrors those associations to the visible trigger and observes later native-input attribute changes. These host attributes are not forwarded. ## Glass surfaces Load `@santi020k/lumen-elements/styles.css` once, register the elements, then use the shared glass attributes. ```html Glass card Glass dialog Glass popover ``` ## Consumer composition recipes See [consumer UI recipes](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md) for static React icons, responsive record tables, keyboard-aware native sheets, whole-unit amount fields, adaptive editors, and asynchronous action states. Each recipe identifies the public primitives and the behavior that remains owned by the application. ## Exact amount fields `lumen-amount-field` creates a visible localized input and a named hidden input containing the complete ASCII decimal string. `ui:amount-change` reports `{ draft, value }`; incomplete drafts have an undefined value. A host ID `amount` gives its visible input ID `amount-input` for labels. ```html ``` See [consumer workflows](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#executable-consumer-workflows) for validation, reset and `auto-scroll` activity feeds. ### Accessible code examples `` enhances its native `pre > code` child with a copy button. Use `copy-label`, `copied-label`, and `error-label` for clipboard feedback, and `code-label` to name its keyboard-scrollable source region. The same labels can be placed on an enclosing ``; child labels take precedence. Copy emits `ui:copy-success` or `ui:copy-error` and announces feedback in a live region. Clipboard failures leave the source available for manual copy. Unwrapped `pre` children receive `tabindex="0"` and region semantics while keeping authored accessible names. Generated names follow `code-label` updates and the current enclosing code tabs after reconnecting. Changing to `wrap="true"` removes only enhancer-added focus attributes. Disabling `copy` removes only generated copy controls and cancels pending feedback. With `wrap="true"`, the component does not add an extra tab stop. Keep native `pre` and `code` children rather than placing source text in HTML attributes. ### Virtual list and editor ownership `VirtualList` displays fixed-height rows with inert spacers that retain the full scroll extent. Rows stay mounted; use pagination when the initial DOM cost matters. Scrolling, resizing, sizing changes and direct row changes refresh the window. Focused rows remain available. See the [fixed-height list contract](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md#fixed-height-virtual-lists). External rich-text engines should handle the cancelable `ui:editor-command-request` event before execution and use `ui:editor-command` only for completion notifications. React also supports `useRichTextEditor({ commandHandler })`. Disable native toolbar state syncing when the external engine owns it. See the [editor guidance](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md). ## Phone presentation in v4 Phone inputs bundle the same offline flag artwork on every platform. The selected country shows its flag and calling code inside one continuous input border. Country names remain in the native picker and its accessible name; flags are supplementary. Unknown flag codes fall back to text. Astro and React `PhoneInput` accept `disabled`, `readOnly`, `required`, `errorMessage`, `showValidationError`, and `inputProps`. Their `id` targets the number input in v4; React also accepts `inputRef`. Web Components use `disabled`, `readonly`, `required`, `error-message`, `show-validation-error="false"`, and `input-id`, with native input attributes on the host. Both controls lock together and validation remains associated with the input. The `phone-input`, `phone-country`, and `country-flag` styling parts plus `--ui-phone-height`, `--ui-phone-padding`, and `--ui-phone-country-gap` replace consumer CSS overlays. Astro and React also export `CountryFlag` (`regionCode`, optional `decorative`) and `PhoneNumber` (`value: LumenPhoneNumber`, optional `link`). A telephone link is rendered only for a complete E.164 value. Use the model returned by the phone normalizer; keep domain persistence in your app. Artwork attribution is shipped with the core package in `PHONE_FLAG_LICENSE.txt`. When `PhoneInput` is registered, `defineLumenElements` also registers `lumen-country-flag` (`country`, `decorative`, optional `label`) and `lumen-phone-number` (`country`, `value`, `link`, optional `locale`). The read-only element normalizes its string value before creating a tel link. ## Combobox keyboard behavior In v4, Combobox retains input focus and exposes its active option through `aria-activedescendant`. Enter commits an active option; text editing and composition remain native. Escape dismisses one nested control at a time. See the [shared keyboard contract](https://github.com/santi020k/lumen/blob/main/docs/ai-usage.md#combobox-keyboard-behavior-in-v4) for dynamic options, controlled inputs and migration guidance. ## Content flow Stack and Grid own sibling spacing. Their gap accepts `related`, `group` (default) and `section`, or canonical `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` sizes. Card owns the inset and gap between its visible parts; use `density="compact"`, `"comfortable"` (default) or `"spacious"`. Elements uses the same names as attributes. Use a nested Stack for CardContent groups and Field for label/control/feedback. See [content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) and the [v4 migration guide](https://github.com/santi020k/lumen/blob/main/docs/migrating-to-lumen.md) for ownership and changed explicit gaps. ### Reading and complete compositions Prose and Typography trim outer child margins and separate headings from preceding text. Container gutters grow from 16px to 32px with viewport width; override `--ui-container-gutter` when a product needs fixed gutters. Card allows interactive overflow; use AspectRatio to clip media. Install `content-flow-header`, `content-flow-settings`, `content-flow-list` or `content-flow-actions` with `lumen add --target astro|react|elements`. MCP returns the same complete examples. Connect application actions and replace sample IDs before reuse. See [content flow](https://github.com/santi020k/lumen/blob/main/docs/content-flow.md) for composition and migration guidance. ### Large fixed-height collections `VirtualList` supports an empty `mode="data"` root with the public Core data controller. Only the visible window, overscan and focused neighbors mount. Stable keys retain row identity; applications own offscreen editing state. See [data rendering](https://github.com/santi020k/lumen/blob/main/docs/virtual-list-data.md) for setup, lifecycle, accessibility and the mounted-mode tradeoff. Forms validate native controls associated through the `form` attribute even outside the form tree. Timed toasts retain their remaining duration until both pointer hover and keyboard focus leave. ### Compound dialog tasks Register `DialogHeader`, `DialogTitle`, `DialogBody`, `DialogFooter`, and `DialogClose` with `Dialog`. Keep the body directly inside the dialog host for independent scrolling. Use a native heading inside the title host and a native button inside the close host; their semantics and disabled behavior remain native. Associate the heading id with the dialog's `aria-labelledby`. ```html

Edit record

Name

Cancel Save ``` A cancelled click or disabled native button does not dismiss the dialog. Nested close actions only dismiss their own dialog. `lumen-file-upload` accepts `selected-files-label` containing `{count}` for localized multiple-file feedback. ### Rich description rows Register `Descriptions`, `DescriptionItem`, `DescriptionTerm`, and `DescriptionDetail` to compose rich values. The item, term, and detail hosts expose `group`, `term`, and `definition` roles respectively. Use a labeled group for the overall collection and associate the detail with its term when the relationship needs an explicit label. These custom hosts provide ARIA semantics; they are not native `dl`, `dt`, or `dd` tags. ```html Status Active ``` For native definition-list markup, place a complete native `dl` with `div`, `dt`, and `dd` children inside `lumen-descriptions` instead of nesting custom hosts inside the `dl`. ### Stepper progress `lumen-stepper` is a generic element: it applies the shared `ui-stepper` presentation class and `ui-stepper--vertical` for `orientation="vertical"`, but owns no step generation or current-step behavior. Provide the complete step markup as light-DOM children: ```html

1 Account

2 Workspace

``` Each step is a native `div` with `role="listitem"`, `class="ui-stepper__step"`, and `data-state="complete" | "current" | "upcoming"`. Give the current step `aria-current="step"`. Each step holds a `ui-stepper__marker` span and a `ui-stepper__content` span containing a `ui-stepper__title` span and an optional `ui-stepper__description` span. ## Attachment composition Use `AttachmentList` to group native `li` children and `AttachmentPreview` for browser-owned images with localized loading, error, and unsupported-file states. Compose independent actions rather than nesting controls inside a linked Attachment. The application retains file validation, authorization, persistence, and object URL cleanup. See the [attachment composition recipe](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md#attachment-previews-and-file-lists) for adapter props, slots, child contracts, retry identity, and safe state events. ### Chart datum actions All seven data charts accept the opt-in `drilldown` attribute. Each plotted observation gains a pointer target and a matching native button under an accessible disclosure, even with `show-table="false"`. Listen for the bubbling, composed `ui:chart-datum-activate` event on the chart host; its validated `LumenChartDatumActivationDetail` contains original data identities and values. Missing measurements and invalid ranges have no actions; pie charts expose only positive slices. ```html ``` Use the `explore-data-label` and `datum-action-prefix` attributes for localized text, or assign a `datumActionFormatter(context)` property for a contextual label formatter. The exported `LumenChartDatumActionsElement` type describes this host property contract. Updating series, data, or labels preserves the open disclosure and restores focus to the same available action. Chart hosts own their controller lifecycle across disconnect/reconnect; mixed Astro pages leave these hosts to Elements. Application code owns navigation, requests, and filtering. ## Dashboard composition `FilterBar` groups host-owned filtering controls, active criteria, reset actions, and a polite result announcement. `ChangeSummary` presents explicit before/after values and application-owned changed state. Neither component owns requests, persistence, parsing, or financial policy. ScatterChart supports independent X/Y formatting, explicit domains, logarithmic positive X values, and labeled reference lines/regions. See [consumer UI recipes](https://github.com/santi020k/lumen/blob/main/docs/consumer-ui-recipes.md) for dashboard tables, freshness, import review, activity inbox, and persistent Kanban patterns. ### Actual-versus-target charts `lumen-bullet-chart` compares a nullable actual `value` with a finite `target` and optional labeled `ranges`. A strong actual bar, target marker, readable value labels, and expandable exact data work together. Domains include zero and all measurements; invalid inputs fail closed. Null values stay distinct from zero. See the [chart guide](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#actual-values-and-targets) for the input, localization, and domain contracts. ### Rankings and paired comparisons Use `LollipopChart` for zero-based rankings and `DumbbellChart` for paired measurements (native `LumenLollipopChart` and `LumenDumbbellChart`). Supply ordered comparison data with `id`, `label`, nullable `value`, optional nullable `reference`, and optional `tone`. Both charts preserve missing values and expose exact data. Set `value-label` to name the current measurement and `reference-label` to name the paired measurement; `summary` supplies an escaped accessible interpretation that remains available when `show-table="false"`. See the [shared visualization contract](https://github.com/santi020k/lumen/blob/main/docs/data-visualization.md#rankings-and-paired-comparisons). ### Calendar activity, ordered stages and distributions `CalendarHeatmap`, `FunnelChart`, and `BoxPlot` share validated geometry with every Lumen adapter. CalendarHeatmap takes date-only UTC `startDate`/`endDate`, nullable `{ date, value }` data and optional `weekStartsOn` (0 for Sunday or 1 for Monday). It fills omitted dates as missing, keeps zero distinct, and limits the inclusive range to 3,660 days. `weekdayLabels` always indexes Sunday through Saturday; `dateFormatter` customizes readable dates without changing their identity. FunnelChart takes ordered `{ id, label, value, tone? }` stages with nonnegative nullable values. Stages retain the supplied order, including increasing values; the chart derives no conversion rates. BoxPlot takes precomputed `{ id, label, min, q1, median, q3, max, outliers?, tone? }` statistics. Statistics must be ordered and finite, or all five must be null for a missing row. Explicit domains must contain all observations and outliers. `statisticLabels` localizes the six statistic names. All three accept `valueFormatter`, chart `labels`, `summary`, and `show-table` (default true). Exact data and missing measurements remain readable; invalid input fails closed instead of dropping observations or clipping the domain. Prefer retaining the data table for complete visual inspection. Register `CalendarHeatmap`, `FunnelChart`, and `BoxPlot` through `defineLumenElements`. Use ``, ``, and ``. Assign typed `data`, `labels`, `valueFormatter`, `dateFormatter`/`weekdayLabels` (calendar), and `statisticLabels` (box) properties, or supply JSON `data` attributes. Calendar supports `week-starts-on` and JSON `weekday-labels`; domains use `domain-min`/`domain-max`. Box statistic attributes are `min-label`, `q1-label`, `median-label`, `q3-label`, `max-label`, and `outliers-label`. `show-table="false"` hides exact-data disclosure; provide an application-owned summary when additional interpretation is useful. ## Combobox lifecycle `lumen-combobox` enhances its input and listbox when both are available. Children can arrive after connection or be replaced by an application renderer. Disconnecting the host releases listeners and observers; reconnecting binds the current children. Decoded chart annotations ignore invalid supplied axes; omitted axes use the shared `y` default. React hosts can assign `type` on scalar input elements before or after connection. The input reflects that property to its native control without clearing the value. Register elements once at the app boundary and handle their bubbling native input events. `lumen-button` activates with Enter or a Space release. Canceled Enter events, canceled Space keydown events before the host handles them, and canceled Space releases suppress activation. The host consumes Space keydown to prevent scrolling; cancel its key release or click to suppress activation from an ancestor after that keydown has been consumed. It blocks disabled/loading activation, including direct clicks. Blocking flags expose `aria-disabled`; removing them restores any prior application-supplied ARIA value. Native nested controls retain their own keyboard path. ## Device demonstrations `DeviceFrame` presents slotted HTML, an image, or a titled iframe inside `macbook-pro`, `macbook-air`, `imac`, `iphone`, `pixel`, and `ipad-pro` frames, with generic `laptop`, `desktop`, `android`, and `tablet` options. Device-specific enclosures include a MacBook Pro display notch and full front edge, a tapered MacBook Air deck, curved iMac stand and chin, rounded phone glass with separate rails and buttons, and an iPad Pro with even bezels and no Home button. The generic `tablet` retains its classic enclosure. Shells are decorative and do not emulate device hardware. `orientation` selects portrait or landscape; `tone` selects light or dark chrome independently of the screen content. Use `color="white"`, `color="black"`, or a 3-, 4-, 6-, or 8-digit hex color such as `color="#a9b8ac"` for a custom hardware finish. `color` takes precedence over `tone`; invalid values fall back to the tone. The finish stays independent of the content theme. For CSS-driven updates, set `--ui-device-color` to a CSS color on the frame. Iframe layouts use the preset screen viewport and scale to the available width. Override `screenWidth` and `screenHeight` for a custom viewport (1–16384 CSS pixels). Slotted HTML shares the host viewport; container queries can adapt it to the screen. Images preserve their proportions. `scroll={false}` clips HTML overflow; an iframe manages its own scrolling. Supply image alternative text and iframe titles. Consumers own iframe `sandbox`, `allow`, loading, and referrer policies. Remote sites can refuse embedding through their response headers. The decorative shell does not alter focus or intercept interactions. Camera and home-indicator details occupy separate chrome outside live HTML and iframe viewports. Direct phone images extend under the decorative camera and home indicator for a full-bleed presentation. Screen presets are 1280 × 800 for MacBook Pro and MacBook Air, 1440 × 810 for iMac, 390 × 844 for iPhone, 412 × 915 for Pixel, and 834 × 1194 for iPad Pro (1194 × 834 in landscape). These are demonstration viewports, not physical display specifications. ```html ``` Register with `defineLumenElements(['DeviceFrame'])` or `defineLumenDeviceFrame()` from `@santi020k/lumen-elements/components/device-frame`. Use `screen-width`, `screen-height`, and `scroll="false"` attributes. The element preserves the initial child nodes inside its screen; append later content to `.ui-device-frame__screen`. ## Visual interactions and product blocks See [visual interactions](https://github.com/santi020k/lumen/blob/main/docs/visual-interactions.md) for keyed motion, semantic effects, chart continuity, AI surfaces, optional SDK integrations, and the four installable product recipes. ## World map WorldMap supports highlighted countries, location markers, dotted or solid styles, country selection, and theme customization. Use `initialView="highlighted"` (Elements: `initial-view`) to start with a regional view. Zoom toward the cursor with Ctrl/Cmd-scroll, or fit highlighted countries using the map controls. Import geography explicitly from `@santi020k/lumen-core/world-map-data`; it is excluded from root exports. See the [WorldMap usage guide](https://github.com/santi020k/lumen/blob/main/docs/world-map.md) for adapter examples, events, localization, accessibility, and customization. ## Studio media workspace Compose MediaViewport, MediaThumbnail, MediaFilmstrip and ImageComparison modes with the [Studio media workspace recipes](https://github.com/santi020k/lumen/blob/main/docs/studio-media-workspaces.md). Applications retain media loading, selection, adjustment algorithms, processing, export and persistence. ## Resources | Guide | What you will find | | --- | --- | | [Styling contract](https://github.com/santi020k/lumen/blob/main/docs/styling-contract.md) | Stable styling parts, component variables, and overrides. | | [Error handling](https://github.com/santi020k/lumen/blob/main/docs/error-handling.md) | Field feedback, summaries, alerts, and recovery surfaces. | | [Contributing](https://github.com/santi020k/lumen/blob/main/CONTRIBUTING.md) | Setup, checks, and contribution workflow. | | [Release history](https://github.com/santi020k/lumen/releases) | Published releases and version notes. | Part of [Lumen UI](https://lumen.santi020k.com), created by [Santiago Molina](https://santi020k.com). Licensed under [MIT](https://github.com/santi020k/lumen/blob/main/LICENSE); third-party artwork retains its own notices. ## Tailwind CSS v4 complement Tailwind is optional. For utility-based customization, load these imports once in your global CSS: ```css @import "@santi020k/lumen-elements/layers.css"; @import "tailwindcss"; @import "@santi020k/lumen-elements/styles.css"; @import "@santi020k/lumen-elements/tailwind.css"; ``` The optional `tailwind.css` bridge (Lumen 4.3+) maps semantic colors to utilities such as `bg-surface`, `text-ink`, and `border-line`. Inline aliases follow root and nested Lumen themes. Use component props for behavior and utilities for local presentation. The standalone stylesheet does not require Tailwind. See the [Tailwind guide](https://lumen.santi020k.com/docs/web/tailwind) for framework examples, source detection, and Preflight choices.