@codenhub/styles 0.6.0 → 0.8.0

package/docs/es/accessibility.md

@@ -0,0 +1,169 @@
+---
+title: Accesibilidad
+description: Lo que hace el CSS con el foco, los estados, el movimiento, el contraste, los colores forzados y el texto de derecha a izquierda, y lo que tu aplicación todavía les debe a sus usuarios.
+order: 5
+source: 88ce6c4707ee04ac76cdb5e6b31dcca399a5327e
+---
+
+# Accesibilidad
+
+La pantalla de ajustes está construida, y el CSS ha hecho su parte por el camino: cada campo muestra dónde está el foco, un email inválido se vuelve rojo y el spinner se detiene para los usuarios que piden menos movimiento. El resto depende de tu HTML y tu JavaScript. Este paquete da estilo a los estados; no aporta elementos semánticos, atributos ARIA, comportamiento de teclado, gestión del foco, validación ni el momento de los anuncios.
+
+Esta página enumera las dos mitades: lo que aporta el CSS y lo que tu aplicación tiene que añadir.
+
+## Lo que aporta el CSS
+
+### Foco y estado
+
+| Característica                  | Comportamiento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`                | Un contorno de foco en cada elemento, dibujado con `--focus-ring`, `--focus-ring-width` y `--focus-ring-offset`. En un componente con un relleno de más de la mitad de intensidad, como un botón `.solid.primary`, una línea de 2px del color de la página recorre el interior del anillo, así que el anillo sigue visible sobre un relleno de su mismo color.                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Foco en controles de formulario | `.ipt`, `.textarea` y `.select` dibujan el contorno de foco y cambian su borde al color de la intención. El texto escrito en un campo con una clase de intención usa el tono legible de esa intención, `--intent-strong`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Controles inválidos             | `aria-invalid="true"` en un control de formulario vuelve destructivos su borde, su color de foco y el texto escrito, este último en el tono legible destructivo. Un checkbox, un radio o un switch se dibuja exactamente igual que su versión `.destructive`, marca de activado incluida.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Controles deshabilitados        | `disabled`, `aria-disabled="true"`, `data-disabled` y `.disabled` muestran el cursor y la opacidad de deshabilitado, y un control deshabilitado no reacciona al hover, tampoco dentro de un `.input-group`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Estado abierto                  | `data-state="open"` en un `.tooltip` muestra su burbuja sin hover ni foco, y `data-state="closed"` la oculta aunque tenga hover o foco. Ningún otro componente lee ninguno de los dos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `<dialog>` nativo               | Un `<dialog>` con `.card`, `.panel`, `.surface` o una clase propia que hace `@apply surface` permanece oculto hasta que se abre, y se abre centrado. Un margen que pongas en el diálogo, como utilidad o en tu propio CSS, sigue sobrescribiendo el centrado, salvo que una utilidad de margen no lo hace cuando tu clase aplica `surface` en CSS plano; consulta [Personalización → Helpers de composición](./usage/customizing.md#helpers-de-composición). Con la [hoja de estilos sin clases](./setup.md#html-sin-clases), un `<dialog>` simple es una `.card.floating` y se comporta igual; con los demás puntos de entrada, un diálogo sin ninguna de estas clases no se toca. Atrapar el foco, cerrar con Escape y dejar inerte la página de detrás es cosa de tu aplicación. |
+
+### Contenido visualmente oculto
+
+`.visually-hidden` oculta contenido en pantalla y lo mantiene para los lectores de pantalla, como hace el `<caption>` de la tabla de claves de API en [Contenido y layout → Tablas](./usage/content-and-layout.md#tablas). Viene con las utilidades de layout: en `.`, `./native`, `./tw`, `./tw/native` y `./tw/utilities`. No está en `./components` ni en los puntos de entrada de componentes `./tw/components` y `./tw/*`.
+
+### Límites de los controles
+
+WCAG 1.4.11 pide que el límite de un control que necesitas ver para usarlo tenga un contraste de al menos 3:1 con lo que lo rodea.
+
+| Característica                  | Comportamiento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto en reposo    | El borde de un control de texto reposa más claro que el borde completo de su intención, por debajo de 3:1 a propósito, para que el hover y el foco tengan un tono más intenso al que cambiar. [Contraste aumentado](#contraste-aumentado) lo dibuja completo.                                                                                                                                                                                                                                           |
+| Toggles                         | `.checkbox`, `.radio` y `.switch` dibujan su borde completo, porque el borde es lo único que muestra una casilla sin marcar. Un `.switch` con su propio `.edgeless` es la excepción, más abajo.                                                                                                                                                                                                                                                                                                         |
+| `.edgeless` desde un contenedor | Lo ignoran todos los controles de texto y toggles: un contenedor no puede quitar el borde de un campo o toggle que contiene.                                                                                                                                                                                                                                                                                                                                                                            |
+| `.edgeless` en el control       | `.ipt`, `.textarea`, `.select` y `.switch` pierden su borde y dejan de cumplir 1.4.11 en reposo. `.switch.ghost` conserva su borde incluso entonces, porque sin relleno y sin borde nada mostraría el carril.                                                                                                                                                                                                                                                                                           |
+| `.checkbox`, `.radio`           | Siempre dibujan su borde, venga `.edgeless` de un contenedor o lo lleven ellos mismos. `.edgeless` en ellos no está soportado.                                                                                                                                                                                                                                                                                                                                                                          |
+| Carril de progreso              | A propósito, la parte rellena lleva el valor y el carril es un fondo discreto. El carril por defecto, `.soft.edgeless`, mide aproximadamente de 1.1:1 a 1.3:1 frente a la página. La parte rellena mide al menos 3:1 frente a ese carril para todas las intenciones excepto warning en claro (unos 2.7:1) e info en oscuro (unos 2.9:1). Donde el propio carril deba cumplir 1.4.11, usa `.ghost.edged` con una clase de intención; consulta [Contornos de progreso](#contornos-de-progreso) más abajo. |
+
+### Contornos de progreso
+
+En un `.progress.ghost.edged`, el carril es la página, y tanto su contorno como la parte rellena se dibujan en el color de la intención. Medido frente a la página, sin estética:
+
+| Intención      | Página clara | Página oscura | Cumple 3:1                                                                    |
+| -------------- | ------------ | ------------- | ----------------------------------------------------------------------------- |
+| `.primary`     | 18.96:1      | 18.96:1       | Sí                                                                            |
+| `.secondary`   | 7.47:1       | 7.63:1        | Sí                                                                            |
+| `.success`     | 5.14:1       | 3.69:1        | Sí                                                                            |
+| `.warning`     | 3.06:1       | 6.20:1        | Sí                                                                            |
+| `.destructive` | 5.80:1       | 3.27:1        | Sí                                                                            |
+| `.info`        | 6.17:1       | 3.07:1        | Sí                                                                            |
+| Sin intención  | 2.48:1       | 1.91:1        | No: el contorno no cumple, aunque la parte rellena, en el color del texto, sí |
+
+Sin clase de intención, el contorno es el gris discreto de los bordes, `--color-border`. Para que un carril neutro cumpla 1.4.11, dale a la barra una clase de intención, o define `--progress-edge` con un color más intenso, como `var(--color-accent)`, que mide 7.47:1 en una página clara y 7.63:1 en una oscura. Warning en una página clara e info en una oscura superan 3:1 por poco margen, así que vuelve a medir si cambias esos colores.
+
+### Movimiento y transparencia
+
+| Característica                      | Comportamiento                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Movimiento reducido, componentes    | Con `prefers-reduced-motion: reduce`, cada componente detiene sus propias transiciones y animaciones: el brillo del skeleton y del progreso, la barra indeterminada, el tooltip, las marcas de los toggles y el movimiento de la pulsación. La pulsación en sí sigue ocurriendo, al instante, con el aspecto por defecto y con cada estética y clase solo, porque es la señal de que un clic se registró. |
+| Movimiento reducido, toda la página | El reset también acorta todas las demás animaciones y transiciones de la página.                                                                                                                                                                                                                                                                                                                          |
+| Transparencia reducida              | Con `prefers-reduced-transparency: reduce`, y con colores forzados, `.glass`, `.glass-liquid` y `.glass-solo` pierden su desenfoque y su lente y se vuelven opacos.                                                                                                                                                                                                                                       |
+
+La regla de movimiento reducido de cada componente viene con el componente, así que cada punto de entrada que lo incluye respeta el movimiento reducido sin el reset, incluidos `@codenhub/styles/components`, `@codenhub/styles/tw/components` y cada punto de entrada de componente `/tw/*`. Los puntos de entrada completo y native añaden la regla del reset para toda la página.
+
+La regla del reset es `!important` dentro de la capa `base`, y un `!important` con capa gana a uno sin capa, así que tu propio `!important` no puede volver a activar una animación. Para mantener una en marcha para los usuarios que piden movimiento reducido, como un spinner de subida que consideres esencial, declárala `!important` en una capa ordenada antes de `base`. La primera sentencia `@layer` que lee el navegador fija el orden, así que la tuya va antes del paquete:
+
+```css
+@layer essential-motion, theme, base, components, utilities;
+@import "@codenhub/styles";
+
+@layer essential-motion {
+  @media (prefers-reduced-motion: reduce) {
+    .upload-spinner {
+      animation-duration: 1s !important;
+      animation-iteration-count: infinite !important;
+    }
+  }
+}
+```
+
+Respetar el movimiento reducido no es todo lo que se pide. El movimiento que sigue en marcha junto al contenido, como un brillo que queda en una tarjeta después de que ha cargado, necesita una forma de detenerlo para todos los usuarios; consulta [Feedback → Animación que no se detiene](./usage/feedback.md#animación-que-no-se-detiene).
+
+### Contraste aumentado
+
+Con `prefers-contrast: more`, los bordes que el paquete dibuja por debajo de 3:1 a propósito se dibujan a 3:1 o más frente a lo que tienen al lado, en ambos temas. El texto, los rellenos sólidos y los anillos de foco ya cumplen sus proporciones y no cambian. `prefers-contrast: less` no se lee.
+
+| Característica      | Comportamiento                                                                                                                                                                                                                                                                           |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto  | `.ipt`, `.textarea`, `.select` e `.input-group` reposan con su borde completo, así que el hover y el foco ya no cambian su tono. El anillo de foco es el mismo.                                                                                                                          |
+| Bordes neutros      | `--color-border` toma un gris más intenso, `neutral-600` en claro y `neutral-400` en oscuro, así que el borde de una tarjeta, un divisor, las líneas de una tabla y el borde de un botón o badge neutro cumplen 3:1. Si defines `--color-border` tú mismo, tu color se conserva; mídelo. |
+| Bordes de intención | El borde de una intención toma su tono fuerte, `--color-<intent>-strong`, así que `.edged` en un `.alert`, `.panel`, `.badge`, `.kbd`, `.code` o `.pre` `.soft` cumple 3:1 tanto frente a su relleno como frente a la página, en todas las intenciones.                                  |
+| Carril de progreso  | El carril dibuja un contorno en su color de borde, que cumple 3:1 con o sin clase de intención. `.edgeless` en la barra o en un contenedor lo sigue quitando.                                                                                                                            |
+| Glass               | `.glass`, `.glass-liquid` y `.glass-solo` pierden su desenfoque y su lente y se vuelven opacos, como con la transparencia reducida, y su línea blanca pasa a ser un borde gris.                                                                                                          |
+| Chunky tile         | `.chunky-tile` dibuja las piezas y las superficies con el gris más intenso que usan sus controles.                                                                                                                                                                                       |
+
+Lo que quitas sigue quitado: `.edgeless` en un control sigue eliminando su borde, y un `.panel` sigue sin tenerlo salvo que añadas `.edged`.
+
+### Color y contraste
+
+Las mediciones de abajo corresponden a los colores incluidos. En cuanto cambies un token de color, vuelve a medir tus propios pares; [Temas → Cambiar el color de marca](./usage/theming.md#cambiar-el-color-de-marca) muestra qué pares comprobar.
+
+| Característica                   | Comportamiento                                                                                                                                                                                                                                                                                                                           |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Etiquetas rellenas               | La etiqueta `.solid` de cada intención cumple 4.5:1 (WCAG 1.4.3) como texto normal, en ambos temas. La más baja es success, con 5.14:1.                                                                                                                                                                                                  |
+| Texto de warning                 | `--color-warning-contrast` es casi negro, no el color de la página, porque un ámbar lo bastante oscuro para llevar texto blanco ya no parece ámbar.                                                                                                                                                                                      |
+| Rellenos parciales               | El color de texto de contraste solo aparece en rellenos por encima de la mitad de intensidad, así que el relleno limitado de un control de texto conserva el color de texto propio de la intención.                                                                                                                                      |
+| Color de intención en oscuro     | En modo oscuro, una etiqueta `.soft` o `.ghost` usa el tono `-300` de su intención, así que conserva su matiz en lugar de volverse blanca.                                                                                                                                                                                               |
+| Texto sobre un padre con relleno | Un componente neutro que no es `.solid`, como un badge en un `.btn.primary` o un botón ghost en una `.card.solid.primary`, imprime en el color de texto de su padre en lugar del de la página, así que conserva el contraste del padre.                                                                                                  |
+| Impresión                        | Una página se imprime con el tema claro, y los componentes con relleno imprimen su fondo (`print-color-adjust: exact`), así que el texto de contraste nunca cae sobre papel en blanco. Una utilidad `dark:` se sigue aplicando al imprimir; consulta [Temas → Impresión](./usage/theming.md#impresión).                                  |
+| Marcas de los toggles            | Una marca activada mide al menos 3:1 frente a cada relleno que su presentación pueda darle, en ambos temas.                                                                                                                                                                                                                              |
+| Rellenos soft con borde          | `.edged` en un `.alert`, `.panel`, `.badge`, `.kbd`, `.code` o `.pre` `.soft` dibuja un borde que mide menos de 3:1 frente al relleno del 12% en algunas intenciones, cuáles depende del tema. Mide el par antes de confiar en ese borde como límite de un control. [Contraste aumentado](#contraste-aumentado) lleva todos ellos a 3:1. |
+
+### Colores forzados y dirección
+
+| Característica      | Comportamiento                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Colores forzados    | Con `forced-colors: active`, los bordes, los estados activados, el chevron de un `.select` y el valor de una barra de progreso siguen visibles, dibujados con colores del sistema, bajo cualquier estética. Una estética que dibuja su borde como una sombra interior, como `.pixel`, dibuja en su lugar un borde real. El cristal se vuelve opaco, porque los colores forzados conservan la transparencia de un fondo. |
+| Dirección del texto | Con `dir="rtl"`, la barra de las citas, el icono de la alerta, el relleno del progreso, el divisor vertical, la perilla del switch, la alineación de las tablas y el chevron de un select cambian de lado. No hace falta ninguna clase.                                                                                                                                                                                 |
+
+Con colores forzados, `.text-control`, `.ipt`, `.textarea`, `.select`, los toggles y tu propia clase que hace `@apply text-control` muestran un contorno de foco `Highlight` de 2px. Dentro de un `.input-group`, el grupo dibuja el anillo del campo y el control interior no dibuja ninguno, así que un campo con foco muestra un solo anillo. El punto de entrada native da el mismo contorno a los inputs de texto, selects, textareas, checkboxes y radios sin clase.
+
+Los checkboxes, radios y switches usan los colores del sistema `Canvas`, `CanvasText`, `Highlight` y `HighlightText`, así que activado y desactivado siguen siendo distinguibles: un toggle activado se rellena con `Highlight` y su marca es `HighlightText`, tanto en las clases como en el punto de entrada native. La forma, el tamaño y el espaciado no cambian.
+
+Una barra `.progress` hace lo mismo: su parte rellena es `CanvasText` sobre un carril `Canvas` con un contorno `CanvasText`, sea cual sea su intención o su presentación, así que una barra a medio llenar no se confunde con una vacía. El brillo de `.active` no se dibuja.
+
+## Lo que hace falta fuera del CSS
+
+Usa el elemento HTML que corresponde a lo que hace el componente, y añade el comportamiento que el CSS no puede dar.
+
+| Interfaz            | Lo que añade tu aplicación                                                                                                                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Botones             | `<button>` para acciones y `<a href>` para navegación. Un nombre accesible, como `aria-label`, en cada `.btn.icon`.                                                                                                                                              |
+| Formularios         | Un `<label>` para cada control, el `type` correcto, validación y `aria-describedby` enlazando pistas y errores. Mantén las pistas y los errores fuera del `<label>`, y dale a un `.switch` `role="switch"`.                                                      |
+| Alertas             | `role="status"` para una confirmación como "Perfil guardado", o `role="alert"` para un error que necesita atención inmediata.                                                                                                                                    |
+| Toasts              | Una región live, una forma de cerrarlo, reglas de foco y una pausa en cualquier temporizador.                                                                                                                                                                    |
+| Tooltips            | Un `id` real y `role="tooltip"` en la burbuja, referenciado desde el `aria-describedby` del disparador. El cierre con Escape escribiendo `data-state="closed"`; consulta [Tooltips](./usage/tooltips.md#hover-permanencia-y-escape). La burbuja ya admite hover. |
+| Progreso            | Un elemento `<progress>`, o `role="progressbar"` o `role="meter"` con valores ARIA, cuando el valor debe anunciarse.                                                                                                                                             |
+| Skeletons           | `aria-hidden="true"` en los elementos visuales de carga, incluido un spinner que aportes tú, y el estado de carga anunciado de otra forma cuando haga falta.                                                                                                     |
+| Movimiento continuo | Una forma de pausar, detener u ocultar el movimiento que no es esencial; consulta [Feedback → Animación que no se detiene](./usage/feedback.md#animación-que-no-se-detiene).                                                                                     |
+| Popovers, modales   | Atrapar el foco, cerrar con Escape, un fondo inerte, etiquetas y roles.                                                                                                                                                                                          |
+
+## Atributos de estado
+
+Prefiere los atributos nativos:
+
+```html
+<button class="btn primary" disabled>Saving…</button> <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+```
+
+Usa atributos ARIA o data donde el elemento o tu librería de componentes no tenga uno nativo:
+
+```html
+<a class="btn secondary" aria-disabled="true">Export data</a>
+<span class="tooltip" data-state="open">
+  <button type="button" class="tooltip-icon" aria-label="About public profiles" aria-describedby="public-profile-help">?</button>
+  <span class="tooltip-bubble" role="tooltip" id="public-profile-help">Anyone with the link can see your name and photo.</span>
+</span>
+```
+
+`aria-disabled="true"` indica a las tecnologías de asistencia que el control está deshabilitado, pero no impide un clic ni una pulsación de tecla. Usa el atributo `disabled`, o detén la acción en JavaScript.
+
+## Siguiente paso
+
+Con esto termina el orden de lectura. La [Introducción](./index.md) enlaza todas las páginas, y [Composición](./usage/composing.md), [Personalización](./usage/customizing.md) y [Contenido y layout](./usage/content-and-layout.md) son las páginas de consulta para más adelante.

package/docs/es/concepts.md

@@ -0,0 +1,212 @@
+---
+title: Construir una pantalla
+description: Maqueta la página de ajustes, define su tipografía y añade tarjetas y botones mientras aprendes qué son la intención, el relleno, el borde y la estética.
+order: 3
+source: 8fa5ed2f6fb9a2786f61301f94bbe806649d7e1d
+---
+
+# Construir una pantalla
+
+Esta página convierte la estructura vacía de [Configuración inicial](./setup.md) en la primera parte real de la pantalla de ajustes: un encabezado de página, una tarjeta de perfil con los botones Guardar y Cancelar, y un resumen del plan junto a una tarjeta de uso. Por el camino presenta las tres decisiones que toma cada componente, intención, presentación y estética, justo cuando la pantalla necesita cada una. Todo lo demás en esta documentación se apoya en este modelo.
+
+## La pantalla más pequeña
+
+Un encabezado de página y una tarjeta con un botón:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack">
+    <h1 class="text-title">Account settings</h1>
+    <section class="card stack">
+      <h2 class="text-title-sm">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <button class="btn primary" type="button">Save changes</button>
+    </section>
+  </div>
+</main>
+```
+
+Cada clase hace una sola cosa:
+
+- `.section` da espacio a la página: un margen lateral adaptable (de 1 a 2rem) y un espacio generoso arriba y abajo (de 4 a 7rem).
+- `.section-content` centra una columna con un ancho máximo; `.narrow` lo deja en 48rem en lugar de 80rem, un ancho cómodo para un formulario.
+- `.stack` coloca sus hijos en vertical con una separación de 1rem.
+- `.text-title` y `.text-title-sm` definen el tamaño de los encabezados: 1.875rem en negrita y 1.25rem en seminegrita.
+- `.card` es un contenedor con borde, esquinas redondeadas y 1.25rem de relleno interior.
+- `.btn` crea un botón, y `.primary` le da el color principal.
+
+Los encabezados no toman su tamaño de la etiqueta: el reset le da a un `<h1>` sin clase de tipografía el mismo tamaño y peso que el texto que lo rodea. Así la estructura del documento, qué nivel de encabezado es un elemento, queda separada del tamaño con el que quieres que se vea. Si quieres que los encabezados reciban estilo automáticamente, consulta [Configuración inicial → HTML sin clases](./setup.md#html-sin-clases).
+
+## Maquetar la página
+
+Tres helpers de layout cubren la mayoría de las pantallas, y los tres usan la misma separación, `--layout-gap` (1rem):
+
+- `.stack` para listas verticales de bloques.
+- `.cluster` para una fila que salta de línea cuando se queda sin espacio, como un grupo de botones. Añade `.between` para llevar el primer y el último elemento a extremos opuestos.
+- `.auto-grid` para una cuadrícula de tarjetas iguales que añade o quita columnas según cambia el espacio. Una columna nunca es más estrecha que `--layout-grid-min` (16rem), salvo que lo sea el propio contenedor.
+
+`.tight` (0.5rem) y `.loose` (1.5rem) cambian la separación del layout en el que están. Un layout anidado dentro conserva su propia separación.
+
+Añade un encabezado y pon los botones en una fila:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+  </div>
+</main>
+```
+
+[Contenido y layout](./usage/content-and-layout.md) enumera todos los helpers de layout, incluidos `.view`, `.divider` y `.visually-hidden`, y la escala tipográfica completa.
+
+## Intención: qué color
+
+El botón Guardar es `.primary` y el botón Cancelar no tiene intención, lo que lo hace neutro. Una clase de intención elige un rol de color:
+
+| Clase          | Úsala para                               | Color por defecto                           |
+| -------------- | ---------------------------------------- | ------------------------------------------- |
+| _ninguna_      | Cualquier cosa sin un significado propio | Los grises de texto y de borde de la página |
+| `.primary`     | La acción principal de una pantalla      | Casi negro en claro, casi blanco en oscuro  |
+| `.secondary`   | Una segunda acción, más discreta         | Gris medio                                  |
+| `.success`     | Confirmaciones y estados completados     | Verde esmeralda                             |
+| `.warning`     | Algo que pronto necesita atención        | Ámbar, con texto oscuro                     |
+| `.destructive` | Eliminar, revocar y errores              | Rojo rosado                                 |
+| `.info`        | Avisos neutros y ayuda                   | Índigo                                      |
+
+La intención se queda en el elemento que la lleva. Poner `.destructive` en una `<section>` no vuelve rojos todos los botones de dentro; la escribes en cada botón. Es deliberado: un contenedor que cambiara en silencio el color de todo lo que contiene también volvería rojo el botón Cancelar de una zona de peligro roja.
+
+`.neutral` nombra explícitamente el valor por defecto. Rara vez lo necesitas, porque no poner ninguna clase de intención ya significa neutro; importa donde el color vendría de otra parte, como en una fila de tabla, que hereda la intención de su tabla.
+
+## Presentación: cuánto color
+
+El botón Cancelar es `.ghost`: sin relleno, solo texto de color, así que se percibe como menos importante que Guardar. Ese es el eje de presentación, dos decisiones independientes:
+
+- **Relleno:** `.solid` rellena el componente con el color de su intención y cambia el texto al color de contraste. `.soft` mezcla un tinte claro del 12% y mantiene el texto en el color de la intención. `.ghost` no tiene relleno en reposo.
+- **Borde:** `.edged` dibuja un borde en el color de la intención; `.edgeless` no dibuja ninguno.
+
+```html
+<button class="btn primary">Save changes</button>
+<button class="btn primary soft">Preview</button>
+<button class="btn primary ghost edged">Export data</button>
+<button class="btn ghost">Cancel</button>
+```
+
+Cada componente tiene su propio valor por defecto cuando no se aplica ninguna clase de presentación. Un botón es sólido y sin borde. Una tarjeta no tiene relleno y tiene borde. Un campo de formulario no tiene relleno y tiene borde. [Composición](./usage/composing.md#valores-por-defecto-de-los-componentes) enumera el valor por defecto de cada componente.
+
+A diferencia de la intención, la presentación se hereda. Un `.soft` en un contenedor vuelve soft todo lo que hay dentro salvo que un elemento diga otra cosa, y una clase en el propio elemento siempre gana a una heredada de un contenedor:
+
+```html
+<div class="cluster soft">
+  <button class="btn primary">Soft primary</button>
+  <button class="btn success">Soft success</button>
+  <button class="btn primary solid">Solid: its own class wins</button>
+</div>
+```
+
+Algunos componentes limitan lo que puede hacer la presentación, para proteger algo que necesitan. Un campo de formulario que hereda un contenedor `.solid` se rellena solo hasta el 6%, para que el texto escrito siga siendo legible. Un checkbox siempre conserva su borde, porque el borde es lo único que muestra una casilla sin marcar. Estos límites aparecen con cada componente y están reunidos en [Composición](./usage/composing.md).
+
+## Terminar la primera pantalla
+
+Añade un resumen del plan junto a una tarjeta de uso en una cuadrícula, y dale al resumen un tinte primario soft para que destaque como el estado actual de la cuenta:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+
+    <div class="auto-grid">
+      <section class="card soft primary stack tight" aria-labelledby="plan-title">
+        <h2 class="text-label" id="plan-title">Current plan</h2>
+        <p class="text-title-sm">Team, billed yearly</p>
+        <p class="text-body">Renews on 12 March 2027.</p>
+      </section>
+      <section class="card stack tight" aria-labelledby="usage-title">
+        <h2 class="text-label" id="usage-title">Storage</h2>
+        <p class="text-title-sm">48 GB of 100 GB</p>
+        <p class="text-body">Shared by 6 members.</p>
+      </section>
+    </div>
+  </div>
+</main>
+```
+
+En una ventana ancha las dos tarjetas quedan una al lado de la otra; cuando la columna es demasiado estrecha para dos columnas de 16rem más la separación entre ellas, se apilan. La página de [Feedback](./usage/feedback.md) convierte el número de la tarjeta de almacenamiento en una barra de uso.
+
+Una `.card` reposa a una unidad de profundidad, pero en el aspecto base esa profundidad no tiene sombra visible; aparece cuando una estética la dibuja o cuando añades `.raised` o `.floating`. [Composición → Elevación](./usage/composing.md#elevación) explica la profundidad.
+
+## Estética: de qué está hecho
+
+El tercer eje cambia el material de todo lo que contiene: esquinas, grosor del borde, sombras y a veces la fuente. Necesita su propio import (consulta [Configuración inicial → Añadir una estética](./setup.md#añadir-una-estética-opcional)):
+
+```html
+<main class="section neobrutalism">
+  <!-- La misma pantalla de ajustes: esquinas rectas, líneas gruesas y oscuras, sombras duras desplazadas -->
+</main>
+```
+
+Como la presentación, una estética se hereda, y un componente dentro de ella puede llevar otra distinta. No la necesitas para construir la pantalla; [Estéticas](./usage/aesthetics.md) compara las seis.
+
+## Vocabulario de esta documentación
+
+Algunas páginas describen cómo se pinta un componente. Estas palabras tienen un único significado cada una:
+
+| Palabra   | Significado                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Relleno   | Cuánto del color de la intención cubre el componente, del 0% (`.ghost`) al 100% (`.solid`).                                                                                                 |
+| Tope      | El relleno máximo que permite un componente. Por ejemplo, un campo de formulario limita un relleno heredado al 6%.                                                                          |
+| Placa     | La superficie pintada del componente: el relleno, mezclado sobre el fondo.                                                                                                                  |
+| Fondo     | El color sobre el que se mezcla el relleno. Normalmente se ve la propia página a través; unos pocos componentes definen la suya, como el tinte claro de la intención bajo `.kbd` y `.code`. |
+| Borde     | El contorno del componente. Es distinto de las líneas divisorias, las líneas dentro de una tabla.                                                                                           |
+| Tinta     | Un color que se usa para dibujar líneas: el borde, las líneas divisorias de una tabla, la marca de un checkbox. "Tinta de texto" es el color del texto impreso sobre una placa.             |
+| Material  | Lo que cambia una estética: radio y forma de las esquinas, grosor y estilo del borde, sombra y transparencia.                                                                               |
+| Losa      | Una sombra dura, sin desenfoque, desplazada hacia abajo y hacia un lado, como la que dibujan `.neobrutalism` y `.chunky-tile`.                                                              |
+| Elevación | Cuánta de la sombra disponible toma un elemento: ninguna (`.flat`), una unidad (`.raised`) o dos (`.floating`).                                                                             |
+
+## Los tokens detrás de las clases
+
+Cada clase lee custom properties de CSS, llamadas tokens, así que puedes cambiar el resultado sin reescribir una clase:
+
+| Tipo         | Controla                                                                                        | Dónde se enumeran                                                                         |
+| ------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Color        | La paleta: colores de intención, texto, bordes y fondos, para claro y oscuro.                   | [Temas → Tokens de color](./usage/theming.md#tokens-de-color)                             |
+| Base         | Anchos y separaciones del layout, radios de esquina, altura de los controles, foco, movimiento. | [Temas → Tokens base](./usage/theming.md#tokens-base)                                     |
+| Intención    | Los huecos de color que lee un componente después de que una clase de intención elige un rol.   | [Temas → Tokens de intención](./usage/theming.md#tokens-de-intención)                     |
+| Presentación | Los porcentajes de relleno y de borde que definen las clases de presentación.                   | [Personalización → Tokens de presentación](./usage/customizing.md#tokens-de-presentación) |
+| Material     | Radio, grosor del borde, geometría de la sombra y transparencia.                                | [Personalización → Tokens de material](./usage/customizing.md#tokens-de-material)         |
+| Estética     | Un control por estética, como `--pixel-unit` o `--tile-lift`.                                   | [Personalización → Tokens de estética](./usage/customizing.md#tokens-de-estética)         |
+
+Los tokens de color y los tokens base son lo que la mayoría de las aplicaciones cambia primero, para ajustarse a una marca. El resto es de más bajo nivel: los componentes los leen, y las clases de presentación y de estética los definen por ti.
+
+## Límites que conviene conocer ya
+
+- **La intención no se hereda.** Escríbela en cada elemento que la muestre. La única excepción son las filas de tabla.
+- **Las clases solo dan estilo.** `<div class="btn">` parece un botón, pero no puede recibir el foco ni pulsarse con el teclado. Usa `<button>` o `<a href>`, y consulta [Accesibilidad](./accessibility.md).
+- **Una combinación que la documentación no describe no está soportada.** Puede que se renderice, pero puede cambiar en cualquier versión; consulta [Introducción → Qué se considera soportado](./index.md#qué-se-considera-soportado).
+
+## Siguiente paso
+
+La pantalla tiene una acción principal y una discreta. [Botones](./usage/buttons.md) añade el resto: una acción destructiva para la zona de peligro, botones de icono, tamaños y estados deshabilitados.

package/docs/es/index.md

@@ -0,0 +1,105 @@
+---
+title: Introducción
+description: Para qué sirve @codenhub/styles, qué cuesta y en qué orden leer esta documentación.
+source: 5f82b6a4d492bdb5ea73406f256d307f775fa1ea
+---
+
+# @codenhub/styles
+
+`@codenhub/styles` te permite construir una interfaz coherente y con temas escribiendo nombres de clase sobre HTML normal. Importas una hoja de estilos y obtienes tokens, un reset, helpers de layout y de tipografía, y clases para botones, campos de formulario, alertas, tarjetas, tablas y tooltips. No hay JavaScript que cargar ni una librería de componentes que envolver: un `<button class="btn primary">` es toda la integración.
+
+Esta documentación construye una pequeña pantalla de principio a fin: una página de ajustes de cuenta con un formulario de perfil, un resumen del plan y una zona de peligro. Cada página le añade algo, así que al final habrás visto todas las partes del paquete trabajando juntas en lugar de por separado.
+
+```html
+<main class="section">
+  <div class="section-content narrow stack">
+    <h1 class="text-title">Account settings</h1>
+    <form class="card stack">
+      <h2 class="text-title-sm">Profile</h2>
+      <div class="field">
+        <label class="label" for="display-name">Display name</label>
+        <input class="ipt" id="display-name" name="display-name" value="Ada Lovelace" />
+      </div>
+      <div class="cluster">
+        <button class="btn primary" type="submit">Save changes</button>
+        <button class="btn ghost" type="reset">Cancel</button>
+      </div>
+    </form>
+  </div>
+</main>
+```
+
+## Tres decisiones por componente
+
+Cada componente responde con clases a tres preguntas independientes, así que un aspecto nuevo nunca necesita una nueva variante del componente:
+
+- **Intención: ¿qué color?** `.primary`, `.secondary`, `.success`, `.warning`, `.destructive` o `.info`. Si no pones ninguna, es neutro.
+- **Presentación: ¿cuánto de ese color?** `.solid`, `.soft` o `.ghost` definen el relleno; `.edged` o `.edgeless` definen el borde.
+- **Estética: ¿de qué está hecho?** Una clase opcional, como `.neobrutalism` o `.glass`, cambia las esquinas, el grosor del borde, las sombras y la tipografía de todo lo que contiene.
+
+`<button class="btn destructive ghost edged">Delete account</button>` es un botón rojo con contorno, y envolver la página en `.pixel` lo convierte en uno de pixel art sin tocar el botón. [Construir una pantalla](./concepts.md) presenta cada eje a medida que la página de ajustes lo necesita.
+
+## CSS compilado o código fuente de Tailwind
+
+El paquete ofrece las mismas clases de dos formas:
+
+- **CSS compilado**, listo para usar. Impórtalo desde cualquier bundler o enlaza el archivo desde un CDN. No necesitas Tailwind.
+- **Código fuente de Tailwind CSS v4**, en `@codenhub/styles/tw`. Úsalo cuando tu proyecto ya usa Tailwind v4, para que tu build compile el paquete junto con tus propias utilidades y tu tema.
+
+[Configuración inicial](./setup.md) te ayuda a elegir.
+
+## Lo que no hace
+
+- **Sin JavaScript.** No hay runtime, ni bindings para frameworks, ni código generado. Todo lo que necesite un script, como abrir un diálogo, cambiar de tema o cerrar un tooltip, es código tuyo.
+- **Sin semántica ni comportamiento.** Las clases pintan elementos; no añaden semántica HTML, ARIA, manejo del teclado, gestión del foco, validación ni anuncios. [Accesibilidad](./accessibility.md) marca el límite exacto.
+- **Sin cambio de tema.** Elegir claro u oscuro es una clase o un atributo que pones tú. El paquete independiente `@codenhub/theme` puede recordar y aplicar esa elección por ti.
+- **Sin fuentes ni iconos.** No se descarga ningún archivo de fuente. Las estéticas que quieren una fuente especial usan una fuente del sistema hasta que tú aportes una. Los iconos, incluidos los spinners de carga, vienen de tu propio conjunto de iconos, como `@codenhub/icons`.
+- **Sin alias de compatibilidad.** Una clase o un token eliminado aparece en el changelog, no se conserva con su nombre antiguo.
+
+## Contrapartidas
+
+Conoce estos costes antes de adoptarlo:
+
+- **Los nombres de clase son cortos y no llevan prefijo.** `.primary`, `.success`, `.dark`, `.label`, `.field`, `.section`, `.stack`, `.flat` y `.ghost` son nombres globales. Otra hoja de estilos en la misma página que los use choca con esta. El paquete está en [capas de cascada](./setup.md#capas-de-cascada), así que tu propio CSS sin capa gana en caso de choque, pero las reglas de una librería de terceros para el mismo nombre se siguen aplicando junto a las del paquete.
+- **Las hojas de estilos completas son grandes antes de comprimir.** En el momento de escribir esto, minificada, la hoja de estilos completa ocupa unos 198 KB, `/native` unos 295 KB y `/components` unos 159 KB. Servidas con gzip ocupan unos 17 KB, 22 KB y 13 KB. Los archivos específicos son mucho más pequeños: `/theme` ocupa unos 12 KB (3 KB con gzip) y una estética, de 4 a 14 KB (de 1 a 2 KB con gzip). La mayor parte del tamaño es composición que cada componente repite, y por eso la compresión elimina tanto. Un archivo compilado incluye todas las clases, las use una página o no. Para incluir solo las clases que usan tus páginas, compila el paquete en tu propio build: con [Tailwind CSS v4](./integrating/tailwind.md) cuando el proyecto lo usa, o con el [comando `build`](./integrating/without-a-bundler.md#generar-solo-las-clases-que-usas) del paquete en cualquier otro proyecto. Así, una página con un botón recibe de 26 a 28 KB minificados, y unos 6 KB con gzip. Si no, importa el punto de entrada más reducido que cubra una página; consulta [Configuración inicial → Todos los puntos de entrada](./setup.md#todos-los-puntos-de-entrada).
+- **`--color-foreground` es un fondo, no un color de texto.** Es el tono un paso por encima de la página sobre el que se apoya una tarjeta o un panel discreto. El color de texto es `--color-text`.
+- **Cuatro colores de hover son valores fijos.** `--color-success-hover`, `--color-warning-hover`, `--color-destructive-hover` y `--color-info-hover` están precalculados, porque mezclarlos en vivo hacía fallar WebKit. Si sobrescribes solo `--color-success`, su hover conserva el tono anterior, así que reemplaza la familia completa; consulta [Temas → Tokens de color](./usage/theming.md#tokens-de-color).
+- **Solo navegadores modernos.** Chrome 123, Safari 17.5 o Firefox 128 y posteriores. No hay una capa de respaldo para navegadores antiguos.
+
+## Qué se considera soportado
+
+Una combinación de clases está soportada cuando esta documentación la describe y la demo pública en [demo.codenhub.dev/styles](https://demo.codenhub.dev/styles/) la muestra. La demo renderiza los fixtures de prueba del paquete, incluidas las matrices completas de intención, presentación y estética, con el CSS compilado. Una combinación que ni está documentada ni aparece en la demo puede seguir produciendo CSS, pero no se mantiene y puede cambiar en cualquier versión.
+
+La demo se reconstruye desde la rama principal, no desde cada versión. Puede mostrar trabajo que todavía no se ha publicado, así que, cuando la demo y esta documentación no coinciden sobre una versión publicada, mandan la documentación y el [changelog](../changelog/index.md) de esa versión.
+
+## Versionado
+
+El paquete está por debajo de 1.0 y sigue la [regla del versionado semántico para las versiones 0.x](https://semver.org/#spec-item-4): la superficie pública todavía puede cambiar entre versiones menores.
+
+- Una versión menor, como de 0.7.0 a 0.8.0, puede romper la compatibilidad. Puede renombrar o eliminar una clase o un token, o cambiar un valor por defecto. Cada cambio incompatible aparece en **Changed** o **Removed** en la página del [changelog](../changelog/index.md) de esa versión, con lo que debes usar en su lugar.
+- Una versión de parche, como de 0.7.0 a 0.7.1, nunca rompe la compatibilidad.
+
+El rango por defecto de npm para una nueva dependencia, `^0.7.0`, ya acepta solo parches, porque por debajo de 1.0 un rango con caret no pasa a la siguiente versión menor. Lee el changelog antes de subirlo. Cuando enlaces un archivo desde un CDN, pon la versión exacta en la URL; consulta [Sin bundler](./integrating/without-a-bundler.md).
+
+Los cambios incompatibles no se suavizan con alias porque el modelo todavía se está asentando, y mantener cada nombre antiguo junto a su reemplazo haría crecer la superficie en cada versión. Un cambio de nombre o una eliminación suele costar un buscar y reemplazar al actualizar; un valor por defecto que cambia puede requerir que reajustes tu propio CSS.
+
+## Orden de lectura
+
+La primera vez, léelas en orden. Cada página añade algo a la pantalla de ajustes y termina indicando la siguiente.
+
+1. [Configuración inicial](./setup.md): instala el paquete, elige entre CSS compilado o código fuente de Tailwind y renderiza la estructura vacía de la página.
+2. [Integración](./integrating/index.md): solo si usas Next.js, Vue, Svelte, Astro, Tailwind v4 o ningún bundler. Cada guía te devuelve al camino principal.
+3. [Construir una pantalla](./concepts.md): maqueta la página, define su tipografía y añade una tarjeta y un botón Guardar, aprendiendo por el camino la intención, el relleno y el borde.
+4. [Uso](./usage/index.md): el resto de la pantalla, en orden:
+   - [Botones](./usage/buttons.md): acciones secundarias y destructivas, tamaños, botones de icono y estados deshabilitados.
+   - [Formularios](./usage/forms.md): campos con etiqueta, pistas, errores, iconos, selects, checkboxes, radios y switches.
+   - [Feedback](./usage/feedback.md): un estado de guardado, una alerta de éxito, un badge del plan, un placeholder de carga y una barra de uso.
+   - [Tooltips](./usage/tooltips.md): ayuda de campo que funciona con ratón, con teclado y con lector de pantalla.
+   - [Temas](./usage/theming.md): modo claro y oscuro, colores de marca y tus propias intenciones.
+   - [Estéticas](./usage/aesthetics.md): cambia el estilo de toda la pantalla con una sola clase.
+   - [Clases solo](./usage/solo.md): pinta una estética sobre un componente al que este paquete no da estilo.
+   - [Composición](./usage/composing.md), [Personalización](./usage/customizing.md) y [Contenido y layout](./usage/content-and-layout.md): páginas de consulta con cada regla de eje, token, valor por defecto y clase helper.
+   - [Preajustes](./usage/presets.md): define un aspecto una sola vez, para una región, un tema o tu propia clase de componente, en lugar de repetirlo en cada elemento.
+5. [Accesibilidad](./accessibility.md): lo que el CSS resuelve por ti y lo que tu aplicación todavía debe hacer.
+
+El [changelog](../changelog/index.md) enumera cada versión y lo que cambió en ella.

package/docs/es/integrating/astro.md

@@ -0,0 +1,35 @@
+---
+title: Astro
+description: Cargar la hoja de estilos en una aplicación Astro.
+order: 5
+source: 4f93b3a6e0d1cd24a0b7d0eb6050cc98690cd598
+---
+
+# Astro
+
+Astro renderiza los componentes de forma estática por defecto, pero el import de una hoja de estilos global sigue necesitando hacerse una sola vez: desde un layout compartido, no desde páginas o islas individuales.
+
+## Importar la hoja de estilos
+
+```astro
+---
+// src/layouts/Layout.astro
+import "@codenhub/styles";
+---
+
+<html lang="en">
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+Cada página que usa este layout carga la hoja de estilos una vez. ¿Usas Tailwind CSS v4? Importa en su lugar `@codenhub/styles/tw` a través de la integración de Tailwind para Astro; consulta [Tailwind CSS v4](./tailwind.md), incluido cuándo hace falta realmente un `@source` explícito.
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en `<html>` para forzar un tema en lugar de seguir la preferencia del sistema; consulta [Temas → Claro y oscuro](../usage/theming.md#claro-y-oscuro).
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) enumera todas las demás hojas de estilos que puedes importar.