ui-lcdl-lib

Una librería de componentes Svelte 4 construida con arquitectura ITCSS, tokens de diseño SCSS y TypeScript.

Instalación

npm install ui-lcdl-lib

Características

• 🎨 Sistema de Diseño: Construido con arquitectura ITCSS y tokens de diseño SCSS
• 🔧 TypeScript: Seguridad de tipos completa con definiciones exportadas
• ♿ Accesible: Componentes compatibles con WCAG y HTML semántico
• 📦 Tree-shakeable: Importa solo lo que necesitas
• 🎭 Storybook: Documentación interactiva de componentes
• ⚡ Compatible con SSR: Renderizado del lado del servidor

Uso

<script>
  import { Button, Card } from 'ui-lcdl-lib';
</script>

<Button variant="solid" size="md">
  Haz clic aquí
</Button>

Estructura del Proyecto

src/
  lib/
    styles/
      settings/      # Tokens de diseño
      tools/         # Mixins y funciones SCSS
      generic/       # Reset y normalize
      elements/      # Estilos de elementos base
      objects/       # Patrones de layout
      components/    # Estilos de componentes
      utilities/     # Clases de utilidad
    components/
      Primitives/    # Primitivas UI básicas
      UI/            # Componentes UI compuestos
      Sections/      # Componentes de sección
    types/
      types.ts       # Definiciones TypeScript

Desarrollo

Requisitos Previos

• Node.js 16+
• npm o pnpm

Configuración

# Instalar dependencias
npm install

# Iniciar servidor de desarrollo
npm run dev

# Ejecutar Storybook
npm run storybook

# Ejecutar tests
npm test

# Compilar librería
npm run build

Principios de Arquitectura

Enfoque CSS-First

• Priorizar CSS para layout y estados
• JavaScript mínimo para comportamiento y accesibilidad
• Usar propiedades personalizadas CSS para tematización

ITCSS + Tokens de Diseño

• Todos los estilos visuales derivan de tokens de diseño en settings/
• SCSS con alcance dentro de archivos de componentes
• Tokens globales solo en settings/

TypeScript

• Todos los componentes exportan definiciones de tipos
• Props, eventos y slots completamente tipados
• API pública estable

Accesibilidad

• HTML semántico primero
• ARIA mínima cuando sea necesario
• Comportamiento nativo del navegador preferido sobre JavaScript

Guía de Componentes

Estructura de Archivos

Cada componente incluye:

• Component.svelte - Implementación del componente
• types.ts - Definiciones TypeScript
• Component.stories.ts - Historias de Storybook
• Component.test.ts - Tests unitarios (opcional)
• index.ts - Exportaciones públicas

Convenciones de Nomenclatura

Clases CSS:

• .c- - Componentes
• .l- - Layouts
• .u- - Utilidades

Variables CSS:

• --component-* - Con alcance de componente
• --color-*, --space-*, etc. - Tokens globales

Plantilla de Componente

<script lang="ts">
  import type { ComponentProps, ComponentEvents } from './types';
  import { createEventDispatcher } from 'svelte';

  export let id: ComponentProps['id'] = undefined;
  export let disabled: ComponentProps['disabled'] = false;
  export let variant: ComponentProps['variant'] = 'solid';

  const dispatch = createEventDispatcher<ComponentEvents>();
</script>

<div
  class="c-component"
  {id}
  data-variant={variant}
  data-disabled={disabled || undefined}
  role="group"
  on:click={(e) => dispatch('click', e)}
>
  <slot />
</div>

<style lang="scss">
  .c-component {
    --pad: var(--space-3);
    padding: var(--pad);
    border-radius: var(--radius-md);

    &[data-variant='solid'] {
      background: var(--color-surface-1);
    }

    &[data-disabled] {
      opacity: 0.5;
      pointer-events: none;
    }
  }
</style>

Definiciones de Tipos

export type ComponentVariant = 'solid' | 'ghost';

export interface ComponentProps {
  id?: string;
  disabled?: boolean;
  variant?: ComponentVariant;
}

export type ComponentEvents = {
  click: MouseEvent;
};

Exportaciones

export { default as Component } from './Component.svelte';
export * from './types';

Testing

Los tests usan Vitest y Testing Library:

import { render, fireEvent } from '@testing-library/svelte';
import { describe, it, expect } from 'vitest';
import Component from './Component.svelte';

describe('Component', () => {
  it('renderiza correctamente', () => {
    const { container } = render(Component);
    expect(container.querySelector('.c-component')).toBeTruthy();
  });
});

Storybook

Las historias siguen este patrón:

import type { Meta, StoryObj } from '@storybook/svelte';
import Component from './Component.svelte';

const meta: Meta<Component> = {
  title: 'Primitives/Component',
  component: Component,
  tags: ['autodocs'],
  args: {
    disabled: false,
    variant: 'solid'
  },
  argTypes: {
    variant: {
      control: { type: 'radio' },
      options: ['solid', 'ghost']
    }
  }
};

export default meta;

export const Default: StoryObj = { args: {} };
export const Disabled: StoryObj = { args: { disabled: true } };

Compilación

El proceso de compilación genera:

• Componentes .svelte compilados
• Declaraciones TypeScript .d.ts
• styles.css empaquetado

npm run build

Mejores Prácticas

• Usar :focus-visible, :focus-within, :has() en lugar de JavaScript
• Transiciones CSS en lugar de animaciones JavaScript
• Evitar duplicar estado con clases y atributos
• No usar aria-live para cambios obvios
• Aprovechar el soporte nativo de teclado

Ejemplo: Disclosure Accesible

<details class="c-accordion" data-variant={variant}>
  <summary class="c-accordion__summary">
    <slot name="summary" />
  </summary>
  <div class="c-accordion__panel">
    <slot />
  </div>
</details>

<style lang="scss">
  .c-accordion[open] {}
  .c-accordion__summary {
    list-style: none;
  }
  .c-accordion__summary::-webkit-details-marker {
    display: none;
  }
</style>

Tokens de Diseño

Todos los componentes usan tokens de diseño globales:

• --color-text - Colores de texto
• --space-* - Escala de espaciado
• --radius-* - Radio de borde
• --shadow-* - Sombras de caja
• --font-* - Escala tipográfica

No se permiten números mágicos - todos los valores deben referenciar tokens.

Soporte

Para problemas y preguntas, por favor usa la página de GitHub Issues.