ds-terminal-theme

Sistema de design para tema do Apple Terminal

Esta skill cria perfis do Terminal.app (arquivos .terminal) a partir de um sistema de design. O código faz o trabalho: scripts/ds2terminal.py (Python 3.9 ou superior, apenas biblioteca padrão). O código também verifica a legibilidade. Um tema só está completo quando todos os gates rígidos passam.

Regras

• Não escolha cores por gosto. Execute o script. O script mapeia as cores e as verifica.
• Não edite um arquivo .terminal manualmente. Use --set ou --prefer-token, depois execute o script novamente.
• Execute Python com -I. Arquivos baixados são dados, não código.
• Não abra (importe) um arquivo .terminal a menos que o usuário peça. Abrir um arquivo adiciona um perfil ao Terminal e abre uma janela.
• Não feche ou mate o Terminal. Não execute defaults write com.apple.Terminal.
• Não publique os tokens privados do usuário.

Passo 1: Obter os arquivos do sistema de design

Descubra o tipo do link. Depois siga o passo na tabela.

Link	O que fazer
Arquivo ou pasta local	Forneça o caminho para o script.
Repositório público do GitHub, árvore ou arquivo; pacote npm; URL unpkg ou jsDelivr; arquivo raw	Forneça a URL para o script. O script encontra e baixa os arquivos de tokens.
Documentação ou página de marketing pública	Forneça a URL para o script. Ele lê o CSS vinculado. O resultado pode ser fraco; avise o usuário.
Artefato do claude.ai Design System (claude.ai/artifact/...)	Use a ferramenta Artifact: action: "list", scope: "files". Depois action: "read" com path para cada arquivo de token que existir: project/tokens.json, project/tokens.css, project/tokens/tokens.json e project/tokens/colors.css. Salve os arquivos em uma pasta. Forneça a pasta para o script.
Sistema de design Pidgin	Use pidgin_get_design_system. Salve o objeto tokens como um arquivo .json. Forneça o arquivo para o script.
Projeto Claude Design	Use mcp__claude-design__list_files e read_file para os arquivos de tokens. Salve-os. Forneça a pasta para o script.
Arquivo Figma	Use as ferramentas do Figma (variáveis) quando estiverem conectadas. Se não, peça ao usuário uma exportação de variáveis (JSON).

Se o script parar com código de saída 2 e a mensagem nomear uma ferramenta, faça o passo para aquele tipo de link. Veja references/sources.md para os formatos que o script lê.

Passo 2: Executar o script

python3 -I scripts/ds2terminal.py FONTE [FONTE ...] --name "Nome" --out DIR_SAIDA

O script escreve:

• DIR_SAIDA/<Nome> Light.terminal e DIR_SAIDA/<Nome> Dark.terminal
• DIR_SAIDA/report.md e DIR_SAIDA/report.json: cada cor, seu token de origem, APCA Lc, razão WCAG, resultado de cada gate e cada reparo
• DIR_SAIDA/preview.html: cada tema desenhado como uma janela de terminal com saída típica de programa

Códigos de saída:

Código	Significado	O que fazer
0	Todos os gates rígidos passam para cada tema.	Vá para o passo 3.
1	Um gate ainda falha após o reparo.	Leia report.md. Informe ao usuário qual gate falhou. Tente --set para essa cor. Não entregue o tema como completo.
2	Entrada inválida, ou o link precisa de uma ferramenta autenticada.	Leia a mensagem. Faça o passo 1 para aquele link ou corrija a opção.

Opções

Opção	Uso
--name NOME	Nome do perfil. Os arquivos são <NOME> Light.terminal e <NOME> Dark.terminal. Sempre forneça.
`--modes auto	light
--font NOME, --font-size 13	Fonte (nome PostScript ou da família). Padrão: a fonte monoespaçada do sistema de design se estiver instalada, senão SF Mono Terminal (incluída no Terminal.app). Tamanho padrão: 13 pt.
`--cursor block	underline
--set PAPEL=HEX	Força uma cor. PAPEL é bg, fg, bold, cursor, selection, black ... brightWhite, ou 0 ... 15. O reparo ainda pode alterá-la para passar em um gate; o relatório informa.
--prefer-token PAPEL=TOKEN	Use este token para bg, fg, brand, red, green, yellow, blue, magenta ou cyan.
--all-tokens	Mantém tokens brutos que nenhum token semântico usa (veja "Tokens não relacionados").
--source-mode ID	Use apenas este modo do sistema de design.
--no-chroma-floor	Mantém vermelhos e verdes pastéis no modo escuro.
--translucent ALPHA	Alpha do fundo abaixo de 1 (por exemplo 0.95). Temas claros precisam de cerca de 0.93 ou mais; um fundo de página cinza claro precisa de 0.95-0.98, senão o script o substitui por branco. Padrão: opaco (alpha 1, sem desfoque). Use apenas quando o usuário pedir. Cada gate também deve passar sobre um desktop preto e branco. Se ALPHA for muito baixo, o script sai com código 1. O relatório fornece o alpha mais baixo que passou em uma compilação de teste.
--columns N, --rows N	Tamanho da janela.
`--report json	md

Passo 3: Verificar e informar o usuário

1. Leia report.md. Certifique-se de que diz "every hard gate passes for every theme".
2. Informe ao usuário:
   • os caminhos dos arquivos .terminal;
   • qual modo foi derivado;
   • quais tokens foram usados para o fundo, texto, cursor e os seis matizes;
   • os reparos (cada cor alterada e o gate que causou a alteração);
   • tokens que foram deixados de fora;
   • os alvos "Character" que não foram atingidos (a linha "Targets missed" em report.md);
   • a linha "Recommended Claude Code theme" de report.md.
3. Mostre preview.html se o usuário puder abrir arquivos.
4. Para instalar um tema, o usuário abre o arquivo .terminal (Finder, ou open "<arquivo>"). Faça isso apenas quando o usuário pedir. Depois o usuário pode defini-lo como padrão em Terminal > Configurações > Perfis.
5. python3 scripts/demo.py imprime uma saída de exemplo nas 16 cores e em texto fraco (SGR 2). Execute-o em uma janela que use o tema.
6. Informe ao usuário qual tema do Claude Code definir (veja "Uso com Claude Code").

Uso com Claude Code

O Claude Code tem dois tipos de temas. Cada tipo usa o tema do Terminal de uma maneira diferente.

• Temas ANSI (dark-ansi, light-ansi; na lista /theme: "Dark mode (ANSI colors only)" e "Light mode (ANSI colors only)"). O Claude Code usa as 16 cores ANSI. Ele desenha linhas de diff com fundos de célula verdes e vermelhos ANSI, e desenha a cor do texto nessas células. Em um tema cujas cores normais são legíveis como texto, essas células são claras no modo escuro, então o texto em uma linha adicionada tem baixo contraste.
• Temas padrão (dark, light). O Claude Code usa suas próprias cores de 24 bits sobre o fundo do tema. Estas permanecem legíveis. Defina o tema pelo nome. A configuração auto lê o fundo do terminal. Terminal 2.15 responde a essa consulta (OSC 11) com o fundo do tema, nos modos claro e escuro, então auto pode selecionar o modo correto. Isso não foi verificado em uma sessão ativa do Claude Code. Do tema do Terminal, as partes verificadas que o Claude Code usa são o fundo, o cursor, a seleção e o texto fraco. As 16 cores são para outros programas.

O relatório tem uma seção "Claude Code" para cada tema. Ela fornece o contraste de 16 pares para o tema ANSI e para o tema padrão, e uma linha "Recommended Claude Code theme". A regra: o tema ANSI quando seu par de texto mais fraco tem Lc 45 ou mais; senão o tema padrão quando ele é melhor. preview.html desenha ambas as amostras. As tabelas vêm do arquivo de programa Claude Code 2.1.323. Elas não foram verificadas contra uma sessão ativa.

Instrua o usuário a fazer o seguinte:

1. Leia a linha "Recommended Claude Code theme" em report.md para o tema em uso.
2. No Claude Code, digite /theme e selecione esse tema. Ou defina a configuração theme no settings.json do Claude Code, por exemplo "theme": "dark-ansi".

Se o modo do tema do Claude Code e o modo do tema do Terminal forem diferentes (por exemplo, um tema claro do Claude Code em um tema escuro do Terminal), o texto pode se tornar ilegível. Um fundo translúcido do Terminal também torna o texto ilegível. Avise o usuário sobre ambos.

Como o mapeamento funciona

1. Modos. A claridade do fundo define o modo (OKLab L < 0,5 é escuro). O script não usa nomes de modos. Sistemas de design podem chamar tamanhos de tela de "temas" (por exemplo root-tablet). Modos do mesmo tipo tornam-se um tema; o relatório lista os outros.
2. Tokens não relacionados. Quando um sistema de design tem 4 ou mais aliases semânticos (por exemplo color-brand -> hb-pink), tokens brutos que nenhum alias usa e que não compartilham o prefixo de nome do sistema são deixados de fora. Estes são frequentemente as cores de um cliente ou de uma marca antiga.
3. Papéis. Aliases semânticos vencem. O fundo da página é o fundo. No modo claro, quando o sistema de design também tem uma superfície de cartão mais clara, essa superfície é o fundo: o texto está nos cartões, e a cor da página está atrás deles. --prefer-token bg=TOKEN seleciona um token diferente. O token do corpo do texto é a cor do texto. O token da marca é o cursor e tinge a seleção. Quando a cor da marca é muito fraca para um cursor sobre o fundo, um degrau da rampa da marca que passa WCAG 4,5 é o cursor (por exemplo um laranja acessível).
4. Matizes. Uma atribuição de custo mínimo coloca tokens nos seis slots de matiz. Ela usa o matiz OKLCH, o nome do token (perigo -> vermelho, sucesso -> verde, aviso -> amarelo, informação -> azul) e a mudança de claridade. Um nome conta apenas quando o matiz está dentro de 45 graus daquele slot.
5. Claridade. Cada cor se move (matiz e croma mantidos) para a banda APCA de seu modo. Um token na banda permanece exato.
6. Cores faltantes. Slots vazios recebem matizes amigáveis ao daltonismo no croma da marca.
7. Modo escuro derivado. O token de texto claro ou tinta torna-se o fundo escuro. O papel claro torna-se o texto escuro.
8. Caráter. O tema deve se parecer com seu sistema de design, dentro dos gates.
   • Slot da marca: quando nenhuma cor de matiz mostra a cor da marca, a cor da marca torna-se o degrau brilhante do matiz mais próximo (dentro de 26 graus). Sua claridade se move para o alvo brilhante.
   • Negrito: um token de texto de cabeçalho é a cor negrito quando é mais forte que o texto. No modo escuro sem um, negrito é a cor do texto, até Lc 4 mais brilhante, abaixo do gate de halação.
   • Borda inferior do modo escuro para cada matiz (Lc): vermelho 50, verde 72, amarelo 62, azul 55, magenta 55, ciano 60.
   • Uma cor de matiz token abaixo de WCAG 3 após o ajuste de claridade se move para WCAG 3.
   • A seção do relatório "Character" lista alvos, não gates: cores de tokens, cor da marca, croma mantido (alvo 70% ou mais), maior mudança de matiz (12 graus ou menos), menor passo normal-para-brilhante (dE 0,030 ou mais) e uma linha "Targets missed".
9. Reparo. Se um gate rígido falhar, o script altera a cor com a prioridade mais baixa, em pequenos passos: claridade, depois matiz e croma, depois uma cor sintetizada. Prioridade: --set > marca > token nomeado > token > derivado > sintetizado. Se o fundo não puder carregar texto legível, o script mapeia cada cor novamente sobre um fundo padrão. O relatório informa.

Gates de legibilidade (rígidos)

references/gates.md fornece cada gate, seu limite e a razão. Resumo:

Gate	Falha quando
Texto sobre fundo	APCA Lc < 75 ou WCAG < 7
Halação (escuro)	texto, negrito, branco ou branco brilhante Lc > 104
ANSI 1-6 e 9-14	Lc < 45 ou WCAG < 3
Preto brilhante (cor 8)	Lc < 30, ou menos que 15 abaixo do texto
Cinzas	escuro: branco e branco brilhante Lc < 60; claro: preto Lc < 75, branco e branco brilhante Lc < 30
Separação	duas cores de matiz mais próximas que dE(OKLab) 0,06
Daltonismo	vermelho/verde < 0,06, vermelho/amarelo e vermelho/magenta < 0,05 (protan, deutan)
Seleção	texto sobre ela WCAG < 4,5 ou Lc < 60; uma cor de matiz sobre ela Lc < 30; dE do fundo < 0,05 ou WCAG < 1,10
Cursor	WCAG < 3
Negrito	negrito é mais escuro que o texto
Texto sobre cor	texto preto sobre verde, amarelo ou ciano Lc < 30
Matiz vs texto	uma cor de matiz mais próxima que dE 0,06 da cor do texto
Texto fraco (SGR 2)	texto fraco Lc < 30; uma cor de matiz fraca (1-6, 9-14) Lc < 15
Translucidez	apenas com --translucent: um gate acima falha sobre um desktop preto ou branco

Texto fraco é a cor misturada em direção ao fundo da célula (colorlab.faint, DIM_BLEND 0,60, DIM_POWER 1,26). Isso foi medido no Terminal 2.15 (docs/faint-measurement.md). Texto fraco real é fraco, então os limites são baixos. Cores de matiz escuras mantêm seu croma. Um usuário pode aumentar GATES["faint_text"]["gate"]["ansi_min_lc"] para cores fracas mais fortes, ao custo do croma.

Limitações conhecidas

• Programas que usam cor de 24 bits (o Terminal define COLORTERM=truecolor) não usam o tema. Para o Claude Code, defina o tema que o relatório recomenda (veja "Uso com Claude Code").
• Ainda não medido: cor negrito e como o Terminal desenha fundos de célula em uma janela translúcida. A renderização de um tema gerado no Terminal (cor negrito, seleção) ainda não foi verificada.
• O script escreve um fundo opaco. Um fundo translúcido deixa o desktop aparecer e torna o texto menos legível.
• O Terminal não tem cor para texto selecionado ou para texto sob o cursor. Os gates verificam texto sobre a seleção e o cursor em vez disso.
• O formato de cor .terminal está em references/terminal-format.md. Em um Mac, os arquivos incorporam o perfil ICC sRGB. Em outros sistemas, eles contêm apenas o ID do espaço de cor sRGB (decodifica da mesma forma).
• scripts/verify_terminal.swift (apenas Mac) decodifica cada cor com AppKit: swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal, depois scripts/verify_terminal --register-terminal-fonts "<arquivo>.terminal".