--- title: "Tu propio sistema de diseño" description: "Mantén un único archivo de capa en tu producto. Un solo comando escribe los tokens y el código de todas las plataformas que publicas, en un solo pull request." url: "https://tanrei.chnotchy.com/es/getting-started/your-design-system/" last_updated: 2026-10-23T21:16:42.000Z --- # Tu propio sistema de diseño > Mantén un único archivo de capa en tu producto. Un solo comando escribe los tokens y el código de todas las plataformas que publicas, en un solo pull request. Los componentes de Tanrei no cambian cuando cambia el aspecto de tu producto. Lo que cambia es una **capa**: un pequeño archivo JSON que da valores al vocabulario compartido y declara tus paletas. `@tanrei/cli` convierte ese único archivo en todo lo que necesita cada plataforma. > [!WARNING] > **Prelanzamiento** > > `0.1.0-next.0` está publicado en npm con la etiqueta de distribución (dist-tag) `next`: hasta `0.1.0`, instala `@tanrei/cli@next` y `@tanrei/mcp@next`. Durante los prelanzamientos 0.x no se mantiene la compatibilidad con versiones anteriores: cualquier prelanzamiento puede romper cualquier cosa, sin un periodo de obsolescencia previo, y su changeset dice qué se rompió. ## Instalación ### Desde npm Añade la herramienta de línea de comandos a tu producto como dependencia de desarrollo; cada comando `npx tanrei …` de esta página ejecuta entonces esa copia. Incluye Theme Studio, que sirve `tanrei studio`. ```sh npm install --save-dev @tanrei/cli ``` El servidor MCP no necesita instalación: `npx` descarga `@tanrei/mcp` cuando un agente lo inicia, tal como se registra más abajo en esta página. ### Desde el código fuente Para usar el código fuente tal como está en `main`, compila los dos paquetes en un clon del repositorio e instala los archivos empaquetados en tu producto como dependencias de desarrollo: ```sh git clone https://github.com/chnotchy/tanrei.git cd tanrei pnpm install pnpm --filter @tanrei/studio build:app # Theme Studio, que sirve `tanrei studio` pnpm --filter @tanrei/cli --filter @tanrei/mcp build pnpm --filter @tanrei/cli --filter @tanrei/mcp pack --pack-destination ../tanrei-packages ``` ```sh # en tu producto: la ruta a la carpeta en la que se escribieron los paquetes npm install --save-dev path/to/tanrei-packages/tanrei-cli-*.tgz path/to/tanrei-packages/tanrei-mcp-*.tgz ``` Para el servidor MCP, registra en su lugar la copia instalada: `claude mcp add tanrei -- npx tanrei-mcp`, ejecutado en la carpeta de tu producto. ## De una capa a cada plataforma 1. **Crea una capa**, a partir del sistema predeterminado o de un preajuste. ```bash npx tanrei init acme --extends tanrei ``` Esto escribe `design/acme.system.json` y `tanrei.json`. ¿Prefieres los controles deslizantes? Da forma a la capa en [Theme Studio](https://tanrei.chnotchy.com/es/foundations/theme-studio/) y descárgala. 2. **Indica adónde va cada salida** en `tanrei.json`. Enumera solo lo que publicas. ```json { "system": "design/acme.system.json", "kotlinPackage": "com.acme.design", "outputs": { "tokens": "design/tokens/acme", "web": "apps/web/src/styles", "swiftui": "apps/ios/Acme/Design", "compose": "apps/android/app/src/main/kotlin/com/acme/design", "flutter": "apps/flutter/lib/design", "react-native": "apps/mobile/src/design" } } ``` 3. **Compila.** ```bash npx tanrei build ``` Confirma el resultado en tu repositorio. Añade `npx tanrei build --check` a la CI: no escribe nada y falla cuando una salida confirmada está desactualizada. 4. **Úsalo.** Los archivos generados contienen los _valores_ de tu sistema; los tipos vienen de la biblioteca, de modo que un cambio en el vocabulario rompe la compilación en lugar de desviarse en silencio. | Plataforma | Obtienes | Escribes | | --- | --- | --- | | Web | `acme.css` | `` | | SwiftUI | `TanreiSystem+Acme.swift` | `.tanreiTheme(TanreiTheme(system: .acme))` | | Compose | `TanreiSystemAcme.kt` | `TanreiTheme(system = TanreiSystem.Acme) { … }` | | Flutter | `acme_system.g.dart` | `TanreiTheme(data: TanreiThemeData.platform(context, system: acmeSystem), …)` | | React Native | `acme.ts` | `` | ## Un cambio, un pull request Edita un valor en la capa, ejecuta `tanrei build`, y el archivo de cada plataforma cambia en el mismo commit. Hacer todo el texto un poco más grande es una sola línea: ```json "tanrei.dial.type.base": { "$value": { "value": 17, "unit": "px" }, "reason": "Se lee a la distancia de un brazo." } ``` Consulta [Sistemas de diseño y personalización](https://tanrei.chnotchy.com/es/foundations/design-systems/) para conocer las cuatro cosas que una capa puede hacer con un valor (ajustar un dial, escalar un token, reorientar un alias o fijar un valor con un motivo), para declarar paletas como un color de marca o el _correcto_ y el _incorrecto_ de un cuestionario, y para [añadir tokens](https://tanrei.chnotchy.com/es/foundations/design-systems/#a%C3%B1adir-al-vocabulario) cuando los valores no bastan. ## Tanto control como quieras, siempre en el mismo archivo La personalización tiene niveles, y todos editan el mismo `.system.json`: | Quieres | Usas | | --- | --- | | Una configuración rápida | **Theme Studio → la columna de la izquierda**: las nueve filas del aspecto (color de marca, gris, tipo de letra, tamaño, esquinas, suavizado de esquinas, iconos, respuesta al pulsar y foco), cada una a un clic, con bloqueo y mezcla | | Ajustar por grupos | **Studio → «Más», en esa columna**: los ocho diales, todas las paletas, cada componente y cada comportamiento | | Tocar los tokens uno a uno, en una interfaz gráfica | **Studio → Inspeccionar → Tokens**: busca en todo el vocabulario; cada token ofrece solo las ediciones que le son válidas y muestra qué depende de él | | Editar el código fuente | **Studio → Inspeccionar → Código fuente**, o tu editor: el JSON, validado con el esquema y por el motor | | Un token que no existe | [Añádelo](https://tanrei.chnotchy.com/es/foundations/design-systems/#a%C3%B1adir-al-vocabulario): un paso en una serie, un tamaño o una variante de Button en una línea, o tokens propios | ```bash npx tanrei studio ``` abre Theme Studio **sobre tu archivo de capa**: las ediciones se guardan en él a medida que las haces (revísalas con git como cualquier otro cambio), nunca se sobrescribe una edición hecha al mismo tiempo en tu editor, y «Build» ejecuta `tanrei build`. Solo escucha en `127.0.0.1`, y el enlace que imprime lleva una clave de un solo uso. El Studio de este sitio es la misma herramienta, con importación y exportación en lugar de un archivo. ## Comprobar el código con tu sistema ```bash npx tanrei audit src ``` lee el código de tu producto —scripts (JS, TS, JSX), marcado (HTML, Vue, Svelte, Astro) y hojas de estilo (CSS, Sass, Less)— e informa de lo que tu sistema no tiene, cada caso con su archivo, línea y columna, y con lo que conviene escribir en su lugar: - un elemento de un componente que el sistema no tiene —`` en una página, una plantilla, JSX o una cadena, un envoltorio de React importado, o un selector CSS que lo nombra—, con los componentes que el sistema ofrece para la misma tarea, los sistemas que lo tienen y la línea de tu capa que lo incorporaría; - una importación desde un punto de entrada que no corresponde al sistema —`@tanrei/web/m3-like` o `@tanrei/react/all` en un producto del sistema predeterminado—, con el que sí corresponde; - un `variant="…"` escrito que el sistema deja fuera, con los valores que ofrece. Compara con el sistema de tu producto (`tanrei.json`) o con el que indique `--system`: un sistema incluido, como `m3-like`, o un archivo de capa. Pásale archivos, directorios o un glob entre comillas (`'src/**/*.{ts,tsx,html,css}'`); un directorio se lee sin `node_modules` ni los directorios ocultos. `--format json` imprime los resultados como datos. Termina con el código 1 cuando encuentra algo, así que puede ejecutarse en CI junto a `tanrei build --check`, y con 2 cuando no puede ejecutarse. El `check_usage` del servidor MCP hace la misma comprobación. Lee el texto, no una página en ejecución: omite los comentarios, pero no ve una variante guardada en una variable ni una etiqueta formada a partir de trozos. ## Tailwind CSS y shadcn/ui Añade `"tailwind"` o `"shadcn"` a `outputs`. Ambos archivos solo **hacen corresponder nombres** con las propiedades personalizadas de Tanrei, así que los temas, los niveles de contraste y los diales en vivo siguen funcionando por debajo. ```css @import "tailwindcss"; @import "@tanrei/web/tokens.css"; @import "./styles/acme.css"; @import "./styles/acme.tailwind.css"; /* bg-primary · text-on-primary · rounded-medium · p-200 · text-heading-4 */ ``` ## Compartir un sistema con personas, herramientas y agentes de IA - La salida `tokens` es un paquete **DTCG 2025.10** autocontenido, con un resolver estándar. Cualquier herramienta de tokens de diseño puede leerlo; los archivos de capa que lo produjeron viajan dentro, y cada grupo lleva indicaciones de uso para agentes en `$extensions["dev.tanrei.llm"]`. - También contiene `components.json`, los componentes que su sistema incluye: cada uno con su elemento (o clase), su nombre en React y el módulo que lo registra, y los componentes que no tiene, con la capa que dejó fuera cada uno y qué usar en su lugar. Un agente que lo lee sugiere solo componentes que su producto puede usar. Cada sistema incluido con Tanrei tiene también el suyo: `@tanrei/web/systems/.components.json`. - `@tanrei/mcp` es un servidor de [Model Context Protocol](https://modelcontextprotocol.io/). Un agente que trabaje en tu repositorio puede buscar en el vocabulario, ver de dónde viene un valor, comparar sistemas, **proponer una extensión** (un nuevo tamaño de Button, un paso, un token propio) con los valores que resultan, y **validar una edición de la capa antes de escribirla**. Además, se le comunican las reglas: cambiar los valores a través de una capa, extender el vocabulario solo añadiendo y con una justificación, dar un motivo a cada valor fijado y no tocar nunca un umbral. Para la interfaz misma responde desde el manifiesto de componentes del sistema y las especificaciones: **qué componentes tiene el sistema** (y, para uno que no tiene, qué usar en su lugar), las props, los eventos y las reglas de comportamiento de un componente, y **qué elementos, importaciones y variantes de tu código no tiene el sistema**, con dónde están: la misma comprobación que hace `tanrei audit`. Regístralo desde npm, en la carpeta de tu producto ([Usar Tanrei con agentes de IA](https://tanrei.chnotchy.com/es/getting-started/ai-agents/) tiene la configuración para otros clientes): ```bash claude mcp add tanrei -- npx -y @tanrei/mcp ``` > [!WARNING] > **Accesibilidad** > > Los umbrales de contraste y las comprobaciones estructurales son constantes. En tu capa, un incumplimiento es una advertencia, nunca silenciosa: `tanrei build` la imprime, se escribe en `a11y-report.json` y se estampa al principio de cada archivo generado. En los contrastes medio y alto, aspira a cero: esos esquemas existen porque una persona pidió contraste. A los preajustes incluidos, por su parte, se les exige fidelidad a los sistemas que imitan, no los criterios de accesibilidad de Tanrei, en todos los esquemas; sus mediciones son información. Una capa que construyes sobre un preajuste sigue siendo tu producto, y también recibe advertencias por lo que hereda.