luxen-ui 0.25.0 → 0.26.0

package/dist/templates/foundations/focus.md

@@ -0,0 +1,303 @@
+---
+outline: deep
+---
+
+# Focus
+
+The focus indicator shows where the keyboard is. Every Luxen element draws it from the same three tokens, on `:focus-visible`, as an `outline`. Press <kbd>Tab</kbd>:
+
+```html
+<div class="flex flex-wrap items-center gap-4">
+  <button
+    type="button"
+    class="l-button"
+    data-variant="primary"
+  >
+    Save
+  </button>
+  <button
+    type="button"
+    class="l-button"
+  >
+    Cancel
+  </button>
+  <label class="flex items-center gap-2 text-sm">
+    <input
+      type="checkbox"
+      class="l-checkbox"
+    />
+    Remember me
+  </label>
+  <label class="flex items-center gap-2 text-sm">
+    <input
+      type="checkbox"
+      role="switch"
+      class="l-switch"
+    />
+    Notifications
+  </label>
+  <l-segmented-control
+    label="View"
+    value="list"
+  >
+    <button value="list">List</button>
+    <button value="board">Board</button>
+  </l-segmented-control>
+  <input
+    class="l-input w-40"
+    placeholder="Search…"
+    aria-label="Search"
+  />
+</div>
+```
+
+## Anatomy
+
+| Part   | Token                                          | Default                             |
+| ------ | ---------------------------------------------- | ----------------------------------- |
+| Offset | `--l-focus-ring-offset`                        | `2px`                               |
+| Ring   | `--l-focus-ring-width`, `--l-focus-ring-color` | `2px`, `#d9461f`                    |
+| Halo   | `--l-form-control-focus-halo-width`            | `3px`, the ring color at 22%        |
+| Border | `--l-form-control-border-width`                | `1px`, in the ring color            |
+| Stroke | `--l-form-control-focus-border-width`          | `2px`, drawn inward over the border |
+
+An invalid field takes `--l-form-control-border-color-invalid` for its halo, border and stroke.
+
+## Placements
+
+| Placement     | Drawn                                                        | Used by                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Outside       | `outline-offset: var(--l-focus-ring-offset)`                 | Button, link, checkbox, radio, switch, tag, avatar, breadcrumb, slider thumb, rating star, carousel buttons                                                     |
+| Inside        | `outline-offset: calc(var(--l-focus-ring-width) * -1)`       | Menu item, tabs, segmented control, disclosure summary, input stepper, carousel dots — items set edge to edge, where an outside ring would overlap the neighbor |
+| Field         | Border recolored, stroke inward, halo outside (`box-shadow`) | Input, textarea, select, `l-input-group`, `l-select` and its search box, `l-combobox`, `l-prose-editor`, the active `l-input-otp` cell                          |
+| Active option | Inside ring, once the arrow keys moved it                    | `l-select` and `l-combobox` options                                                                                                                             |
+
+In a listbox, DOM focus stays on the field and `aria-activedescendant` points at the option. The browser draws no focus there, so the option draws the ring itself when the keyboard moved it. A mouse-driven highlight stays a tint, like a hover.
+
+## Shown when it helps
+
+[`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible) lets the browser decide whether focus needs an indicator. Luxen never styles `:focus` alone.
+
+| Focus arrives by           | On                         | Indicator                      |
+| -------------------------- | -------------------------- | ------------------------------ |
+| <kbd>Tab</kbd>, arrow keys | Any control                | Shown                          |
+| Click or tap               | Button, checkbox, tab, row | Hidden                         |
+| Click or tap               | Text field                 | Shown — typing follows         |
+| Script (`element.focus()`) | Any control                | Same as the element focus left |
+
+When a script moves focus after a click and the user must see where it landed, force it: `element.focus({ focusVisible: true })`.
+
+## Contrast
+
+The ring needs **3:1** against the surface it sits on. The default passes on Luxen surfaces in both schemes, not on every background you may put under it.
+
+Tokens cascade: set the color on the container that changes the background.
+
+```css
+.hero {
+  --l-focus-ring-color: white;
+}
+```
+
+```html
+<div
+  class="flex w-full flex-wrap items-center gap-4 rounded-lg bg-[#1e3a8a] p-6 [color-scheme:dark] [--l-focus-ring-color:white]"
+>
+  <button
+    type="button"
+    class="l-button"
+    data-variant="primary"
+  >
+    Get started
+  </button>
+  <button
+    type="button"
+    class="l-button"
+  >
+    Learn more
+  </button>
+</div>
+```
+
+Over a photo or a video no single color is safe. Use two — a light ring edged with dark ([WCAG technique C40](https://www.w3.org/WAI/WCAG22/Techniques/css/C40)), as `l-stories-viewer` does for the buttons over its media:
+
+```css
+.on-media :focus-visible {
+  outline: var(--l-focus-ring-width) solid white;
+  outline-offset: var(--l-focus-ring-offset);
+  box-shadow: 0 0 0 calc(var(--l-focus-ring-offset) + var(--l-focus-ring-width) * 2) black;
+}
+```
+
+## Never hidden
+
+A sticky header or bar can cover the element that just received focus. Reserve their height on the scroll container:
+
+```css
+html {
+  scroll-padding-block: 4rem 5rem; /* sticky header, sticky bar */
+}
+```
+
+A container with `overflow: hidden` clips an outside ring. Give it padding of at least offset + width (`4px` by default).
+
+## Forced colors
+
+In forced colors mode (Windows High Contrast), the browser drops every `box-shadow` and repaints `outline` in a system color. Luxen rings are outlines. A field's halo is a shadow, so fields add a transparent outline there for the system to repaint.
+
+## Variants
+
+Deliberate departures from the three tokens, each for a reason:
+
+| Where                                 | Variant                                                            | Why                                                                |
+| ------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| Invalid field                         | Border, stroke and halo in `--l-form-control-border-color-invalid` | The error stays readable while the field is focused                |
+| Destructive menu item                 | Ring in `--l-color-text-danger`                                    | Matches the item's own danger color                                |
+| Tree row, prose editor toolbar button | Half the offset                                                    | Rows and buttons sit edge to edge; a full gap reaches the neighbor |
+| Carousel buttons                      | Gap filled with `--l-color-surface`                                | They float over slides: the ring always sits next to a known color |
+| Stories viewer buttons                | Light ring edged with a dark band                                  | They float over video, whose brightness is unknown                 |
+| `l-input-otp`, `l-prose-editor`       | `--cell-focus-color`, `--border-color-focus`                       | Per-element color override, defaulting to `--l-focus-ring-color`   |
+
+## Your own controls
+
+Plain links, `<button>` and `<summary>` already take the ring from Luxen's base CSS (zero specificity: any rule of yours wins). For anything else, reuse the tokens so custom controls match:
+
+```css
+.card-link:focus-visible {
+  outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
+  outline-offset: var(--l-focus-ring-offset);
+}
+
+/* Inside a clipping container: flush with the inner edge */
+.menu-row:focus-visible {
+  outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
+  outline-offset: calc(var(--l-focus-ring-width) * -1);
+}
+
+/* Ring on a wrapper whose focusable child is visually hidden */
+.swatch:has(input:focus-visible) {
+  outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
+  outline-offset: var(--l-focus-ring-offset);
+}
+```
+
+## Theming
+
+### Brand color
+
+One value per scheme with `light-dark()` — 6.9:1 on white, 8.8:1 on the dark surface. For a neutral ring that follows the scheme and forced colors on its own, use the system color `CanvasText`.
+
+```css
+:root {
+  --l-focus-ring-color: light-dark(oklch(48% 0.2 265), oklch(78% 0.14 265));
+}
+```
+
+### One thickness everywhere
+
+Point the field stroke at the ring width and drop the halo:
+
+```css
+:root {
+  --l-focus-ring-width: 3px;
+  --l-form-control-focus-border-width: var(--l-focus-ring-width);
+  --l-form-control-focus-halo-width: 0;
+}
+```
+
+```html
+<div
+  class="flex flex-wrap items-center gap-4 [--l-focus-ring-width:3px] [--l-form-control-focus-border-width:var(--l-focus-ring-width)] [--l-form-control-focus-halo-width:0px]"
+>
+  <button
+    type="button"
+    class="l-button"
+  >
+    Save
+  </button>
+  <label class="flex items-center gap-2 text-sm">
+    <input
+      type="checkbox"
+      class="l-checkbox"
+    />
+    Remember me
+  </label>
+  <input
+    class="l-input w-48"
+    placeholder="Full name"
+    aria-label="Full name"
+  />
+</div>
+```
+
+### Crisp field
+
+The stroke alone, no halo. The stroke is drawn inward: the field keeps its size and its text does not move.
+
+```css
+:root {
+  --l-form-control-focus-halo-width: 0;
+}
+```
+
+```html
+<div class="grid max-w-sm gap-4 [--l-form-control-focus-halo-width:0px]">
+  <l-form-field>
+    <label>Start date</label>
+    <input type="date" />
+  </l-form-field>
+  <l-form-field>
+    <label>Plan</label>
+    <select class="l-select">
+      <option>Starter</option>
+      <option>Pro</option>
+    </select>
+  </l-form-field>
+  <l-select
+    label="Team"
+    placeholder="Pick a team…"
+  >
+    <datalist>
+      <option value="design">Design</option>
+      <option value="dev">Development</option>
+    </datalist>
+  </l-select>
+  <l-combobox
+    label="Country"
+    placeholder="Search a country…"
+  >
+    <datalist>
+      <option value="fr">France</option>
+      <option value="de">Germany</option>
+    </datalist>
+  </l-combobox>
+</div>
+```
+
+## Accessibility
+
+- **Visible** — Every focusable element shows an indicator on keyboard focus
+- **Contrast** — The indicator has 3:1 against adjacent colors: 4.3:1 on white, 4.1:1 on the dark surface
+- **Size** — Outside rings are a solid 2px perimeter, the minimum area of Focus Appearance (AAA). Inside rings and the field stroke are drawn inward, which covers less: set `--l-focus-ring-width` and `--l-form-control-focus-border-width` to `3px` to meet it everywhere
+- **Not obscured** — Rings between items set edge to edge are drawn inside, so none is covered by a neighbor; `scroll-padding` keeps focus clear of sticky content
+- **Forced colors** — Indicators are outlines, repainted by the system; never a `box-shadow` alone
+- **Order** — Focus follows DOM order; composite widgets (tabs, tree, menu, radio group) are one Tab stop with arrow keys inside, and focus is never trapped
+
+### Rules
+
+- Never write `outline: none` without an equally visible replacement
+- Style `:focus-visible`, not `:focus`
+- Draw indicators with `outline`; a `box-shadow` alone disappears in forced colors
+- Keep `--l-focus-ring-width` at `2px` or more
+- Check `--l-focus-ring-color` at 3:1 against every background it lands on, in light and dark; scope it where a background differs
+- Set `scroll-padding` on the scroll container when the page has sticky headers or bars
+- Never use a positive `tabindex`
+
+## Tokens
+
+- `--l-focus-ring-color` (default: `#d9461f`) — Color of the focus indicator, shown on :focus-visible: the ring around buttons, checkbox, radio, switch, tabs, tags, menu and tree items, links, and the border and halo of a focused text field. Keep at least 3:1 against every surface it lands on (WCAG 1.4.11) — the default gives 4.3:1 on white and 4.1:1 on the dark surface. Re-theme it on an ancestor to scope it, e.g. a lighter color over a photo.
+- `--l-focus-ring-width` (default: `2px`) — Thickness of the :focus-visible ring drawn around interactive elements — buttons, checkbox, radio, switch, slider thumb, rating, tabs, tags, menu and tree items, toolbar and adornment buttons, close buttons, avatars, breadcrumb links. Keep it at 2px or more (WCAG 2.4.13). Rings set inside their element (items laid edge to edge — menu items, tabs, segmented control — where an outer ring would overlap a neighbor or the panel edge) grow inward with it. Text fields show focus on their border instead: see --l-form-control-focus-border-width, which a consumer can point at this token for one focus thickness everywhere.
+- `--l-focus-ring-offset` (default: `2px`) — Gap between an element and its :focus-visible ring, so the ring reads apart from the element's own border or fill. Rings set inside their element (menu items, tabs, segmented control, disclosure summary — items laid edge to edge, where an outer ring would overlap a neighbor or the panel edge) ignore it and sit flush inside the edge instead.
+
+- `--l-form-control-focus-border-width` (default: `2px`) — Width of the stroke drawn on a focused text field (input, textarea, native select, input group, l-select and its search box, l-combobox, l-prose-editor, the active l-input-otp cell), in the focus-ring color (the invalid color on an invalid field). Drawn inward from the outer edge, over the border: the control keeps its size and its text does not move. The default `2px` covers the 1px border and 1px more inside, so a focused field reads as clearly as a ring around a button. A value at or below --l-form-control-border-width adds nothing visible: the resting border alone takes the focus color.
+- `--l-form-control-focus-halo-width` (default: `3px`) — Width of the soft halo around a focused text field — a ring of the focus-ring color (the invalid color on an invalid field) at 22% opacity, outside the border. Set to `0` for a crisp stroke with no halo, typically together with --l-form-control-focus-border-width. The color is mixed at the control, so a --l-focus-ring-color re-themed on an ancestor recolors the halo too.

package/elements.json

@@ -356,6 +356,15 @@
       "inMockups": true,
       "selector": ".l-switch"
     },
+    {
+      "name": "table",
+      "displayName": "Table",
+      "kind": "native",
+      "type": "native",
+      "inSkill": true,
+      "inMockups": true,
+      "selector": ".l-table"
+    },
     {
       "name": "tabs",
       "displayName": "Tabs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxen-ui",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Modern web components and CSS-first UI library built with Lit. Framework-agnostic, customizable prefix, design tokens.",
   "keywords": [
     "custom-elements",

package/postcss-plugin-prefix.js

@@ -70,14 +70,14 @@ plugin.postcss = true;
  *
  * Each element ships its shadow-DOM CSS baked into the element JS, built once
  * with the default `l` prefix — that CSS never passes through this plugin, so
- * it keeps reading `var(--l-focus-ring)` etc. Meanwhile the consumer's imported
+ * it keeps reading `var(--l-focus-ring-color)` etc. Meanwhile the consumer's imported
  * preset now only defines `--{cssPrefix}-*`. Without a bridge the two
  * namespaces never meet and every shadow token resolves to nothing.
  *
  * So for every `--l-*` token declaration we just renamed, append a one-time
  * `:root` alias pointing the canonical name at the prefixed one:
  *
- *   :root { --l-focus-ring: var(--p-focus-ring); … }
+ *   :root { --l-focus-ring-color: var(--p-focus-ring-color); … }
  *
  * The block rides along with whichever imported file defines the tokens
  * (preset / tokens / aliases), stays exhaustive automatically (it mirrors

package/templates/SKILL.md.tpl

@@ -42,6 +42,7 @@ These rules apply across all elements; element-specific detail lives in the per-
 - **Variants and state use `data-*` attributes** (`data-variant`, `data-appearance`), not modifier classes.
 - **Show/hide overlays with the invoker pattern**: `command="--show"` / `command="--hide"` + `commandfor="<id>"` for dialog and drawer.
 - **Colors, spacing, and typography come from design tokens** — see [references/tokens.md](references/tokens.md). Use the semantic tokens and utility classes listed there rather than arbitrary values.
+- **Focus states follow [references/foundations/focus.md](references/foundations/focus.md)** — read it before styling `:focus-visible` on any control, overriding a focus token, or placing controls on a custom background.
 - **Customize through the documented surface** — CSS custom properties, CSS parts, events. Before overriding an element's styles through `::part()` or working around one of its behaviours (motion, event timing), check its spec: the knob usually exists. When it does not, that is a gap in {{name}} — report it upstream rather than shipping a local workaround.
 
 ## Choosing an element

package/templates/choosing-elements.md.tpl

@@ -109,6 +109,7 @@ the platform genuinely can't express the behavior (a modal, a combobox, a toast)
 | A keyboard key                                        | `.l-kbd`                                 |
 | A separator between content                          | `<l-divider>`                            |
 | Hierarchical, expandable data                        | `<l-tree>`                               |
+| Records in rows and columns                          | `.l-table` (on `<table>`)                |
 
 ### Navigate or organize