@axzydev/axzy_ui_system 1.2.12 → 1.2.14

package/README.md

@@ -34,23 +34,35 @@ export default defineConfig({
 })
 ```
 
-### 4. Importar Tailwind CSS
+### 4. Importar Tailwind + el CSS de la librería (en el orden de capas correcto)
+
+`dist/index.css` es un build de Tailwind **independiente y ya compilado** (tiene sus propias
+capas `@layer theme, base, components, utilities`). Si tu app también hace
+`@import "tailwindcss";` por su cuenta, el navegador acaba con **dos** juegos de esas mismas
+capas compartiendo nombre, y gana la que se registró en último lugar en el documento — normalmente
+el Preflight/reset de tu propia app, que no conoce los tokens de AXZY. Eso es lo que rompe cosas
+como el Sidebar: se ve bien solo mientras tu app no tiene su propio Tailwind corriendo.
+
+La forma correcta es importar el CSS de la librería con un **layer propio** y fijar el orden de
+capas explícitamente, para que el reset/tema de AXZY nunca dependa del orden de imports:
 
 `src/index.css`:
 
 ```css
+/* El orden aquí es el que manda, independientemente de en qué orden se
+   importen los archivos: axzy-ui-system se ejecuta después del `base` de
+   Tailwind (así su reset nunca lo pisa) pero antes de `utilities` (así tus
+   clases de Tailwind siguen pudiendo sobrescribir estilos de AXZY cuando
+   haga falta). */
+@layer theme, base, axzy-ui-system, components, utilities;
+
 @import "tailwindcss";
+@import "@axzydev/axzy_ui_system/dist/index.css" layer(axzy-ui-system);
 ```
 
-### 5. Importar el CSS de la librería
-
-`src/main.tsx`:
-
-```tsx
-import "@axzydev/axzy_ui_system/dist/index.css"
-```
+Con esto **ya no** se importa `dist/index.css` desde `main.tsx` — todo entra por `index.css`.
 
-### 6. Envolver con ITThemeProvider
+### 5. Envolver con ITThemeProvider
 
 `src/main.tsx`:
 
@@ -131,10 +143,45 @@ pnpm bundle       # tsup + CSS
 | `pnpm storybook` | Storybook local |
 | `pnpm build-storybook` | Build estático de Storybook |
 | `pnpm lint` | ESLint |
+| `pnpm check:atomic` | Valida dependencias atómicas (sin imports hacia capas superiores) |
+| `pnpm check:css` | Valida aislamiento CSS (selectores `it-*`, tokens `--it-*`, sin duplicados) |
 | `pnpm preview` | Preview del build |
 
 ---
 
+## Arquitectura atómica y aislamiento CSS
+
+Los componentes se organizan en **capas atómicas** con dependencias unidireccionales
+(una capa solo importa de capas iguales o inferiores):
+
+| Capa | Regla | Ejemplos |
+|------|-------|----------|
+| `atoms/` | Primitivos, sin dependencias de componentes | `ITButton`, `ITInput`, `ITText`, `ITGrid`, `ITFlex`, `ITStack` |
+| `molecules/` | Combinan átomos y moléculas | `ITCard`, `ITDatePicker`, `ITSelect`, `ITTable`, `ITStepper` |
+| `organisms/` | Composiciones complejas | `ITDataTable`, `ITFormBuilder`, `ITDialog`, `ITSidebar`, `ITTopbar` |
+| `templates/` | Páginas/estructuras completas | `ITLayout`, `ITPage` |
+| `theme-provider/` | Provider (no capa visual) | `ITThemeProvider` |
+
+### Garantía de aislamiento
+
+Anidar componentes (p.ej. **`ITDatePicker` dentro de `ITCard`**) **no** produce
+interferencia de estilos. Esto se garantiza por convención y se valida en CI:
+
+1. **Clases propias siempre con prefijo `it-`** (BEM: `.it-card`, `.it-date-picker__popover`).
+   Nunca clases genéricas (`.card`, `.toast-enter`, `.animate-*`).
+2. **Selectores con `:where(.it-*)`** → especificidad 0, para que las utilities de
+   Tailwind del consumidor sigan overrideando sin conflicto.
+3. **CSS plano en `@layer components`** → las utilities (layer `utilities`) ganan siempre.
+4. **Tokens públicos con namespace `--it-*`** (`--it-card-bg`, `--it-input-border`, ...).
+   El resto de tokens `--color-*`/`--radius-*` son internos de Tailwind.
+5. **Checks automáticos**: `pnpm check:css` (selectores/tokens genéricos) y
+   `pnpm check:atomic` (grafo de dependencias) fallan si se viola la convención.
+
+Story de validación visual: `src/components/isolation/isolation.stories.tsx`
+(`Components/Isolation/CSS Encapsulation`).
+
+---
+
 ## Theming
 
 Personaliza la paleta de colores en runtime sin recompilar:
@@ -153,6 +200,14 @@ const myTheme = {
 </ITThemeProvider>
 ```
 
+Override fino por CSS: los tokens de componente usan el namespace **`--it-*`**
+(`--it-card-bg`, `--it-topbar-bg`, `--it-calendar-selected-bg`, ...). Sobrescribir
+estas variables en cualquier contenedor estila solo ese subárbol.
+
+> **Breaking (v1.3)**: los tokens se renombraron de `--card-*`, `--input-*`,
+> `--topbar-*`, `--sidebar-*`, `--modal-*`, `--calendar-*`, `--layout-*` a `--it-*`
+> para evitar colisiones con CSS de la app consumidora.
+
 ---
 
 ## Componentes disponibles