La idea

Un componente de angela es, casi siempre, un archivo CSS y un trozo de marcado. No hay clases de JavaScript ni envoltorios: el HTML nativo hace el trabajo y el CSS lo viste. Por eso aportar uno es sencillo, y por eso hay unas pocas reglas que no se negocian.

Lo escribes en el laboratorio, lo pruebas ahí mismo y, cuando pase la revisión, abres un pull request en el repositorio. Queda a tu nombre y se mezcla cuando esté revisado.

Las reglas

  1. La plataforma primero. Antes de escribir JavaScript, comprueba si HTML y CSS ya lo resuelven:<dialog>, popover, command/commandfor,<details name>, :user-invalid, focusgroup.
  2. Todo el CSS en capas. Dentro de @layer angela.components, para que el CSS de quien use la librería siempre gane sin pelear con la especificidad.
  3. Valores por defecto en :where(). Así los data-* y el CSS de quien lo use pueden sobrescribirlos.
  4. Solo tokens. Nada de #hex ni de 24px sueltos: var(--color-…),var(--space-…), var(--radius-…), var(--fs-…).
  5. Variantes con atributos, no con clases .bloque--modificador.
  6. Propiedades lógicas (inline-size, padding-inline-start), para que funcione también en árabe o hebreo.
  7. Accesibilidad AA como mínimo: :focus-visible, forced-colors,prefers-reduced-motion, y el estado nunca solo con color.
  8. El JavaScript es opcional y mínimo. Un módulo por función, sin dependencias, que devuelva su limpieza y aguante el renderizado en servidor.

La guía de diseño tiene el detalle de colores, tipografía, espacio y movimiento.

Cómo se le pasan parámetros a un componente

En HTML nativo no hay props. Lo que hay son cuatro mecanismos, y cada uno sirve para una cosa distinta.

Mecanismos para parametrizar un componente
Qué quieres pasarCon quéCuándo
Contenidodata-slotMarca el elemento que recibe lo que va dentro. Al insertar el componente en el laboratorio, el cursor queda ahí.
Variantesdata-variant · data-tone · data-sizeUn número cerrado de opciones. Nunca clases tipo .boton--rojo.
Medidas y ajustes--mi-componente-algoLo que quien lo use pueda querer cambiar: anchos, separaciones, duraciones.
EstadoAtributos y pseudoclases nativas:hover, :focus-visible, [aria-pressed], [disabled], :user-invalid…

Contenido: data-slot

Cuando tu componente envuelve a otros (una rejilla que recibe tarjetas, un panel con acciones), marca condata-slot el elemento que los contiene:

<section class="cards" data-slot>
  <article class="card">Inserta aquí tus tarjetas.</article>
</section>

Lo que escribas dentro es tu ejemplo: se ve en la vista previa mientras lo editas. Al insertar el componente en otro, ese ejemplo se descarta y el cursor queda en el hueco, listo para escribir o para insertar otro componente. Si tenías algo seleccionado, se envuelve con él.

Un solo hueco por componente

Se usa el primer data-slot que aparezca. Si tu componente necesita dos zonas distintas (cabecera y cuerpo, por ejemplo), pártelo en dos componentes, como hacen .card y .card-header.

Medidas: propiedades personalizadas

Lo que quien use el componente pueda querer cambiar se declara como una variable con su valor por defecto. El nombre lleva por delante el del componente, para que no choque con nada:

@layer angela.components {
  .cards {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--cards-min, 16rem)), 1fr));
    gap: var(--cards-gap, var(--space-6));
  }
}

Y quien lo usa solo cambia lo que necesita, sin tocar tu CSS:

<section class="cards" style="--cards-min: 14rem">

El min(100%, …) no es un adorno: sin él, una tarjeta de 16rem desborda la pantalla por debajo de 320 px.

Componentes que se complementan

A veces hacen falta dos: un contenedor y lo que va dentro. La regla es que cada uno funcione solo, y que se entiendan por una variable, no por conocerse las clases.

En el efecto 3D, por ejemplo, la perspectiva tiene que estar en el padre y la rotación en el hijo. El contenedor pone la perspectiva y avisa de que ya lo ha hecho:

/* contenedor */
.cards {
  perspective: var(--cards-perspective, 900px);
  --card-3d-perspective: none;   /* contrato: la pongo yo */
}

/* tarjeta: sola usa la suya, dentro del contenedor hereda none */
.card-3d {
  --_fuga: perspective(var(--card-3d-perspective, 900px));
  transform: var(--_fuga);
}

La tarjeta nunca nombra a .cards, así que puedes usarla suelta. Y el contenedor acepta cualquier hijo.

Escribir los dos a la vez

En la librería cada componente es su propio archivo, pero para escribirlos necesitas verlos juntos. En el laboratorio van en el mismo CSS, separados por un marcador:

/* @componente cards */
@layer angela.components {
  .cards { … }
}

/* @componente card-3d */
@layer angela.components {
  .card-3d { … }
}

Los pruebas juntos en la vista previa y, al proponerlos, el pull request creacards.css y card-3d.css por separado, con sus dos @import. El marcado de ejemplo viaja en la descripción del pull request, de modo que quien revisa ve cómo se usan juntos. Lo que escribas antes del primer marcador (tokens compartidos, un comentario de cabecera) va con la primera pieza.

Pasos para aportarlo

  1. Créalo en el laboratorio

    Escribe el HTML, el CSS y, solo si hace falta, el JavaScript. Pruébalo en claro y oscuro, y con el fondo de la vista previa.

  2. Pasa la revisión

    El panel de Revisión comprueba las reglas que se pueden verificar con código. Corrige los avisos rojos y repasa los naranjas. Si tienes la IA configurada en Ajustes, «Revisar con IA» repasa también lo que el código solo no ve: te enseña qué había y qué propone, y tú aceptas o rechazas.

  3. Haz las comprobaciones manuales

    Teclado, lector de pantalla, zoom al 200 % y 320 px de ancho. Esto no lo puede revisar ningún programa por ti.

  4. Ponle nombre y cuenta qué aporta

    En el diálogo de «Proponer al proyecto». Añade también las notas de accesibilidad: es lo único que no se puede leer del código.

  5. Abre el pull request

    Con «Proponer al proyecto». Sube el CSS, su @import y la página de documentación, y abre el pull request a tu nombre con tu token de GitHub.

Lo que ningún programa revisa por ti

  • Recórrelo entero con el teclado: todo se alcanza con Tab y se ve dónde está el foco.
  • Pruébalo con un lector de pantalla (VoiceOver con Cmd+F5): cada control dice qué es y qué hace.
  • Míralo en claro y en oscuro, y con el zoom al 200 %.
  • Compruébalo a 320 px de ancho: sin scroll horizontal.
  • El estado nunca se entiende solo por el color: hay texto, ícono o forma.

Qué debe llevar el pull request

  • packages/angela/src/components/<nombre>.css — tu componente, con un comentario arriba que explique el marcado y los atributos.
  • Una línea @import en packages/angela/src/angela.css, en el orden en el que aparecen los demás.
  • docs/src/data/componentes/<nombre>.js — su página de documentación. La escribe el laboratorio al proponer el componente, con el ejemplo y la tabla de API sacada del propio CSS; tú repasas el texto y añades los ejemplos que falten. El catálogo la carga sola, así que al mezclar el pull request ya está en la web.
  • Si lleva JavaScript: un módulo en packages/angela/src/js/ que exporte su función de activación (enhance…(root)), registrado en src/js/index.js y con su test. El laboratorio lo registra solo; el test lo añades tú.
  • Si encaja, su envoltorio en packages/angela-react.

Rama feat/…, commits en español siguiendo Conventional Commits, y antes de subir:pnpm test y pnpm check:contrast.

La revisión automática

Cada pull request pasa tests, tipos, contraste y build, y se revisa cada componente que crea o edita con las mismas reglas del laboratorio y las de esta página. En una edición solo cuenta lo que cambia: lo que ya estaba no te bloquea. El resultado llega como un comentario en el pull request.

Si algo incumple las reglas, el check falla y el comentario dice qué corregir. Si todo cumple, queda la revisión visual: quien mantiene el proyecto abre la preview, la compara con producción y mezcla. La revisión automática no aprueba ni despliega nada.

Abrir un pull request