achs-web-kit

v0.0.2

Published

2 months ago

ACHS Design System - Web Kit con shadcn/ui y soporte multi-marca

0High
0Medium
0Low

ACHS Web Kit

Design system para ACHS compatible con Adonis + Inertia (Vite) y basado en shadcn/ui (Tailwind). Soporte multi-marca mediante data-brand.

Estructura

/achs-web-kit
├── apps/
│   ├── docs/              # Ladle - vitrina de componentes
│   └── demo-inertia/      # Demo Vite+React (validación de integración)
├── packages/
│   ├── tokens/            # CSS variables por marca (salud, seguro, servicios)
│   └── ui/                # Componentes shadcn + BrandProvider
└── pnpm-workspace.yaml

Comandos

pnpm install
pnpm docs      # Ladle en http://localhost:6006
pnpm demo      # Demo en http://localhost:5173

Instalación en tu proyecto

Añadir dependencias:
```
pnpm add @achsux/tokens @achsux/ui
```
Importar tokens + estilos en el entry (ej. main.tsx o app.ts):
```
import '@achsux/tokens'
import '@achsux/ui/globals.css';
```

Configurar Tailwind para incluir el paquete UI (build en dist/):

// tailwind.config.js
content: [
  './src/**/*.{ts,tsx,js,jsx}',
  './node_modules/@achsux/ui/dist/**/*.{js,jsx,ts,tsx}',
],

Añadir data-brand en el HTML o usar BrandProvider:
```
<html data-brand="salud">
```

Cómo usar los componentes

import { Button, Input, Card, BrandProvider, BrandSelector } from '@achsux/ui';

function App() {
  return (
    <BrandProvider>
      <BrandSelector />
      <Button>Primario</Button>
      <Input placeholder="Nombre" />
    </BrandProvider>
  );
}

Cómo cambiar de marca

Opción 1: BrandProvider + useBrand

import { BrandProvider, useBrand } from '@achsux/ui';

function MySelector() {
  const { brand, setBrand } = useBrand();
  return (
    <select value={brand} onChange={(e) => setBrand(e.target.value)}>
      <option value="salud">Salud</option>
      <option value="seguro">Seguro</option>
      <option value="servicios">Servicios</option>
    </select>
  );
}

Opción 2: Atributo directo

document.documentElement.dataset.brand = 'seguro';

Opción 3: HTML

<html data-brand="seguro">

El BrandSelector persiste la marca en localStorage automáticamente.

Marcas disponibles

| Valor | Descripción | |-------------|--------------| | salud | ACHS Salud | | seguro | ACHS Seguro | | servicios | ACHS Servicios |

Componentes incluidos

Button (default, secondary, outline, ghost, destructive, loading)
Input, Textarea
Select, Checkbox, Radio, Switch
Card
Tabs
Dialog
Toast (sonner)
Alert
Table
Skeleton

Cómo agregar nuevos componentes

Crear el componente en packages/ui/src/components/ui/.
Usar clases de Tailwind que referencien variables: bg-primary, text-foreground, border-border, ring-ring, etc.
Evitar colores hardcodeados (#hex, rgb()).
Exportar en packages/ui/src/index.ts.
Añadir demo en apps/docs/src/*.stories.tsx.

Integración con Adonis + Inertia

Crear la app: npm init adonisjs@latest mi-app -- -K=inertia --adapter=react
Añadir dependencias: pnpm add @achsux/tokens @achsux/ui

En el entry de Inertia (por ejemplo resources/js/app.tsx):

import '@achsux/tokens';
import '@achsux/ui/globals.css';

En resources/views/inertia_layout.edge: <html data-brand="salud">

En tailwind.config.js, añadir la librería al content:

content: [
  './resources/**/*.{ts,tsx,js,jsx,edge}',
  './node_modules/@achsux/ui/dist/**/*.{js,jsx,ts,tsx}',
],

Envolver la app con BrandProvider si usas useBrand o BrandSelector.

Accesibilidad y contraste

Los componentes usan focus-visible:ring-2 para foco keyboard.
Estados disabled usan opacity-50.
Los tokens de marca (--primary, --primary-foreground) deben cumplir WCAG AA (contraste 4.5:1 texto normal). Validar con herramientas como WebAIM Contrast Checker.