@sbseguros/design-system/README.md

A Vue 3 design system with Tailwind CSS and Lucide icons.

# 🎨 SBS Design System

Sistema de diseño para Vue 3 con Tailwind CSS y Lucide icons, desarrollado por SBS Seguros Colombia. Una librería de componentes reutilizables que proporciona una base sólida para el desarrollo de interfaces de usuario consistentes y escalables.

## 🚀 Características Clave

- **Vue 3:** Framework reactivo moderno con Composition API y `<script setup>`
- **TypeScript:** Tipado estático para mayor robustez y mantenibilidad del código
- **Tailwind CSS:** Framework de utilidades CSS para diseño rápido y consistente
- **Lucide Icons:** Biblioteca de iconos moderna y ligera
- **Vite:** Bundler ultrarrápido con HMR instantáneo
- **Storybook:** Documentación interactiva y desarrollo aislado de componentes
- **Vitest:** Framework de testing moderno y rápido
- **Class Variance Authority:** Gestión avanzada de variantes de componentes
- **Distribución Multi-formato:** Soporte para ESM, CJS, UMD e IIFE

## 🛠️ Configuración del Proyecto

### Requisitos Previos

Asegúrate de tener instalado:
- [Node.js](https://nodejs.org/) versión **20.18.0** o superior
- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) versión **10.8.2** o superior, o [Yarn](https://yarnpkg.com/getting-started/install)

## 📦 Instalación

### Para Usuarios del Design System

Instala el paquete en tu proyecto:

```bash
npm install @sbs/design-system
# O con Yarn:
yarn add @sbs/design-system
```

### Para Desarrollo del Design System

Clona el repositorio e instala las dependencias:

```bash
git clone https://github.com/sbs-seguros-col/sbs-common-components.git
cd sbs-common-components
npm install
```

## 🛠️ Herramientas de Desarrollo

### IDE y Extensiones Recomendadas

Se recomienda usar **VS Code** con las siguientes extensiones:

- **Vue Language Features (Volar):** Extensión oficial de VS Code para Vue 3
- **TypeScript Vue Plugin (Volar):** Para mejor soporte de TypeScript en archivos `.vue`
- **Tailwind CSS IntelliSense:** Autocompletado para clases de Tailwind
- **ESLint:** Para garantizar la consistencia del código
- **Prettier:** Para formatear el código automáticamente

### Stack Tecnológico

- **Framework:** Vue 3.5.13+ con Composition API
- **Lenguaje:** TypeScript 5.8.3
- **Bundler:** Vite 6.3.5
- **CSS Framework:** Tailwind CSS 3.4.17
- **Iconos:** Lucide Vue Next 0.511.0
- **Testing:** Vitest 3.1.4 + Playwright 1.52.0
- **Documentación:** Storybook 8.6.14
- **Utilidades:** Class Variance Authority, clsx, tailwind-merge

### Compatibilidad de Navegadores

Este design system es compatible con:
- Últimas 2 versiones de navegadores principales
- Navegadores con más del 1% de uso global
- Excluye Internet Explorer 11 y navegadores obsoletos

## 🚀 Comandos Disponibles

### Desarrollo

Inicia el servidor de desarrollo:

```bash
npm run dev
# O
yarn dev
```

### Storybook

Ejecuta Storybook para documentación y desarrollo de componentes:

```bash
npm run storybook
# O
yarn storybook
```

Accede a Storybook en `http://localhost:6006`.

### Build

Compila la librería para producción:

```bash
npm run build
# O
yarn build
```

Compila Storybook para producción:

```bash
npm run build-storybook
# O
yarn build-storybook
```

### Testing

Ejecuta las pruebas:

```bash
npm run test
# O
yarn test
```

### Linting

Analiza el código en busca de errores y problemas de estilo:

```bash
npm run lint
# O
yarn lint
```

### Releases

Genera una nueva versión automáticamente:

```bash
# Versión automática basada en commits
npm run release

# Versiones específicas
npm run release:major    # 1.0.0 -> 2.0.0
npm run release:minor    # 1.0.0 -> 1.1.0
npm run release:patch    # 1.0.0 -> 1.0.1
```

## 🤝 Contribución

Si deseas contribuir a este design system, sigue estos pasos:

1. **Fork** este repositorio
2. Crea una nueva rama: `git checkout -b feature/nombre-de-tu-caracteristica`
3. Realiza tus cambios y asegúrate de que pasen las pruebas y el linting
4. Haz commits siguiendo la convención de [Conventional Commits](https://www.conventionalcommits.org/)

### Ejemplos de commits:

```bash
feat(components): añade componente DatePicker
fix(button): corrige estilos en modo oscuro
docs(readme): actualiza guía de instalación
style(card): mejora espaciado interno
test(input): añade pruebas unitarias
```

5. Envía tus cambios: `git push origin feature/nombre-de-tu-caracteristica`
6. Abre un **Pull Request** describiendo tus cambios

### Proceso de Release

Este proyecto utiliza **commit-and-tag-version** para automatizar releases. Los maintainers pueden generar nuevas versiones usando:

```bash
npm run release        # Versión automática
npm run release:patch  # Incremento de patch (bugfixes)
npm run release:minor  # Incremento menor (nuevas features)
npm run release:major  # Incremento mayor (breaking changes)
```

## 📝 Documentación

### Storybook

La documentación interactiva de componentes está disponible en Storybook. Para acceder localmente:

```bash
npm run storybook
```

### Enlaces Útiles

- **Repositorio:** [sbs-common-components](https://github.com/sbs-seguros-col/sbs-common-components)
- **Issues:** [Reportar problemas](https://github.com/sbs-seguros-col/sbs-common-components/issues)
- **CHANGELOG:** Ver historial de cambios en el archivo `CHANGELOG.md`

## 👥 Equipo

### Maintainers

- **John Andrade** - *Senior Developer* - [john.andrade@sbseguros.co](mailto:john.andrade@sbseguros.co)

## 📄 Licencia

Este proyecto está bajo la [Licencia MIT](LICENSE).

---

<div align="center">
  <p><strong>Desarrollado con ❤️ por el equipo de SBS Seguros Colombia</strong></p>
</div>