@edgeandnode/eds-react 1.0.2 → 1.1.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eds
-version: 1.0.2
+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://e4b81a8--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.2",
+    "@edgeandnode/eds-react": "^1.1.0",
     "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,11 +700,11 @@ 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.
@@ -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.
+
+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`).
 
@@ -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)

package/src/EDSProvider.tsx

@@ -6,7 +6,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
-  useState,
+  useSyncExternalStore,
   type ComponentProps,
 } from 'react'
 import { mergeProps } from '@base-ui/react'
@@ -24,17 +24,15 @@ import {
 } from './EDSContext.ts'
 import { useControlled } from './hooks/useControlled.ts'
 import { useIsHydrated } from './hooks/useIsHydrated.ts'
+import {
+  COOKIE_REGEX,
+  isValidTheme,
+  parseThemeCookie,
+  PERSISTENCE_KEY,
+  VALID_THEMES,
+} from './theme-persistence.ts'
 import { cn } from './utils/index.ts'
 
-const PERSISTENCE_KEY = 'eds-active-theme'
-const COOKIE_REGEX = new RegExp(`(?:^|; )${PERSISTENCE_KEY}=([^;]+)`)
-
-const VALID_THEMES: readonly Theme[] = ['dark', 'light', 'system']
-
-function isValidTheme(value: unknown): value is Theme {
-  return typeof value === 'string' && (VALID_THEMES as readonly string[]).includes(value)
-}
-
 interface PersistenceAdapter {
   get: () => Theme | null
   set: (value: Theme) => void
@@ -67,17 +65,14 @@ function resolvePersistence(persistTheme: ThemePersistence | undefined): Persist
     return {
       get: () => {
         try {
-          const match = document.cookie.match(COOKIE_REGEX)
-          if (match === null) return null
-          const value = decodeURIComponent(match[1] as string)
-          return isValidTheme(value) ? value : null
+          return parseThemeCookie(document.cookie) ?? null
         } catch {
           return null
         }
       },
       set: (value) => {
         try {
-          document.cookie = `${PERSISTENCE_KEY}=${encodeURIComponent(value)}; path=/; max-age=31536000; samesite=lax`
+          document.cookie = `${PERSISTENCE_KEY}=${value}; path=/; max-age=31536000; samesite=lax`
         } catch {
           // ignore restrictive environments
         }
@@ -107,12 +102,13 @@ function resolvePersistence(persistTheme: ThemePersistence | undefined): Persist
 const prefersDarkMediaQuery =
   typeof window !== 'undefined' ? window.matchMedia('(prefers-color-scheme: dark)') : null
 
-function resolveTheme(theme: Theme, systemFallback: ResolvedTheme = 'dark'): ResolvedTheme {
-  if (theme === 'system') {
-    if (prefersDarkMediaQuery === null) return systemFallback
-    return prefersDarkMediaQuery.matches ? 'dark' : 'light'
-  }
-  return theme
+function subscribeToSystemTheme(onChange: () => void) {
+  prefersDarkMediaQuery?.addEventListener('change', onChange)
+  return () => prefersDarkMediaQuery?.removeEventListener('change', onChange)
+}
+
+function getSystemTheme(): ResolvedTheme {
+  return prefersDarkMediaQuery?.matches === false ? 'light' : 'dark'
 }
 
 export interface EDSProviderProps extends Omit<ComponentProps<'div'>, 'dir'> {
@@ -138,16 +134,22 @@ export interface EDSProviderProps extends Omit<ComponentProps<'div'>, 'dir'> {
    * - `'localStorage'`: reads/writes `localStorage['eds-active-theme']`. Inline pre-hydration script
    *   reads the value before first paint — no SSR flash.
    * - `'cookie'`: reads/writes a `eds-active-theme` cookie (`path=/; max-age=31536000;
-   *   samesite=lax`). Same no-flash SSR; also readable server-side (e.g. via Next.js `headers()`).
+   *   samesite=lax`). Same no-flash SSR; pass `getThemeFromCookies()` to `defaultTheme` on the
+   *   server so it renders the saved theme too.
    * - `{ get, set }`: custom adapter (different key, encryption, remote storage, etc.). Invalid
-   *   values from `get()` fall back to `defaultTheme`. No pre-hydration script is emitted; for
-   *   zero-flash SSR, inject your own inline script that adds the matching `eds-*` class to
-   *   `<html>` before paint.
+   *   values from `get()` fall back to `defaultTheme`. In uncontrolled mode, no pre-hydration
+   *   script is emitted; for zero-flash SSR, inject your own inline script that adds the matching
+   *   `eds-*` class to `<html>` before paint.
    *
    * The two string presets share the key `'eds-active-theme'` — use a custom adapter for per-app
    * isolation on the same origin.
    */
   persistTheme?: ThemePersistence | undefined
+  /**
+   * Nonce for the inline scripts and styles `EDSProvider` adds, if your Content Security Policy
+   * requires one.
+   */
+  nonce?: string | undefined
   /** @default 'ltr' */
   direction?: ComponentProps<typeof DirectionProvider>['direction'] | undefined
   /** @default 'en' // or for `direction="rtl"`, 'ar' */
@@ -161,7 +163,8 @@ export type { EDSContextValue, ResolvedTheme, Theme, ThemePersistence } from './
  * Provides global configuration and enhancements for EDS components.
  *
  * Note: Only one EDSProvider should be used per app, typically at the root. If you need different
- * themes for different parts of the app, use the `Dark` and `Light` components instead.
+ * themes for different parts of the app, use the `Dark`, `Light`, and `LocalTheme` components
+ * instead.
  *
  * **Next.js App Router:** add `suppressHydrationWarning` to your `<html>` tag in `app/layout.tsx`.
  * The pre-hydration script applies the theme class to `<html>` before React hydrates (preventing a
@@ -200,6 +203,7 @@ export function EDSProvider({
   defaultTheme = 'dark',
   onThemeChange,
   persistTheme,
+  nonce,
   direction = 'ltr',
   language = direction === 'rtl' ? 'ar' : 'en',
   buttonOrLinkConfig,
@@ -288,6 +292,7 @@ export function EDSProvider({
     }
 
     const style = document.createElement('style')
+    if (nonce !== undefined) style.nonce = nonce
     style.textContent = '*:not(.eds-segmented-control *) { transition: none !important; }'
     document.head.appendChild(style)
     removeClasses()
@@ -301,30 +306,15 @@ export function EDSProvider({
       style.remove()
       removeClasses()
     }
-  }, [theme])
-
-  // `activeTheme` resolves `'system'` to `'dark'` or `'light'` via `prefers-color-scheme`. Initial
-  // state skips `matchMedia` to keep SSR and first client render in sync; the effect catches up
-  // pre-paint.
-  const systemFallback: ResolvedTheme = defaultTheme === 'system' ? 'dark' : defaultTheme
+  }, [theme, nonce])
 
-  const [activeTheme, setActiveTheme] = useState<ResolvedTheme>(() =>
-    theme === 'system' ? systemFallback : theme,
+  // The server can't know the OS preference, so it renders `'dark'`, `:root`'s default
+  const systemTheme = useSyncExternalStore<ResolvedTheme>(
+    subscribeToSystemTheme,
+    getSystemTheme,
+    () => 'dark',
   )
 
-  useLayoutEffect(() => {
-    setActiveTheme(resolveTheme(theme, systemFallback))
-
-    if (theme !== 'system') return
-
-    const handleChange = (event: MediaQueryListEvent) => {
-      setActiveTheme(event.matches ? 'dark' : 'light')
-    }
-
-    prefersDarkMediaQuery?.addEventListener('change', handleChange)
-    return () => prefersDarkMediaQuery?.removeEventListener('change', handleChange)
-  }, [theme, systemFallback])
-
   /**
    * Add the `data-eds-active` attribute to the `html` element when the Space key is pressed to
    * improve Tailwind's `active` state.
@@ -390,20 +380,22 @@ export function EDSProvider({
     if (lightDarkTest !== '' && !lightDarkTest.includes('light-dark')) {
       // oxlint-disable-next-line no-console
       console.warn(
-        "[EDSProvider] `light-dark()` was transpiled by your build tools, so components inside `Dark` and `Light` will use the page's colors. Target Chrome 123, Safari 17.5, and Firefox 120 or newer (see the `@edgeandnode/eds-react` README).",
+        "[EDSProvider] `light-dark()` was transpiled by your build tools, so components inside `Dark`, `Light`, and `LocalTheme` will use the page's colors. Target Chrome 123, Safari 17.5, and Firefox 120 or newer (see the `@edgeandnode/eds-react` README).",
       )
     }
   }, [])
 
+  const isHydrated = useIsHydrated()
+
   const edsContextValue = useMemo(
     () => ({
       theme,
-      activeTheme,
       setTheme,
+      systemTheme,
       direction,
       language,
     }),
-    [theme, activeTheme, setTheme, direction, language],
+    [theme, setTheme, systemTheme, direction, language],
   )
 
   return (
@@ -412,10 +404,19 @@ export function EDSProvider({
         <Pane.Provider>
           <Tooltip.Provider timeout={300}>
             <ButtonOrLink.Config {...buttonOrLinkConfig}>
-              {/* Set the theme class on <html> before first paint to prevent a flash */}
-              <PreHydrationScript>
-                {buildThemeScript(controlledTheme, defaultTheme, persistTheme)}
-              </PreHydrationScript>
+              {/**
+               * Apply the theme before first paint to prevent a flash, as the browser runs this script and
+               * applies this style while parsing the server-rendered HTML. The style applies a light or system
+               * theme until a theme class is set on `<html>`, in case there's no script (with a custom
+               * `persistTheme` adapter) or it can't run (e.g. blocked by a Content Security Policy). Both are
+               * removed after hydration.
+               */}
+              {isHydrated ? null : (
+                <>
+                  {renderThemeScript(controlledTheme, defaultTheme, persistTheme, nonce)}
+                  {renderThemeStyle(controlledTheme ?? defaultTheme, nonce)}
+                </>
+              )}
               <div
                 dir={direction}
                 lang={language}
@@ -431,38 +432,43 @@ export function EDSProvider({
   )
 }
 
-function buildThemeScript(
+function renderThemeScript(
   controlledTheme: Theme | undefined,
   defaultTheme: Theme,
   persistTheme: ThemePersistence | undefined,
+  nonce: string | undefined,
 ) {
-  // Controlled mode and the `undefined` / custom-adapter cases use the known theme — only the
-  // string presets need a storage lookup.
-  if (controlledTheme !== undefined) {
-    return `document.documentElement.classList.add('eds-${controlledTheme}')`
-  }
-  if (persistTheme !== 'localStorage' && persistTheme !== 'cookie') {
-    return `document.documentElement.classList.add('eds-${defaultTheme}')`
+  if (controlledTheme !== undefined || persistTheme === undefined) {
+    const script = `document.documentElement.classList.add('eds-${controlledTheme ?? defaultTheme}')`
+    return <script nonce={nonce}>{script}</script>
   }
+  // Custom adapters need the app's own script (see `persistTheme`), which this would conflict with
+  if (persistTheme !== 'localStorage' && persistTheme !== 'cookie') return null
 
-  const invalidCheck = VALID_THEMES.map((t) => `t!=='${t}'`).join('&&')
+  const invalidCheck = VALID_THEMES.map((theme) => `t!=='${theme}'`).join('&&')
   const readExpression =
     persistTheme === 'localStorage'
       ? `localStorage.getItem('${PERSISTENCE_KEY}')`
-      : `decodeURIComponent((document.cookie.match(/(?:^|; )${PERSISTENCE_KEY}=([^;]+)/)||[])[1]||'')`
-  return `(function(){try{var t=${readExpression};if(${invalidCheck})t='${defaultTheme}';document.documentElement.classList.add('eds-'+t)}catch(e){document.documentElement.classList.add('eds-${defaultTheme}')}})()`
+      : `(document.cookie.match(${COOKIE_REGEX})||[])[1]`
+  const script = `(function(){try{var t=${readExpression};if(${invalidCheck})t='${defaultTheme}';document.documentElement.classList.add('eds-'+t)}catch(e){document.documentElement.classList.add('eds-${defaultTheme}')}})()`
+  return <script nonce={nonce}>{script}</script>
 }
 
-interface PreHydrationScriptProps extends ComponentProps<'script'> {}
+const ROOT_WITHOUT_THEME_CLASS = `:root:not(${Object.values(THEME_CLASSES)
+  .map((themeClass) => `.${themeClass}`)
+  .join(', ')})`
 
 /**
- * Renders a `<script>` element that exists only until React hydration completes.
- *
- * Outputs its tag during SSR and during the client's initial render (ensuring the markup matches),
- * and removes itself after hydration to keep the DOM clean. The browser executes the inline script
- * as it parses the HTML, before React hydrates and before any styled body content paints.
+ * `:root` is dark by default, so other themes need a style until the theme class is set on
+ * `<html>`.
  */
-function PreHydrationScript({ children, ...props }: PreHydrationScriptProps) {
-  if (useIsHydrated()) return null
-  return <script {...props}>{children}</script>
+const THEME_STYLES: Record<Theme, string | null> = {
+  dark: null,
+  light: `${ROOT_WITHOUT_THEME_CLASS}{color-scheme:only light;--eds-color-scheme:light}`,
+  system: `${ROOT_WITHOUT_THEME_CLASS}{color-scheme:light dark}@media (prefers-color-scheme:light){${ROOT_WITHOUT_THEME_CLASS}{--eds-color-scheme:light}}`,
+}
+
+function renderThemeStyle(theme: Theme, nonce: string | undefined) {
+  const style = THEME_STYLES[theme]
+  return style !== null ? <style nonce={nonce}>{style}</style> : null
 }

package/src/components/Address.tsx

@@ -26,14 +26,15 @@ export declare namespace AddressProps {
   interface ButtonProps
     extends
       CommonProps,
-      MaybeButtonOrLinkProps.ButtonProps,
+      Omit<MaybeButtonOrLinkProps.ButtonProps, 'as'>,
       MaybeButtonOrLinkProps.DisableableProps {}
   interface LinkProps
     extends
       CommonProps,
-      MaybeButtonOrLinkProps.LinkProps,
+      Omit<MaybeButtonOrLinkProps.LinkProps, 'as'>,
       MaybeButtonOrLinkProps.DisableableProps {}
-  interface OtherElementProps extends CommonProps, MaybeButtonOrLinkProps.OtherElementProps {}
+  interface OtherElementProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as'> {}
 }
 
 export type AddressProps =

package/src/components/Avatar.tsx

@@ -36,10 +36,14 @@ export declare namespace AvatarProps {
     tooltip?: TooltipProps['content'] | Omit<TooltipProps, 'children'> | undefined
   }
   interface CommonProps extends OwnProps, EDSComponentProps<typeof AvatarMeta> {}
-  interface ButtonProps extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'children'> {}
-  interface LinkProps extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'children'> {}
+  interface ButtonProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'as' | 'children' | 'render'> {}
+  interface LinkProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'as' | 'children' | 'render'> {}
   interface OtherElementProps
-    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'children'> {}
+    extends
+      CommonProps,
+      Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as' | 'children' | 'render'> {}
 }
 
 export type AvatarProps =

package/src/components/Breadcrumbs.parts.tsx

@@ -269,9 +269,10 @@ export declare namespace BreadcrumbsItemProps {
     current?: boolean | undefined
   }
   interface CommonProps extends OwnProps, EDSComponentProps<typeof BreadcrumbsItemMeta> {}
-  interface ButtonProps extends CommonProps, MaybeButtonOrLinkProps.ButtonProps {}
-  interface LinkProps extends CommonProps, MaybeButtonOrLinkProps.LinkProps {}
-  interface OtherElementProps extends CommonProps, MaybeButtonOrLinkProps.OtherElementProps {}
+  interface ButtonProps extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'as'> {}
+  interface LinkProps extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'as'> {}
+  interface OtherElementProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as'> {}
 }
 
 export type BreadcrumbsItemProps =