@beweco/aurora-ui 1.0.0-beta.111 → 1.0.0-beta.113

package/README.md

@@ -31,6 +31,45 @@ function App() {
 }
 ```
 
+## Consumo en una app (aurora-ui v1, Tailwind 4)
+
+El paquete publica dos ficheros CSS con papeles distintos:
+
+| Export | Fichero | Qué es | Quién lo procesa |
+|---|---|---|---|
+| `@beweco/aurora-ui/theme` | `dist/assets/css/theme.css` | **Fuente** de tokens: SOLO el bloque `@theme static` (paleta base + escalas 50–900 + sombras). Copia literal de `src/styles/theme-tokens.generated.css`, sin compilar. | El Tailwind **de la app**, importado con `theme(reference)` (que anula el `static`): es lo que hace que genere `bg-primary-100`, `text-secondary-600`, `bg-content1`… sin volver a emitir las variables. |
+| `@beweco/aurora-ui/styles` | `dist/assets/css/styles.css` | CSS **compilado** de la librería: las variables de tema en `:root`, los 14 packs de color por clase (`.blue-light`, `.purple-dark`…), el puente `--accent` a HeroUI v3, HeroUI v3 + neutralización + utilidades de sus componentes. | Nadie: ya está compilado, solo se incluye. |
+
+Receta para el CSS de entrada de la app:
+
+```css
+/* src/index.css de la app */
+@import "tailwindcss";
+@import "@beweco/aurora-ui/theme" theme(reference); /* fuente de tokens (@theme puro) → el Tailwind de la app genera bg-primary-100, text-secondary-600, bg-content1…; con `reference` NO emite las variables */
+@import "@beweco/aurora-ui/styles";                 /* CSS compilado de la librería: variables de tema en :root + 14 packs + puente --accent + HeroUI v3 + neutralize + utilidades de sus componentes (o `import "@beweco/aurora-ui/styles"` en el entry JS, una de las dos) */
+@source "../src";
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+Por qué `theme(reference)`:
+
+- `styles.css` ya trae **todas** las variables `--color-*` emitidas en `:root` (la librería compila ese
+  mismo `@theme static` porque hay componentes que leen `var(--color-*)` en runtime) más los 14 packs
+  por clase. Si la app importa `./theme` **sin** `reference`, su Tailwind vuelve a emitir
+  esas mismas variables y el CSS final las lleva **dos veces** (~95 kB duplicados, medidos).
+- Con `reference` (que anula el `static` del fichero), el Tailwind de la app **conoce** los tokens (y por tanto genera `bg-primary-100`,
+  `text-secondary-600`, `bg-content1`… como `background-color: var(--color-primary-100)`), pero **no
+  emite** ninguna variable: los valores los aporta `styles.css`, que por eso es obligatorio.
+- `./theme` es `@theme` puro a propósito: Tailwind rechaza `theme(reference)` sobre un fichero que
+  contenga cualquier otra cosa («must only contain `@theme` blocks»). Los packs por clase no van ahí:
+  viajan compilados dentro de `styles.css`.
+
+Notas:
+
+- La app **no** importa `@heroui/styles` ni `@heroui/react` directamente: los trae `@beweco/aurora-ui` (dependencia fijada a la versión exacta de HeroUI v3 con la que se construyó).
+- Instalar con versión **exacta** (`"@beweco/aurora-ui": "1.0.0-beta.N"`, sin `^`): las prereleases no son compatibles entre sí bajo semver y un rango arrastraría cambios no probados.
+- `@custom-variant dark` es obligatorio: sin él, Tailwind 4 ata `dark:` a `prefers-color-scheme` en vez de a la clase `.dark`, y el render cambia.
+
 ## Development
 
 ### Prerequisites