@edgeandnode/eds-react 1.0.1 → 1.1.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eds
-version: 1.0.1
+version: 1.1.0
 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://f87aca8--6ab2abb8934bb76c7e8e086c.chromatic.com/mcp"
+      "url": "https://3ebe140--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.1",
+    "@edgeandnode/eds-react": "^1.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -67,6 +67,8 @@ Add this to the project's `.mcp.json` file (create it if it doesn't exist). For
 
 **Important:** `@edgeandnode/eds-css`, which `@edgeandnode/eds-react` depends on, disables Tailwind's default content scanning as an optimization, so you must explicitly [register your source paths with `@source` directives](https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources). Make sure to include all paths where Tailwind classes are used.
 
+**Browser targets:** EDS's color tokens rely on native `light-dark()`, so the app must target Chrome 123, Safari 17.5, and Firefox 120 or newer. Otherwise, build tools transpile it (e.g. Lightning CSS, which Vite and Next.js use) and components inside `<Dark>`/`<Light>` get the page's colors (`EDSProvider` warns in the console; with Vite, only in production builds). In Next.js, add `"browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5", "ios_saf >= 17.5"]` to `package.json`; in Vite, set `build.target: ['chrome123', 'edge123', 'firefox120', 'safari17.5', 'ios17.5']` (it also covers CSS, and unlike `build.cssTarget`, a Vite-based Storybook picks it up).
+
 ### App Root
 
 ```tsx
@@ -80,21 +82,32 @@ function App() {
 }
 ```
 
-**Only one `EDSProvider` per app** — rendering more than one will throw an error. To apply different themes to parts of the UI, use the `eds-dark` / `eds-light` / `eds-system` classes instead (see "Theme Classes" in [tokens.md](references/tokens.md)).
+**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'
+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).
+`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)
 
@@ -159,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`.
@@ -212,7 +242,7 @@ import { EDSProvider } from '@edgeandnode/eds-react'
 </Button>
 ```
 
-15. **Pass icons as components, not elements, in addon props.** Use `addonBefore={PlayIcon}` not `addonBefore={<PlayIcon alt="" />}`. The element form (`<PlayIcon alt="..." />`) is only needed when passing a non-empty `alt` or a `variant`, or when the component consuming the addon is a React Server Component (RSCs can't receive functions as props — use `addonBefore={<PlayIcon alt="" />}`). Addons have a default size tied to the parent component — don't set `size` on them.
+15. **Pass icons as components, not elements, in addon props.** Use `addonBefore={PlayIcon}` not `addonBefore={<PlayIcon alt="" />}`. The element form (`<PlayIcon alt="..." />`) is only needed when passing a non-empty `alt` or a `variant`, or when passing it from a server component (server components can't pass functions to client components — use `addonBefore={<PlayIcon alt="" />}`). Addons have a default size tied to the parent component — don't set `size` on them.
 
 16. **EDS icons don't shrink.** Icons from `@edgeandnode/eds-react/icons` have `shrink-0` built in. Don't add it manually — it's redundant. However, if you wrap an icon in another element (e.g. a `div`), that wrapper may still need `shrink-0` if it's a child of a `flex` container.
 
@@ -402,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
@@ -509,46 +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.                  |
-| `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
 
@@ -626,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
 }
@@ -641,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
 
@@ -664,16 +695,16 @@ Some components expand to fill available width by default: `Card`, `CodeBlock`,
 
 - **Address:** Handles truncation, ENS/friendly names (via `children`), copy (`'auto'` by default — shows on hover/focus). **Note:** `Address` renders its own `Avatar` using `createIdenticon(address)` — don't add a separate `Avatar` next to it or you'll get duplicate avatars.
 - **Button & ButtonGroup:** Set `size` on the group, not nested buttons. Can mix `tertiary` and `secondary`. `orientation="vertical"` for modals/panes. `fullWidth` makes buttons equal width; `className="w-full"` makes them grow proportionally. Danger takes over primary's visual role. **Sizing:** Product UIs should default to `size="small"` for most buttons; use medium (default) only for important actions. `size="large"` is for marketing pages only.
-- **Breadcrumbs:** Structure: `Product Name > Section > Current Page`. **Quirk:** `current` defaults to `true` when no `href` — always pass `current` explicitly.
+- **Breadcrumbs:** Structure: `Product Name > Section > Current Page`. The last item defaults to `current`, so only set `current` to override that.
 - **Chip.Group:** Requires `aria-label`.
 - **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.
@@ -689,15 +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` / `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.
+
+When `Card` isn't a button or link, its `as` also only takes a tag name, and 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`).
 
@@ -724,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, activeTheme, setTheme, 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

@@ -166,15 +166,9 @@ Standard Tailwind spacing works (4px grid). EDS does **not** override spacing to
 
 When in doubt, add more space. Dense UIs look cheap.
 
-## Theme Classes
+## Theme Sections
 
-| Class        | Effect                                                     |
-| ------------ | ---------------------------------------------------------- |
-| `eds-dark`   | Forces dark color scheme for this element and descendants  |
-| `eds-light`  | Forces light color scheme for this element and descendants |
-| `eds-system` | Follows the OS color scheme preference                     |
-
-These can be applied to any element to create nested theme regions. The `EDSProvider` `theme` prop sets the root theme; these classes override it locally.
+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

@@ -6,6 +6,12 @@ import type { DirectionProvider } from '@base-ui/react/direction-provider'
 export type Theme = 'dark' | 'light' | 'system'
 export type ResolvedTheme = Exclude<Theme, 'system'>
 
+export const THEME_CLASSES: Record<Theme, string> = {
+  dark: 'eds-dark',
+  light: 'eds-light',
+  system: 'eds-system',
+}
+
 export type ThemePersistence =
   | 'localStorage'
   | 'cookie'
@@ -16,10 +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`, `Light`, or `LocalTheme` ancestor, if any. */
+export const LocalThemeContext = createContext<ResolvedTheme | undefined>(undefined)