@neus-al/neus-al-design-system

v0.3.1

Published

10 days ago

Design System core de NEUS-AL — tokens CSS, componentes, hooks, scaffold y assets

0High
0Medium
0Low

@neus-al/neus-al-design-system v0.3.1

Design System Foundation de NEUS-AL S.A.S. — tokens CSS, primitivas base, componentes core, hooks React, scaffold y assets visuales.

Paquete npm publicado bajo el scope @neus-al. Diseñado para ser consumido por cualquier proyecto de la empresa (via-pro, nuevos proyectos, etc.) como capa base sobre la que construir design systems específicos.

Instalación

pnpm add @neus-al/neus-al-design-system

Instalar el paquete no modifica tu proyecto. Si quieres el scaffold (assets/, constants/, hooks/) en la raíz, ejecútalo explícitamente:

pnpm exec neus-al-init           # crea solo lo que falte
pnpm exec neus-al-init --force   # sobrescribe con la versión del paquete

Qué incluye (v0.3.1)

| Capa | Contenido | |------|-----------| | Tokens CSS | 70+ custom properties: surfaces, semantic colors (primary/accent/success/special/creative), tipografía (4 fuentes), spacing, radius, shadows, glows, gradients, motion, layout, z-index | | Primitivas Forms | Input, textarea, select, checkbox, radio, toggle, label, hint, error, field-group, tamaños (sm/base/lg), estados (error/success) | | Primitivas Feedback | Badge (6 variantes: primary/success/warning/error/info/neutral), Status dot (5 estados: online/loading/error/idle/offline) | | Primitivas Loading | Skeleton (text/circle/rect + shimmer), Spinner (sm/base/lg) | | Primitivas Overlay | Modal/Dialog base (overlay, header/body/footer, close, keyframes fade-in/slide-up) | | Primitivas Toast | Toast container + 4 variantes (success/error/warning/info) con icon, title, message, close | | Layout Utilities | core-container, core-stack (sm/lg/xl), core-inline, core-grid (2/3/4 cols responsive), core-divider, core-truncate (1/2/3 líneas) | | Color/Text/Border Utils | core-bg-* (10), core-text-* (10), core-border-* (6) | | Accessibility | :focus-visible, .sr-only, .skip-link, prefers-reduced-motion, z-index scale | | Componentes de sitio | core-btn-pill (+ gradient/outline/light), core-card-soft, core-card-spotlight, core-eyebrow, core-field, core-icon-tile, core-text-gradient, core-bg-grid, core-bg-cta, core-pulse-dot | | Core Components | .core-card, .core-btn, .core-badge, .chat-bubble, .workflow-node, .code-block, .creative-container, .special-mode-panel | | Temas | Oscuro (por defecto) y claro vía data-neus-al-theme="light" | | Fuentes | fonts.css con @font-face para Space Grotesk, JetBrains Mono, Syne e Inter | | Hooks React | useNeusAlTheme, useColorScheme, useThemeColor | | Constants JS/TS | Colors, neusAlBrand, icons, images, neusAlAssets, neusAlImageSlots | | Scaffold (neus-al-init) | 5 fuentes TTF, 13 iconos PNG, 3 logos, constants TS, hooks TS |

Uso

CSS (tokens + primitivas + componentes)

// En tu entry point (Next.js app/, Vite main.ts, Expo web, etc.)
import "@neus-al/neus-al-design-system/fonts.css";  // @font-face (opcional si ya cargas las fuentes)
import "@neus-al/neus-al-design-system/styles.css";

Todas las variables CSS y clases quedan disponibles globalmente.

Con Tailwind CSS: las utilidades del paquete llevan prefijo core- (core-container, core-grid, core-text-primary…) para no pisar las clases de Tailwind. Ojo: la capa base estiliza también input, textarea y select sin clase y aplica un reset (* { margin: 0; padding: 0 }).

Ejemplos rápidos

<!-- Forms -->
<div class="field-group">
  <label class="label">Email</label>
  <input type="email" class="input" placeholder="[email protected]">
  <span class="hint">Correo corporativo</span>
</div>

<!-- Feedback -->
<span class="badge badge-success">Activo</span>
<span class="badge badge-warning">Pendiente</span>
<span class="badge badge-error">Fallido</span>
<span class="status-dot online"></span>

<!-- Loading -->
<div class="skeleton skeleton-text" style="width: 200px;"></div>
<div class="spinner"></div>

<!-- Modal -->
<div class="modal-overlay">
  <div class="modal">
    <div class="modal-header">
      <h3 class="modal-title">Confirmar</h3>
      <button class="modal-close" aria-label="Cerrar">✕</button>
    </div>
    <div class="modal-body">¿Estás seguro?</div>
    <div class="modal-footer">
      <button class="core-btn core-btn-primary">Cancelar</button>
      <button class="core-btn" style="background: var(--color-error-500)">Eliminar</button>
    </div>
  </div>
</div>

<!-- Toast -->
<div class="toast-container">
  <div class="toast toast-success">
    <div class="toast-icon">✓</div>
    <div class="toast-content">
      <div class="toast-title">Guardado</div>
      <div class="toast-message">Cambios aplicados correctamente.</div>
    </div>
    <button class="toast-close" aria-label="Cerrar">✕</button>
  </div>
</div>

<!-- Layout -->
<div class="core-container">
  <div class="core-stack core-stack-lg">
    <div class="core-grid core-grid-3">
      <div class="core-card">Card 1</div>
      <div class="core-card">Card 2</div>
      <div class="core-card">Card 3</div>
    </div>
  </div>
</div>

<!-- Utilities -->
<div class="core-bg-primary-gradient core-text-inverse p-4 rounded-lg">Gradient primario</div>
<p class="core-text-success">Éxito</p>
<div class="core-border-primary p-4">Borde primario</div>

Landing en tema claro

<html data-neus-al-theme="light">
  <section style="position:relative">
    <div class="core-bg-grid" style="position:absolute;inset:0"></div>
    <span class="core-eyebrow"><span class="core-pulse-dot"></span> Disponibles</span>
    <h1>Construimos el <span class="core-text-gradient">software</span> que escala</h1>
    <a class="core-btn-pill core-btn-gradient" href="/contacto">Hablemos</a>
    <a class="core-btn-pill core-btn-outline" href="/proyectos">Ver proyectos</a>
  </section>

  <article class="core-card-soft core-card-spotlight" style="padding:32px">
    <span class="core-icon-tile">…</span>
    <h3>Desarrollo Web</h3>
  </article>

  <input class="core-field" placeholder="[email protected]">

  <div class="core-bg-cta" style="padding:48px">
    <a class="core-btn-pill core-btn-light" href="/contacto">Iniciar proyecto</a>
  </div>
</html>

core-card-spotlight lee --mx y --my (porcentajes). Para que el brillo siga al cursor, actualízalos en mousemove:

card.addEventListener("mousemove", (e) => {
  const r = card.getBoundingClientRect();
  card.style.setProperty("--mx", `${((e.clientX - r.left) / r.width) * 100}%`);
  card.style.setProperty("--my", `${((e.clientY - r.top) / r.height) * 100}%`);
});

Constantes (JS/TS)

import { Colors, neusAlBrand, icons, images } from "@neus-al/neus-al-design-system";

console.log(Colors.primary[400]);        // "#2563EB"
console.log(Colors.elevation.modal);      // shadow string
console.log(Colors.zIndex.toast);         // 1300
console.log(neusAlBrand.name);            // "NEUS-AL"
console.log(icons.home);                  // "assets/icons/home.png"
console.log(images.logoHorizontal);       // "assets/images/logohorizontal.svg"

Estructura Colors (TypeScript incluido en scaffold):

Colors: {
  surface, primary, accent, success, special, creative,
  warning, error, text, feedback, border,
  typography, radius, spacing,
  shadow, glow, gradient, motion, layout,
  elevation, zIndex   // ← NUEVO en v0.2.0
}

Hooks (React DOM)

import { useNeusAlTheme } from "@neus-al/neus-al-design-system/hooks/useNeusAlTheme";

function ThemeToggle() {
  const { theme, setTheme } = useNeusAlTheme("dark");
  return <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
    Tema: {theme}
  </button>;
}

useNeusAlTheme(default?) → setea data-neus-al-theme en <html>; con "light" el CSS cambia superficies, texto, bordes y sombras (también funciona sin React: document.documentElement.dataset.neusAlTheme = "light")
useColorScheme() → detecta prefers-color-scheme (web) / hardcodea "dark" (native via scaffold)
useThemeColor({ light, dark }, colorName) → resuelve color según tema

Scaffold (`pnpm exec neus-al-init`)

Al ejecutar el comando, tu proyecto recibe:

tu-proyecto/
  assets/
    fonts/    → SpaceGrotesk-Variable.ttf, JetBrainsMono-Variable.ttf,
                Syne-Variable.ttf, InterVariable.ttf, InterVariable-Italic.ttf
    icons/    → 13 PNGs (home, profile, search, plus, menu, arrows, upload,
                logout, eye, eye-hide, play, bookmark)
    images/   → logohorizontal.svg, logohorizontal-oscuro.svg, logosymbol.svg,
                logosymbol.ico
  constants/
    colors.ts → Tokens tipados (idénticos a Colors JS + elevation + zIndex)
    icons.js  → Mapa de iconos
    images.js → Mapa de logos
    index.js  → Barrel export
  hooks/
    useColorScheme.ts      → Proxy a react-native
    useColorScheme.web.ts  → Hardcodea "dark"
    useThemeColor.ts       → Resolvedor de color temático

Fuentes: en web basta con import "@neus-al/neus-al-design-system/fonts.css" (Vite, Astro y webpack copian los TTF al build). En Expo/React Native cárgalas con useFonts desde assets/fonts/.
Iconos e imágenes: icons.js e images.js exportan rutas relativas a la raíz del proyecto ("assets/icons/home.png"). En web sirve assets/ como estático; en React Native usa require() con esas rutas. Los logos son SVG: en React Native necesitas react-native-svg para mostrarlos.

Exports (package.json)

| Subpath | Archivo | Contenido | |---------|---------|-----------| | . (default) | constants/index.js | neusAlBrand, neusAlAssets, neusAlImageSlots, Colors, icons, images | | ./styles.css | dist/index.css | CSS completo (tokens + primitivas + componentes) | | ./fonts.css | fonts.css | @font-face de las 4 familias | | ./constants/colors | constants/colors.js | Objeto Colors | | ./constants/icons | constants/icons.js | Mapa iconos → rutas | | ./constants/images | constants/images.js | Mapa logos → rutas | | ./hooks/useNeusAlTheme | hooks/useNeusAlTheme.js | Hook tema (React DOM) | | ./hooks/useColorScheme | hooks/useColorScheme.js | Detector esquema claro/oscuro | | ./hooks/useThemeColor | hooks/useThemeColor.js | Resolvedor color temático | | ./assets/manifest | assets/manifest.json | Especificación assets requeridos |

Build y publicación (mantenedores)

cd "LIBRERIAS JS/neus-al-design-system"

# 1. Sincronizar CSS desde fuente raíz
node scripts/sync-css.mjs

# 2. Verificar tarball
pnpm pack

# 3. Publicar (requiere pnpm login + permisos @neus-al)
pnpm publish --access public

El script prepack ejecuta sync-css.mjs automáticamente antes de publicar.

Versiones

| Versión | Cambios | |---------|---------| | 0.3.1 | Logos horizontales sin "S.A.S." en el dibujo (el <title> conserva el nombre completo); se quitan las claves logoHorizontalPng / logoSymbolPng y los PNG de logos. Ver CHANGELOG.md | | 0.3.0 | Tokens faltantes (spacing, motion, typography, layout), tema claro, fonts.css, utilidades con prefijo core-, scaffold manual (neus-al-init) en lugar de postinstall. Ver CHANGELOG.md | | 0.2.0 | Foundation completa: +Forms, +Feedback, +Loading, +Modal, +Toast, +Layout Utils, +Color/Text/Border Utils, +A11y, +elevation/zIndex tokens, +TypeScript exports completos | | 0.1.0 | Tokens, core components, hooks, scaffold básico |

Licencia

MIT — NEUS-AL S.A.S.