@edgeandnode/eds-react 1.0.2 → 1.1.1

package/dist/theme-persistence.d.ts

@@ -0,0 +1,18 @@
+import type { Theme } from './EDSContext.ts';
+export declare const PERSISTENCE_KEY = "eds-active-theme";
+export declare const COOKIE_REGEX: RegExp;
+export declare const VALID_THEMES: readonly Theme[];
+export declare function isValidTheme(value: unknown): value is Theme;
+export declare function parseThemeCookie(cookies: string | null): Theme | undefined;
+/**
+ * Returns the theme saved by `EDSProvider`'s `persistTheme="cookie"` from the request's headers, or
+ * `undefined` if there's none. Pass the result to `defaultTheme`, so the server renders the saved
+ * theme too.
+ *
+ * @example
+ *   ````tsx
+ *   <EDSProvider persistTheme="cookie" defaultTheme={getThemeFromCookies(await headers())}>
+ *   ````
+ */
+export declare function getThemeFromCookies(headers: Pick<Headers, 'get'>): Theme | undefined;
+//# sourceMappingURL=theme-persistence.d.ts.map

package/dist/theme-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-persistence.d.ts","sourceRoot":"","sources":["../src/theme-persistence.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE5C,eAAO,MAAM,eAAe,qBAAqB,CAAA;AACjD,eAAO,MAAM,YAAY,QAAsD,CAAA;AAE/E,eAAO,MAAM,YAAY,EAAE,SAAS,KAAK,EAAgC,CAAA;AAEzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAE3D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,qBAGtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,qBAEhE"}

package/dist/theme-persistence.js

@@ -0,0 +1,25 @@
+// Not a client module, so server components can call `getThemeFromCookies`
+export const PERSISTENCE_KEY = 'eds-active-theme';
+export const COOKIE_REGEX = new RegExp(`(?:^|;\\s*)${PERSISTENCE_KEY}=([^;]+)`);
+export const VALID_THEMES = ['dark', 'light', 'system'];
+export function isValidTheme(value) {
+    return typeof value === 'string' && VALID_THEMES.includes(value);
+}
+export function parseThemeCookie(cookies) {
+    const value = cookies?.match(COOKIE_REGEX)?.[1];
+    return isValidTheme(value) ? value : undefined;
+}
+/**
+ * Returns the theme saved by `EDSProvider`'s `persistTheme="cookie"` from the request's headers, or
+ * `undefined` if there's none. Pass the result to `defaultTheme`, so the server renders the saved
+ * theme too.
+ *
+ * @example
+ *   ````tsx
+ *   <EDSProvider persistTheme="cookie" defaultTheme={getThemeFromCookies(await headers())}>
+ *   ````
+ */
+export function getThemeFromCookies(headers) {
+    return parseThemeCookie(headers.get('cookie'));
+}
+//# sourceMappingURL=theme-persistence.js.map

package/dist/theme-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-persistence.js","sourceRoot":"","sources":["../src/theme-persistence.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAI3E,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAA;AACjD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,cAAc,eAAe,UAAU,CAAC,CAAA;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;AAEzE,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACzF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC/C,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,OAAO,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgeandnode/eds-react",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "React components for the Edge Design System",
   "author": "Edge & Node and contributors",
   "license": "MIT",
@@ -47,48 +47,48 @@
     "tailwindcss": "^4.3.2"
   },
   "dependencies": {
-    "@base-ui/react": "^1.8.0",
-    "@base-ui/utils": "^0.4.0",
-    "@edgeandnode/eds-css": "1.0.2",
+    "@base-ui/react": "~1.9.0",
+    "@base-ui/utils": "^0.5.0",
+    "@edgeandnode/eds-css": "1.1.0",
     "@edgeandnode/eds-icons": "1.0.2",
     "@edgeandnode/eds-utils": "1.0.2",
     "@react-aria/utils": "^3.34.1",
     "@react-hookz/web": "^26.1.0",
     "@ver0/deep-equal": "^2.0.1",
     "escape-string-regexp": "^5.0.0",
-    "motion": "^13.4.5",
-    "react-aria": "^3.52.1",
-    "react-keyed-flatten-children": "^5.1.3",
+    "motion": "^14.3.0",
+    "react-aria": "^3.53.1",
+    "react-keyed-flatten-children": "^5.1.4",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
-    "shiki": "^4.4.3",
+    "shiki": "^4.5.0",
     "style-observer": "^0.1.2",
     "ts-extras": "^1.3.0",
     "type-fest": "^5.10.0"
   },
   "devDependencies": {
-    "@storybook/addon-mcp": "^10.6.0",
-    "@storybook/addon-themes": "^10.6.0",
-    "@storybook/addon-vitest": "^10.6.0",
-    "@storybook/react": "^10.6.0",
-    "@storybook/react-vite": "^10.6.0",
+    "@storybook/addon-mcp": "^10.6.2",
+    "@storybook/addon-themes": "^10.6.2",
+    "@storybook/addon-vitest": "^10.6.2",
+    "@storybook/react": "^10.6.2",
+    "@storybook/react-vite": "^10.6.2",
     "@svgr/core": "^8.1.0",
     "@svgr/plugin-jsx": "^8.1.0",
     "@svgr/plugin-svgo": "^8.1.0",
     "@tailwindcss/cli": "^4.3.3",
     "@tailwindcss/postcss": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@types/react-is": "^19.3.0",
-    "@web3icons/react": "^4.1.22",
+    "@web3icons/react": "^4.1.24",
     "lightningcss": "^1.33.0",
-    "postcss": "^8.5.28",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "react-is": "^19.3.0",
-    "storybook": "^10.6.0",
+    "postcss": "^8.5.30",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "react-is": "^19.3.1",
+    "storybook": "^10.6.2",
     "storybook-addon-rtl": "^3.0.2",
     "tailwindcss": "^4.3.3"
   },

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eds
-version: 1.0.2
+version: 1.1.1
 description: The Edge Design System (EDS) is for building user interfaces for Edge & Node products. Use this skill when designing, implementing, reviewing, or polishing Edge & Node product UIs, when using `@edgeandnode/eds-react`, or when EDS is mentioned. Covers component selection, design patterns, tokens, and best practices – not just APIs. APIs are fully typed in the npm package.
 allowed-tools:
   - mcp__storybook__get-changed-stories
@@ -28,7 +28,7 @@ EDS is the design system for Edge & Node products. This skill teaches you how to
   "mcpServers": {
     "storybook": {
       "type": "http",
-      "url": "https://e4b81a8--6ab2abb8934bb76c7e8e086c.chromatic.com/mcp"
+      "url": "https://e3c7a4b--6ab2abb8934bb76c7e8e086c.chromatic.com/mcp"
     }
   }
 }
@@ -43,7 +43,7 @@ Add this to the project's `.mcp.json` file (create it if it doesn't exist). For
 ```json
 {
   "dependencies": {
-    "@edgeandnode/eds-react": "^1.0.2",
+    "@edgeandnode/eds-react": "^1.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -82,21 +82,32 @@ function App() {
 }
 ```
 
-**Only one `EDSProvider` per app** — rendering more than one will throw an error. To render part of the UI in a different theme, wrap it in `<Dark>` or `<Light>` instead (e.g. `<Dark as="section">`).
+**Only one `EDSProvider` per app** — rendering more than one will throw an error. To render part of the UI in a different theme, wrap it in `<Dark>` or `<Light>` instead (e.g. `<Dark as="section">`), or in `<LocalTheme theme={…}>` if the theme changes.
 
 ### Theming
 
 `EDSProvider`'s theme handling supports **controlled** mode (pass `theme`, optionally with `onThemeChange`) and **uncontrolled** mode (omit `theme`; optionally pass `defaultTheme`, which defaults to `'dark'`). To make the user's theme selection survive reloads, opt into persistence with `persistTheme="localStorage"`, `persistTheme="cookie"`, or a custom `{ get, set }` adapter — omit for no persistence.
 
+With `persistTheme="cookie"` in a server-rendered app, also pass the saved theme to `defaultTheme`, so the server renders it instead of switching to it after hydration (e.g. `ThemeSwitcher`'s selected option), except for a saved `'system'` theme, which the server can't resolve. `getThemeFromCookies()` reads it from the request's headers, and returns `undefined` if there's none (add `?? 'system'` for a default other than `'dark'`). In Next.js, do it in the root layout (which makes routes render on each request), and if `EDSProvider` is in a client component, pass the saved theme to it through a prop (the `Theme` type is exported):
+
+```tsx
+import { headers } from 'next/headers'
+import { EDSProvider, getThemeFromCookies } from '@edgeandnode/eds-react'
+
+<EDSProvider persistTheme="cookie" defaultTheme={getThemeFromCookies(await headers())}>
+```
+
+If the app's Content Security Policy requires nonces on inline scripts and styles, pass the nonce to `EDSProvider`'s `nonce` prop.
+
 To read or change the theme from anywhere in the app, use the `useEDS()` hook:
 
 ```tsx
 import { useEDS } from '@edgeandnode/eds-react/hooks'
 
-const { theme, activeTheme, setTheme } = useEDS()
+const { theme, setTheme, activeTheme } = useEDS()
 ```
 
-`theme` is `'dark' | 'light' | 'system'`. `activeTheme` resolves `'system'` to `'dark'` or `'light'` based on the user's OS preference. `setTheme(theme)` changes it (use `<ThemeSwitcher>` for the UI). `localTheme` is the theme of the nearest `<Dark>` or `<Light>` ancestor, or `undefined` if there's none (including inside a `Modal`, which always uses the page's theme) — use `localTheme ?? activeTheme` when rendering something that depends on the theme in JavaScript. `localThemeClass` is that ancestor's class (or `undefined` if there's none) — add it to content you render outside of that ancestor in the DOM (e.g. with `createPortal`) so it keeps its theme.
+`theme` is the page's theme, `'dark' | 'light' | 'system'`, and `setTheme(theme)` changes it (use `<ThemeSwitcher>` for the UI). `activeTheme` is the theme content is rendered in, `'dark'` or `'light'` — use it when rendering something that depends on the theme in JavaScript. It's `localTheme` if there is one, or else the page's theme with `'system'` resolved to `systemTheme` (the OS preference). `localTheme` is the theme of the nearest `<Dark>`, `<Light>`, or `<LocalTheme>` ancestor, or `undefined` if there's none (including inside a `Modal`, which always uses the page's theme). `localThemeClass` is that ancestor's class (or `undefined` if there's none) — add it to content you render outside of that ancestor in the DOM (e.g. with `createPortal`) so it keeps its theme.
 
 ### Router Integration (Next.js)
 
@@ -161,6 +172,23 @@ import { EDSProvider } from '@edgeandnode/eds-react'
 >
 ```
 
+### Plain CSS (Without EDS's Tailwind Setup)
+
+If the project can't use `@edgeandnode/eds-react` and EDS's Tailwind setup (e.g. it doesn't use Tailwind, or it's built with a framework that ships its own Tailwind build), it can still use EDS's design tokens and fonts as plain CSS custom properties from `@edgeandnode/eds-css`. **This setup has no components and no utilities**, so every UI element has to be built and styled by hand. Only use it when the regular setup isn't possible, and tell the user about this trade-off when suggesting it.
+
+Import the tokens and fonts, and set the page's color scheme:
+
+```css
+@import '@edgeandnode/eds-css/fonts.css';
+@import '@edgeandnode/eds-css/variables.css';
+
+:root {
+  color-scheme: dark;
+}
+```
+
+The tokens in [tokens.md](references/tokens.md) map to variables named after their utilities' namespaces, with an `eds-` prefix: `text-default` is `var(--eds-text-color-default)`, `bg-muted` is `var(--eds-background-color-muted)`, `border-subtle` is `var(--eds-border-color-subtle)`, `text-14` is `var(--eds-text-14)` (and `var(--eds-text-14--line-height)`), `font-medium` is `var(--eds-font-weight-medium)`, `rounded-8` is `var(--eds-radius-8)`, and `p-4` is `calc(var(--eds-spacing) * 4)`. Color tokens use `light-dark()`, so set `color-scheme` (`dark`, `light`, or `light dark`) on the page and on any part of it that should use the other theme. The constraints below about components and utilities don't apply, but the design guidance does.
+
 ## Constraints
 
 1. **Check component APIs before using them.** If the Storybook MCP is available, call `get-documentation` first — it shows prop types, valid values, and real usage examples. Otherwise, check the TypeScript types and JSDoc comments in `@edgeandnode/eds-react`. Never guess prop names or values. Fix all TypeScript errors. Do not use `as any` or `@ts-ignore`.
@@ -404,7 +432,7 @@ Login buttons are typically `secondary`, not `primary`. Sign-up or critical CTAs
 - **`text-caption` is for small annotations, not section headings.** Use it for labels like "STATUS", "CATEGORY", "OVERVIEW" in small text. For section headings, use regular `text-20 font-medium` or `text-18 font-medium`.
 - **`text-10` is very small.** Use it sparingly, mostly paired with `text-caption`. For labels and small text, prefer `text-12`.
 - **`font-sans` (Inter) is the default and inherits.** Never set it explicitly.
-- **`font-serif` (Newsreader) is opt-in.** Use it for editorial and marketing headings. Don't use it in product UI unless the user asks for it.
+- **`font-serif` (Newsreader) is opt-in.** Use it for editorial and marketing headings. Don't use it in product UI unless the user asks for it. For serif headings in `prose` content, add the `prose-serif` class (or the `serif` prop on `<Prose>`) instead of setting it on each heading.
 - **`font-mono` is the system monospace font on purpose.** Don't replace it with a web font. `CodeBlock` and `CodeInline` already apply it.
 
 ### Anti-Patterns
@@ -511,47 +539,47 @@ EDS components handle basic accessibility. Your job:
 
 Memorize this list before any UI work to avoid reimplementing existing components.
 
-| Component                      | Description                                                        |
-| ------------------------------ | ------------------------------------------------------------------ |
-| `Address`                      | Crypto addresses. Auto-truncates. Supports copy, friendly name.    |
-| `Avatar` / `AvatarGroup`       | User/wallet avatars from hashes. Can be clickable.                 |
-| `Breadcrumbs`                  | Navigation hierarchy. Auto-collapses. Underused.                   |
-| `Button` / `ButtonGroup`       | Actions/navigation. `<button>` or `<a>` based on `href`.           |
-| `Card`                         | Content grouping. Can be clickable with interactive content.       |
-| `Checkbox` / `Checkbox.Group`  | Multi-select. `Checkbox.Area` for card-style.                      |
-| `Chip` / `Chip.Group`          | Filters, tags. `type="checkbox"` for multi-select.                 |
-| `Cluster`                      | "+X more" patterns. Works with `AvatarGroup`, `Tag`. Underused.    |
-| `CodeBlock` / `CodeBlock.Tabs` | Code snippets with syntax highlighting. Underused.                 |
-| `CodeInline`                   | Inline code for variables, function names, etc.                    |
-| `CopyButton`                   | Copy to clipboard. Extends `Button`.                               |
-| `CurrencyInput`                | Crypto amounts. Use with `useCurrencyInput` hook.                  |
-| `Dark` / `Light`               | Renders part of the page in the dark or light theme.               |
-| `DescriptionList`              | Key-value pairs, metadata. Underused.                              |
-| `Divider`                      | Visual separation. Horizontal or vertical.                         |
-| `Icon`                         | Wraps icons. `src` and `alt` required.                             |
-| `Input`                        | Text/number input. Use `useNumberInput` for numbers.               |
-| `Keyboard`                     | Keyboard shortcut display. Use instead of `<kbd>`. Underused.      |
-| `Label`                        | Form labels only, not general styling.                             |
-| `Link`                         | Navigation. Inherits font size/weight. `href` required.            |
-| `Menu`                         | Dropdowns, selects, context menus. `trigger` for uncontrolled.     |
-| `Modal`                        | Dialogs. `trigger` for uncontrolled.                               |
-| `OTCInput`                     | One-time codes (2FA, OTP). Extends `Input`.                        |
-| `Pane`                         | Responsive sidebars. Overlay on mobile via CSS props.              |
-| `Prose`                        | Renders markdown as styled HTML with EDS components.               |
-| `Radio` / `Radio.Group`        | Single-select. `Radio.Area` for card-style.                        |
-| `Search`                       | Search input. `focusKey` defaults to `'/'`.                        |
-| `SegmentedControl`             | View options. Requires `aria-label`.                               |
-| `Select`                       | Single or `multiple`, `searchable`, declarative or data-driven.    |
-| `Status`                       | Status indicators. Colored dot + optional text.                    |
-| `Stepper`                      | Multi-step flow indicators.                                        |
-| `Switch` / `Switch.Area`       | Toggle on/off. `Switch.Area` for card-style.                       |
-| `Table`                        | Data tables. Declarative or data-driven.                           |
-| `TabSet`                       | View switching. `fullWidth` for constrained space. Underused.      |
-| `Tag`                          | Tags/categories. Not clickable; use `Chip` if clickable.           |
-| `TextArea`                     | Multi-line input.                                                  |
-| `ThemeSwitcher`                | Light/dark theme toggle. Right-click to toggle system sync.        |
-| `ToggleButton`                 | Toggle actions. Extends `Button` with `checked`/`onCheckedChange`. |
-| `Tooltip`                      | Hover hints. Only wrap interactive elements.                       |
+| Component                       | Description                                                        |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `Address`                       | Crypto addresses. Auto-truncates. Supports copy, friendly name.    |
+| `Avatar` / `AvatarGroup`        | User/wallet avatars from hashes. Can be clickable.                 |
+| `Breadcrumbs`                   | Navigation hierarchy. Auto-collapses. Underused.                   |
+| `Button` / `ButtonGroup`        | Actions/navigation. `<button>` or `<a>` based on `href`.           |
+| `Card`                          | Content grouping. Can be clickable with interactive content.       |
+| `Checkbox` / `Checkbox.Group`   | Multi-select. `Checkbox.Area` for card-style.                      |
+| `Chip` / `Chip.Group`           | Filters, tags. `type="checkbox"` for multi-select.                 |
+| `Cluster`                       | "+X more" patterns. Works with `AvatarGroup`, `Tag`. Underused.    |
+| `CodeBlock` / `CodeBlock.Tabs`  | Code snippets with syntax highlighting. Underused.                 |
+| `CodeInline`                    | Inline code for variables, function names, etc.                    |
+| `CopyButton`                    | Copy to clipboard. Extends `Button`.                               |
+| `CurrencyInput`                 | Crypto amounts. Use with `useCurrencyInput` hook.                  |
+| `Dark` / `Light` / `LocalTheme` | Renders part of the page in the dark or light theme.               |
+| `DescriptionList`               | Key-value pairs, metadata. Underused.                              |
+| `Divider`                       | Visual separation. Horizontal or vertical.                         |
+| `Icon`                          | Wraps icons. `src` and `alt` required.                             |
+| `Input`                         | Text/number input. Use `useNumberInput` for numbers.               |
+| `Keyboard`                      | Keyboard shortcut display. Use instead of `<kbd>`. Underused.      |
+| `Label`                         | Form labels only, not general styling.                             |
+| `Link`                          | Navigation. Inherits font size/weight. `href` required.            |
+| `Menu`                          | Dropdowns, selects, context menus. `trigger` for uncontrolled.     |
+| `Modal`                         | Dialogs. `trigger` for uncontrolled.                               |
+| `OTCInput`                      | One-time codes (2FA, OTP). Extends `Input`.                        |
+| `Pane`                          | Responsive sidebars. Overlay on mobile via CSS props.              |
+| `Prose`                         | Renders markdown as styled HTML with EDS components.               |
+| `Radio` / `Radio.Group`         | Single-select. `Radio.Area` for card-style.                        |
+| `Search`                        | Search input. `focusKey` defaults to `'/'`.                        |
+| `SegmentedControl`              | View options. Requires `aria-label`.                               |
+| `Select`                        | Single or `multiple`, `searchable`, declarative or data-driven.    |
+| `Status`                        | Status indicators. Colored dot + optional text.                    |
+| `Stepper`                       | Multi-step flow indicators.                                        |
+| `Switch` / `Switch.Area`        | Toggle on/off. `Switch.Area` for card-style.                       |
+| `Table`                         | Data tables. Declarative or data-driven.                           |
+| `TabSet`                        | View switching. `fullWidth` for constrained space. Underused.      |
+| `Tag`                           | Tags/categories. Not clickable; use `Chip` if clickable.           |
+| `TextArea`                      | Multi-line input.                                                  |
+| `ThemeSwitcher`                 | Light/dark theme toggle. Right-click to toggle system sync.        |
+| `ToggleButton`                  | Toggle actions. Extends `Button` with `checked`/`onCheckedChange`. |
+| `Tooltip`                       | Hover hints. Only wrap interactive elements.                       |
 
 ### Icons
 
@@ -629,7 +657,7 @@ import type { DistributedOmit } from 'type-fest'
 import { Card, type CardProps } from '@edgeandnode/eds-react'
 import { cn } from '@edgeandnode/eds-react/utils'
 
-interface EntityCardProps extends DistributedOmit<CardProps, 'variant'> {
+type EntityCardProps = DistributedOmit<CardProps, 'variant'> & {
   name: string
   imageUrl: string
 }
@@ -644,7 +672,7 @@ function EntityCard({ name, imageUrl, className, ...props }: EntityCardProps) {
 }
 ```
 
-Use `DistributedOmit` from `type-fest` (not `Omit`) to preserve discriminated unions in prop types. Spread `{...props}` to forward all remaining props including `ref`.
+Many EDS prop types (e.g. `CardProps`, `PaneProps`, `DarkProps`) are unions, which interfaces can't extend, so combine them with `&` in a type alias, and use `DistributedOmit` from `type-fest` (not `Omit`) to preserve the union. Spread `{...props}` to forward all remaining props including `ref`.
 
 ### Controlling components
 
@@ -672,18 +700,18 @@ Some components expand to fill available width by default: `Card`, `CodeBlock`,
 - **DescriptionList:** Long values truncate with gradient fade, scroll on mobile.
 - **Input:** For number inputs, use the `useNumberInput` hook (or `useCurrencyInput` for currency amounts) — it handles parsing, formatting, and min/max/required validation, and returns `props` to spread on `<Input>` (or `<CurrencyInput>`).
 - **Link:** Inherits font properties (except color when `variant="primary"`). External links auto-get `ArrowUpRightInteractiveIcon` via `addonAfter`; prevent with `addonAfter={null}`. Default variant is `primary` (emphasized) — use `variant="secondary"` for de-emphasized links like footers, fine print, etc.
-- **Menu:** Prefer the uncontrolled `trigger` prop (element form when possible, function form for advanced customization) over the controlled `open` + `onOpenChange`. Set `triggerMode="right-click"` and `anchor="pointer"` to turn any `Menu` into a context menu anchored at the right-click location (or long-press on mobile). Use `<Menu.Search>` in `header` for a search input that integrates with the menu's keyboard nav, and `<Menu.Empty>` for the empty state (defaults to `"No results"`).
-- **Modal:** Prefer the uncontrolled `trigger` prop (element form when possible, function form for advanced customization) over the controlled `open` + `onOpenChange`. Body text inside a `Modal` is muted by default; add `text-default` explicitly on headings or emphasized text (or use the `prose` class / `<Prose>`, which handle it automatically).
+- **Menu:** Prefer the uncontrolled `trigger` prop (element form when possible, function form for advanced customization) over the controlled `open` + `onOpenChange`. Set `triggerMode="right-click"` and `anchor="pointer"` to turn any `Menu` into a context menu anchored at the right-click location (or long-press on mobile). Set `searchable` to add a search input that filters items by their rendered text, addons included (e.g. a `Tag`); set `label` on a `Menu.Item` to match against something else instead (e.g. `label={address}` on an item showing `formatAddress(address)`). Pass a function to `searchable` for custom matching, or `"manual"` to filter items yourself (e.g. results from an API) with `searchValue` and `onSearchValueChange`, and set `loading` while fetching them. `empty` replaces the default `"No results"` state. A custom `header` must include `<Menu.Search>`, which handles the keyboard navigation.
+- **Modal:** Prefer the uncontrolled `trigger` prop (element form when possible, function form for advanced customization) over the controlled `open` + `onOpenChange`. Body text inside a `Modal` is muted by default; add `text-default` explicitly on headings or emphasized text (or use the `prose` class / `<Prose>`, which handle it automatically). A `Modal.Header` title names the dialog; without one, pass `aria-label` (`aria-label`, `aria-labelledby`, and `aria-describedby` go on the dialog itself).
 - **Multi-step Modals:** Always render the exact same set of `<Modal.Header>` / `<Modal.Body>` / `<Modal.Footer>` in every step — leave one empty if a step doesn't need it, don't omit it. If every step is inlined in the same file, you can render them directly (see the `WithSteps` story). If you extract any step into its own component, wrap the conditional in an outer `<Modal.Step>` (provider) AND have each extracted step component wrap its Header/Body/Footer in an inner `<Modal.Step>` (consumer). Together they preserve stable element identity for the slots so React doesn't remount them across steps, which is what lets the transition animate. See the "Multi-step Modals" section in [patterns.md](references/patterns.md) for a complete example.
 - **Pane:** Use `prop-layout-overlay` at the appropriate breakpoint (e.g. `max-lg:`) for mobile overlay.
-- **Prose:** Apply the `prose` class to any container of text that may wrap or contain formatting, even a single paragraph. It styles headings, lists (`<ul>`, `<ol>`), and inline formatting (`<strong>`, `<em>`, etc.), and applies `text-muted` to body text with `text-default` on headings and emphasized (bolded) elements. The `<Prose>` component is a superset: it renders a container with the `prose` class AND converts markdown links, inline code, code blocks, and tables into proper EDS components (`Link`, `CodeInline`, `CodeBlock`, `Table`). Use it specifically for rendering markdown content; for hand-written JSX, use the `prose` class and reach for EDS components directly.
+- **Prose:** Apply the `prose` class to any container of text that may wrap or contain formatting, even a single paragraph. It styles headings, lists (`<ul>`, `<ol>`), and inline formatting (`<strong>`, `<em>`, etc.), and applies `text-muted` to body text with `text-default` on headings and emphasized (bolded) elements. Regular links, inline code, and code blocks look like `Link`, `CodeInline`, and `CodeBlock` (without syntax highlighting), but prefer the components in JSX. The `<Prose>` component is a superset: it renders a container with the `prose` class AND converts markdown links, inline code, code blocks, and tables into proper EDS components (`Link`, `CodeInline`, `CodeBlock`, `Table`). Use it specifically for rendering markdown content; for hand-written JSX, use the `prose` class and reach for EDS components directly.
 - **Search:** `focusKey` defaults to `'/'`; set to `null` if multiple on same page.
 - **SegmentedControl:** Requires `aria-label`. Options can be icon-only.
 - **Select:** Renders its own trigger by default. Only use the `trigger` prop for a custom trigger — prefer its element form over its function form.
 - **Table:** Use `align="end"` on `Table.HeaderCell` for right-aligned columns (e.g. action buttons) — all cells in that column are automatically styled. Don't use `text-end` or `justify-end` on cell contents. Similarly, use `width` and `shrink` props on `Table.HeaderCell` to control column sizing.
 - **TabSet:** `TabSet.Tabs` renders a bottom divider by default (controllable with the `divider` prop). Add `gap-*` between `TabSet.Tabs` and `TabSet.Panels` for visual breathing room. Put borders on `TabSet.Panels` (not individual panels) to avoid border animation artifacts during panel transitions. Check `TabSet.stories.tsx` for good examples.
 - **Tag:** Not clickable; use `Chip` if you need a clickable tag.
-- **Tooltip:** Hard to discover on mobile. Use inline text for essential info.
+- **Tooltip:** Hard to discover on mobile. Use inline text for essential info. It gives its trigger an `onClick`, which turns an `Avatar`, `Address`, `Cluster`, or `Breadcrumbs.Item` into a button, so pass them `as="span"` inside a link or another button (e.g. `<Cluster as="span">` in a clickable `Card`).
 
 ### Unstyled components
 
@@ -692,16 +720,22 @@ Some components carry no built-in visual styles — only behavior, semantics, or
 - **`Checkbox.Area` / `Radio.Area` / `Switch.Area`** — clickable label wrappers for card-style checkable patterns; style them as `Card`s, rows, tiles, whatever the design calls for. See the "Checkable Cards" section in [patterns.md](references/patterns.md).
 - **`Radio.Group`** — semantic wrapper around a group of `<Radio>`s. Apply your own layout (`flex`, `gap`, etc.).
 - **`Pane`** — responsive sidebar container. Provides positioning behavior but no visual styling.
-- **`Dark` / `Light`** — render their element (`as`, `div` by default) in the dark or light theme. They only set the color scheme and default text color, so style them as the section needs (e.g. `bg-default p-8`). `dark:`/`light:` variants on the element itself still follow the outer theme (style queries only look at ancestors), so use them on its descendants.
+- **`Dark` / `Light` / `LocalTheme`** — render their element (a `div` by default, see below) in the dark or light theme. `LocalTheme` takes it as a `theme` prop, so changing it doesn't remount the content like switching between `Dark` and `Light` would. They only set the color scheme and default text color, so style them as the section needs (e.g. `bg-default p-8`). `dark:`/`light:` variants on the element itself still follow the outer theme (style queries only look at ancestors), so use them on its descendants.
 - **`ButtonOrLink`** (from `@edgeandnode/eds-react/base`) — semantic `<button>`/`<a>` wrapper with no visual styling. The other base components (`Transition`, `ExperimentalTransition`, `Presence`, `Render`, `Portal`) have transition or structural styles you shouldn't override.
 
+### Changing the rendered element
+
+`Dark`, `Light`, `LocalTheme`, and `Pane` render a `div` by default, and their props are typed for any HTML element (e.g. `ref` takes an `HTMLElement`). Pass a tag name in `as` (e.g. `<Pane as="aside">`), or an element in `render` to render a component or pass props specific to the element (e.g. `<Dark render={<NextLink href="/" />}>`). `as` and `render` can't be combined.
+
+`Card`, `Avatar`, `Address`, `Cluster`, and `Breadcrumbs.Item` render a button or link when given an `onClick` or `href`. Otherwise, their `as` also only takes a tag name, and it keeps them from becoming a button when something else gives them an `onClick` (see `Tooltip` above). When `Card` isn't a button or link, its props are typed for any HTML element too.
+
 ### Base components
 
 Available from `@edgeandnode/eds-react/base`. These are mostly unstyled lower-level building blocks — most consumers won't use them directly, but they're useful for advanced patterns:
 
 - `ButtonOrLink` — the foundation of `Button`, `Link`, `Address`, `Avatar`, `Card`, etc. Renders `<button>` or `<a>` based on `href`. Supports `linkComponent` for router integration.
 - `Transition` / `ExperimentalTransition` — Enter/exit animations with height transition. Used internally by `Modal`, `TabSet`, etc.
-- `Render` — polymorphic rendering via the `render` prop (e.g. `render={<Card as="label" />}`).
+- `Render` — renders a `div`, the tag name passed in `as`, or the element or render function passed in `render` (e.g. `render={<Card as="label" />}`). The `AsOrRenderProps` and `HTMLElementProps` types add the same `as` and `render` props to your own components.
 - `Portal` — renders children in a portal (used by `Modal`, `Tooltip`, `Menu`).
 - `Presence` — conditionally renders children with enter/exit transitions (used by `ExperimentalTransition`, `Pane`).
 
@@ -728,7 +762,7 @@ import { formatBigInt, parseBigInt, numberToBigInt, bigIntToNumber } from '@edge
 ```
 
 - `cn` — concatenate class names, filtering out falsy values (like `clsx`)
-- `useEDS` — read and change the current theme (`{ theme, setTheme, activeTheme, localTheme, localThemeClass, dirProps }`); see "Theming"
+- `useEDS` — read and change the current theme (`{ theme, setTheme, systemTheme, localTheme, activeTheme, localThemeClass, dirProps }`); see "Theming"
 - `useControlled` — manage controlled/uncontrolled state
 - `useNumberInput` — numeric input validation and formatting (use with `Input`)
 - `useCurrencyInput` — currency input validation (use with `CurrencyInput`)

package/skill/references/tokens.md

@@ -168,7 +168,7 @@ When in doubt, add more space. Dense UIs look cheap.
 
 ## Theme Sections
 
-The `EDSProvider` `theme` prop sets the root theme. To render part of the UI in another theme, wrap it in `<Dark>` or `<Light>` (e.g. `<Dark as="section">`). They can be nested, and components inside them can read the section's theme with `useEDS().localTheme`. Menus, selects, and tooltips use the theme of the section they're in, while modals use the page's theme.
+The `EDSProvider` `theme` prop sets the root theme. To render part of the UI in another theme, wrap it in `<Dark>` or `<Light>` (e.g. `<Dark as="section">`), or in `<LocalTheme theme={…}>` if the theme changes (switching between `Dark` and `Light` would remount their content). They can be nested, and components inside them can read the section's theme with `useEDS().activeTheme`. Menus, selects, and tooltips use the theme of the section they're in, while modals use the page's theme.
 
 ## Breakpoints
 

package/src/EDSContext.ts

@@ -22,13 +22,13 @@ export type ThemePersistence =
 
 export interface EDSContextValue {
   theme: Theme
-  activeTheme: ResolvedTheme
   setTheme: (theme: Theme) => void
+  systemTheme: ResolvedTheme
   direction: NonNullable<ComponentProps<typeof DirectionProvider>['direction']>
   language: string
 }
 
 export const EDSContext = createContext<EDSContextValue | null>(null)
 
-/** The theme of the nearest `Dark` or `Light` ancestor, if any. */
+/** The theme of the nearest `Dark`, `Light`, or `LocalTheme` ancestor, if any. */
 export const LocalThemeContext = createContext<ResolvedTheme | undefined>(undefined)