@apiux-ds/design-system-full

Design System de Apiux: tokens y componentes React derivados del Brandbook Apiux 2024. Es la única fuente de verdad visual para los fronts de la organización y el paquete que consume el skill react-admin-shell.

• 28 componentes React tipados (.d.ts publicados)
• Light y dark completos, con data-theme y prefers-color-scheme
• Contraste WCAG 2.2 AA verificado por script en cada build
• Cero colores inventados: todo sale del brandbook o es una derivación comentada en tokens.css

Instalación

npm install @apiux-ds/design-system-full

react y react-dom (>=18) son peer dependencies: los aporta la app.

Uso

// main.tsx — una sola vez, lo antes posible
import '@apiux-ds/design-system-full/styles.css';
// Tipografía de marca (brandbook p.16). Los pesos que use tu app:
import '@fontsource/montserrat/400.css';
import '@fontsource/montserrat/500.css';
import '@fontsource/montserrat/600.css';
import '@fontsource/montserrat/700.css';

import { Button, Card, FormField, Input, useTheme } from '@apiux-ds/design-system-full';

export function Pantalla() {
  const { isDark, toggleTheme } = useTheme();
  return (
    <Card header="Nueva propuesta">
      <FormField label="Cliente" required>
        <Input placeholder="Ej: Superintendencia de Educación" />
      </FormField>
      <Button variant="primary">Guardar</Button>
      <Button variant="ghost" onClick={toggleTheme}>
        {isDark ? 'Tema claro' : 'Tema oscuro'}
      </Button>
    </Card>
  );
}

Solo los tokens

import '@apiux-ds/design-system-full/tokens.css';          // variables CSS
import { tokens, chartPalette } from '@apiux-ds/design-system-full/tokens'; // valores en JS

Tema claro/oscuro

El tema se controla con el atributo data-theme en <html> (light | dark).

• Si usas useTheme(), el hook lo escribe y lo persiste en localStorage (clave apiux-theme).
• Si tu app maneja el tema por su cuenta (por ejemplo el ThemeContext de react-admin-shell), basta con que escriba ese mismo atributo.
• Sin atributo, la hoja respeta prefers-color-scheme, así que el primer paint ya sale correcto.

Para pintar el fondo de la página con el token del tema, agrega class="apx-body" al <body> o class="apx-app" al contenedor raíz.

Íconos

El DS no trae set propio (el brandbook define construcción de íconos, no una librería). El estándar es lucide-react, igual que en react-admin-shell:

npm install lucide-react

import { Plus } from 'lucide-react';
<Button variant="primary" leftIcon={<Plus size={18} strokeWidth={2} />}>Nueva propuesta</Button>

Arquitectura de tokens

Dos capas, siempre en este orden:

1. Marca — --apiux-*: los valores literales del brandbook (--apiux-yellow: #ffce00). No cambian entre temas.
2. Semántica — --color-*, --space-*, --radius-*, --shadow-*, --font-*: los que consumen los componentes y las apps. Sí cambian entre temas.

En una app siempre se usa la capa semántica. Usar --apiux-yellow directo rompe el modo oscuro.

Alias del contrato con react-admin-shell: --color-bg, --color-bg-elevated, --color-surface, --color-border, --color-border-strong, --color-text, --color-text-muted, --color-text-inverse, --color-primary, --color-primary-soft, --color-primary-contrast, --color-accent, --color-accent-soft, --color-accent-contrast, --color-hover, --color-active, --color-focus, --color-success|warning|danger|info (+ -soft y -contrast), --font-body, --font-heading, --radius-sm|md|lg|full, --shadow-sm|md|lg, --space-1..16, --transition-fast|base.

Desarrollo

npm install
npm run build          # check de contraste + tsc (JS y .d.ts) + styles.css
npm run check:contrast # solo la verificación WCAG
npm run typecheck

scripts/check-contrast.mjs recorre todos los pares texto/fondo declarados en tokens.css en light y en dark y falla si alguno queda bajo 4.5:1 (3:1 para bordes y foco). Un par que no cumple se corrige ajustando el gris o el semántico derivado, nunca el color de marca.

Publicación

El paquete queda listo con la versión y el CHANGELOG. Para publicar, desde tu sesión ya autenticada:

npm publish --access public

El scope @apiux-ds debe existir como organización en npmjs.com antes del primer publish (npmjs.com → Add Organization, plan gratuito = paquetes públicos ilimitados). Un 404 Not Found en el PUT significa que el scope no existe o tu usuario no es miembro.

Documentación

• docs/AI-GUIDE.md — jerarquía de color, árboles de decisión, patrones y antipatrones de la marca.
• docs/components.json — metadata de los 28 componentes con props, defaults y opciones.

Licencia

© Apiux Tecnología. Todos los derechos reservados. El paquete se distribuye públicamente para uso en los productos y proyectos de Apiux; la marca, el logo y la paleta son propiedad de Apiux y su uso fuera de ese contexto no está autorizado. Ver LICENSE.