Tema

El ThemeProvider hace que la librería sea autónoma: define sus propios tokens de superficie y permite forzar light, dark o system sin depender del host (incluido el tema de estas docs).

Preview principal

THEME PROVIDER

tema: system · resuelto: lightdark

Los componentes leen --ds-surface, --ds-text y bordes del provider — no del tema de la página.

Patrones comunes

Dos providers aislados en la misma página — light y dark a la vez.

Forzado: clarodefaultTheme="light"

Misma UI, tokens propios. Independiente del tema de Starlight.

Forzado: oscurodefaultTheme="dark"

Misma UI, tokens propios. Independiente del tema de Starlight.

Propiedades

Prop	Tipo	Descripción
`defaultTheme`	`light \| dark \| system`	Tema inicial (por defecto `system`)
`storageKey`	`string`	Clave de localStorage (por defecto `ds-theme`)
`storage`	`boolean`	Persiste el tema (por defecto `true`)

Hook

import { ThemeProvider, ThemeToggle, useTheme } from "devsoftec-ui";

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <Toolbar />
    </ThemeProvider>
  );
}

function Toolbar() {
  const { theme, resolvedTheme, setTheme } = useTheme();
  return (
    <>
      <span>{theme} → {resolvedTheme}</span>
      <ThemeToggle cycle />
      <button onClick={() => setTheme("dark")}>Oscuro</button>
    </>
  );
}

En demos/SSR, para mostrar el tema resuelto sin esperar la hidratación usa ResolvedThemeLabel (CSS + prefers-color-scheme).

Valor	Descripción
`theme`	Preferencia elegida: `light`, `dark` o `system`
`resolvedTheme`	Tema efectivo: siempre `light` o `dark` (tras hidratar; en SSR con `system` puede diferir hasta el cliente)
`setTheme`	Cambia la preferencia (y persiste si `storage` está activo)

Tokens de superficie

El provider aplica estos tokens inline en su contenedor (claro / oscuro):

Token	Light	Dark
`--ds-surface`	`#FAFAFA`	`#171717`
`--ds-text`	`#0A0A0A`	`#FAFAFA`
`--ds-muted`	`#737373`	`#A3A3A3`
`--ds-border`	`#D4D4D4`	`#404040`
`--ds-control-accent`	`#0A0A0A`	`#FAFAFA`
`--brand-fg` / `--brand-bg`	invertidos según tema	(aisla el island del host)

También reescribe un subconjunto de --sl-color-* dentro del árbol del provider, para que componentes que caen a tokens Starlight sigan leyendo la paleta correcta.

¿Por qué es autónomo?

Los componentes ds-* leen --ds-surface, --ds-text y bordes del provider. Así se ven bien aunque la página (o Starlight) defina otros colores. Puedes montar un island light dentro de una app dark — o al revés.

Accesibilidad

Respeta prefers-color-scheme cuando el tema es system (vía CSS en el primer paint — sin flash light→dark).
Aplica color-scheme para que scrollbars e inputs nativos se adapten.
ThemeToggle expone radiogroup / radio cuando cycle está activo.