@espressif/dashboard-ui-components 1.11.2 → 1.12.0

package/.claude/rules/dashboard-ui-consumption.md

@@ -17,14 +17,19 @@ Use only paths declared under `package.json` → `exports`:
 |---------|---------|
 | `@espressif/dashboard-ui-components` | Root barrel: re-exports **components**, **common**, and **layouts**. Use only when the app intentionally pulls from multiple surfaces; otherwise prefer narrower subpaths below. |
 | `@espressif/dashboard-ui-components/components` | Public UI components and their types. |
+| `@espressif/dashboard-ui-components/components/<folder>` | One component folder (`/components/button`, `/components/dialog`, …): the same names and objects `/components` exports for it. **Prefer this.** |
+| `@espressif/dashboard-ui-components/charts` · `/data-table` · `/markdown` · `/date` · `/carousel` · `/forms` · `/animation` · `/toast` | One heavy family (recharts, tanstack, react-markdown + shiki, react-day-picker, embla, react-hook-form, lottie, sonner). |
 | `@espressif/dashboard-ui-components/layouts` | `WorkspaceLayout`, `EntryLayout`, and related layout exports. |
 | `@espressif/dashboard-ui-components/common` | Shared blocks (e.g. `AppLogo`, `ProfileCard`, `FooterCard`). |
 | `@espressif/dashboard-ui-components/utils` | Utilities such as `cn`. |
-| `@espressif/dashboard-ui-components/styles` | Global CSS (design tokens / base styles). |
+| `@espressif/dashboard-ui-components/styles` | Global CSS: Tailwind + every token + base page styles. |
+| `@espressif/dashboard-ui-components/theme.css` | Tokens only (no `@import "tailwindcss"`, no Preflight, no page styles), for apps that bring their own Tailwind. |
 | `@espressif/dashboard-ui-components/tailwind-preset` | Tailwind v4 preset. |
 
 **Do not** import from deep paths that are not in `exports` (they will fail under strict package managers or break without warning). **Do not** treat `@espressif/dashboard-ui-components/core` as a supported app API: it exists in `exports` for technical reasons, but consumers must not import `core` — use composed exports from `/components`.
 
+**Import from the narrowest path you can**: `/components/<folder>` for one component, a grouped path for a heavy family, a surface (`/components`, `/layouts`, …) only when importing many. Tests and dev servers evaluate everything an entry reaches. Entries that include Toast (`/toast`, `/components/toast`, `/components`, root) import sonner's CSS from JS; the others do no work at import time.
+
 ## Import style
 
 - Prefer **named imports**: `import { Button, Alert } from '…/components'`.
@@ -38,6 +43,7 @@ Do **not** invent component or prop names from memory. The authoritative list of
 exports and their props is the shipped type declarations:
 
 - Components: `node_modules/@espressif/dashboard-ui-components/dist/components/index.d.ts`
+- One component folder: `…/dist/components/<folder>/index.d.ts`; grouped entries: `…/dist/<group>/index.d.ts`
 - Layouts / common / utils: the sibling `dist/<surface>/index.d.ts` files
 - The README "Available Components" table for a human-readable overview
 
@@ -66,8 +72,73 @@ export function Example() {
 ## Styling and theming
 
 - Add the library's styles once in your Tailwind v4 entry CSS: `@import "@espressif/dashboard-ui-components/styles";`. That file already declares the `@source` for the compiled `dist/`, so no extra `content`/`@source` entry is needed.
-- Retheme by redeclaring the CSS custom properties (design tokens) **after** the `@import`, in both `:root` and `.dark`. Override `--font-sans` inside an `@theme` block.
+- Retheme by redeclaring the CSS custom properties (design tokens) **after** the `@import`, in both `:root` and `.dark` (or `[data-theme="dark"]`). Override `--font-sans` / `--font-mono` inside an `@theme` block.
+- Layout heights: use `--espd-shell-header-height`, `--espd-workspace-layout-footer-height` and
+  `--espd-workspace-layout-hidden-footer-height`. The old names (`--espd-header-height`,
+  `--espd-footer-height`, `--espd-hidden-footer-height`) are deprecated fallbacks: do not use them
+  in new code, and when migrating rename an app's overrides and its own reads together.
+- `MinimalWorkspaceLayout` (from `/layouts`) is the header-less alternative to `WorkspaceLayout`
+  with the same props: switch by renaming the component. It has no header bar or status footer
+  (`footerConfig`, `hideBreadcrumbs`, `sidebarConfig.allowCollapsible` / `variant` do not exist on
+  it), starts collapsed (`defaultSidebarOpen` defaults to `false`), and puts `topRightContent`
+  (fallback `headerConfig.rightContent`) over the content. Theme it with the
+  `--espd-minimal-workspace-layout-*` tokens, not `className` overrides on its parts: the sidebar
+  surface defaults to the page background (`-sidebar-background`, `-sidebar-background-expanded`),
+  and its border, shadow and row accent are derived from that surface unless `-sidebar-border-color`,
+  `-sidebar-elevation` or `-sidebar-accent` are set. Keep `-sidebar-width-collapsed` within 48–56px.
+  With `sidebarConfig.hideWhenCollapsed` the collapsed sidebar is hidden instead of a rail: a click
+  on the content's left edge peeks it over the content until the pointer leaves it, and
+  `MinimalWorkspaceSidebarTrigger` (from `/layouts`, placed in `topRightContent`) opens it inline;
+  a peek never reaches `onSidebarOpenChange`. Do not build an edge or trigger in the app. The edge
+  strip and the peek shadow are `-edge-color`, `-edge-width` and `-sidebar-overlay-elevation`.
 - The library ships **no fonts**; the app supplies its own typeface via `--font-sans`.
+- Pick `./theme.css` instead of `./styles` only when the app has its own `@import "tailwindcss"` (or legacy CSS a reset would break); then the app styles `body` itself.
+- Dark mode applies under `.dark` **or** `[data-theme="dark"]` on an ancestor; override dark tokens under the selector the app uses. The library has no `prefers-color-scheme` handling.
+- Beyond colour, retheme with the semantic tokens on `:root` (and the style-axis role tokens, next section): `--espd-control-height-sm|md|lg`, `--espd-button-padding-x-sm|md|lg`, `--espd-duration-fast|normal|slow`, `--espd-ring-width`, `--espd-ring-offset`, `--espd-on-solid-foreground` (plus Tailwind's `--radius-*`, `--shadow-*`, `--spacing`). Do not add new token names in app CSS.
+- New variants (e.g. `glow`) are registered, not forked: augment `interface VariantRegistry` in `declare module '@espressif/dashboard-ui-components/components'` (in a file that imports that entry) and call `registerVariant('glow', (color) => ({ container, foreground, description }))` once at start-up. Built-in variants cannot be replaced.
+
+## Shape, elevation, border and density (style axes)
+
+Change corner radius, shadow, border width or density with the library's axes, not with
+`className` overrides on every component:
+
+- **A kind of component, app-wide:** set a **role token** in CSS after the `@import`:
+  `--espd-radius-{control|surface|overlay|pill|item}`,
+  `--espd-elevation-{control|surface|overlay}`, `--espd-border-width-{control|surface}`.
+  Unset means each component keeps its own look. Overlays render in portals, so set overlay
+  tokens on `:root`, not on a wrapper.
+- **A subtree, from React:** `<StyleScope radius={{ control: "full" }} elevation={{ surface: "none" }} density="compact">`
+  (from `/components/style-scope`). It sets the same tokens on a `display: contents` wrapper.
+- **One component:** the `radius`, `elevation` and `border` props, where the component's
+  type declares them (check its `.d.ts`; not every component takes every axis). They affect
+  that component only, never the components nested inside it. The date pickers' `radius` is
+  the trigger's; their calendar popover takes `popoverRadius` / `popoverElevation`.
+- **Density:** `density="compact" | "default" | "comfortable"` on Table, DataTable, Card, List,
+  SimpleList, FiltersBar, Sidebar, DialogContent, SheetContent, or on `StyleScope`. It also sets
+  `--espd-gap-field` (FormItem) and `--espd-gap-stack` (DialogContent); for a form, wrap it in
+  `StyleScope density` (Form renders no element).
+
+Precedence: `className` > instance prop > role token > the component's own default.
+
+Things agents get wrong:
+
+- An elevation token takes a `box-shadow` value: use `0 0 #0000` for "flat", **not** `none`
+  (it would also remove focus rings). The `elevation="none"` prop already does this.
+- Older props still work: `rounded` (Input, InputOTP, FileInput, Tag, date pickers) equals
+  `radius="full"`; `noShadow` / `noBorder` (SimpleCard). When both are passed, `radius` /
+  `elevation` / `border` win. Prefer the new props in new code.
+- Instance props need the library stylesheet (`./styles` or `./theme.css`).
+- New values are registered, not invented: augment `RadiusRegistry` / `ElevationRegistry` /
+  `BorderRegistry` / `DensityRegistry` in `declare module '@espressif/dashboard-ui-components/components'`
+  and call `registerStyleValue(axis, name, css)` or `registerDensity(name, tokens)` once at
+  start-up. Built-ins cannot be replaced.
+
+## Buttons
+
+- Use the styled `Button` from `/components` (or `/components/button`). `/core` has an uncoloured base `Button` with the same name: not for apps.
+- `fullWidth` **defaults to `true`**; pass `fullWidth={false}` for an inline button.
+- For a link that looks like a button use `asChild`, never a Button that navigates in `onClick`:
+  `<Button asChild startIcon={<Plus />}><Link to="/new">Add</Link></Button>`. With `disabled`/`loading` the link gets `aria-disabled`, `tabIndex={-1}` and its clicks are cancelled.
 
 ## Optional peer dependencies
 
@@ -80,7 +151,7 @@ Install only when the feature is used:
 | `shiki` | `Code` / syntax highlighting |
 | `recharts` | Chart components |
 
-Required peers for any usage: `react`, `react-dom`, `tailwindcss` (v4).
+Required peers for any usage: `react`, `react-dom`, `tailwindcss` (v4.1+).
 
 Do **not** tell users to install `react-markdown`, `remark-gfm`, or `rehype-slug` for
 `MarkdownContent` — they are regular dependencies of this package and install with it.
@@ -141,12 +212,112 @@ Things agents get wrong about it:
   if that matters.
 - `className` / `style` style the editor box, not the `<textarea>`.
 
+## Coverflow, Carousel or CardRail
+
+- `Coverflow` (from `/components`): a 3D ring of image cards with a glass reflection and a
+  caption node per item, for a showcase of a few pictures (featured projects, boards).
+  `Carousel`: plain slides of any content in a strip. `CardRail`: a scrolling row of cards
+  that shows several at once.
+- Items are `{ id, name, image?, imageAlt?, caption? }`; `name` is the accessible name.
+  Without `onOpen` the front card is a picture, not a button.
+- `renderFace` is drawn **twice** (the card and its reflection): return a picture only —
+  nothing focusable, no `id`s. It receives `{ offset, visible }`; render expensive faces only
+  while `visible`.
+- It draws no background. The reflection only reads on a dark floor: wrap it in a `.dark`
+  scope with `bg-background` (or any dark surface). Size comes from `aspect`
+  (`landscape` 4:3, `square`); do not set the stage height through `className`.
+- The reflection fade uses `mask-*` utilities, which need Tailwind **4.1+**.
+
+## CategoryCard or SimpleClickableCard
+
+- `CategoryCard` (from `/components`): a "browse by kind" card, stacked: icon tile, a count
+  (`value`) in the corner, name, one line, a few `tags`. `SimpleClickableCard`: one action in a
+  row with a chevron. Prop names match where they mean the same (`icon`, `title`,
+  `description`, `color`, `radius`, `onClick`).
+- It sizes itself by its own width (a container query): below 12rem it tightens and drops the
+  tags. Do not hide the tags per breakpoint in the app.
+- A filter row passes `selected` (gives `aria-pressed`); a navigating row passes `href` (a real
+  link) and leaves `selected` unset. Pass `aria-label` when the name to read is richer than
+  the visible text ("Show only Drivers, 65 blocks").
+- Token tints the colour presets lack (the swatches) go in `iconClassName`, which replaces
+  `color` (do not pass both).
+
+## PopoverGroup — one hover preview across many items
+
+- Wrap a grid or row of `Popover openOnHover` items in `PopoverGroup` (from `/components`) so
+  only one is open: the first opens after the popover's `openDelay`, another takes over only
+  after the pointer rests `switchDelay` (default 350 ms) on it, and reaching the open content
+  cancels a pending switch — so a diagonal path to the panel never switches it. Do not build
+  hover-intent timers in the app.
+- Give each `Popover` a `value` when the app needs to know which is open; read it from the
+  group's `value` / `onValueChange` (a member's own `onOpenChange` does not fire when another
+  takes over). A `Popover` with an explicit `open` stays outside the group.
+- Click still pins, Escape and an outside press close, and a hover-opened panel never takes
+  focus — the same as a lone `openOnHover` popover.
+
+## FlipCard
+
+- `FlipCard` (from `/components`): two faces, controlled by `flipped`; each change moves the
+  same way, never back. `effect="turn"` (default) turns it over (`axis="x"` a split-flap, `"y"`
+  a page); `effect="slide"` slides the showing face out while the next follows it in (`x` down,
+  `y` sideways). To show a stream of items in one slot, load the next item into the hidden
+  face, then toggle `flipped`.
+- The hidden face is `aria-hidden` and `inert`. Size the card from its parent or `className`;
+  the faces fill it (`faceClassName` styles both). Timing (`duration-*`, `ease-*`, `delay-*`)
+  goes in `turnClassName`.
+- `onFlipEnd` fires when a turn finishes — at once under reduced motion, where the faces swap
+  without turning.
+
+## Work areas: Toolbar, resizable panels, floating windows
+
+- `Toolbar` (from `/components`) takes `start` / `center` / `end` nodes; fill them with
+  `ToolbarButton`s (28px, icon-only: `label` is the accessible name AND the tooltip). Do not
+  add arrow-key handling: the toolbar already moves focus between its controls.
+- `ResizableGroup` fills its parent: give the parent a height. Children alternate
+  `ResizablePanel` / `ResizableSeparator`; every panel needs an `id`, and `defaultLayout`'s keys
+  are those ids (percentages). Persist `onLayoutChanged`, not the live drag. Sizes are
+  `PanelSize`: a number is pixels, a unitless string a percentage (`"20"`).
+- A panel that is shown and hidden by a flag is `ColumnPanel` (`open`, `openSize`), not a
+  conditional render: it stays mounted (state survives) and goes `inert` when hidden. For your
+  own collapsible `ResizablePanel`, pass `usePanelFlag(open, openSize)` as its `panelRef`.
+- `FloatingWindow` does not keep its own position: hold `position` in the app (null = default
+  spot) and store what `onMove` hands back. Minimized it renders only its pill.
+- `AnchoredPanel` is non-modal and positioned by a zero-size anchor element the app keeps at
+  the point (`anchorRef`); pass `keepOpenFor` for the control that toggles it, or that
+  control's own click closes and reopens it.
+- `MessageScroller` scrolls itself: give it a height or a flex parent; do not wrap it in
+  another `ScrollArea`. Put messages (`Bubble`s) directly inside.
+
+## Catalogue pages: ShowcaseCard, ChoiceCard, facet filters
+
+- `ShowcaseCard` opens something; `ChoiceCard` chooses something (a toggle button with
+  `aria-pressed`). For a router link pass `open={{ link: (title) => <Link to=…>{title}</Link> }}`,
+  not `href` (which reloads the page).
+- The facet filters (`FiltersPanel`, `FiltersPill`, `ActiveFilters`) count nothing and
+  translate nothing: the app passes groups with counts, the selection and every label.
+  Use `useFiltersCollapsed()` for the panel/pill state and pass
+  `animate={!supportsViewTransitions}`.
+
+## Chart legends and distribution bars
+
+- Every chart takes `legendLayout="inline" | "rows" | "columns"` (default `inline`) with
+  `showLegend`. `rows` / `columns` render below the chart: swatch, label, value aligned
+  right. `columns` (`legendColumns`, default 2) drops to one column under a 28rem-wide legend;
+  do not add media queries for it.
+- `legendValue="value" | "percent" | "both" | "none"`. Cartesian charts show each
+  series' **total across `data`**; pass `legendValue="none"` where a sum means nothing
+  (e.g. temperatures on a `LineChart`).
+- A single distribution bar is `BarChart` with `layout="vertical" stacked segmented
+  hideXAxis hideYAxis`, one data row, and a small plot height such as
+  `className="aspect-auto h-3.5"`. `className` sizes the plot only; the list legend adds
+  its own height below it.
+
 ## Bundle size and tooling (what agents should assume)
 
-- The published library is **pre-bundled ESM** (tsup). Consumers receive **large `dist` chunks**, not one file per source component.
+- The published library is **pre-built ESM with one module per source file**; production bundlers drop components an app does not import.
 - **Tree-shaking:** Bundlers can often drop **unused named exports**, but anything **statically reachable** from an imported symbol remains — including shared chunks and **eager inlined assets** (e.g. Lottie animations with `AnimatedCard`, SVG strings with `Illustration`, embedded images as data URLs).
 - A **Babel** log such as "deoptimised the styling … exceeds the max of 500KB" on a file under `node_modules/…/dist/` is usually **informational** (Babel compact output for huge files), not a build failure.
-- When suggesting "smaller bundles," recommend **subpath entry points**, **optional peers only as needed**, and **avoiding heavy components on critical routes** — not inventing non-exported deep imports.
+- When suggesting "smaller bundles," recommend **the narrowest entry point** (`/components/<folder>`, grouped paths), **optional peers only as needed**, and **avoiding heavy components on critical routes** — not inventing non-exported deep imports.
 
 ## Removed APIs — do not reintroduce
 

package/.cursor/rules/dashboard-ui-consumption.mdc

@@ -13,14 +13,19 @@ Use only paths declared under `package.json` → `exports`:
 |---------|---------|
 | `@espressif/dashboard-ui-components` | Root barrel: re-exports **components**, **common**, and **layouts**. Use only when the app intentionally pulls from multiple surfaces; otherwise prefer narrower subpaths below. |
 | `@espressif/dashboard-ui-components/components` | Public UI components and their types. |
+| `@espressif/dashboard-ui-components/components/<folder>` | One component folder (`/components/button`, `/components/dialog`, …): the same names and objects `/components` exports for it. **Prefer this.** |
+| `@espressif/dashboard-ui-components/charts` · `/data-table` · `/markdown` · `/date` · `/carousel` · `/forms` · `/animation` · `/toast` | One heavy family (recharts, tanstack, react-markdown + shiki, react-day-picker, embla, react-hook-form, lottie, sonner). |
 | `@espressif/dashboard-ui-components/layouts` | `WorkspaceLayout`, `EntryLayout`, and related layout exports. |
 | `@espressif/dashboard-ui-components/common` | Shared blocks (e.g. `AppLogo`, `ProfileCard`, `FooterCard`). |
 | `@espressif/dashboard-ui-components/utils` | Utilities such as `cn`. |
-| `@espressif/dashboard-ui-components/styles` | Global CSS (design tokens / base styles). |
+| `@espressif/dashboard-ui-components/styles` | Global CSS: Tailwind + every token + base page styles. |
+| `@espressif/dashboard-ui-components/theme.css` | Tokens only (no `@import "tailwindcss"`, no Preflight, no page styles), for apps that bring their own Tailwind. |
 | `@espressif/dashboard-ui-components/tailwind-preset` | Tailwind v4 preset. |
 
 **Do not** import from deep paths that are not in `exports` (they will fail under strict package managers or break without warning). **Do not** treat `@espressif/dashboard-ui-components/core` as a supported app API: it exists in `exports` for technical reasons, but this repo’s policy is that **consumers must not import `core`** — use composed exports from `/components` (see project overview rule).
 
+**Import from the narrowest path you can**: `/components/<folder>` for one component, a grouped path for a heavy family, a surface (`/components`, `/layouts`, …) only when importing many. Tests and dev servers evaluate everything an entry reaches. Entries that include Toast (`/toast`, `/components/toast`, `/components`, root) import sonner's CSS from JS; the others do no work at import time.
+
 ## Import style
 
 - Prefer **named imports**: `import { Button, Alert } from '…/components'`.
@@ -33,6 +38,7 @@ Use only paths declared under `package.json` → `exports`:
 Do **not** invent component or prop names from memory. The authoritative list of exports and their props is the shipped type declarations:
 
 - Components: `node_modules/@espressif/dashboard-ui-components/dist/components/index.d.ts`
+- One component folder: `…/dist/components/<folder>/index.d.ts`; grouped entries: `…/dist/<group>/index.d.ts`
 - Layouts / common / utils: the sibling `dist/<surface>/index.d.ts` files
 - The README "Available Components" table for a human-readable overview
 
@@ -57,6 +63,16 @@ export function Example() {
 }
 ```
 
+## Styling and theming
+
+- Add the library's styles once in your Tailwind v4 entry CSS: `@import "@espressif/dashboard-ui-components/styles";`. It already declares the `@source` for `dist/`.
+- Retheme by redeclaring the CSS custom properties (design tokens) **after** the `@import`, in both `:root` and `.dark` (or `[data-theme="dark"]`). Override `--font-sans` / `--font-mono` inside an `@theme` block.
+- Pick `./theme.css` instead of `./styles` only when the app has its own `@import "tailwindcss"` (or legacy CSS a reset would break); then the app styles `body` itself.
+- Dark mode applies under `.dark` **or** `[data-theme="dark"]` on an ancestor; override dark tokens under the selector the app uses. The library has no `prefers-color-scheme` handling.
+- `MinimalWorkspaceLayout` (from `/layouts`) is the header-less alternative to `WorkspaceLayout` with the same props: switch by renaming the component. It has no header bar or status footer (`footerConfig`, `hideBreadcrumbs`, `sidebarConfig.allowCollapsible` / `variant` do not exist on it), starts collapsed (`defaultSidebarOpen` defaults to `false`), and puts `topRightContent` (fallback `headerConfig.rightContent`) over the content. Theme it with the `--espd-minimal-workspace-layout-*` tokens, not `className` overrides on its parts: the sidebar surface defaults to the page background (`-sidebar-background`, `-sidebar-background-expanded`), and its border, shadow and row accent are derived from that surface unless `-sidebar-border-color`, `-sidebar-elevation` or `-sidebar-accent` are set. Keep `-sidebar-width-collapsed` within 48–56px. With `sidebarConfig.hideWhenCollapsed` the collapsed sidebar is hidden instead of a rail: a click on the content's left edge peeks it over the content until the pointer leaves it, and `MinimalWorkspaceSidebarTrigger` (from `/layouts`, placed in `topRightContent`) opens it inline; a peek never reaches `onSidebarOpenChange`. Do not build an edge or trigger in the app. The edge strip and the peek shadow are `-edge-color`, `-edge-width` and `-sidebar-overlay-elevation`.
+- Beyond colour, retheme with the semantic tokens on `:root` (and the style-axis role tokens, next section): `--espd-control-height-sm|md|lg`, `--espd-button-padding-x-sm|md|lg`, `--espd-duration-fast|normal|slow`, `--espd-ring-width`, `--espd-ring-offset`, `--espd-on-solid-foreground` (plus Tailwind's `--radius-*`, `--shadow-*`, `--spacing`). Do not add new token names in app CSS.
+- New variants (e.g. `glow`) are registered, not forked: augment `interface VariantRegistry` in `declare module '@espressif/dashboard-ui-components/components'` (in a file that imports that entry) and call `registerVariant('glow', (color) => ({ container, foreground, description }))` once at start-up. Built-in variants cannot be replaced.
+
 ## Removed APIs — do not reintroduce
 
 Earlier internal versions of this library are **not** representative of the public package. Do not add these back based on prior knowledge:
@@ -66,6 +82,49 @@ Earlier internal versions of this library are **not** representative of the publ
 
 If code references any of the above, it is targeting an old version — update it to the current API rather than re-adding the removed symbols.
 
+## Shape, elevation, border and density (style axes)
+
+Change corner radius, shadow, border width or density with the library's axes, not with
+`className` overrides on every component:
+
+- **A kind of component, app-wide:** set a **role token** in CSS after the `@import`:
+  `--espd-radius-{control|surface|overlay|pill|item}`,
+  `--espd-elevation-{control|surface|overlay}`, `--espd-border-width-{control|surface}`.
+  Unset means each component keeps its own look. Overlays render in portals, so set overlay
+  tokens on `:root`, not on a wrapper.
+- **A subtree, from React:** `<StyleScope radius={{ control: "full" }} elevation={{ surface: "none" }} density="compact">`
+  (from `/components/style-scope`). It sets the same tokens on a `display: contents` wrapper.
+- **One component:** the `radius`, `elevation` and `border` props, where the component's
+  type declares them (check its `.d.ts`; not every component takes every axis). They affect
+  that component only, never the components nested inside it. The date pickers' `radius` is
+  the trigger's; their calendar popover takes `popoverRadius` / `popoverElevation`.
+- **Density:** `density="compact" | "default" | "comfortable"` on Table, DataTable, Card, List,
+  SimpleList, FiltersBar, Sidebar, DialogContent, SheetContent, or on `StyleScope`. It also sets
+  `--espd-gap-field` (FormItem) and `--espd-gap-stack` (DialogContent); for a form, wrap it in
+  `StyleScope density` (Form renders no element).
+
+Precedence: `className` > instance prop > role token > the component's own default.
+
+Things agents get wrong:
+
+- An elevation token takes a `box-shadow` value: use `0 0 #0000` for "flat", **not** `none`
+  (it would also remove focus rings). The `elevation="none"` prop already does this.
+- Older props still work: `rounded` (Input, InputOTP, FileInput, Tag, date pickers) equals
+  `radius="full"`; `noShadow` / `noBorder` (SimpleCard). When both are passed, `radius` /
+  `elevation` / `border` win. Prefer the new props in new code.
+- Instance props need the library stylesheet (`./styles` or `./theme.css`).
+- New values are registered, not invented: augment `RadiusRegistry` / `ElevationRegistry` /
+  `BorderRegistry` / `DensityRegistry` in `declare module '@espressif/dashboard-ui-components/components'`
+  and call `registerStyleValue(axis, name, css)` or `registerDensity(name, tokens)` once at
+  start-up. Built-ins cannot be replaced.
+
+## Buttons
+
+- Use the styled `Button` from `/components` (or `/components/button`). `/core` has an uncoloured base `Button` with the same name: not for apps.
+- `fullWidth` **defaults to `true`**; pass `fullWidth={false}` for an inline button.
+- For a link that looks like a button use `asChild`, never a Button that navigates in `onClick`:
+  `<Button asChild startIcon={<Plus />}><Link to="/new">Add</Link></Button>`. With `disabled`/`loading` the link gets `aria-disabled`, `tabIndex={-1}` and its clicks are cancelled.
+
 ## Optional peer dependencies
 
 Install only when the feature is used:
@@ -77,7 +136,7 @@ Install only when the feature is used:
 | `shiki` | `Code` / syntax highlighting |
 | `recharts` | Chart components |
 
-Required peers for any usage: `react`, `react-dom`, `tailwindcss` (v4 per project docs).
+Required peers for any usage: `react`, `react-dom`, `tailwindcss` (v4.1+ per project docs).
 
 Do **not** tell users to install `react-markdown`, `remark-gfm`, or `rehype-slug` for
 `MarkdownContent` — they are regular dependencies of this package and install with it.
@@ -138,12 +197,112 @@ Things agents get wrong about it:
   if that matters.
 - `className` / `style` style the editor box, not the `<textarea>`.
 
+## Coverflow, Carousel or CardRail
+
+- `Coverflow` (from `/components`): a 3D ring of image cards with a glass reflection and a
+  caption node per item, for a showcase of a few pictures (featured projects, boards).
+  `Carousel`: plain slides of any content in a strip. `CardRail`: a scrolling row of cards
+  that shows several at once.
+- Items are `{ id, name, image?, imageAlt?, caption? }`; `name` is the accessible name.
+  Without `onOpen` the front card is a picture, not a button.
+- `renderFace` is drawn **twice** (the card and its reflection): return a picture only —
+  nothing focusable, no `id`s. It receives `{ offset, visible }`; render expensive faces only
+  while `visible`.
+- It draws no background. The reflection only reads on a dark floor: wrap it in a `.dark`
+  scope with `bg-background` (or any dark surface). Size comes from `aspect`
+  (`landscape` 4:3, `square`); do not set the stage height through `className`.
+- The reflection fade uses `mask-*` utilities, which need Tailwind **4.1+**.
+
+## CategoryCard or SimpleClickableCard
+
+- `CategoryCard` (from `/components`): a "browse by kind" card, stacked: icon tile, a count
+  (`value`) in the corner, name, one line, a few `tags`. `SimpleClickableCard`: one action in a
+  row with a chevron. Prop names match where they mean the same (`icon`, `title`,
+  `description`, `color`, `radius`, `onClick`).
+- It sizes itself by its own width (a container query): below 12rem it tightens and drops the
+  tags. Do not hide the tags per breakpoint in the app.
+- A filter row passes `selected` (gives `aria-pressed`); a navigating row passes `href` (a real
+  link) and leaves `selected` unset. Pass `aria-label` when the name to read is richer than
+  the visible text ("Show only Drivers, 65 blocks").
+- Token tints the colour presets lack (the swatches) go in `iconClassName`, which replaces
+  `color` (do not pass both).
+
+## PopoverGroup — one hover preview across many items
+
+- Wrap a grid or row of `Popover openOnHover` items in `PopoverGroup` (from `/components`) so
+  only one is open: the first opens after the popover's `openDelay`, another takes over only
+  after the pointer rests `switchDelay` (default 350 ms) on it, and reaching the open content
+  cancels a pending switch — so a diagonal path to the panel never switches it. Do not build
+  hover-intent timers in the app.
+- Give each `Popover` a `value` when the app needs to know which is open; read it from the
+  group's `value` / `onValueChange` (a member's own `onOpenChange` does not fire when another
+  takes over). A `Popover` with an explicit `open` stays outside the group.
+- Click still pins, Escape and an outside press close, and a hover-opened panel never takes
+  focus — the same as a lone `openOnHover` popover.
+
+## FlipCard
+
+- `FlipCard` (from `/components`): two faces, controlled by `flipped`; each change moves the
+  same way, never back. `effect="turn"` (default) turns it over (`axis="x"` a split-flap, `"y"`
+  a page); `effect="slide"` slides the showing face out while the next follows it in (`x` down,
+  `y` sideways). To show a stream of items in one slot, load the next item into the hidden
+  face, then toggle `flipped`.
+- The hidden face is `aria-hidden` and `inert`. Size the card from its parent or `className`;
+  the faces fill it (`faceClassName` styles both). Timing (`duration-*`, `ease-*`, `delay-*`)
+  goes in `turnClassName`.
+- `onFlipEnd` fires when a turn finishes — at once under reduced motion, where the faces swap
+  without turning.
+
+## Work areas: Toolbar, resizable panels, floating windows
+
+- `Toolbar` (from `/components`) takes `start` / `center` / `end` nodes; fill them with
+  `ToolbarButton`s (28px, icon-only: `label` is the accessible name AND the tooltip). Do not
+  add arrow-key handling: the toolbar already moves focus between its controls.
+- `ResizableGroup` fills its parent: give the parent a height. Children alternate
+  `ResizablePanel` / `ResizableSeparator`; every panel needs an `id`, and `defaultLayout`'s keys
+  are those ids (percentages). Persist `onLayoutChanged`, not the live drag. Sizes are
+  `PanelSize`: a number is pixels, a unitless string a percentage (`"20"`).
+- A panel that is shown and hidden by a flag is `ColumnPanel` (`open`, `openSize`), not a
+  conditional render: it stays mounted (state survives) and goes `inert` when hidden. For your
+  own collapsible `ResizablePanel`, pass `usePanelFlag(open, openSize)` as its `panelRef`.
+- `FloatingWindow` does not keep its own position: hold `position` in the app (null = default
+  spot) and store what `onMove` hands back. Minimized it renders only its pill.
+- `AnchoredPanel` is non-modal and positioned by a zero-size anchor element the app keeps at
+  the point (`anchorRef`); pass `keepOpenFor` for the control that toggles it, or that
+  control's own click closes and reopens it.
+- `MessageScroller` scrolls itself: give it a height or a flex parent; do not wrap it in
+  another `ScrollArea`. Put messages (`Bubble`s) directly inside.
+
+## Catalogue pages: ShowcaseCard, ChoiceCard, facet filters
+
+- `ShowcaseCard` opens something; `ChoiceCard` chooses something (a toggle button with
+  `aria-pressed`). For a router link pass `open={{ link: (title) => <Link to=…>{title}</Link> }}`,
+  not `href` (which reloads the page).
+- The facet filters (`FiltersPanel`, `FiltersPill`, `ActiveFilters`) count nothing and
+  translate nothing: the app passes groups with counts, the selection and every label.
+  Use `useFiltersCollapsed()` for the panel/pill state and pass
+  `animate={!supportsViewTransitions}`.
+
+## Chart legends and distribution bars
+
+- Every chart takes `legendLayout="inline" | "rows" | "columns"` (default `inline`) with
+  `showLegend`. `rows` / `columns` render below the chart: swatch, label, value aligned
+  right. `columns` (`legendColumns`, default 2) drops to one column under a 28rem-wide legend;
+  do not add media queries for it.
+- `legendValue="value" | "percent" | "both" | "none"`. Cartesian charts show each
+  series' **total across `data`**; pass `legendValue="none"` where a sum means nothing
+  (e.g. temperatures on a `LineChart`).
+- A single distribution bar is `BarChart` with `layout="vertical" stacked segmented
+  hideXAxis hideYAxis`, one data row, and a small plot height such as
+  `className="aspect-auto h-3.5"`. `className` sizes the plot only; the list legend adds
+  its own height below it.
+
 ## Bundle size and tooling (what agents should assume)
 
-- The published library is **pre-bundled ESM** (tsup). Consumers receive **large `dist` chunks**, not one file per source component.
+- The published library is **pre-built ESM with one module per source file**; production bundlers drop components an app does not import.
 - **Tree-shaking:** Bundlers can often drop **unused named exports**, but anything **statically reachable** from an imported symbol remains — including shared chunks and **eager inlined assets** (e.g. many Lottie animations with `AnimatedCard`, SVG strings with `Illustration`, embedded images where the build uses data URLs).
 - A **Babel** log such as “deoptimised the styling … exceeds the max of 500KB” on a file under `node_modules/…/dist/` is usually **informational** (Babel compact output for huge files), not a signal that the build is invalid.
-- When suggesting “smaller bundles,” recommend **subpath entry points**, **optional peers only as needed**, and **avoiding heavy components on critical routes** — not inventing non-exported deep imports.
+- When suggesting “smaller bundles,” recommend **the narrowest entry point** (`/components/<folder>`, grouped paths), **optional peers only as needed**, and **avoiding heavy components on critical routes** — not inventing non-exported deep imports.
 
 ## Demo vs consumer code