@darcy-achs/ds-backoffice

Design system para productos back office de ACHS. Sistema independiente de @achsux/ui, orientado a interfaces de gestión interna con alta densidad de información.

Versión estable: ver package.json — librería en GitHub Packages (@darcy-achs/ds-backoffice).

Instalación

Copiá .npmrc.example a .npmrc del proyecto:

@darcy-achs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Token: PAT de GitHub con scope read:packages (y acceso al repo del paquete). En local: export GITHUB_TOKEN=ghp_...

Importante: en GitHub Packages, público significa visible en la web de GitHub, pero npm/pnpm siempre piden autenticación para descargar. No está en registry.npmjs.org.

npm install @darcy-achs/ds-backoffice tailwindcss-animate
# o
pnpm add @darcy-achs/ds-backoffice tailwindcss-animate

Requisitos: React ≥18, Tailwind CSS ≥4, tailwindcss-animate ≥1.0

Uso rápido

1. Importar los tokens CSS

En el entry point de tu app (ej. main.tsx o styles.css):

import "@darcy-achs/ds-backoffice/tokens";

Esto agrega todas las CSS custom properties al :root. A partir de ahí podés usar los tokens en tus componentes:

.mi-card {
  background: var(--card);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-card);
  padding: var(--space-card);
}

2. Tokens individuales

Si solo necesitás un subconjunto:

import "@darcy-achs/ds-backoffice/tokens/colors";
import "@darcy-achs/ds-backoffice/tokens/typography";

3. Utilidades

import { cn } from "@darcy-achs/ds-backoffice";

// Combina clases Tailwind sin conflictos
const className = cn("px-4 py-2", isActive && "bg-primary");

Tokens disponibles

Colores (/tokens/colors)

| Token | Uso | | --------------------------------------------------- | ----------------------------------------- | | --background | Canvas de la página (blanco) | | --foreground | Texto principal | | --card / --cream | Superficie de cards (blanco) | | --ink | Texto oscuro, CTAs primarios | | --primary / --primary-foreground | Acción principal | | --mint | Verde ACHS marca (#085F21), énfasis, foco | | --success / --warning / --info / --critical | Estados semánticos | | --border / --input / --ring | Bordes y foco | | --sidebar-* | Tokens específicos de sidebar | | --chart-1..5 | Serie de datos en gráficos | | --chip-*-bg/fg/border | Colores de chips por estado |

Tipografía (/tokens/typography)

| Token | Valor | Uso | | ------------------- | --------- | -------------------------- | | --text-2xs | 10px | Etiquetas uppercase | | --text-xs | 11px | Captions, hints | | --text-sm | 12px | Badges, texto secundario | | --text-md | 13px | Label estándar back office | | --text-base | 14px | Body | | --text-3xl | 26px | H1 de página | | --text-4xl | 30px | Valores KPI | | --type-page-title | compuesto | font shorthand para h1 | | --type-kpi-value | compuesto | font shorthand para KPIs | | --type-label | compuesto | font shorthand para labels |

Espaciado (/tokens/spacing)

Escala --space-0 a --space-24 (base 4px) + alias semánticos: --space-card, --space-page-x, --space-table-cell-x, etc.

Sombras (/tokens/shadows)

| Token | Uso | | ------------------ | --------------------------- | | --shadow-card | Card flotante sobre canvas | | --shadow-raised | Botones, elementos elevados | | --shadow-overlay | Dropdowns, popovers | | --shadow-modal | Modales, drawers | | --shadow-focus | Ring de foco accesible |

Capas (/tokens/layers)

| Token | Uso | | ------------- | ------------------------ | | --z-overlay | Backdrop de modales | | --z-modal | Diálogos, CommandPalette | | --z-toast | Notificaciones |

Motion (/tokens/motion)

| Token | Valor | Uso | | --------------------- | ------------ | ----------------------- | | --duration-fast | 140ms | Hover, toggles | | --duration-base | 200ms | Modales, dropdowns | | --duration-slow | 300ms | Drawers, sidebar | | --ease-default | spring suave | Mayoría de transiciones | | --transition-colors | shorthand | Color/background/border |

Configuración con Tailwind v4

Setup en 3 líneas (cualquier framework)

En el CSS principal de tu app:

@import "tailwindcss";
@plugin "tailwindcss-animate";
@import "@darcy-achs/ds-backoffice/setup"; /* escaneo automático de clases */
@import "@darcy-achs/ds-backoffice/tokens"; /* tokens CSS custom properties */

El archivo ./setup le indica a Tailwind v4 dónde encontrar las clases del DS — sin configurar nada más. Sin él los componentes renderizan sin estilos (botones sin color, layouts sin espaciado) y no hay error en consola.

Exponer tokens como utilidades Tailwind (opcional)

Si querés usar bg-primary, text-mint, etc. como clases de Tailwind:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-card: var(--card);
  --color-success: var(--success);
  --color-warning: var(--warning);
  --color-critical: var(--critical);
  --color-info: var(--info);
  --color-mint: var(--mint);
  --color-ink: var(--ink);
  --color-sidebar: var(--sidebar);
}

Por qué se necesita tailwindcss-animate

Los overlays (Combobox, DatePicker, ConfirmDialog, Sheet, Toast) usan clases como animate-in, fade-in-0, zoom-in-95 que pertenecen a este plugin. Sin él, las animaciones no funcionan.

Modo oscuro con Tailwind

Para activar el modo oscuro vía clase en el <html>:

/* En tu styles.css, después del @import de Tailwind */
@custom-variant dark (&:is(.dark *));

// En tu app, donde quieras togglear
document.documentElement.classList.toggle("dark");

Roadmap

• [x] v0.0.1 — Tokens: colores, tipografía, espaciado, sombras, motion, layers
• [x] v0.1.0 — Primitivos, formularios, DataTable, overlays base
• [x] v0.2.0 — Layout: Shell, Page, PageHeader, FilterBar, Breadcrumb
• [x] v0.3.0 — Datos: KPICard, ProgressBar, PillTabs, Sparkline, Stepper, Timeline
• [x] v0.4.0 — Feedback: EmptyState, ErrorPage, ErrorBoundary, LoadingPage, ConfirmDialog
• [x] v1.0.0 — Primera versión estable como librería npm reutilizable
• [x] Docs visuales — Ladle / catálogo interactivo (pnpm ladle)

Documentación

| Recurso | Contenido | | -------------------------------------------- | -------------------------------------- | | docs/COMPONENTS.md | Catálogo de exports | | MIGRATION.md | Adoptar el DS en un producto existente | | docs/PUBLISHING.md | Versionado y publicación | | CHANGELOG.md | Historial de versiones |

Contribuir

Ver CONTRIBUTING.md para el proceso completo: setup del entorno, convenciones de código, cómo agregar un componente y el proceso de PR.

Los cambios de API requieren un changeset: pnpm changeset.

Catálogo visual (Ladle)

Documentación interactiva del design system — foundations, componentes, patterns y landing.

pnpm ladle          # servidor de desarrollo (http://localhost:61000)
pnpm ladle:build    # build estático en build/
pnpm ladle:preview  # previsualizar el build

El catálogo vive en ladle/ y consume los tokens de src/tokens/. Para regenerar desde ejemplo ladle/:

node scripts/convert-ladle.mjs

Publicar en Vercel

El catálogo se despliega como sitio estático. La config está en vercel.json.

Primera vez (conectar GitHub → Vercel):

1. Sube el repo a GitHub (achs-cl/achs-ds-backoffice o tu fork).
2. En vercel.com/new → Import Git Repository → elige el repo.
3. Vercel lee vercel.json automáticamente. No cambies build ni output salvo que sepas por qué:
   • Build command: pnpm ladle:build
   • Output directory: build
   • Install command: pnpm install --frozen-lockfile
4. Deploy. Cada push a la rama de producción (p. ej. main) redeploya el catálogo.

URL del catálogo: la que asigne Vercel (*.vercel.app) o tu dominio custom. El story por defecto es el catálogo completo; también puedes usar ?story=catalog--catalog.

Nota: el paquete npm (pnpm build → dist/) es independiente del catálogo. Vercel solo publica Ladle; no publica el paquete a GitHub Packages.

Release (Changesets)

El workflow .github/workflows/release.yml abre un PR de versión cuando hay archivos en .changeset/. Si falla con:

GitHub Actions is not permitted to create or approve pull requests

activa en el repo Settings → Actions → General → Workflow permissions:

1. Read and write permissions
2. Marca Allow GitHub Actions to create and approve pull requests

Luego re-ejecuta el workflow desde la pestaña Actions (o haz un push que toque .changeset/).

Si aún no publicas el paquete npm, puedes ignorar ese workflow: no afecta el CI ni el deploy de Vercel.