Skip to content

QUICK_START.md

Latest commit

 

History

History
146 lines (99 loc) · 4.83 KB

QUICK_START.md

File metadata and controls

146 lines (99 loc) · 4.83 KB

Guía de Inicio Rápido

De cero a tu primera contribución en menos de 10 minutos.

🇬🇧 English version

Requisitos previos

Herramienta Versión Instalación
Node.js ver .nvmrc nodejs.org
pnpm última npm i -g pnpm
nvm cualquiera UNIX / Windows
git cualquiera git-scm.com

1. Clonar e instalar

git clone https://github.com/Stack-and-Flow/design-system.git
cd design-system
nvm use
pnpm install

2. Iniciar Storybook

pnpm run storybook

Storybook se abre en http://localhost:6006. Este es tu entorno de desarrollo — cada componente vive aquí.

3. Encontrar algo en qué trabajar

Ve al tablero del proyecto en GitHub y elige un issue abierto de la columna Todo.

¿Primera vez? Busca issues etiquetados como layer: atom con category: component — son autocontenidos y bien definidos.

Antes de escribir código, asegurate de que la spec esté definida y la issue tenga el label status:approved. Recién entonces corré START WORK:

  • asignate la issue;
  • movela a In progress;
  • registrá branch y worktree plan.

4. Crear tu rama

Si la tarea viene de una issue, usá naming derivado de issue:

git checkout -b feat/123-tu-componente
# o
git checkout -b fix/128-descripcion-corta

Si trabajás con worktree, usa el sibling path equivalente:

../design-system-feat-123-tu-componente

El nombre de las ramas sigue Conventional Commits:

  • feat/ — nuevo componente o funcionalidad
  • fix/ — corrección de bug
  • a11y/ — mejora de accesibilidad
  • tokens/ — cambio de token de diseño
  • docs/ — solo documentación

5. Construir tu componente

Cada componente sigue el patrón de 6 archivos. Usá CONTRIBUTOR-FLOW.md como flujo canónico y crealo manualmente en la capa atómica correcta:

src/components/atoms/tu-componente/
├── types.ts                  # Tipos + JSDoc controls + variantes CVA
├── useTuComponente.ts        # Capa Container — lógica, estado, handlers
├── TuComponente.tsx          # Capa Presentacional — solo JSX
├── TuComponente.test.tsx     # Tests de hook y comportamiento
├── TuComponente.stories.tsx  # Documentación de Storybook
└── index.ts                  # Exportaciones públicas

Lee CONTRIBUTOR-FLOW.md para el flujo completo y GUIDELINES.md para las reglas de arquitectura antes de escribir código.

6. Ejecutar tests

pnpm test

Todos los tests deben pasar antes de abrir un PR. Si estás añadiendo un nuevo componente, añade también sus tests.

7. Abrir un Pull Request

Sube tu rama y abre un PR contra main:

git push origin feat/123-tu-componente

Luego ve a GitHub → tu rama → Compare & pull request.

  • Usa la plantilla de PR — completa cada sección
  • Vincula el issue en el resumen (Closes #123)
  • Añade capturas de pantalla si hay cambios visuales
  • Limpia artefactos MCP antes de commit/review: rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

El project lead revisa y fusiona. La tarea pasa a Done solo con END WORK después de PR merged o aprobación explícita.

Formato de mensajes de commit

Usamos Conventional Commits. Los hooks de git rechazarán commits que no sigan este formato.

feat(button): add loading state variant
fix(switch): forward aria-label prop correctly
docs(modal): add usage examples to Storybook
fix(a11y): improve input focus ring visibility
chore(tokens): update spacing token docs

Formato: <type>(<scope opcional>): <descripción> (scope es opcional)

Tipos comunes: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.

Usa a11y, tokens o infra como scopes, no como tipos personalizados.

Uso de agentes IA (opcional)

Este proyecto soporta opencode con contexto preconfigurado. Si lo usas:

opencode

El agente carga automáticamente las reglas del proyecto desde .atl/AGENTS.md — no necesitas configuración manual. Lee CONTRIBUTING.md para el flujo completo de trabajo con IA.

¿Necesitas ayuda?