/// Utilities
PdsProvider
Stamps theme/accent/density/env on a subtree and exposes them via context.
import { PdsProvider, usePdsContext } from "@protocore/pds";Live theme switching
PdsProvider stamps data-theme on its wrapper, and every token resolves against that attribute — so flipping the theme recolors the whole subtree live, scoped to this box, no reload. The child reads and sets the theme through usePdsContext().
Syncing block 21,904,118
Accent
accent stamps data-accent, remapping --pds-accent — the single brand signal used by focus rings, the one live number, and selected markers. Five accents ship: green (default), blue, red, amber, violet.
1,284 tx/s
Density & environment
density stamps data-density (compact shrinks control heights for dense dashboards) and env stamps data-env to drive environment chrome like EnvBadge and EnvStrip. Both are static props, set per subtree.
density=default · env=prod
density=compact · env=staging
When to use it
PdsProvider does two jobs: it stamps the theming attributes (data-theme, data-accent, data-density, data-env) on its subtree, and it exposes them — plus setTheme/setAccent — through PdsContext for runtime toggles and density-aware components. Wrap your app once near the root. Apps typically *also* set data-theme on <html> (for the initial paint and full-page background) and use this provider for the reactive context. Theme and accent are controllable (theme/defaultTheme + onThemeChange, same for accent) following the standard PDS controlled/uncontrolled pattern; density and env are plain props. Because attributes are scoped to the subtree, you can nest providers to preview a different theme or env in one panel — as the density/env demo does.
usePdsContext()
Call usePdsContext() inside any descendant to read { theme, setTheme, accent, setAccent, density, env }. It throws if used outside a <PdsProvider>, so a caught error means a component is mounted without the provider above it. Use the setters to build theme/accent toggles (they respect controlled mode — if you passed theme, drive it through onThemeChange instead).
Usage
Do
- Wrap your app once near the root, and also set `data-theme` on `<html>` for the first paint and page background.
- Read and toggle theme/accent through `usePdsContext()` rather than manipulating attributes yourself.
- Nest a provider to scope a different theme or `env` to a preview panel.
- Use `defaultTheme`/`defaultAccent` for uncontrolled, or the controlled prop + `onChange` when app state owns the value.
Don't
- Don't call `usePdsContext()` outside a provider — it throws by design.
- Don't scatter many providers across a page for styling; one near the root plus deliberate nested previews.
- Don't set `data-theme` on `<html>` and forget the provider — density-aware components and toggles need the context.
- Don't mix controlled `theme` with `setTheme` writes; drive controlled state through `onThemeChange`.
Accessibility
- PdsProvider renders a plain `<div>` (or merges onto its child with `asChild`) and adds no roles — it's a context/attribute host, not a landmark.
- Theming affects color only; it never changes DOM order or focus, so keyboard and screen-reader flow are unaffected.
- Respect the user's OS color-scheme preference when choosing the initial theme, and keep contrast within AA across whichever accent you expose.
- Density changes control heights, not hit targets' semantics — keep `compact` targets large enough to remain comfortably tappable.
PdsProvider props
| Prop | Type | Default | Description |
|---|---|---|---|
accent | enum | — | Controlled accent. Pair with `onAccentChange`. |
asChild | boolean | false | Merge props onto the child element instead of rendering a wrapper div. |
className | string | — | |
defaultAccent | enum | green | Initial accent in uncontrolled mode. |
defaultTheme | enum | dark | Initial theme in uncontrolled mode. |
density | enum | default | UI density; stamps `data-density`. |
env | enum | — | Deployment environment; stamps `data-env` for env chrome. |
onAccentChange | ((accent: "green" | "blue" | "red" | "amber" | "violet") => void) | — | Fires when the accent changes. |
onThemeChange | ((theme: "dark" | "light") => void) | — | Fires when the theme changes. |
style | CSSProperties | — | |
theme | enum | — | Controlled theme. Pair with `onThemeChange`. |