# Ryukami-UI (v2.4.0)

> Librería de 35 componentes Neo-Brutalistas, 10 bloques de página modulares y 6 temas con presets de color para Astro 7, Tailwind CSS v4 y TypeScript 7. Incluye CLI propio (`ryukami-ui`), servidor MCP nativo (`ryukami-ui mcp`), auditor de integridad SHA-256 (`ryukami-ui diff`) y endpoints W3C (`/r/tokens.json`).

## Resumen y Filosofía
- **Framework:** Astro 7.4.0 (Vite 8 + Rolldown, 0 KiB JS bundles externos).
- **Estilos:** Tailwind CSS 4.3.3 (`@theme`, variables reactivas en tiempo real, `@custom-variant dark`).
- **Diseño:** Neo-Brutalismo con esquinas de `0px`, bordes negros de `2px`, sombras duras de `-4px 4px 0px 0px`, controles de ventana geométricos `[ - ][ □ ][ × ]`.
- **Repositorio Oficial:** https://github.com/Alecwce/ryukami-ui
- **Sitio en Producción:** https://ryukami-ui.pages.dev

## Arquitectura de Rutas Web (Paridad 8bitcn / shadcn)
- `/` — Portada interactiva con terminal y catálogo en vivo.
- `/docs` — Introducción y guía de inicio rápido.
- `/docs/cli` — Referencia completa del CLI (`init`, `add`, `list`, `diff`, `mcp`).
- `/docs/mcp` — Especificación de integración del protocolo MCP para agentes de IA.
- `/docs/components` — Catálogo navegable de los 35 componentes con vista previa y propiedades.
- `/docs/components/[slug]` — Páginas dedicadas por componente (`/button`, `/modal`, `/drawer`, `/bento-grid`, etc.).
- `/blocks` — Galería de 10 bloques modulares (Hero, Features, CTA, FAQ, Login, Bento, DataTable, Shell, ASCII, Footer).
- `/themes` — Laboratorio de temas y 6 presets nombrados con copiado de tokens CSS y W3C tokens.

## Instalación del CLI, Registro y Servidor MCP

### 1. Obtener el CLI oficial
El CLI vive en `bin/ryukami-ui.mjs` y se enlaza globalmente en `~/.local/bin/ryukami-ui`:
```bash
git clone https://github.com/Alecwce/ryukami-ui.git ~/.local/share/ryukami-ui
ln -sf ~/.local/share/ryukami-ui/bin/ryukami-ui.mjs ~/.local/bin/ryukami-ui
chmod +x ~/.local/bin/ryukami-ui
```

### 2. Inicializar en un proyecto Astro + Tailwind v4 (u Obsidian)
Inyecta `src/styles/global.css` con los tokens de Tailwind v4, genera `ryukami.json` y opcionalmente `design-tokens.json` (`--obsidian`):
```bash
ryukami-ui init --obsidian --dir ./mi-proyecto
```

### 3. Instalar componentes específicos o auditar integridad SHA-256
```bash
ryukami-ui add button card callout bento-grid data-table code-block drawer --dir ./mi-proyecto
ryukami-ui diff --dir ./mi-proyecto
```

### 4. Instalar los 35 componentes a la vez
```bash
ryukami-ui add --all --dir ./mi-proyecto
```

### 5. Servidor MCP para Agentes de IA (`stdio` JSON-RPC 2.0)
Expone las herramientas `list_components`, `get_component` y `get_design_tokens`:
```bash
ryukami-ui mcp
```

## Consumo Directo del Registro JSON por Agentes de IA
- Manifiesto completo de los 35 módulos: `https://ryukami-ui.pages.dev/r/registry.json`
- Tokens W3C Design System v4.1: `https://ryukami-ui.pages.dev/r/tokens.json`
- Tokens globales CSS de Tailwind v4: `https://ryukami-ui.pages.dev/r/styles.json`
- Endpoint directo de cada componente: `https://ryukami-ui.pages.dev/r/<id>.json`

## Catálogo de los 35 Componentes

1. `button` (`src/components/Button.astro`): Botón mecánico Neo-Brutalista con 5 variantes y síntesis de clic Web Audio.
2. `badge` (`src/components/Badge.astro`): Etiquetas y pastillas TUI de estado con sombra dura de -2px 2px.
3. `card` (`src/components/Card.astro`): Ventana de consola TUI interactiva con controles geométricos [ - ][ □ ][ × ].
4. `kbd` (`src/components/Kbd.astro`): Representación física de teclas de atajos de teclado ([Ctrl] + [K]).
5. `progress-bar` (`src/components/ProgressBar.astro`): Barra de progreso segmentada estilo BIOS con lectura ASCII [████████░░░░] en vivo.
6. `avatar` (`src/components/Avatar.astro`): Identificador cuadrado de operador TUI con indicador de estado (ONLINE/BUSY/IDLE).
7. `skeleton` (`src/components/Skeleton.astro`): Bloque de carga de búfer ASCII ([ ░░░ SYNC ░░░ ]) con estructura brutalista.
8. `stat-card` (`src/components/StatCard.astro`): Tarjeta KPI de telemetría con delta porcentual (▲/▼) y sparkline ASCII [▁▂▃▅▆▇█].
9. `tooltip` (`src/components/Tooltip.astro`): Etiqueta emergente accesible por teclado y hover con sombra dura -2px 2px.
10. `input` (`src/components/Input.astro`): Campo de entrada brutalista con prefijo de terminal ($ / tcp://), hints y validación.
11. `textarea` (`src/components/Textarea.astro`): Editor multilínea de búfer UTF-8 con contador en vivo de líneas y bytes.
12. `select` (`src/components/Select.astro`): Selector desplegable brutalista con prefijo OPT // e indicador mecánico.
13. `slider` (`src/components/Slider.astro`): Control deslizante de rango con barra de caracteres ASCII [====|----] en tiempo real.
14. `radio-group` (`src/components/RadioGroup.astro`): Selector exclusivo de opciones con indicadores de terminal ( • ) y (   ).
15. `checkbox` (`src/components/Checkbox.astro`): Casilla de verificación cuadrada con marca pixel-art (X) y descripción.
16. `switch` (`src/components/Switch.astro`): Interruptor táctil deslizante (role="switch") con variantes crimson, cyan y gold.
17. `tabs` (`src/components/Tabs.astro`): Paneles multipestaña TUI con navegación por flechas de teclado y sonido mecánico.
18. `accordion` (`src/components/Accordion.astro`): Acordeón exclusivo nativo con `<details name="...">` accesible y buscable en página.
19. `breadcrumb` (`src/components/Breadcrumb.astro`): Ruta de navegación estilo sistema de archivos Unix (~/ryukami/core/nodes).
20. `pagination` (`src/components/Pagination.astro`): Barra de paginación mecánica TUI ([ ◄ PREV ] [ 01 ] [ 02 ] [ NEXT ► ]).
21. `popover` (`src/components/Popover.astro`): Globo flotante de telemetría con API nativa `popover="auto"` sin dependencias JS.
22. `alert` (`src/components/Alert.astro`): Callouts de sistema con 4 niveles de severidad (crimson, gold, cyan, emerald).
23. `callout` (`src/components/Callout.astro`): Callout canónico compatible con Obsidian (`[!dragon]`, `[!scorch]`, `[!terminal]`, `[!tui]`, `[!summary]`).
24. `modal` (`src/components/Modal.astro`): Diálogo modal nativo `<dialog closedby="any">` con bloqueo de scroll de fondo.
25. `drawer` (`src/components/Drawer.astro`): Panel lateral deslizante nativo `<dialog closedby="any">` con apertura izquierda o derecha.
26. `toast-container` (`src/components/ToastContainer.astro`): Motor global de notificaciones flotantes con síntesis de audio por severidad.
27. `command-palette` (`src/components/CommandPalette.astro`): Consola de comandos interactiva (Ctrl+K) con buscador en vivo y atajos de teclado.
28. `bento-grid` (`src/components/BentoGrid.astro`): Sistema modular de grillas Neo-Brutalistas (1x, 2x, 3x) con telemetría y cabeceras TUI.
29. `data-table` (`src/components/DataTable.astro`): Tabla de datos interactiva con filtrado en vivo, ordenamiento por columna y badges de estado.
30. `code-block` (`src/components/CodeBlock.astro`): Visor de código TUI con numeración de líneas, resaltado diff (+/-) y copiado en 1 clic.
31. `audio-synth` (`src/components/AudioSynth.astro`): Sintetizador interactivo de 4 pads acústicos Web Audio API (Cherry MX, Pip, Ack, Scorch Pulse).
32. `terminal-emulator` (`src/components/TerminalEmulator.astro`): Consola interactiva en vivo (`0xSCORCH_SHELL`) con comandos (`neofetch`, `status`, `dragon`, `cli`, `theme`, `clear`).
33. `component-preview` (`src/components/ComponentPreview.astro`): Visor interactivo `[ PREVIEW | CODE | PROPS ]` con botón de copiado de CLI y código en 1 clic.
34. `theme-studio` (`src/components/ThemeStudio.astro`): Personalizador en vivo de tokens CSS, sombras brutalistas y trama halftone.
35. `ascii-generator` (`src/components/AsciiGenerator.astro`): Forja de banners ASCII 8-bit y emblema del Dragón Scorch en tiempo real.

## Galería de Bloques Modulares (`src/blocks/` y `/blocks`)
1. `HeroBlock` (`src/blocks/HeroBlock.astro`): Sección de cabecera con llamadas de acción dobles y badges TUI.
2. `FeaturesBlock` (`src/blocks/FeaturesBlock.astro`): Cuadrícula de capacidades con glifos geométricos.
3. `CtaBlock` (`src/blocks/CtaBlock.astro`): Boletín y suscripción de terminal con validación en vivo.
4. `FaqBlock` (`src/blocks/FaqBlock.astro`): Preguntas frecuentes con HTML5 details nativo.
5. `LoginBlock` (`src/blocks/LoginBlock.astro`): Formulario de autenticación de operador con prefijos id:// y key://.
6. `BentoGrid`: Tablero bento asimétrico de telemetría.
7. `DataTable`: Clúster de servicios con filtrado y ordenamiento interactivo.
8. `TerminalEmulator`: Consola de comandos TUI con respuesta inmediata.
9. `AsciiGenerator`: Motor de generación ASCII con copiado al portapapeles.
10. `FooterBlock` (`src/blocks/FooterBlock.astro`): Pie de página neo-brutalista de 4 columnas.