Saltar al contenido

Contribuir

Beta

Cómo se suma o se cambia un componente en Polen, de Figma al código y a esta documentación.

Un componente está listo cuando existe en los tres lugares con el mismo nombre y las mismas propiedades: Figma, código y docs. Este es el camino.

1. Empezá por la necesidad

Antes de diseñar, revisá Estado de componentes y los Patrones: a menudo lo que falta es una variante o una composición, no un componente nuevo. Si hace falta uno, escribí en una línea qué problema resuelve y qué no es (Chip no es Button).

2. Figma

En 🌻 FDS Components, en la página del componente:

  • Solo roles de Semantic para color; variables de Spacing, Radius y Size para medidas; text styles para todo el texto. Cero valores sueltos.
  • Propiedades con los nombres del sistema: Style, Color, Size, Radius, State (Default · Hover · Focus · Pressed · Disabled), Show …, Icon … (+ swap).
  • Los iconos semánticos (éxito, error) van fijos por variante, no como swap.
  • Auto-layout en todo; nada absoluto salvo focus rings y acentos.
  • Descripción del componente y link a su página de esta documentación.
  • Nada de sets "OLD" ni páginas __: lo viejo se archiva.

3. Código

En registry/ds/<nombre>.tsx:

  • Un archivo por componente, con un JSDoc arriba que resume medidas y tokens (es lo que lee el registry para la descripción).
  • Comportamiento accesible sobre Base UI cuando existe la pieza (Dialog, Menu, Select…); estilo 100 % con utilidades de roles semánticos (bg-primary-subtle, text-fg-muted). Nunca colores ni píxeles sueltos.
  • Props con los mismos nombres que Figma: variant, size, radius, disabled… El error es error (mensaje), no un booleano.
  • Clases por variante escritas completas (no interpoladas), para que Tailwind las detecte.
  • Ejemplos en registry/examples/<nombre>/*.tsx: cada archivo es un ejemplo que se renderiza y se muestra como código. basic.tsx es el hero.
  • Playground en registry/playgrounds/<nombre>.tsx (todos los componentes tienen uno): define({ controls, render, snippet }). Controles solo para props que cambian algo visible. tests/playgrounds.test.tsx lo monta, le pasa axe y renderiza cada opción de cada control.
  • Templates: una página entera en registry/examples/templates/<nombre>.tsx (autocontenida, con sus datos de ejemplo), su doc en content/docs/templates/<nombre>.mdx con <Template name="<nombre>" /> y el título en src/lib/templates.ts. Se publica sola en /templates/<nombre> y como template-<nombre> en el registry.
  • npm run registry regenera los índices y el registry instalable. Las URLs de instalación salen de src/lib/site-url.ts: en Vercel toma solo el dominio de producción; NEXT_PUBLIC_SITE_URL lo sobreescribe si hace falta.
  • Si un componente usa una utilidad nueva de Tailwind que sale de un token (text-*, shadow-*, ease-*, rounded-*…), el mapeo va en src/styles/polen.css, no en globals.css: ese archivo se instala con los tokens y es lo que hace que el componente se vea igual fuera del sitio.

4. Documentación

content/docs/components/<nombre>.mdx con la plantilla:

---
title: Nombre
description: Una línea que diga qué hace.
status: beta
figma: https://www.figma.com/design/…?node-id=…
source: registry/ds/nombre.tsx
---

<Example name="nombre/basic" />

<DocTabs labels={["Uso", "Specs", "Código", "Accesibilidad"]}>
<DocTab>  ## Cuándo usarlo · Anatomy · DoDont · Contenido  </DocTab>
<DocTab>  ## Medidas · TokenUsage · FigmaProps  </DocTab>
<DocTab>  ## Instalación (Install) · Playground · Props (PropsTable)  </DocTab>
<DocTab>  ## Teclado (KeyboardTable) · Qué viene resuelto · Qué cuidar  </DocTab>
</DocTabs>

Agregalo a content/docs/components/meta.json en su sección y actualizá registry/status.ts.

5. Verificación antes de mergear

  • npm run build, npm run lint y npm test limpios.
  • Los tests corren con Vitest + Testing Library. Cada ejemplo del registry pasa por axe automáticamente (tests/a11y.test.tsx): si tu componente nuevo tiene un aria-label sobre un <div> sin rol o dos <nav> con el mismo nombre, falla ahí. Sumá tests de comportamiento en tests/<familia>.test.tsx (teclado, estados, ARIA) para lo que Base UI no cubra solo.
  • Probado en navegador: estados, teclado, dark mode, sin errores de consola.
  • Los colores computados coinciden con los tokens de Figma.
  • Cada par texto/fondo pasa 3:1 (criterio FDS); los que pasan 4.5:1, mejor.
  • Branch feat/<nombre> → preview → merge a main.

Cambios a lo que ya existe

Un cambio de token se hace en Figma primero y se re-exporta (scripts/import-tokens.ts); un cambio de comportamiento, en el componente y su página a la vez. Anotalo en el Changelog.