dashler

v0.6.1

Published

a day ago

Librería de componentes React para dashboards administrativos

0High
0Medium
0Low

ramalopez

react components dashboard admin ui design-system sass

Dashler

Librería de componentes React para dashboards administrativos. 49 componentes, tema claro y oscuro, y sin más dependencias que React.

npm install dashler

import { Button, Datatable, DatePicker } from "dashler";
import "dashler/styles.css"; // una sola vez, en la raíz de la app

<DatePicker label="Fecha de alta" value={fecha} onValueChange={setFecha} />;

Sin el CSS no se ve nada: los componentes no traen estilos inline.

El tema se elige con un atributo en el <html>. Sin atributo, se respeta la preferencia del sistema operativo:

<html data-theme="dark">

Para que lo cambie el usuario hay un botón hecho y un hook, y ninguno de los dos necesita provider:

import { ThemeToggle, useTheme } from "dashler";

<ThemeToggle />;

const { tema, efectivo, setTema, alternarTema } = useTheme();

tema es lo que eligió el usuario —"light", "dark" o "system"— y efectivo es lo que se está viendo. La preferencia se guarda en localStorage, sigue al sistema operativo en vivo mientras valga "system", y se sincroniza entre pestañas.

Falta una línea más, y solo si algún usuario va a elegir un tema distinto al de su sistema: sin esto la primera pintura usa el del sistema y se corrige cuando monta React, o sea que parpadea.

<!-- index.html, arriba de todo en el <head> -->
<script>
  (function(){try{var t=localStorage.getItem("ds-theme");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t)}catch(e){}})();
</script>

Con SSR va desde el string exportado: SCRIPT_TEMA.

Qué trae

| | | | --- | --- | | Formularios | Field · Input · TextArea · Select · NumberInput · SearchInput · PasswordField · Checkbox · Radio · Switch · CheckboxCards · RadioCards · InputFile · Slider · Calendar · DatePicker | | Datos | Datatable · DescriptionList · Stat · Badge · Avatar · Indicator · EmptyState · Checklist · Scheduler | | Capas | Modal · Drawer · Popover · Dropdown · Tooltip · Alert · Toast · Callout | | Estructura | Card · PageHeader · Breadcrumb · Sidebar · Tabs · Accordion · Stepper · Pagination · Separator · ScrollArea · Gallery · Spinner | | Acciones | Button · IconButton · ButtonGroup · ThemeToggle |

Cada uno tiene su documentación con ejemplos vivos en Storybook.

Para trabajar con una IA

La librería trae una skill de Claude Code adentro del paquete:

npx dashler skill

Copia a .claude/skills/dashler/ del proyecto las reglas de uso, cinco pantallas completas de ejemplo y el índice de dónde está la firma de cada componente. Con eso el agente escribe código que usa la librería bien en vez de adivinar props.

El índice se regenera en cada build de la librería, así que siempre refleja la versión instalada. Conviene volver a correr el comando después de cada npm update, porque lo que se copió queda como estaba.

Requiere dashler 0.2.0 o superior: en versiones anteriores el paquete no traía el comando, y npx se termina bajando otra copia del registro en vez de usar la que tenés instalada.

Tres decisiones que se notan al usarla

Las fechas van y vienen como string ISO "2026-08-23", nunca como Date. Un Date arrastra huso horario y corre el día: new Date("2026-08-23").getDate() devuelve 22 en Argentina. Para convertir en el borde están aFecha() y deFecha().

Los colores son roles, no valores. color="danger", no un hex. De cada rol salen varios tokens que no son intercambiables —el de identidad, el que sirve como texto, el de fondo tenue— y el contraste está verificado en tiempo de compilación contra WCAG AA, en los dos temas.

Sin Tailwind, ni como dependencia ni como clases. Todo sale de props (size, variant, color, radius). El proyecto que la consuma sí puede usarlo: por eso todo lleva prefijo ds- y el className que pasás se fusiona con las clases internas en vez de reemplazarlas.

<Button className="mt-4 w-full">Guardar</Button>

Desarrollo de la librería

Lo de acá abajo es para trabajar en dashler, no para usarla.

Stack

| Pieza | Qué usa | | --- | --- | | UI | React 19 + TypeScript | | Estilos | Sass → CSS plano (compila el Live Sass Compiler de VS Code) | | Playground | Storybook 10 | | Build | Vite en modo librería (ES + UMD) + tsc para los .d.ts |

Arranque

1. Compilar el tema. El proyecto no compila Sass por su cuenta: lo hace la extensión Live Sass Compiler de VS Code. Abrí la carpeta dashler como raíz del workspace y hacé click en Watch Sass en la barra de estado. Eso genera src/css/theme.css, de donde salen todos los tokens. La configuración ya está en .vscode/settings.json.

2. Levantar Storybook.

npm run storybook

Comandos

| Comando | Qué hace | | --- | --- | | npm run storybook | Playground + docs en http://localhost:6006 | | npm run build-storybook | Sitio estático de documentación | | npm run build | Compila la librería a dist/ y regenera el índice de la skill | | npm run typecheck | Chequeo de tipos sin emitir nada |

Estructura

src/
├── components/          un directorio por componente
│   └── button/
│       ├── Button.tsx
│       ├── Button.stories.tsx
│       └── Button.mdx
├── hooks/
├── utils/               fecha, máscaras, cx, texto
├── sass/                CÓDIGO FUENTE de los estilos
│   ├── partials/
│   │   ├── _variables.scss    prefijo, tipografía, espaciado, capas
│   │   ├── _colors.scss       paleta y roles semánticos
│   │   ├── _functions.scss    v(), spacer(), radius(), shade()...
│   │   ├── _mixins.scss       focus-ring, truncate, visually-hidden...
│   │   ├── _flotante.scss     el cuerpo de los paneles anclados
│   │   ├── _a11y.scss         contraste WCAG calculado en Sass
│   │   └── _index.scss        reexporta todo lo anterior
│   └── theme.scss             ÚNICO archivo que compila a CSS
├── css/                 SALIDA del Live Sass Compiler (no editar a mano)
└── index.ts             exports públicos de la librería
skill/                   la skill que viaja en el paquete

Cómo se agrega un componente

1. El SCSS en src/sass/button.scss. Una línea alcanza para tener todos los tokens:

@use "partials" as *;

.#{$prefix}button {
  height: control-height("md");
  padding-inline: spacer("4");
  border-radius: v("radius");
  background: v("color-primary-solid");
  color: v("color-primary-on");

  @include focus-ring;
}

Al guardar, el Live Sass Compiler escribe src/css/button.css.

2. El componente en src/components/button/Button.tsx, importando el CSS ya compilado (import "../../css/button.css").

3. El export en src/index.ts, el componente y el tipo de sus props.

Convenciones

Clases: ds- (.ds-button). Sale de $prefix, se cambia en un solo lugar.
Variantes por data-*, no por clases sueltas: data-variant, data-size, data-color, data-radius.
Nada de valores hardcodeados en el SCSS de un componente: si falta un token, se agrega al partial que corresponda.
El contraste no se verifica a mano: _a11y.scss implementa el cálculo de WCAG 2.1 en Sass y theme.scss se valida a sí mismo. Si un color no llega a 4.5:1, no compila.

Las reglas completas están en CLAUDE.md, y el inventario de qué está hecho y qué falta, en COMPONENTES.md.