luxen-ui 0.18.3 → 0.19.0

package/dist/metadata/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.18.3",
+  "version": "0.19.0",
   "elements": [
     {
       "name": "alert",
@@ -2313,6 +2313,14 @@
           "reflects": true,
           "description": "Whether this item's submenu is open. Managed by the parent `l-dropdown`."
         },
+        {
+          "name": "checkPlacement",
+          "attribute": "check-placement",
+          "type": "'start' | 'end'",
+          "default": "'start'",
+          "reflects": true,
+          "description": "Which side of a `type=\"checkbox\"` item carries the check mark. `start` (the\ndefault) puts it in the leading column, where it takes the place of any\n`prefix`. `end` moves it to the trailing edge, freeing that column so the\nitem can show its own icon alongside the state."
+        },
         {
           "name": "hasSubmenu",
           "attribute": null,
@@ -2364,7 +2372,7 @@
         },
         {
           "name": "prefix",
-          "description": "Leading content (e.g. icon)."
+          "description": "Leading content (e.g. icon). A `type=\"checkbox\"` item ignores it unless `check-placement=\"end\"` frees the leading column."
         },
         {
           "name": "suffix",
@@ -5672,6 +5680,72 @@
         }
       ]
     },
+    {
+      "name": "color-scheme-icon",
+      "displayName": "Color scheme icon",
+      "type": "shadow",
+      "isCustomElement": true,
+      "tag": "l-color-scheme-icon",
+      "nativeTag": null,
+      "selector": "l-color-scheme-icon",
+      "subItemOf": null,
+      "summary": "A sun that morphs into a moon. Purely presentational: it shows a\ncolor scheme, it does not choose or store one.\n\nThe two glyphs are a single shape — the disc grows, a mask slides in to carve\nthe crescent, and the rays retract in a ripple — so the change reads as one\nobject turning rather than two icons swapping. That is why this is authored\nSVG rather than an `<l-icon>`: an Iconify icon is opaque, and you cannot grow\none into another or animate a mask inside it.\n\nUse it wherever a scheme needs a glyph and the surrounding element is already\nthe control — a `menuitemcheckbox` row, a button, a legend. With no `scheme`\nit follows the page's scheme from `luxen-ui/color-scheme`, so it needs no\nwiring; set `scheme` to pin it.",
+      "status": "stable",
+      "appearances": [],
+      "import": {
+        "css": null,
+        "js": "luxen-ui/color-scheme-icon"
+      },
+      "properties": [
+        {
+          "name": "scheme",
+          "attribute": "scheme",
+          "type": "ColorScheme | undefined",
+          "default": null,
+          "reflects": true,
+          "description": "Which glyph to show. Leave it unset and the icon follows the page's scheme\n(`colorScheme.current` — a stored override, else the OS preference), so it\nstays in step with every other control without wiring. Set it to pin the\nglyph, for a legend or a preview that must not move."
+        },
+        {
+          "name": "label",
+          "attribute": "label",
+          "type": "string | undefined",
+          "default": null,
+          "reflects": false,
+          "description": "Accessible label. When set, the glyph becomes meaningful (`role=\"img\"`);\nwhen absent it is decorative and hidden from assistive tech — the right\ndefault inside a row or button that already carries the name."
+        }
+      ],
+      "attributes": [],
+      "events": [],
+      "methods": [],
+      "slots": [],
+      "cssClasses": [],
+      "cssParts": [
+        {
+          "name": "base",
+          "description": "The root `<svg>`, for overriding the morph's timing or tilt."
+        }
+      ],
+      "cssProperties": [
+        {
+          "name": "--size",
+          "default": "1em",
+          "description": "Width and height of the glyph."
+        },
+        {
+          "name": "--color",
+          "default": "currentColor",
+          "description": "Glyph color."
+        }
+      ],
+      "commands": [],
+      "examples": [
+        {
+          "title": "In a menu row, where the row is the control",
+          "language": "html",
+          "code": "```html\n<l-dropdown-item type=\"checkbox\" checked>\n<l-color-scheme-icon slot=\"prefix\" scheme=\"dark\"></l-color-scheme-icon>\nDark theme\n</l-dropdown-item>\n```"
+        }
+      ]
+    },
     {
       "name": "toast",
       "displayName": "Toast",

package/dist/registry.d.ts

@@ -1,5 +1,5 @@
 /** Every component base name the library ships. */
-export type ElementBaseName = 'alert' | 'alert-dialog' | 'avatar' | 'badge' | 'button-group' | 'carousel' | 'carousel-item' | 'combobox' | 'dialog' | 'divider' | 'drawer' | 'dropdown' | 'dropdown-item' | 'dropdown-label' | 'form-field' | 'icon' | 'input-group' | 'input-otp' | 'input-stepper' | 'popover' | 'prose-editor' | 'skeleton' | 'slider' | 'spinner' | 'rating' | 'segmented-control' | 'select' | 'sticky-bar' | 'stories' | 'story' | 'stories-viewer' | 'tabs' | 'tag' | 'toast' | 'toast-item' | 'tooltip' | 'tree' | 'tree-item';
+export type ElementBaseName = 'alert' | 'alert-dialog' | 'avatar' | 'badge' | 'button-group' | 'carousel' | 'carousel-item' | 'combobox' | 'dialog' | 'divider' | 'drawer' | 'dropdown' | 'dropdown-item' | 'dropdown-label' | 'form-field' | 'icon' | 'input-group' | 'input-otp' | 'input-stepper' | 'popover' | 'prose-editor' | 'skeleton' | 'slider' | 'spinner' | 'rating' | 'segmented-control' | 'select' | 'sticky-bar' | 'stories' | 'story' | 'stories-viewer' | 'tabs' | 'tag' | 'color-scheme-icon' | 'toast' | 'toast-item' | 'tooltip' | 'tree' | 'tree-item';
 /** Set the global prefix. Must be called before defining elements. */
 export declare function setPrefix(prefix: {
     element: string;

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/html/registry.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,cAAc,GACd,QAAQ,GACR,OAAO,GACP,cAAc,GACd,UAAU,GACV,eAAe,GACf,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,MAAM,GACN,aAAa,GACb,WAAW,GACX,eAAe,GACf,SAAS,GACT,cAAc,GACd,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,mBAAmB,GACnB,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,OAAO,GACP,gBAAgB,GAChB,MAAM,GACN,KAAK,GACL,OAAO,GACP,YAAY,GACZ,SAAS,GACT,MAAM,GACN,WAAW,CAAC;AAMhB,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGxE;AAED,gCAAgC;AAChC,wBAAgB,SAAS,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAE5D;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED,sEAAsE;AACtE,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExC;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE/D;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAE9D"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/html/registry.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,cAAc,GACd,QAAQ,GACR,OAAO,GACP,cAAc,GACd,UAAU,GACV,eAAe,GACf,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,MAAM,GACN,aAAa,GACb,WAAW,GACX,eAAe,GACf,SAAS,GACT,cAAc,GACd,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,mBAAmB,GACnB,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,OAAO,GACP,gBAAgB,GAChB,MAAM,GACN,KAAK,GACL,mBAAmB,GACnB,OAAO,GACP,YAAY,GACZ,SAAS,GACT,MAAM,GACN,WAAW,CAAC;AAMhB,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGxE;AAED,gCAAgC;AAChC,wBAAgB,SAAS,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAE5D;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED,sEAAsE;AACtE,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExC;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE/D;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAE9D"}

package/dist/templates/elements/color-scheme-icon.md

@@ -0,0 +1,279 @@
+---
+outline: deep
+---
+
+# Color scheme icon
+
+A sun that morphs into a moon.
+
+**`<l-color-scheme-icon>`** — Custom Element · Shadow DOM
+
+```html
+<l-color-scheme-icon scheme="dark"></l-color-scheme-icon>
+```
+
+The two glyphs are one shape: the disc grows, a mask slides in to carve the crescent, and the rays retract in a ripple. Nothing is added or removed, so the change reads as a single object turning rather than two icons swapping.
+
+Its home is an icon-only button in a header — the button owns the role, the name and the pressed state; the glyph shows which scheme is in effect.
+
+```html
+<header
+  class="flex w-full items-center justify-between gap-4 rounded-xl border px-4 py-3 border-[var(--l-color-border)] bg-[var(--l-color-surface)]"
+>
+  <div class="flex items-center gap-6">
+    <span class="text-sm font-semibold text-[var(--l-color-text-primary)]">Acme</span>
+
+    <nav class="flex gap-4 text-sm text-[var(--l-color-text-secondary)]">
+      <a href="#">Dashboard</a>
+      <a href="#">Reports</a>
+      <a href="#">Settings</a>
+    </nav>
+  </div>
+
+  <button
+    class="l-button"
+    data-icon-only
+    aria-pressed="false"
+    aria-label="Dark theme"
+  >
+    <l-color-scheme-icon></l-color-scheme-icon>
+  </button>
+</header>
+```
+
+It is **presentational only** — it shows a scheme, it never chooses or stores one. With no `scheme` it follows [`colorScheme.current`](/overview/color-scheme), so it stays in step with every other control on the page without wiring; set `scheme` to pin it.
+
+The example above uses inline handlers to stay readable. In an application, the click and the pressed state are what you wire — the glyph needs nothing:
+
+```js
+import { colorScheme } from 'luxen-ui/color-scheme';
+
+const button = document.querySelector('[aria-label="Dark theme"]');
+
+button.addEventListener('click', () => colorScheme.toggle());
+
+// Called once with the current scheme, then on every change — no initial pass.
+colorScheme.subscribe((scheme) => {
+  button.setAttribute('aria-pressed', String(scheme === 'dark'));
+});
+```
+
+### Which scheme does the glyph show?
+
+The one **in effect**, not the one a click would move to: dark mode shows the moon. That is what makes it correct inside a `role="switch"` thumb or beside an `aria-pressed` button, where the state is already announced and the glyph should agree with it.
+
+To advertise the destination instead — a sun meaning "switch to light" — pass the opposite of your current scheme. Pick one convention and hold it across the app; mixing them is how a toggle stops being readable.
+
+## Options
+
+### Scheme
+
+Leave `scheme` unset and the icon follows the page's [color scheme](/overview/color-scheme) — a stored override, else the OS preference — updating itself when it changes anywhere, including in another tab.
+
+Set `scheme` and the store is out of the picture: the glyph shows what you tell it and nothing else moves it. That is the hook for an app that already owns its light/dark state — a framework store, a class on `<html>` written by the server, a user setting fetched from an API — and also what pins a glyph in a legend or a preview.
+
+```js
+// Your state, your rules. The icon just draws it.
+theme.subscribe((value) => (icon.scheme = value));
+```
+
+```html
+<div class="flex items-center gap-8">
+  <div class="flex flex-col items-center gap-2">
+    <l-color-scheme-icon
+      scheme="light"
+      class="[--size:2rem]"
+    ></l-color-scheme-icon>
+    <code class="text-xs text-[var(--l-color-text-secondary)]">scheme="light"</code>
+  </div>
+
+  <div class="flex flex-col items-center gap-2">
+    <l-color-scheme-icon
+      scheme="dark"
+      class="[--size:2rem]"
+    ></l-color-scheme-icon>
+    <code class="text-xs text-[var(--l-color-text-secondary)]">scheme="dark"</code>
+  </div>
+
+  <div class="flex flex-col items-center gap-2">
+    <l-color-scheme-icon class="[--size:2rem]"></l-color-scheme-icon>
+    <code class="text-xs text-[var(--l-color-text-secondary)]">follows the page</code>
+  </div>
+</div>
+```
+
+### Size & color
+
+`--size` sets width and height (default `1em`, so it scales with the surrounding text). `--color` defaults to `currentColor`.
+
+```html
+<div class="flex items-center gap-8">
+  <l-color-scheme-icon scheme="dark"></l-color-scheme-icon>
+
+  <l-color-scheme-icon
+    scheme="dark"
+    class="[--size:2rem]"
+  ></l-color-scheme-icon>
+
+  <l-color-scheme-icon
+    scheme="dark"
+    class="[--size:3rem] [--color:var(--l-color-text-info)]"
+  ></l-color-scheme-icon>
+</div>
+```
+
+### Accessible name
+
+The icon is decorative by default and hidden from assistive tech, which is what you want inside a row or button that already carries the name. Set `label` to make it meaningful — it then exposes `role="img"` with that name.
+
+Both icons below look identical; the difference exists only in the accessibility tree.
+
+```html
+<div class="flex items-center gap-8">
+  <button
+    class="l-button"
+    data-icon-only
+    aria-label="Dark theme"
+  >
+    <l-color-scheme-icon></l-color-scheme-icon>
+  </button>
+
+  <l-color-scheme-icon
+    label="Currently in dark theme"
+    scheme="dark"
+    class="[--size:2rem]"
+  ></l-color-scheme-icon>
+</div>
+```
+
+## Examples
+
+### In a menu row
+
+Put it in a `type="checkbox"` [dropdown item](/elements/dropdown#theme-row) and the row is the control: whole row clickable, `menuitemcheckbox` role, menu stays open. The icon stays decorative.
+
+Add `check-placement="end"` so the check moves to the trailing edge and leaves the leading column free — the glyph then lines up with every other row's icon.
+
+```html
+<header
+  class="flex w-full items-center justify-between gap-4 rounded-xl border px-4 py-3 border-[var(--l-color-border)] bg-[var(--l-color-surface)]"
+>
+  <div class="flex items-center gap-6">
+    <span class="text-sm font-semibold text-[var(--l-color-text-primary)]">Acme</span>
+
+    <nav class="flex gap-4 text-sm text-[var(--l-color-text-secondary)]">
+      <a href="#">Dashboard</a>
+      <a href="#">Reports</a>
+    </nav>
+  </div>
+
+  <l-dropdown placement="bottom-end">
+    <l-avatar
+      slot="trigger"
+      interactive
+      name="Jane Cooper"
+      aria-label="Account"
+      class="[--appearance:circle] [--color:var(--l-color-blue-200)]"
+    ></l-avatar>
+
+    <div
+      slot="header"
+      class="flex flex-col px-2 py-1.5"
+    >
+      <span class="text-sm font-medium text-[var(--l-color-text-primary)]">Jane Cooper</span>
+      <span class="text-xs text-[var(--l-color-text-secondary)]">jane.cooper@acme.com</span>
+    </div>
+
+    <l-divider></l-divider>
+
+    <l-dropdown-item
+      type="checkbox"
+      check-placement="end"
+      value="theme"
+    >
+      <l-color-scheme-icon slot="prefix"></l-color-scheme-icon>
+      Dark theme
+    </l-dropdown-item>
+
+    <l-dropdown-item
+      type="checkbox"
+      check-placement="end"
+      value="compact"
+      checked
+    >
+      <iconify-icon
+        slot="prefix"
+        icon="lucide:rows-3"
+      ></iconify-icon>
+      Compact rows
+    </l-dropdown-item>
+
+    <l-divider></l-divider>
+
+    <l-dropdown-item value="signout">
+      <iconify-icon
+        slot="prefix"
+        icon="lucide:log-out"
+      ></iconify-icon>
+      Sign out
+    </l-dropdown-item>
+  </l-dropdown>
+</header>
+```
+
+Here the row carries the state, so `checked` is what you keep in step:
+
+```js
+import { colorScheme } from 'luxen-ui/color-scheme';
+
+const item = document.querySelector('l-dropdown-item[value="theme"]');
+
+document.querySelector('l-dropdown').addEventListener('select', (event) => {
+  if (event.item === item) colorScheme.set(item.checked ? 'dark' : 'light');
+});
+
+colorScheme.subscribe((scheme) => (item.checked = scheme === 'dark'));
+```
+
+Do not put a [switch](/elements/switch) in a menu row instead: a `role="menu"` may only own `menuitem`, `menuitemcheckbox` and `menuitemradio` children, and a nested control gives the row two competing click targets.
+
+## Accessibility
+
+### Criteria
+
+- **Decorative by default** — With no `label` the icon is `aria-hidden` — the surrounding row or button carries the accessible name, so nothing is announced twice
+- **Meaningful when named** — Setting `label` exposes `role=img` with that name, for the rare case where the glyph stands alone
+- **Reduced motion** — The morph collapses to 0ms under `prefers-reduced-motion`; the glyph still changes, it just does not animate
+
+### Rules
+
+- Leave the icon decorative when it sits inside a control that already has a name — a menu row, a button
+- Never rely on the glyph alone to convey the state; pair it with a label or an `aria-checked` row
+- Leave `scheme` unset unless the glyph must be pinned — it then follows the page and cannot disagree with it
+
+## API reference
+
+### Importing
+
+```js
+import 'luxen-ui/color-scheme-icon';
+```
+
+### Properties
+
+- **scheme**: `ColorScheme | undefined` — Which glyph to show. Leave it unset and the icon follows the page's scheme
+(`colorScheme.current` — a stored override, else the OS preference), so it
+stays in step with every other control without wiring. Set it to pin the
+glyph, for a legend or a preview that must not move.
+- **label**: `string | undefined` — Accessible label. When set, the glyph becomes meaningful (`role="img"`);
+when absent it is decorative and hidden from assistive tech — the right
+default inside a row or button that already carries the name.
+
+### CSS custom properties
+
+- `--size` (default: `1em`) — Width and height of the glyph.
+- `--color` (default: `currentColor`) — Glyph color.
+
+### CSS parts
+
+- `base` — The root `<svg>`, for overriding the morph's timing or tilt.

package/dist/templates/elements/dropdown.md

@@ -394,6 +394,55 @@ Use the `header` slot for a profile row, the `prefix` slot on each `<l-dropdown-
 </l-dropdown>
 ```
 
+### Theme row {#theme-row}
+
+A display setting belongs in the menu as a `type="checkbox"` item, not as a switch nested inside one. The whole row is then the control — one click target, `role="menuitemcheckbox"`, and the menu stays open so the change is visible immediately. A nested switch would give the row two competing targets, and `role="menu"` may only own `menuitem`, `menuitemcheckbox` and `menuitemradio` children.
+
+A checkbox item puts its check in the leading column, which leaves no room for an icon. Set `check-placement="end"` to move the check to the trailing edge and free that column, so the row keeps its icon **and** shows whether it is on — and its icon lines up with every other row in the menu.
+
+[`<l-color-scheme-icon>`](/elements/color-scheme-icon) in the `prefix` slot then morphs from sun to moon as the row toggles. It stays decorative: the row carries the name, the role and the state.
+
+```html
+<l-dropdown>
+  <l-avatar
+    slot="trigger"
+    interactive
+    name="Jane Cooper"
+    aria-label="Account"
+    style="--appearance: circle; --color: var(--color-purple-200)"
+  ></l-avatar>
+
+  <l-dropdown-item value="whats-new">
+    <iconify-icon
+      slot="prefix"
+      icon="lucide:megaphone"
+    ></iconify-icon>
+    What's new
+  </l-dropdown-item>
+
+  <l-dropdown-item
+    type="checkbox"
+    check-placement="end"
+    value="theme"
+  >
+    <l-color-scheme-icon slot="prefix"></l-color-scheme-icon>
+    Dark theme
+  </l-dropdown-item>
+
+  <l-divider></l-divider>
+
+  <l-dropdown-item value="signout">
+    <iconify-icon
+      slot="prefix"
+      icon="lucide:log-out"
+    ></iconify-icon>
+    Sign out
+  </l-dropdown-item>
+</l-dropdown>
+```
+
+The row reflects and changes the page's [color scheme](/overview/color-scheme); the same glyph works in a header button, outside any menu.
+
 ## Accessibility
 
 ### Criteria
@@ -487,12 +536,16 @@ while open.
 - **variant**: `'destructive' | undefined` (default: `undefined`) — Visual variant. `destructive` marks a delete-style action in red.
 - **checked**: `boolean` (default: `false`) — Whether the checkbox item is checked.
 - **submenu-open**: `boolean` (default: `false`) — Whether this item's submenu is open. Managed by the parent `l-dropdown`.
+- **check-placement**: `'start' | 'end'` (default: `'start'`) — Which side of a `type="checkbox"` item carries the check mark. `start` (the
+default) puts it in the leading column, where it takes the place of any
+`prefix`. `end` moves it to the trailing edge, freeing that column so the
+item can show its own icon alongside the state.
 - **hasSubmenu**: `boolean` — Whether this item has nested `slot="submenu"` items.
 
 ### `dropdown-item` Slots
 
 - **(default)** — Label text.
-- **prefix** — Leading content (e.g. icon).
+- **prefix** — Leading content (e.g. icon). A `type="checkbox"` item ignores it unless `check-placement="end"` frees the leading column.
 - **suffix** — Trailing content.
 - **submenu** — Nested `l-dropdown-item` elements rendered in a submenu panel anchored to this item. Drop an `<hr>` between them for a separator.
 

package/dist/templates/elements/tabs.md

@@ -134,7 +134,9 @@ Set `value="1"` to activate a specific tab on load (0-based index).
 
 ### Disabled tab
 
-Add `disabled` to a tab button to take it out of play. It is skipped by arrow keys, `Home` and `End`, it cannot be selected by a click or by `value`, and it never shows the hover pill. Use `aria-disabled="true"` instead if the tab should stay focusable so keyboard users can still discover it.
+Add `disabled` to a tab button to take it out of play. It is skipped by arrow keys, `Home` and `End`, it cannot be selected by a click or by `value`, and it never shows the hover pill. `aria-disabled="true"` behaves identically — reach for it only when the native attribute is out of reach (a framework binding, a non-`button` element).
+
+`l-tabs` itself takes no `disabled` attribute. To freeze tab switching — while a page loads, say — put `inert` on the tablist `div`: the tabs leave the tab sequence and stop answering clicks, and the active panel stays reachable.
 
 ```html
 <l-tabs variant="line">
@@ -178,6 +180,7 @@ Add `disabled` to a tab button to take it out of play. It is skipped by arrow ke
 - The first child of `l-tabs` must be a `div` containing `button` elements for the tab triggers
 - Each remaining child `div` maps to a tab panel in order
 - Do not add `role` or `aria-*` attributes manually — the custom element sets them automatically
+- `l-tabs` has no host-level `disabled` attribute — put `inert` on the tablist `div` to freeze tab switching
 
 ### Keyboard interactions
 

package/elements.json

@@ -373,6 +373,14 @@
       "inMockups": true,
       "selector": ".l-textarea"
     },
+    {
+      "name": "color-scheme-icon",
+      "displayName": "Color scheme icon",
+      "kind": "element",
+      "type": "shadow",
+      "inSkill": true,
+      "inMockups": false
+    },
     {
       "name": "toast",
       "displayName": "Toast",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxen-ui",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Modern web components and CSS-first UI library built with Lit. Framework-agnostic, customizable prefix, design tokens.",
   "keywords": [
     "custom-elements",
@@ -117,6 +117,10 @@
       "types": "./dist/shared/localize.d.ts",
       "import": "./dist/shared/localize.js"
     },
+    "./color-scheme": {
+      "types": "./dist/color-scheme.d.ts",
+      "import": "./dist/color-scheme.js"
+    },
     "./translations/*": {
       "types": "./dist/translations/*.d.ts",
       "import": "./dist/translations/*.js"

package/vite-plugin.ts

@@ -83,11 +83,30 @@ export interface LuxenOptions {
    * commit it and edit freely.
    */
   emitTypes?: string | EmitTypesOptions;
+  /**
+   * Build-time defaults for the `luxen-ui/color-scheme` store, so a project
+   * never has to call `colorScheme.configure()` from its entry point.
+   */
+  colorScheme?: ColorSchemeOptions;
+}
+
+/** Build-time defaults for `luxen-ui/color-scheme`. */
+export interface ColorSchemeOptions {
+  /**
+   * `localStorage` key holding the light/dark override. Default
+   * `'luxen-color-scheme'`; `''` disables persistence. The before-first-paint
+   * snippet in your `<head>` must read the same key — it runs before any module
+   * and cannot be rewritten by the build.
+   */
+  storageKey?: string;
+  /** Have the store write `color-scheme` on `<html>` itself. Default `false`. */
+  apply?: 'root' | false;
 }
 
 export default function luxen(options: LuxenOptions = {}): Plugin {
   let elementPrefix = 'l';
   let cssPrefix = 'l';
+  let colorSchemeCfg: ColorSchemeOptions = {};
 
   return {
     name: 'luxen',
@@ -99,6 +118,7 @@ export default function luxen(options: LuxenOptions = {}): Plugin {
       const fileCfg = await loadLuxenConfig();
       elementPrefix = options.elementPrefix ?? fileCfg?.elementPrefix ?? 'l';
       cssPrefix = options.cssPrefix ?? fileCfg?.cssPrefix ?? 'l';
+      colorSchemeCfg = { ...fileCfg?.colorScheme, ...options.colorScheme };
       const emitTypes = options.emitTypes ?? fileCfg?.emitTypes;
 
       if (emitTypes) {
@@ -127,20 +147,63 @@ export default function luxen(options: LuxenOptions = {}): Plugin {
      * switching), but ordinary consumers don't need to call it.
      */
     transform(code, id) {
-      if (elementPrefix === 'l' && cssPrefix === 'l') return null;
-      if (!isLuxenRegistry(id)) return null;
-      let out = code;
-      if (elementPrefix !== 'l') {
-        out = out.replace(/_elementPrefix = 'l';/g, `_elementPrefix = '${elementPrefix}';`);
+      if (isLuxenRegistry(id)) {
+        if (elementPrefix === 'l' && cssPrefix === 'l') return null;
+        let out = code;
+        if (elementPrefix !== 'l') {
+          out = out.replace(/_elementPrefix = 'l';/g, `_elementPrefix = '${elementPrefix}';`);
+        }
+        if (cssPrefix !== 'l') {
+          out = out.replace(/_cssPrefix = 'l';/g, `_cssPrefix = '${cssPrefix}';`);
+        }
+        return out === code ? null : { code: out, map: null };
       }
-      if (cssPrefix !== 'l') {
-        out = out.replace(/_cssPrefix = 'l';/g, `_cssPrefix = '${cssPrefix}';`);
+
+      // Same trick for the color-scheme store: rewrite the two literal
+      // initialisers in `color-scheme.js` so a project's `luxen.config.mjs`
+      // defaults are baked in. `configure()` remains the runtime path.
+      if (isLuxenColorScheme(id)) {
+        const { storageKey, apply } = colorSchemeCfg;
+        if (storageKey === undefined && apply === undefined) return null;
+        let out = code;
+        if (storageKey !== undefined) {
+          out = bakeInitialiser(out, '_storageKey', "'luxen-color-scheme'", storageKey);
+        }
+        if (apply !== undefined) out = bakeInitialiser(out, '_apply', 'false', apply);
+        return out === code ? null : { code: out, map: null };
       }
-      return out === code ? null : { code: out, map: null };
+
+      return null;
     },
   };
 }
 
+/**
+ * Rewrite `let <name>[: Type] = <literal>;` to hold `value`.
+ *
+ * The optional type annotation is what makes this a helper rather than a plain
+ * `String.replace`: the module resolves to the compiled `let _apply = false;` in
+ * `dist`, but to `let _apply: ColorSchemeApply = false;` when a project points at
+ * the TypeScript source — which `isLuxenColorScheme` accepts. A pattern that only
+ * matched the compiled shape would drop half a project's configuration there,
+ * silently and with no build error.
+ */
+function bakeInitialiser(code: string, name: string, literal: string, value: unknown): string {
+  const pattern = new RegExp(
+    `${name}(\\s*:\\s*[\\w.<>|'" ]+?)? = ${literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')};`,
+    'g',
+  );
+  return code.replace(
+    pattern,
+    (_match, annotation) => `${name}${annotation ?? ''} = ${JSON.stringify(value)};`,
+  );
+}
+
+function isLuxenColorScheme(id: string): boolean {
+  const path = id.replace(/\\/g, '/').split('?')[0] ?? '';
+  return /\/luxen-ui\/(?:dist|src\/html)\/color-scheme\.(?:js|ts)$/.test(path);
+}
+
 function isLuxenRegistry(id: string): boolean {
   // Normalise for Windows + strip Vite query params (`?import`, `?used`, …)
   const path = id.replace(/\\/g, '/').split('?')[0] ?? '';