Workbeat Design System

InicioFundamentosComponentesPatronesEjemplosReferenciaGuíasChangelogAgentes IA

Workbeat Design System

Catálogo, documentación API, ejemplos y changelog del WDS para producto, desarrollo y agentes de IA.

Reglas que no cambian Usa sólo tokens semánticos (cero hex, cero clases de paleta con tono, cero valores arbitrarios), no edites src/design-system en un host y mantén el título del navegador como “Workbeat”.

Instalación

Seis pasos para que un host renderice el DS con theme, sesión y side panels.

  1. Trae el snapshot local del DS

    El DS no se instala desde npm: llega como carpeta src/design-system sincronizada desde el repo fuente (workbeat-ia-2.1) por el equipo de frontend. En un host esa carpeta es de sólo lectura: los cambios se piden en el repo fuente, nunca se editan localmente (rompen el sync). Para un proyecto nuevo usa la skill wds-scaffold-new-project; para reparar uno existente, wds-setup.

  2. Prerrequisitos

    • React 19, Tailwind CSS v4 y alias @/* → src/*.
    • Las dependencias de src/design-system/dependencies.json (Radix, sonner, lucide-react, oidc-client-ts…).
    • No cargues fuentes: styles.css ya declara WB Open Sans desde los assets del DS.

  3. Importa los estilos

    src/styles.css
    /* src/styles.css del host: importa el DS una sola vez */
@import "./design-system/styles.css";

/* estilos exclusivos del host (sin @layer, después del import) */

  4. Monta el provider raíz

    src/Root.tsx
    import { WDSProvider } from "@/design-system/contexts/WDSProvider";
import { SideCanvas } from "@/design-system/components/layout/SideCanvas";

const HOST_COMPONENT_DEFAULTS = { avatar: { shape: "square" } } as const;

export function Root() {
  return (
    <WDSProvider authAdapter={authAdapter} env={runtimeEnv} componentDefaults={HOST_COMPONENT_DEFAULTS}>
      <App />
      <SideCanvas />
    </WDSProvider>
  );
}

    WDSProvider monta auth, configuración, theme, tooltips, sitios, feature toggles, permisos, Toaster y el provider de SideCanvas. Monta SideCanvas si alguna vista abre side panels. Para sesión real, el host inyecta un WDSAuthAdapter (BFF OIDC con cookie httpOnly).

  5. Usa componentes y patrones

    import { Button } from "@/design-system/components/ui/button";
import { FullTable } from "@/design-system/components/patterns/full-table";
import { useSideCanvas } from "@/design-system/hooks/useSideCanvas";

    Si existe un patrón para tu necesidad, es obligatorio usarlo (ver Inventario de patrones). Los datos siempre pasan por service objects (src/services/*), también en modo mock.

  6. Themes y modo oscuro

    El theme se resuelve solo (prop theme → claim Theme → default). El modo oscuro lo activa el host con .dark en <html>. Pruébalo en Fundamentos · Themes y modo oscuro.

Siguiente lectura

Integración en aplicaciones host

Cómo vive el DS dentro de un host: sync, alias, estilos y providers.

Checklist de integración host

Lo que se revisa antes de dar por integrado un proyecto.

Contrato de autenticación

WDSAuthAdapter, BFF OIDC y sesión con cookie httpOnly.