Cómo contribuir

El design system es la fuente única para la marca Seim Seim. Cualquier proyecto (dashboard, event app, site, reservas) importa el theme.css y los componentes shadcn instalados localmente heredan automáticamente colores, tipografía, espaciado y radios de la marca.

Antes de agregar algo nuevo, busca en el sidebar — probablemente ya existe. Si necesitas algo que no está, esta guía explica cómo sumarlo.

Arquitectura

• Brand tokens viven en design-system/public/theme.css — un solo archivo publicado en design.seimseim.com/theme.css.
• Componentes UI se instalan vía npx shadcn add <nombre> en cada proyecto consumer. No mantenemos una librería propia.
• El sitio de docs (este sitio) muestra fundamentos, lista los componentes shadcn aprobados y cómo se ven con la marca aplicada.

Sumar un componente shadcn al registro

1. Instálalo en tu proyecto — desde la raíz del consumer (ej. seimseim-reservas/frontend/):

   npx shadcn add <nombre>

2. Verifica visualmente que respeta marca cuando el theme.css está importado. Si algo no se ve Seim Seim (radios fuera de escala, color que no aparece en la paleta, fuente equivocada), abre un issue en monoku/seimseim antes de seguir — probablemente falte un mapeo en theme.css.

3. Crea la página de documentación en design-system/src/pages/componentes/shadcn/<nombre>.astro. Sigue el patrón de los componentes existentes (alert, badge, button como referencia):

   • import DocPage from '../../../layouts/DocPage.astro';
   • Si usa íconos Phosphor: import "@phosphor-icons/web/regular"; y/o "/fill";
   • const headings = [...] con cada <h2> listado para que el TOC del lado derecho funcione
   • Cada <h2> con id={slug} que matchee la entrada en headings
   • Una sección por categoría (Variantes, Tamaños, Estados, Familias de marca…) — solo las que aplican al componente
   • Cada preview va dentro de un stage: <div class="not-prose my-4 border border-ss-tinta-200 rounded-md p-8 bg-ss-tinta-100 font-ostia flex items-center justify-center min-h-[140px]">…</div>
   • Footer con estado theme + link a ui.shadcn.com/docs/components/<nombre> con target="_blank" rel="noopener noreferrer"

4. Regístralo en el sidebar — agrega una línea en design-system/src/lib/sidebar-data.ts dentro del grupo de componentes shadcn, alfabéticamente.

5. Actualiza el changelog con una línea bajo la fecha actual.

6. Abre un PR en monoku/seimseim.

Modificar tokens de marca

Los tokens viven en design-system/public/theme.css. Editar ahí impacta a todos los consumers en el siguiente deploy.

1. Cambio de valor (ej. tinta-200 más oscuro): edita la variable directo. Verifica visualmente las páginas de fundamentos.
2. Mapeo shadcn (ej. cambiar --destructive a otro tono de aji): edita en las dos secciones, :root {} (light) y .dark {} (dark).
3. Token nuevo (ej. una familia adicional): agrégalo en el @theme {} block siguiendo la estructura de las 10 familias existentes. Después documéntalo en el fundamento correspondiente.

Convenciones que aplican siempre

Tokens, no hex

Iconografía

Detalle completo en Iconografía.

Tipografía en previews

Los stages de preview usan font-ostia para que el texto interno se vea con la fuente de marca, igual que en producción cuando el consumer carga Ostia Antica.

Checklist antes de pedir review

• La página <nombre>.astro tiene headings, <h2 id="slug">, frontmatter completo.
• Cada preview vive en un stage bg-ss-tinta-100 font-ostia con padding consistente.
• Los componentes adentro usan clases shadcn estándar (bg-primary, text-foreground…) o tokens de marca (bg-ss-{family}-{tone}). Cero hex.
• Si hay íconos, son Phosphor con peso correcto (regular/fill) y color heredado o explícito vía token.
• El sidebar incluye la nueva entrada en orden alfabético.
• El changelog tiene la línea correspondiente.
• npm run build pasa limpio en design-system/.
• Los links a docs oficiales tienen target="_blank" rel="noopener noreferrer".