@codenhub/styles 0.5.0 → 0.7.0

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,104 @@
+---
+title: Introducción
+description: Para qué sirve @codenhub/styles, qué cuesta y en qué orden leer esta documentación.
+source: 238cac2f0ca6132818c99d938219a6c537bc837a
+---
+
+# @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 410 KB, `/native` unos 575 KB y `/components` unos 320 KB. Servidas con gzip ocupan unos 19 KB, 25 KB y 15 KB. Los archivos específicos son mucho más pequeños: `/theme` ocupa unos 10 KB (2 KB con gzip) y una estética, de 4 a 21 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. 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.
+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.

package/docs/es/integrating/index.md

@@ -0,0 +1,47 @@
+---
+title: Visión general
+description: Cómo se carga la hoja de estilos en el build de un framework, y qué guía seguir.
+group: Integración
+order: 2
+source: f2ccb27bbdbe15278726278864c01a586505eb16
+---
+
+# Integración
+
+Esta sección es un desvío del orden de lectura principal, para proyectos cuyo framework decide dónde puede ir el CSS global. El paquete no tiene JavaScript ni bindings para frameworks (consulta [Introducción](../index.md#lo-que-no-hace)), así que integrarlo se reduce a dos cosas: dónde te deja tu framework cargar una hoja de estilos global, y si el proyecto usa Tailwind CSS v4. Sigue la guía que corresponde a tu stack y después vuelve a [Construir una pantalla](../concepts.md).
+
+## El modelo común
+
+Todos los stacks hacen los mismos dos imports, desde el mismo tipo de lugar: un layout raíz, un archivo de entrada de la aplicación o un archivo CSS global, nunca una página o un componente más abajo en el árbol:
+
+1. Un [punto de entrada](../setup.md#todos-los-puntos-de-entrada): el compilado `@codenhub/styles` para cualquier build, o `@codenhub/styles/tw` cuando el proyecto ya usa Tailwind CSS v4.
+2. `@codenhub/styles/aesthetics` (o `/tw/aesthetics`) después, solo si el proyecto usa una [estética](../usage/aesthetics.md).
+
+Importar desde un solo lugar importa por dos motivos. Algunos frameworks solo _permiten_ CSS global desde un archivo raíz designado y, si no, el build falla; el Pages Router de Next.js es uno de ellos, consulta [Next.js → Solución de problemas](./nextjs.md#solución-de-problemas). Donde un framework lo permite de forma más amplia, como hace el App Router de Next.js, importar desde la raíz sigue siendo la opción recomendada para que el orden del CSS sea predecible; además, importar en cada componente cargaría las mismas reglas de reset y de tokens una vez por componente en lugar de una vez por aplicación.
+
+## Qué guía seguir
+
+| Stack                                                                      | Guía                                  |
+| -------------------------------------------------------------------------- | ------------------------------------- |
+| Un proyecto con Tailwind CSS v4 en cualquier bundler                       | [Tailwind CSS v4](./tailwind.md)      |
+| Next.js / React                                                            | [Next.js](./nextjs.md)                |
+| Vue                                                                        | [Vue](./vue.md)                       |
+| Svelte / SvelteKit                                                         | [Svelte](./svelte.md)                 |
+| Astro                                                                      | [Astro](./astro.md)                   |
+| HTML simple, Rails, Django o cualquier aplicación sin paso de build de CSS | [Sin bundler](./without-a-bundler.md) |
+
+Un proyecto sin framework, un build simple con Vite, webpack o Parcel, no necesita nada más allá de [Configuración inicial → Importar la hoja de estilos](../setup.md#importar-la-hoja-de-estilos): importa la hoja de estilos compilada desde la entrada CSS global que el proyecto ya tiene.
+
+## Comprobar que funciona
+
+Después del import, renderiza un elemento con estilo y confirma que ha tomado los tokens del paquete y no los valores por defecto del navegador:
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+Un botón redondeado relleno con el color principal (casi negro en una página clara, casi blanco en una oscura) significa que la hoja de estilos se ha cargado. Un texto sin estilo, con los valores por defecto del navegador, casi siempre significa que el especificador del import no se ha resuelto: consulta en la [tabla de puntos de entrada](../setup.md#todos-los-puntos-de-entrada) el especificador exacto que debes importar, y confirma que tus herramientas de build resuelven imports de CSS de paquetes; consulta [Configuración inicial → Requisitos](../setup.md#requisitos). Sin herramienta de build, enlaza el archivo por su ruta; consulta [Sin bundler](./without-a-bundler.md). [Configuración inicial → Cuando nada tiene estilo](../setup.md#cuando-nada-tiene-estilo) enumera las otras causas habituales.
+
+## Siguiente paso
+
+Cuando el botón se renderice, vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes.

package/docs/es/integrating/nextjs.md

@@ -0,0 +1,67 @@
+---
+title: Next.js
+description: Cargar la hoja de estilos en una aplicación Next.js / React.
+order: 2
+source: fd8dc12652c64995638c5b902a1ca35787f9a37c
+---
+
+# Next.js
+
+Next.js tiene dos arquitecturas de router, y tratan el CSS global de forma distinta:
+
+- **App Router** (un directorio `app/`): el CSS global, incluida la hoja de estilos de un paquete externo como este, se puede importar desde cualquier layout, página o componente dentro de `app/`. Importarlo desde el layout raíz es solo una recomendación, para que el orden del CSS sea predecible entre rutas; Next.js no lo impone y no se produce ningún error si lo importas en otro sitio.
+- **Pages Router** (un directorio `pages/`, sin `app/`): el CSS global está restringido a `pages/_app.tsx`. Importarlo desde cualquier otro sitio hace fallar el build; lo impone el propio Next.js, no este paquete; consulta [Solución de problemas](#solución-de-problemas).
+- **Ambos directorios presentes** (a mitad de una migración): importa la hoja de estilos en los dos archivos raíz. Los dos routers sirven sus propias rutas de forma independiente, así que una ruta dentro de `pages/` nunca ve una hoja de estilos importada solo en `app/layout.tsx`, y viceversa.
+
+## Importar la hoja de estilos
+
+Añade el import al archivo raíz de tu router:
+
+**App Router**
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Pages Router**
+
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+¿Usas Tailwind CSS v4? `@import "@codenhub/styles/tw"` es una directiva de CSS, así que va en un archivo CSS, no como import suelto en `layout.tsx`/`_app.tsx`: añádelo (con `@source` si hace falta; `/tw` ya importa Tailwind, así que no pongas tu propio `@import "tailwindcss"`) a tu archivo CSS global, e importa ese archivo desde el mismo archivo raíz de arriba. Consulta [Tailwind CSS v4](./tailwind.md).
+
+## 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).
+
+```tsx
+<html lang="en" className="dark">
+```
+
+## Solución de problemas
+
+**El build con Pages Router falla con "Global CSS cannot be imported from files other than your Custom `<App>`"**
+
+- **Qué ha pasado:** Next.js ha rechazado una sentencia `import` de CSS global fuera de `pages/_app.tsx`. Esta restricción es propia del Pages Router: la impone el propio Next.js, no este paquete, y se aplica a cualquier import de CSS global, no solo a `@codenhub/styles`. No se aplica al App Router, donde el mismo import funciona desde cualquier layout, página o componente.
+- **Por qué:** el Pages Router no tiene un límite de CSS por ruta como el App Router, así que Next.js exige un único archivo predecible para las hojas de estilos globales y así evitar conflictos de orden entre páginas.
+- **Solución:** mueve la línea `import "@codenhub/styles"` a `pages/_app.tsx` y quítala de donde esté ahora.
+
+## 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.

package/docs/es/integrating/svelte.md

@@ -0,0 +1,45 @@
+---
+title: Svelte
+description: Cargar la hoja de estilos en una aplicación Svelte / SvelteKit.
+order: 4
+source: 9c8bc0fee69e4b2bf1edd85c784b7df8ff1e883d
+---
+
+# Svelte
+
+Svelte y SvelteKit te permiten importar CSS desde cualquier componente, pero el reset y los tokens del paquete deberían cargarse una vez, antes de que se renderice cualquier componente. Esta página muestra dónde va ese único import en SvelteKit y en una aplicación Svelte simple.
+
+## Importar la hoja de estilos
+
+**SvelteKit**: importa desde el layout raíz para que se cargue una vez para todas las rutas:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+**Svelte simple + Vite**: importa en su lugar desde el archivo de entrada:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });
+```
+
+¿Usas Tailwind CSS v4? Importa en su lugar `@codenhub/styles/tw` desde la entrada CSS de la aplicación; consulta [Tailwind CSS v4](./tailwind.md).
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en `<html>` (edita `src/app.html` en SvelteKit) 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.

package/docs/es/integrating/tailwind.md

@@ -0,0 +1,78 @@
+---
+title: Tailwind CSS v4
+description: Usar los puntos de entrada de código fuente /tw en un proyecto con Tailwind CSS v4.
+order: 1
+source: 7988dc023c91950991a720ea7da7edfe3378d4d7
+---
+
+# Tailwind CSS v4
+
+Un proyecto que ya usa Tailwind CSS v4 puede compilar el código fuente de este paquete en lugar de cargar su salida compilada. Así, las utilidades de tu aplicación y las clases del paquete salen de un solo build, comparten un tema y usan una sola variante `dark:`. Esta página cubre el import, las estéticas, los puntos de entrada específicos y los problemas de build con los que probablemente te encuentres.
+
+## Por qué código fuente en lugar de compilado
+
+Los puntos de entrada `/tw` publican código fuente copiado y sin compilar desde `dist/tw`; tu propio build de Tailwind lo compila junto con tu aplicación, así que sus directivas `@theme`, `@utility` y `@apply` se resuelven junto con las tuyas. Los puntos de entrada compilados (`@codenhub/styles`) siguen funcionando en un proyecto con Tailwind, pero entonces se ejecutan dos pipelines de CSS separados en paralelo en lugar de uno: usa `/tw` salvo que un motivo concreto lo descarte.
+
+## Importar el punto de entrada de código fuente
+
+```css
+@import "@codenhub/styles/tw";
+
+@source "./src";
+```
+
+`/tw` importa el propio Tailwind, así que sustituye a tu `@import "tailwindcss"` en lugar de sumarse a él: con los dos, el Preflight de Tailwind se emite dos veces. Todos los demás puntos de entrada `/tw/*` esperan que tu import vaya primero; consulta [Usar un punto de entrada específico](#usar-un-punto-de-entrada-específico).
+
+Tailwind CSS v4 escanea tu proyecto automáticamente: la mayoría de los proyectos no necesita nada más que el import anterior. Las rutas de `@source` se resuelven respecto al archivo CSS que las declara, no respecto a la raíz de tu proyecto, así que aquí `./src` significa "el `src/` que está junto a esta hoja de estilos"; ajústalo según dónde esté realmente tu hoja de estilos global. Añade `@source` solo para el markup al que el escaneo automático de Tailwind no llega por sí solo: una ruta excluida por defecto (incluida en `.gitignore`, o dentro de `node_modules`, por ejemplo una librería de componentes externa) o, en un monorepo, una que está fuera del árbol de directorios de este archivo. Apúntalo al markup de tu aplicación, no a este paquete: `/tw` ya incluye todas las definiciones de clase que publica, así que escanearlo también solo ralentiza el build sin añadir clases.
+
+## Añadir estéticas
+
+Añade una estética desde el punto de entrada de código fuente igual que con el compilado, después del import base:
+
+```css
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+## Usar un punto de entrada específico
+
+Importa un punto de entrada `/tw/*` específico en lugar del combinado, como `/tw/button` o `/tw/form`, cuando un build solo necesita una familia de componentes; consulta la [tabla de puntos de entrada](../setup.md#todos-los-puntos-de-entrada) completa para ver qué compone cada uno.
+
+A diferencia de `/tw`, los puntos de entrada específicos y `/tw/native` no importan Tailwind, así que mantén tu propio import primero:
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw/button";
+```
+
+## Solución de problemas
+
+**Las clases no producen ningún estilo**
+
+- **Qué ha pasado:** los componentes usan clases documentadas como `.btn.primary`, pero no aparece ningún estilo aunque `@import "@codenhub/styles/tw"` está en la hoja de estilos.
+- **Por qué:** rara vez es por el propio `@source`, porque Tailwind ya escanea tu proyecto automáticamente. La causa más habitual es un markup que vive en un lugar que el escaneo automático excluye por defecto: una ruta incluida en `.gitignore`, o un componente que viene de `node_modules`. Puede que Tailwind no vea una clase usada solo ahí y no genere una regla para ella.
+- **Solución:** añade un `@source` explícito que apunte a ese directorio, resuelto respecto a esta hoja de estilos, como en el [ejemplo de arriba](#importar-el-punto-de-entrada-de-código-fuente).
+
+**Reglas de tokens y de reset duplicadas**
+
+- **Qué ha pasado:** la hoja de estilos generada es más grande de lo esperado, y las herramientas de desarrollo del navegador muestran las mismas custom properties o reglas de reset definidas dos veces.
+- **Por qué:** una de dos cosas. Importar en el mismo build un punto de entrada compilado (`@codenhub/styles`) y un punto de entrada `/tw` (`@codenhub/styles/tw`) compila los mismos tokens y el mismo reset desde dos fuentes independientes; el build de Tailwind no tiene forma de saber que describen el mismo paquete. O bien tu hoja de estilos importa `tailwindcss` junto a `/tw`, que ya lo importa, así que el Preflight se emite dos veces.
+- **Solución:** elige un camino por proyecto, los puntos de entrada `/tw` para un proyecto con Tailwind CSS v4 y los compilados en todos los demás casos, y quita tu propio `@import "tailwindcss"` cuando importes `/tw`.
+
+**Una clase construida en tiempo de ejecución no tiene estilo**
+
+- **Qué ha pasado:** `<button class="btn primary">` tiene estilo, pero un botón cuya intención viene de una variable, como `` `btn ${tone}` ``, no.
+- **Por qué:** Tailwind genera una clase solo cuando encuentra el nombre completo en tus archivos fuente. Las clases de componente y de eje del propio paquete se generan siempre, pero tus propias utilidades no, y un nombre armado a partir de strings es invisible para el escaneo.
+- **Solución:** escribe nombres de clase completos en tu código, por ejemplo en un objeto de consulta (`{ save: "btn primary", remove: "btn destructive" }`), o enumera los nombres que tu código puede producir con `@source inline("...")` en tu hoja de estilos.
+
+Todos los puntos de entrada `/tw` requieren Tailwind CSS 4.3.2 o posterior, por debajo de 5: el código fuente usa `@source not` y `@source inline()`, que llegaron en la 4.1, y se prueba con la 4.3.2.
+
+## La variante `dark:`
+
+Los puntos de entrada `/tw` definen su propia variante `dark:`, así que tus utilidades cambian con los mismos selectores claro y oscuro que usan los tokens del paquete. Tiene una diferencia conocida respecto a los tokens cuando los temas están anidados; consulta [Temas → La variante dark:](../usage/theming.md#la-variante-dark).
+
+## 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. Todo lo que muestra funciona igual con `/tw`.

package/docs/es/integrating/vue.md

@@ -0,0 +1,31 @@
+---
+title: Vue
+description: Cargar la hoja de estilos en una aplicación Vue / Vite.
+order: 3
+source: 9cc23f66518b0aa3ce886602f39d05820b2b8bcf
+---
+
+# Vue
+
+Vue no pone ninguna restricción sobre desde dónde se importa el CSS, pero importarlo una vez, desde el archivo de entrada de la aplicación, evita que el reset y los tokens se carguen más de una vez y garantiza que estén listos antes de que se renderice cualquier componente.
+
+## Importar la hoja de estilos
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
+```
+
+¿Usas Tailwind CSS v4? Importa `@codenhub/styles/tw` desde un archivo CSS de entrada en lugar de `main.ts`, con el plugin `@tailwindcss/vite`; consulta [Tailwind CSS v4](./tailwind.md).
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en el elemento raíz 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.