bord-design-system

v0.0.10

Published

5 days ago

0High
0Medium
0Low

bord_npm_user

⚡Welcome to .Bord design system ⚡

📕📕 StoryBook

✨ Crea, documenta y valida tus componentes con Storybook al instante.

🚀 Entorno aislado, recarga rápida y configuración lista para escalar tu Design System sin fricción.

1️⃣ Clonar el repositorio

Primero, clona el proyecto a tu máquina local:

git  clone https://github.com/somosnudos/bord-design-system.git

cd  bord-design-system

2️⃣ Preparar tu entorno

Para que bord-design-system funcione correctamente, incluimos un archivo .nvmrc en la raíz del proyecto.

Este archivo define la versión de Node recomendada para usar con este proyecto.

Pasos:

Asegúrate de tener instalado nvm.
En la carpeta del proyecto, ejecuta:

nvm use

Esto hará que tu terminal use la versión de Node indicada en .nvmrc.
Si la versión no está instalada, nvm te indicará cómo instalarla.

Instala las dependencias:

yarn install

⚠️ Usamos solo yarn para instalar dependencias y ejecutar scripts, porque el repo está configurado específicamente para yarn.
4. Inicia el servidor de desarrollo:

npm run storybook

⚡ Ahora tu entorno está listo y todos los colaboradores usarán la misma versión de Node, evitando problemas de compatibilidad.

📂 Estructura del Proyecto

La carpeta principal es src/. Cada directorio tiene una responsabilidad única para mantener el proyecto escalable:

🖼️ assets/ — Archivos estáticos como imágenes, fuentes y vectores.

📂 Estructura de Componentes (Design System)

🧩 components/ — Componentes pertenecienstes al DesingSystem Estructura components

components/
└── ComponentName/
    ├── ComponentName.tsx           # 🧠 Lógica y estructura
    ├── ComponentName.scss          # 🎨 Estilos encapsulados
    ├── ComponentName.types.ts      # 🔎 Tipado fuerte de props
    └── ComponentName.stories.tsx   # 📚 Documentación en Storybook
index.tsx Punto de entrada del componente.  Centraliza y exporta el componentes (y sus tipos si es necesario) para facilitar imports limpios y organizados desde el exterior. (si no exportas tu componente aqui no lo vas a poder utilizar en ningun proyecto).

🔢 constants/ — Enums, mensajes fijos y configuraciones que no cambian.
⚓ hooks/ — Custom hooks globales para lógica compartida.
🛣️ providers/ — componentes que envuelven tus stories para darles contexto global, igual que en tu aplicación real.
🎨 styles/ — Configuración global, mixins y variables (Solo archivos SCSS).
🏷️ types/ — Interfaces y tipos de TypeScript compartidos.
🛠️ utils/ — Funciones de ayuda, formateadores y helpers generales.

🚀 Guía de Estilo y Flujo de Trabajo (Git Workflow)

Para garantizar la calidad y consistencia del código, este proyecto implementa un sistema automatizado de validación utilizando Husky, Lint-Staged, ESLint 9 (Flat Config) y TypeScript.

📝 1. Convención de Mensajes de Commit

Contamos con un hook de validación que bloquea mensajes genéricos. Los commits deben seguir el estándar de Conventional Commits.

Formato: tipo: descripción en minúsculas

Ejemplo correcto: feat: implementar el filtrado de desarrolladores
Ejemplo incorrecto: ajustes realizados (El commit será rechazado automáticamente).

🏗 2. Orden de Importaciones (ESLint)

El linter organiza automáticamente los bloques de importación para maximizar la legibilidad. El orden jerárquico es de lo más "externo" a lo más "interno", con una línea en blanco entre grupos de distinta categoría.

Jerarquía de orden:

Librerías Externas: react siempre debe ser la primera línea.
Lógica Interna: Hooks personalizados, estados globales (Zustand/Redux), servicios o API.
Componentes y Assets: Componentes locales e imágenes.
Tipos: Importaciones de interfaces o tipos de TypeScript (import type).
Estilos: Archivos .scss o .css siempre al final.

Ejemplo visual:

// 1. Externos
import React, { useState } from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Internos (Lógica y Estado)
import { useAuth } from '@/hooks/useAuth';
import { api } from '@/services/api';

// 3. Componentes y Assets
import { Button } from '@/components/Button';
import logo from '@/assets/logo.svg';

// 4. Tipos
import type { UserProfile } from '@/types/user';

// 5. Estilos
import './ProfileCard.scss';

3. 🚀 Estrategia de Versionado (SemVer)

Para desplegar en npm, es obligatorio seguir el sistema de versiones $X.Y.Z$ . Cada número tiene un propósito específico dependiendo del impacto del cambio:

Plaintext

v MAJOR . MINOR . PATCH
  ^       ^       ^
  1   .   2   .   3

🛠️ ¿Cuándo aumentar cada número?

MAJOR (1.x.x) — Cambios Mayores * Cuándo: Cuando hay cambios que rompen la compatibilidad (Breaking Changes).
- Ejemplos: Cambiar configuraciones base, modificar la API de componentes existentes, o actualizar versiones de React/Tailwind que obliguen a refactorizar el código.
MINOR (x.2.x) — Nuevas Funcionalidades * Cuándo: Despliegue de nuevos componentes o funcionalidades adicionales por sprint.
- Regla: Siempre que no rompan nada de lo que ya existe (retrocompatible).
PATCH (x.x.3) — Correcciones (Fixes) * Cuándo: Ajustes menores, bug fixes o mejoras visuales en componentes que ya funcionan.
- Regla: No cambia la forma en que se usan los componentes, solo mejora su funcionamiento interno.

⚠️ Nota sobre Despliegue y Ciclo de Vida

No es obligatorio incrementar la versión de la librería para actualizaciones exclusivas de GitHub Pages (documentación o Storybook). El versionado semántico se reservará estrictamente para el registro en npm.

[!IMPORTANT] Consenso de Versionado: Antes de realizar un release en la librería, se debe validar en equipo la versión resultante. El objetivo es evitar el versionado arbitrario y prevenir conflictos de dependencias en los proyectos que consumen el Design System.

URL GIT-PAGES

https://somosnudos.github.io/bord-design-system/?path=/story/bordactionbutton--active