# TaishoDS Core
> TaishoDS Core es un sistema de diseño para HTML: CSS con tokens y clases de utilidad, 56 componentes listos para copiar y el JavaScript de su comportamiento, con el tema propio compilado en el CSS. Paquete `@taishods/core`, gratuito, licencia MIT.
Versión en inglés: https://taisho.design/llms.txt
## Reglas para escribir marcado con TaishoDS
1. Todo elemento que usa clases del sistema lleva la clase `ts`: `class="ts button size-md variant-primary"`. Sin ella, el elemento no recibe estilo.
```html
```
2. En el marcado no se escribe `ts-`: el sistema usa `ts` como llave y las clases van sin prefijo (`button`, `variant-primary`, `gap-base`).
3. El vocabulario es cerrado: no hay valores arbitrarios (nada como `p-[13px]` ni `w-[37%]`). Una clase que no está en el vocabulario no hace nada, y `npx taisho check` la señala.
4. El espaciado se escribe con palabras (`none`, `quarter`, `half`, `base`, `section`, `double`), que siguen la densidad del tema, o con números, que son píxeles (`p-4` es 4 px). Los márgenes negativos llevan `neg-` delante del valor (`mx-neg-base`, `mt-neg-16`).
```html
Nuevo
```
5. Los colores salen sólo de las escalas del tema: `bg-{color}-{tono}`, `color-{color}-{tono}`, `border-{color}-{tono}`. Con el tema de fábrica los colores son `gray`, `brand`, `brand-secondary`, `accent`, `success`, `warning`, `info`, `danger` y los tonos van de 100…1000. Un tema propio puede sumar más (se ven con `npx taisho check`). No hay `dark:`: los tonos ya cambian solos en modo oscuro.
```html
Aviso
```
6. Las variantes (el prefijo antes de los dos puntos) son una lista cerrada y se encadenan hasta tres, en este orden: pantalla o contenedor, grupo, estado.
- Pantallas: `sm:`, `md:`, `lg:`, `xl:`; hasta una pantalla: `max-xl:`, `max-lg:`, `max-md:`, `max-sm:`; contenedores: `@sm:`, `@md:`, `@lg:`, `@xl:`, `@2xl:`, `@3xl:`, `@4xl:`, `@5xl:`, `@6xl:`, `@7xl:`; impresión: `print:`.
- Estados: `hover:`, `focus:`, `focus-visible:`, `active:`, `aria-busy:`, `aria-checked:`, `aria-disabled:`, `aria-expanded:`, `aria-hidden:`, `aria-pressed:`, `aria-readonly:`, `aria-required:`, `aria-selected:`, `aria-invalid:`, `checked:`, `invalid:`, `disabled:`, `data-{nombre}:`.
- Grupos: `group-{estado}:` y `peer-{estado}:`, con un nombre opcional (`group-hover/fila:`) para elegir cuál. El elemento de referencia lleva `group` o `peer`.
```html
Título
```
7. Los componentes se copian de su ficha y no se inventan: el marcado de la ficha ya trae las clases, los roles ARIA y los atributos `data-ts-*`. El comportamiento sale de esos atributos y de `taisho.core.js`; si la ficha dice que no necesita JavaScript, no hay nada que cargar.
8. Después de escribir, se corre `npx taisho check` hasta que dé 0 avisos: cada aviso es una clase o una variable que el sistema no conoce.
9. Los íconos salen de Lucide: `npm i -D lucide-static` hace falta sólo si se usan íconos (`npx taisho init` ofrece instalarlo y `npx taisho init --install-icons` lo instala sin preguntar). Si el código usa íconos que no se resuelven por faltar el paquete, `npx taisho generate` lo avisa con el comando y termina con error; si el proyecto no usa íconos, no dice nada.
## Si ya se conoce Tailwind
- Los números de las medidas son píxeles, no pasos: `p-4` es 4 px. Lo que en Tailwind es `p-4` (16 px) acá es `p-16`, o una palabra de ritmo (`half`, `base`) si se quiere que siga la densidad del tema.
- Todo elemento lleva la clase `ts`. No hay valores arbitrarios ni `dark:`: los tonos cambian solos en modo oscuro.
- Equivalencias frecuentes (`flex`, `grid`, `hidden`, `items-center`, `justify-between`, `w-full` y los prefijos `sm:`, `md:`, `lg:`, `xl:` se escriben igual):
| Tailwind | TaishoDS |
| --- | --- |
| `p-4` | `p-16` |
| `mt-2` | `mt-8` |
| `gap-4` | `gap-16` |
| `text-sm` | `text-14` |
| `font-bold` | `weight-bold` |
| `rounded-lg` | `radius-lg` |
| `text-left` | `align-start` |
| `text-right` | `align-end` |
`npx taisho migrate --from tailwind` hace la conversión: informa lo que cambiaría y, con `--write`, lo aplica.
## Instalación
### 1. Por CDN: tres líneas
Es la más corta, no instala nada. La versión va fija en la URL:
```html
```
El orden importa: primero el tema, que define las variables; después el CSS del sistema, que las
consulta; al final el JS, que se inicializa solo. Las clases se escriben con la llave `ts` en el
mismo elemento: `class="ts button size-md variant-primary"`.
### 2. Con este paquete: tu marca en el CSS
Para que el CSS lleve tus colores y fuentes, y sólo las clases que se usan, se instala el paquete y
se corre el comando `taisho` desde la raíz de tu proyecto (Node 22.18 o más nuevo):
```bash
npm i -D @taishods/core
npx taisho init # pregunta idioma, marca, nombre del tema, fuentes e íconos propios y la carpeta de salida, y escribe taisho.config.ts
npx taisho generate # compila tu CSS y copia el JS de comportamiento a esa carpeta
```
La carpeta de salida es la que se despliega con el sitio (por ejemplo `public/taisho`, `static/taisho` o
`./taisho`); `init` propone una según la estructura del proyecto y la guarda en `taisho.config.ts`. Al
terminar, `generate` imprime las líneas `` y `
```
#### Con un empaquetador (Vite y similares)
Si el proyecto ya usa un empaquetador, el CSS y el JS se importan por nombre desde el paquete, sin copiar
ni enlazar archivos:
```js
import '@taishods/core/css/tokens/taisho.css'; // el tema del sistema
import '@taishods/core/css/taisho.full.css'; // el CSS completo
import '@taishods/core/core'; // el comportamiento
```
## Servidor MCP
`npx taisho mcp` arranca un servidor MCP local y de sólo lectura (sin red ni telemetría) con herramientas para consultar componentes, utilidades y el tema del proyecto, y para validar marcado. Configuración y ejemplos: https://taisho.design/docs/ai-assistants#servidor-mcp
## Componentes
- [Accordion](https://taisho.design/docs/accordion.md): Lista de secciones colapsables coordinadas entre sí.
- [AlertDialog](https://taisho.design/docs/alert-dialog.md): Diálogo que fuerza una decisión antes de seguir: bloquea, y a diferencia de Modal el fondo NO lo descarta.
- [AspectRatio](https://taisho.design/docs/aspect-ratio.md): Mantiene una relación de aspecto fija para su contenido — imágenes, video, iframes, mapas — para que nada salte mientras carga.
- [Avatar](https://taisho.design/docs/avatar.md): Representa a un usuario o entidad con una imagen, o con las iniciales derivadas del nombre como fallback (si la imagen falla, el Core las escribe).
- [Badge](https://taisho.design/docs/badge.md): Etiqueta compacta para estados, categorías o conteos.
- [Banner](https://taisho.design/docs/banner.md): Mensaje de ancho completo para un estado global de la página o la app.
- [Breadcrumbs](https://taisho.design/docs/breadcrumbs.md): Ruta de navegación jerárquica: muestra dónde está el usuario y le da la vuelta hacia arriba.
- [Button](https://taisho.design/docs/button.md): Dispara una acción.
- [Card](https://taisho.design/docs/card.md): Contenedor de superficie para agrupar contenido relacionado.
- [Checkbox](https://taisho.design/docs/checkbox.md): Casilla booleana.
- [Code](https://taisho.design/docs/code.md): Bloque de código con etiqueta de lenguaje y botón de copiar.
- [Collapsible](https://taisho.design/docs/collapsible.md): Muestra u oculta un bloque de contenido con una transición de altura.
- [Combobox](https://taisho.design/docs/combobox.md): Un `` editable con autocompletado (patrón APG combobox): se tipea para filtrar la lista y se elige una opción o, con `data-ts-allow-custom` en la raíz, se deja un valor libre.
- [CommandPalette](https://taisho.design/docs/command-palette.md): Paleta de comandos estilo ⌘K: búsqueda difusa sobre acciones agrupadas, navegable por teclado.
- [Container](https://taisho.design/docs/container.md): Envoltorio de página: acota el ancho máximo, centra horizontalmente y agrega el padding lateral (`max-w-*`, `mx-auto`, `px-*`).
- [ContextMenu](https://taisho.design/docs/context-menu.md): Menú de acciones que aparece con clic derecho sobre un elemento.
- [DatePicker](https://taisho.design/docs/date-picker.md): Selección de una fecha: un disparador tipo input abre un calendario navegable por teclado (patrón APG).
- [Drawer](https://taisho.design/docs/drawer.md): Panel que entra desde un borde de la pantalla sin tapar del todo lo de atrás.
- [EmptyState](https://taisho.design/docs/empty-state.md): El bloque que va cuando una lista, tabla o vista no tiene contenido: ícono, título, descripción y acción, centrados y unificados, en vez de repetir el HTML en cada pantalla.
- [Field](https://taisho.design/docs/field.md): Primitiva de formularios: ata el label, la ayuda y el error a su control — id compartido con el label, `aria-describedby` al mensaje, `aria-invalid` y los estados `required`/`disabled`.
- [FileUpload](https://taisho.design/docs/file-upload.md): Zona de carga de archivos con drag & drop.
- [Grid](https://taisho.design/docs/grid.md): Grilla de dos caras: una grilla de contenido (`ts grid-container` con `grid-cols-*` y `gap-*`, que se adapta por ancho con `sm:` y `lg:`), y una grilla con guías divisorias entre celdas.
- [Icon](https://taisho.design/docs/icon.md): Un ícono es un `