Sistema de Diseño Stack-and-Flow

Qué es este proyecto

Stack-and-Flow es un design system educativo, accesible y publicable como paquete npm, construido con React, TypeScript, Tailwind CSS v4, Radix UI primitives, CVA, Storybook y Vite.

El objetivo es aprender y practicar cómo se construye una librería de componentes real: tokens, arquitectura, documentación viva, tests, accesibilidad, revisión visual y flujo de contribución con GitHub Projects.

Stack

Inicio rápido

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

Storybook queda disponible en http://localhost:6006.

Demo pública: sf-design-system.netlify.app

Arquitectura de componentes

Cada componente vive en src/components/{atoms|molecules|organisms}/{kebab-name}/ y usa el patrón obligatorio de 6 archivos:

src/components/atoms/button/
├── types.ts              # Props, tipos públicos y variantes CVA
├── useButton.ts          # Lógica, estado, handlers, aria y className computado
├── Button.tsx            # JSX presentacional; consume el hook
├── Button.test.tsx       # Tests de hook y comportamiento del componente
├── Button.stories.tsx    # Storybook autodocs, args, variants y estados
└── index.ts              # Named export del componente + type exports

Reglas base:

• type, nunca interface.
• Sin any explícito.
• CVA vive en types.ts.
• El componente .tsx no contiene lógica ni llamadas CVA.
• Exports/imports públicos son nombrados, por ejemplo import { Button } from '@stack-and-flow/design-system'.
• Storybook usa JSDoc encima de const meta y encima de cada export const StoryName.
• No usamos parameters.docs.description.component.

Contribuir

Este proyecto usa GitHub Issues + GitHub Projects como flujo de trabajo.

Ruta corta:

1. Elegí una issue del Project Board.
2. Antes de implementar, verificá que la spec esté definida y que la issue tenga el label status:approved.
3. Recién después ejecutá START WORK:
   • asignar la issue al contributor;
   • mover el Project item a In progress;
   • registrar branch y worktree.
4. Usá branch issue-based:
   • feat/{issue-number}-{slug}
   • fix/{issue-number}-{slug}
   • docs/{issue-number}-{slug}
5. Si necesitás worktree, crealo como sibling del repo:
   • ../design-system-{type}-{issue-number}-{slug}
   • no en /tmp, salvo pedido explícito.
6. Implementá con el patrón de 6 archivos.
7. Corré tests/build/revisión visual según corresponda.
8. Antes de commit/review, limpiá artefactos MCP:

rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

9. Al cerrar, usá END WORK sólo si hay PR merged o aprobación explícita del maintainer/usuario, con evidencia de validación.

Documentación recomendada:

• Quick Start
• Contributor Flow
• Contributing
• Guidelines
• Design Reference
• Components Reference

Reglas de oro

• Sólo usamos Radix UI primitives como base sin estilos.
• No usamos shadcn como fuente de componentes ni configuración.
• Usá tokens desde src/styles/theme.css; no hardcodees colores, fuentes o spacing.
• Si falta un token, proponé agregarlo centralmente antes de usar valores raw.
• Accesibilidad obligatoria: nombre accesible, teclado, focus visible, contraste, reduced motion.
• Código, comentarios, Storybook y nombres públicos en inglés.

Scripts útiles

pnpm run storybook       # Storybook local
pnpm run test            # Vitest
pnpm run test:coverage   # Cobertura
pnpm run build           # Build de librería + tipos

Playwright MCP y auditoría visual AI

Playwright MCP es infraestructura opcional para agentes AI. Puede generar artefactos como .playwright-mcp/, page-*.png, page-*.jpeg o *.md.playwright-output.

Estos archivos no se commitean. Antes de commit o review:

rm -rf .playwright-mcp page-*.png page-*.jpeg *.md.playwright-output

Recursos

• Storybook live: sf-design-system.netlify.app
• Project Board: GitHub Projects
• Wiki Deepwiki: deepwiki.com/Stack-and-Flow/design-system

Proyecto educativo

Este repositorio está abierto a colaboración. Es ideal si querés aprender design systems, React, TypeScript, arquitectura de componentes, accesibilidad, Storybook y publicación de librerías.

Contacto

---

⭐ Si este proyecto te resulta útil, considera darle una estrella en GitHub ⭐