destiny-kit-ui

Librería de Web Components del Design System, construida con Stencil. Los componentes son estándar (custom elements), por lo que funcionan en Astro, React, Angular, Vue, HTML plano o cualquier entorno interno.

Scripts

| Comando | Descripción | | ----------------- | ---------------------------------------------------- | | pnpm build | Compila la librería (dist/, loader/) | | pnpm dev | Build en watch + playground local (src/index.html) | | pnpm test | Pruebas unitarias (spec) con el runner de Stencil | | pnpm test:watch | Pruebas en modo watch | | pnpm lint | ESLint + Stylelint | | pnpm typecheck | Verificación de tipos con tsc |

Consumo desde una aplicación

// 1. Carga los estilos globales (incluyen los tokens, una sola vez)
import 'destiny-kit-ui/destiny-kit-ui.css';

// 2a. Registro global con lazy loading (recomendado para apps)
import { defineCustomElements } from 'destiny-kit-ui/loader';
defineCustomElements();

// 2b. O import individual tree-shakeable (bundlers modernos)
import 'destiny-kit-ui/components/ds-button';

<ds-button variant="primary" size="md">Guardar</ds-button>

Componentes

| Tag | Descripción | | ------------ | -------------------------------------------------------------------------- | | ds-button | Botón base, asociado a formularios (formAssociated). | | ds-link | Enlace o botón-enlace según reciba href. | | ds-alert | Retroalimentación no-modal de un estado del sistema. | | ds-gallery | Galería de imágenes: mosaico, diálogo con filtros y visor a pantalla completa. |

La API de cada uno vive en el readme.md de su carpeta, generado por Stencil a partir del código.

Crear un componente nuevo

1. Crea la carpeta src/components/ds-<nombre>/ con:
   • ds-<nombre>.tsx — lógica y template (decorador @Component, styleUrl a SCSS, shadow: true).
   • ds-<nombre>.scss — estilos consumiendo tokens vía var(--ds-*) y mixins de src/styles/.
   • ds-<nombre>.spec.ts — pruebas unitarias con newSpecPage.
   • ds-<nombre>.stories.ts — documentación y casos de uso en Storybook.
2. Exporta el componente en src/index.ts.
3. pnpm build regenera src/components.d.ts y el readme.md del componente.

Componentes compuestos

Cuando una pieza de UI tiene varias capas que siempre viajan juntas (como ds-gallery: mosaico + diálogo + visor), no se parte en varios custom elements: se mantiene un solo tag y por dentro se modulariza con componentes funcionales — funciones que devuelven JSX y se renderizan en el shadow root del componente, sin registrar un elemento propio.

ds-gallery/
├─ ds-gallery.tsx          # el único @Component: estado y orquestación
├─ ds-gallery.scss         # :host y sus custom properties locales
├─ parts/
│  ├─ gallery-mosaic.tsx   # componente funcional + su hoja de estilos
│  ├─ gallery-mosaic.scss
│  └─ …
├─ gallery.types.ts        # contratos de datos compartidos
├─ gallery.utils.ts        # helpers puros (parseo, foco, scroll)
├─ ds-gallery.spec.ts
└─ ds-gallery.stories.ts

Las hojas de cada pieza se declaran juntas en styleUrls, y Stencil las concatena en el mismo shadow root:

@Component({
  tag: 'ds-gallery',
  styleUrls: ['ds-gallery.scss', 'parts/gallery-mosaic.scss', 'parts/gallery-dialog.scss'],
  shadow: true,
})

Así el consumidor instala, versiona y tematiza una sola unidad, y el estado compartido (foco, teclado, bloqueo de scroll) se resuelve en un solo lugar.

Convenciones

• Prefijo de tag: ds-.
• Clases internas: BEM (ds-button__label, ds-button--primary).
• Nada de colores/espaciados hardcodeados: siempre var(--ds-*) de los tokens internos.
• Un componente = una carpeta con código, estilos, pruebas y stories colocalizados.
• Los archivos de un componente compuesto (parts/, *.types.ts, *.utils.ts) viven en esa misma carpeta.