ds-terminal-theme

Sistema de diseño a tema de Apple Terminal

Este skill crea perfiles de Terminal.app (archivos .terminal) a partir de un sistema de diseño. El código hace el trabajo: scripts/ds2terminal.py (Python 3.9 o superior, solo librería estándar). El código también verifica la legibilidad. Un tema está completo solo cuando todas las puertas estrictas pasan.

Reglas

• No elijas colores por gusto. Ejecuta el script. El script mapea los colores y los verifica.
• No edites un archivo .terminal a mano. Usa --set o --prefer-token, luego vuelve a ejecutar el script.
• Ejecuta Python con -I. Los archivos descargados son datos, no código.
• No abras (importes) un archivo .terminal a menos que el usuario lo solicite. Abrir un archivo agrega un perfil a Terminal y abre una ventana.
• No cierres ni mates Terminal. No ejecutes defaults write com.apple.Terminal.
• No publiques los tokens privados del usuario.

Paso 1: Obtener los archivos del sistema de diseño

Identifica el tipo de enlace. Luego realiza el paso correspondiente en la tabla.

Enlace	Qué hacer
Archivo o carpeta local	Proporciona la ruta al script.
Repositorio público de GitHub, árbol o archivo; paquete npm; URL de unpkg o jsDelivr; archivo raw	Proporciona la URL al script. El script encuentra y descarga los archivos de tokens.
Documentación pública o página de marketing	Proporciona la URL al script. Lee el CSS vinculado. El resultado puede ser débil; informa al usuario.
Artefacto de sistema de diseño de claude.ai (claude.ai/artifact/...)	Usa la herramienta Artifact: action: "list", scope: "files". Luego action: "read" con path para cada archivo de token que exista: project/tokens.json, project/tokens.css, project/tokens/tokens.json y project/tokens/colors.css. Guarda los archivos en una carpeta. Proporciona la carpeta al script.
Sistema de diseño Pidgin	Usa pidgin_get_design_system. Guarda su objeto tokens como un archivo .json. Proporciona el archivo al script.
Proyecto de diseño Claude	Usa mcp__claude-design__list_files y read_file para los archivos de tokens. Guárdalos. Proporciona la carpeta al script.
Archivo de Figma	Usa las herramientas de Figma (variables) cuando estén conectadas. Si no, pide al usuario una exportación de variables (JSON).

Si el script se detiene con el código de salida 2 y el mensaje menciona una herramienta, realiza el paso para ese tipo de enlace. Consulta references/sources.md para conocer los formatos que lee el script.

Paso 2: Ejecutar el script

python3 -I scripts/ds2terminal.py FUENTE [FUENTE ...] --name "Nombre" --out DIR_SALIDA

El script escribe:

• DIR_SALIDA/<Nombre> Light.terminal y DIR_SALIDA/<Nombre> Dark.terminal
• DIR_SALIDA/report.md y DIR_SALIDA/report.json: cada color, su token de origen, APCA Lc, ratio WCAG, resultado de cada puerta y cada reparación
• DIR_SALIDA/preview.html: cada tema dibujado como una ventana de terminal con salida de programa típica

Códigos de salida:

Código	Significado	Qué hacer
0	Todas las puertas estrictas pasan para cada tema.	Ve al paso 3.
1	Una puerta aún falla después de la reparación.	Lee report.md. Indica al usuario qué puerta falla. Intenta --set para ese color. No entregues el tema como completo.
2	Entrada incorrecta, o el enlace necesita una herramienta con sesión iniciada.	Lee el mensaje. Realiza el paso 1 para ese enlace, o corrige la opción.

Opciones

Opción	Uso
--name NOMBRE	Nombre del perfil. Los archivos son <NOMBRE> Light.terminal y <NOMBRE> Dark.terminal. Siempre proporciónalo.
`--modes auto	light
--font NOMBRE, --font-size 13	Fuente (nombre PostScript o de familia). Predeterminado: la fuente monoespaciada del sistema de diseño si está instalada, si no, SF Mono Terminal (incluida en Terminal.app). Tamaño predeterminado: 13 pt.
`--cursor block	underline
--set ROL=HEX	Forzar un color. ROL es bg, fg, bold, cursor, selection, black ... brightWhite, o 0 ... 15. La reparación aún puede cambiarlo para pasar una puerta; el informe lo indica.
--prefer-token ROL=TOKEN	Usar este token para bg, fg, brand, red, green, yellow, blue, magenta o cyan.
--all-tokens	Conservar tokens sin procesar que ningún token semántico usa (ver "Tokens no relacionados").
--source-mode ID	Usar solo este modo del sistema de diseño.
--no-chroma-floor	Mantener los rojos y verdes pastel como pastel en modo oscuro.
--translucent ALPHA	Alfa de fondo por debajo de 1 (por ejemplo, 0.95). Los temas claros necesitan aproximadamente 0.93 o más; un fondo de página gris claro necesita 0.95-0.98, de lo contrario el script lo reemplaza con blanco. Predeterminado: opaco (alfa 1, sin desenfoque). Úsalo solo cuando el usuario lo solicite. Cada puerta debe entonces pasar también sobre un escritorio negro y uno blanco. Si ALPHA es demasiado bajo, el script termina con el código 1. El informe proporciona el alfa más bajo que pasó en una compilación de prueba.
--columns N, --rows N	Tamaño de la ventana.
`--report json	md

Paso 3: Verificar e informar al usuario

1. Lee report.md. Asegúrate de que diga "cada puerta estricta pasa para cada tema".
2. Informa al usuario:
   • las rutas de los archivos .terminal;
   • qué modo está derivado;
   • qué tokens se usaron para el fondo, el texto, el cursor y los seis tonos;
   • las reparaciones (cada color cambiado y la puerta que causó el cambio);
   • los tokens que se omitieron;
   • los objetivos "Character" que no se alcanzaron (la línea "Targets missed" en report.md);
   • la línea "Recommended Claude Code theme" de report.md.
3. Muestra preview.html si el usuario puede abrir archivos.
4. Para instalar un tema, el usuario abre el archivo .terminal (Finder, o open "<file>"). Haz esto solo cuando el usuario lo solicite. Luego el usuario puede configurarlo como predeterminado en Terminal > Preferencias > Perfiles.
5. python3 scripts/demo.py imprime una salida de muestra en los 16 colores, y en texto tenue (SGR 2). Ejecútalo en una ventana que use el tema.
6. Indica al usuario qué tema de Claude Code debe establecer (ver "Uso con Claude Code").

Uso con Claude Code

Claude Code tiene dos tipos de temas. Cada tipo usa el tema de Terminal de una manera diferente.

• Temas ANSI (dark-ansi, light-ansi; en la lista /theme: "Dark mode (ANSI colors only)" y "Light mode (ANSI colors only)"). Claude Code usa los 16 colores ANSI. Dibuja las líneas de diff con fondos de celda verde y rojo ANSI, y dibuja el color del texto sobre esas celdas. En un tema cuyos colores normales son legibles como texto, estas celdas son claras en modo oscuro, por lo que el texto en una línea añadida tiene poco contraste.
• Temas estándar (dark, light). Claude Code usa sus propios colores de 24 bits sobre el fondo del tema. Estos permanecen legibles. Configura el tema por nombre. La configuración auto lee el fondo de la terminal. Terminal 2.15 responde a esa consulta (OSC 11) con el fondo del tema, tanto en modo claro como oscuro, por lo que auto puede seleccionar el modo correcto. Esto no se verificó en una sesión de Claude Code en ejecución. De los elementos del tema de Terminal que Claude Code utiliza, se verifican el fondo, el cursor, la selección y el texto tenue. Los 16 colores son para otros programas.

El informe tiene una sección "Claude Code" para cada tema. Proporciona el contraste de 16 pares para el tema ANSI y para el tema estándar, y una línea "Recommended Claude Code theme". La regla: el tema ANSI cuando su par de texto más débil tiene Lc 45 o más; de lo contrario, el tema estándar cuando es mejor. preview.html dibuja ambas muestras. Las tablas provienen del archivo de programa Claude Code 2.1.323. No se verificaron contra una sesión en ejecución.

Indica al usuario que haga lo siguiente:

1. Lee la línea "Recommended Claude Code theme" en report.md para el tema en uso.
2. En Claude Code, escribe /theme y selecciona ese tema. O configura el ajuste theme en el archivo settings.json de Claude Code, por ejemplo "theme": "dark-ansi".

Si el modo del tema de Claude Code y el modo del tema de Terminal son diferentes (por ejemplo, un tema claro de Claude Code en un tema oscuro de Terminal), el texto puede volverse ilegible. Un fondo de Terminal translúcido también hace que el texto sea ilegible. Advierte al usuario sobre ambos casos.

Cómo funciona el mapeo

1. Modos. La luminosidad del fondo establece el modo (OKLab L < 0.5 es oscuro). El script no usa nombres de modo. Los sistemas de diseño pueden llamar "temas" a los tamaños de pantalla (por ejemplo root-tablet). Los modos del mismo tipo se convierten en un tema; el informe enumera los otros.
2. Tokens no relacionados. Cuando un sistema de diseño tiene 4 o más alias semánticos (por ejemplo color-brand -> hb-pink), los tokens sin procesar que ningún alias usa y que no comparten el prefijo del nombre del sistema se omiten. Estos suelen ser colores de un cliente o de una marca antigua.
3. Roles. Los alias semánticos ganan. El fondo de la página es el fondo. En modo claro, cuando el sistema de diseño también tiene una superficie de tarjeta más clara, esa superficie es el fondo: el texto está sobre las tarjetas, y el color de la página está detrás de ellas. --prefer-token bg=TOKEN selecciona un token diferente. El token del texto del cuerpo es el color del texto. El token de la marca es el cursor y tiñe la selección. Cuando el color de la marca es demasiado débil para un cursor sobre el fondo, se usa un paso de la rampa de la marca que pase WCAG 4.5 como cursor (por ejemplo, un naranja accesible).
4. Tonos. Una asignación de costo mínimo coloca los tokens en las seis ranuras de tono. Utiliza el tono OKLCH, el nombre del token (danger -> rojo, success -> verde, warning -> amarillo, info -> azul) y el cambio de luminosidad. Un nombre cuenta solo cuando el tono está dentro de los 45 grados de esa ranura.
5. Luminosidad. Cada color se mueve (conservando tono y croma) hacia la banda APCA de su modo. Un token en la banda permanece exacto.
6. Colores faltantes. Las ranuras vacías reciben tonos amigables para el daltonismo con el croma de la marca.
7. Modo oscuro derivado. El token de texto claro o tinta se convierte en el fondo oscuro. El papel claro se convierte en el texto oscuro.
8. Carácter. El tema debe verse como su sistema de diseño, dentro de las puertas.
   • Ranura de marca: cuando ningún color de tono muestra el color de la marca, el color de la marca se convierte en el paso brillante del tono más cercano (dentro de 26 grados). Su luminosidad se mueve al objetivo brillante.
   • Negrita: un token de texto de encabezado es el color de negrita cuando es más fuerte que el texto. En modo oscuro sin uno, la negrita es el color del texto, hasta Lc 4 más brillante, por debajo de la puerta de halación.
   • Límite inferior del modo oscuro para cada tono (Lc): rojo 50, verde 72, amarillo 62, azul 55, magenta 55, cian 60.
   • Un color de tono de token por debajo de WCAG 3 después del ajuste de luminosidad se mueve a WCAG 3.
   • La sección del informe "Character" enumera objetivos, no puertas: colores de tokens, color de marca, croma conservado (objetivo 70% o más), cambio de tono más grande (12 grados o menos), paso más pequeño de normal a brillante (dE 0.030 o más), y una línea "Targets missed".
9. Reparación. Si falla una puerta estricta, el script cambia el color con la prioridad más baja, en pasos pequeños: luminosidad, luego tono y croma, luego un color sintetizado. Prioridad: --set > marca > token nombrado > token > derivado > sintetizado. Si el fondo no puede soportar texto legible, el script mapea cada color nuevamente sobre un fondo estándar. El informe lo indica.

Puertas de legibilidad (estrictas)

references/gates.md proporciona cada puerta, su límite y la razón. Resumen:

Puerta	Fallo cuando
Texto sobre fondo	APCA Lc < 75 o WCAG < 7
Halación (oscuro)	texto, negrita, blanco o blanco brillante Lc > 104
ANSI 1-6 y 9-14	Lc < 45 o WCAG < 3
Negro brillante (color 8)	Lc < 30, o menor que 15 por debajo del texto
Grises	oscuro: blanco y blanco brillante Lc < 60; claro: negro Lc < 75, blanco y blanco brillante Lc < 30
Separación	dos colores de tono más cercanos que dE(OKLab) 0.06
Daltonismo	rojo/verde < 0.06, rojo/amarillo y rojo/magenta < 0.05 (protan, deutan)
Selección	texto sobre ella WCAG < 4.5 o Lc < 60; un color de tono sobre ella Lc < 30; dE del fondo < 0.05 o WCAG < 1.10
Cursor	WCAG < 3
Negrita	la negrita es más tenue que el texto
Texto sobre color	texto negro sobre verde, amarillo o cian Lc < 30
Tono vs texto	un color de tono más cercano que dE 0.06 al color del texto
Texto tenue (SGR 2)	texto tenue Lc < 30; un color de tono tenue (1-6, 9-14) Lc < 15
Translucidez	solo con --translucent: una puerta anterior falla sobre un escritorio negro o blanco

El texto tenue es el color mezclado hacia el fondo de la celda (colorlab.faint, DIM_BLEND 0.60, DIM_POWER 1.26). Esto se midió en Terminal 2.15 (docs/faint-measurement.md). El texto tenue real es débil, por lo que los límites son bajos. Los colores de tono oscuro conservan su croma. Un usuario puede aumentar GATES["faint_text"]["gate"]["ansi_min_lc"] para colores tenues más fuertes, a costa del croma.

Limitaciones conocidas

• Los programas que usan color de 24 bits (Terminal establece COLORTERM=truecolor) no usan el tema. Para Claude Code, configura el tema que recomienda el informe (ver "Uso con Claude Code").
• Aún no medido: color de negrita y cómo Terminal dibuja los fondos de celda en una ventana translúcida. El renderizado de un tema generado en Terminal (color de negrita, selección) aún no se ha verificado.
• El script escribe un fondo opaco. Un fondo translúcido deja ver el escritorio y hace que el texto sea menos legible.
• Terminal no tiene un color para el texto seleccionado o para el texto bajo el cursor. Las puertas verifican el texto sobre la selección y el cursor en su lugar.
• El formato de color .terminal está en references/terminal-format.md. En una Mac, los archivos incrustan el perfil ICC sRGB. En otros sistemas, solo contienen el ID del espacio de color sRGB (se decodifica igual).
• scripts/verify_terminal.swift (solo Mac) decodifica cada color con AppKit: swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal, luego scripts/verify_terminal --register-terminal-fonts "<file>.terminal".