Temas

Um tema é a aparência do app. Ele define as cores, as tipografias, o formato dos controles, a sensação da página e as cores do terminal. É um arquivo JSON pequeno. O Collie inclui quatro. Você pode importar outros a partir de um arquivo, e pode exportar qualquer tema para copiar e editar. Um tema é uma configuração de um dispositivo, mantida naquele navegador, e não altera nada na bridge.

Todo tema tem duas metades. A metade clara é o conjunto de cores para o modo claro. A metade escura é o conjunto para o modo escuro. Uma cor em um tema tem um nome, como background ou primary, e esse nome é um token.

Os quatro temas

O Collie inclui quatro temas, e três deles usam todas as partes de um arquivo de tema. Cada imagem mostra o Dashboard, claro à esquerda e escuro à direita.

• —
  Collie é a aparência que o app sempre teve. É o padrão, e escolhê-lo remove qualquer tema ativo. Ele não define formato, aparência ou paleta, portanto cada palavra dele é a palavra padrão de sua lista.

  !O tema Collie no Dashboard, claro e escuro.

• —
  Nightwatch é para o celular de plantão na cama. A metade escura é preto puro com um âmbar suave, e a metade clara é um papel quente de entardecer. É quadrado e plano, com linhas pesadas, texto em negrito e uma faixa âmbar suave atrás do cabeçalho e das barras. O terminal exibe uma paleta âmbar sobre preto puro.

  !O tema Nightwatch no Dashboard, claro e escuro.

• —
  Daylight é para sol direto e baixa visão. O texto do corpo tem contraste de 7:1 ou superior, as bordas são mais fortes, e bloqueado é laranja enquanto concluído é azul, para que os dois fiquem distintos sem vermelho e verde. Tem cantos arredondados, linhas como cards destacados em uma página que escurece em direção ao rodapé no modo claro e clareia no escuro, e espaçamentos mais amplos. O terminal exibe uma paleta vívida e de alto contraste.

  !O tema Daylight no Dashboard, claro e escuro.

• —
  Harbour é para pessoas que vivem em um terminal. Um azul-acinzentado frio com um destaque teal, na linha do Nord e Solarized, e cores de código fáceis de ler como em um editor. Tem cantos suaves, uma textura fina sob a página e ícones finos. O terminal exibe uma paleta baseada no Solarized.

  !O tema Harbour no Dashboard, claro e escuro.

A tabela lista cada palavra que cada tema usa. A primeira palavra de cada lista é a aparência de hoje: sharp, default, flat, page, rules e caps. As palavras são explicadas em Formato, Aparência e Paleta do terminal.

Escolha um tema

Escolha um tema em Configurações → Aparência, e todo o app muda de uma vez.

O cartão Tema é o primeiro cartão. Toque em um nome e o app muda de uma vez. Cada nome exibe os cantos e o peso do seu próprio tema, para que você veja a forma antes de tocar. O cartão fica acima do cartão Aparência, que contém Sistema, Claro e Escuro. Essas são duas configurações. O tema define as cores, a forma e a aparência, e Sistema, Claro ou Escuro define qual metade das cores você vê.

Um tema que especifica uma tipografia a grava no cartão Tipografia uma única vez, quando você escolhe o tema. Depois disso, o cartão Tipografia tem prioridade: escolha outra fonte lá e ela permanece até você escolher um tema novamente. A fonte de exibição de um tema não faz parte desse cartão: os títulos a mantêm. As tipografias têm sua própria seção.

As fontes que esses temas usam incluem apenas Latin mais Latin Extended-A; portanto, textos em cirílico e CJK usam a fonte do sistema sob esses temas (o tema do Collie mantém sua fonte companheira em cirílico).

Importar um tema

Importe um arquivo .json no cartão Tema, leia a prévia e toque em Aplicar.

1. 01
   No cartão Tema, toque em Importar e escolha um arquivo .json.
2. 02
   O Collie lê o arquivo e mostra uma prévia. Ele mostra o nome, o autor, ambas as metades como amostras, uma página pequena para cada metade, a forma em um exemplo, as cores do terminal e um relatório de contraste.
3. 03
   Toque em Aplicar para manter o tema e alternar para ele, ou em Cancelar para não manter nada.

Um aviso é uma linha do relatório de contraste, como "dark: status-blocked chip on card measures 3.9. The floor is 4.5". Isso significa que o tema é difícil de ler em um ponto. O Aplicar continua ativo, porque a escolha é sua.

Uma recusa significa que o arquivo quebrou uma regra. O Collie lista as causas, não mantém nada e não aplica nada. A lista mostra no máximo 25 causas e depois a linha "and N more". Um arquivo é recusado por qualquer um destes motivos:

• —
  Não é um objeto JSON ou tem mais de 64 KiB.
• —
  Não define nenhuma cor.
• —
  Tem uma chave desconhecida, uma versão que o Collie não lê, um valor que não é uma cor ou uma fonte tipográfica que o Collie não inclui.
• —
  Uma palavra de forma não está na lista, ou há um número onde deveria haver uma palavra.
• —
  Tem um bloco surface, uma fonte fonts.display ou um bloco ansi, e indica a versão 1.
• —
  Seu bloco ansi não tem uma chave, tem uma cor com canal alfa ou falha em uma validação sob Paleta do terminal.
• —
  Tem um id, name ou author inválido, ou o id pertence a um tema incluído de fábrica.
• —
  Seria o nono tema importado. O Collie recusa no toque em Importar, antes de você escolher um arquivo, e novamente em Aplicar.

O Collie verifica mais uma coisa em Aplicar. Um arquivo cujo id já está no dispositivo é recusado com "already imported". Remova o tema antigo primeiro ou altere o id.

Um tema altera a aparência do aplicativo e nada mais. Ele não pode executar código, carregar arquivos ou acessar um servidor.

Um dispositivo suporta até oito temas importados. Remover funciona apenas enquanto um tema importado estiver ativo. Ele exclui esse tema, e o aplicativo volta para o Collie. A fonte tipográfica continua como estava.

O relatório de contraste

O relatório mede as cores de um tema em ambas as metades, e uma linha que falha é um aviso que você pode aceitar.

A paleta do terminal é a única exceção, porque suas validações recusam o arquivo. A tabela lista os limites mínimos das outras partes. Um limite mínimo é uma taxa de contraste, portanto um número maior é mais fácil de ler.

• —
  O texto destrutivo fica restrito ao que o Collie mede quando você mantém suas cores. O vermelho-claro do próprio Collie em sua página mede 4.38. Um tema que mantém ambas as cores do par fica restrito a esse valor e nunca abaixo de 3. Um tema que altera qualquer uma das cores fica restrito a 4.5.
• —
  Um gradiente ou granulado é medido em sua extremidade final. O relatório mede o texto da página, os chips, o texto destructive, o texto status-blocked e rule novamente no rodapé do gradiente ou na cor da linha do granulado, com os mesmos limites mínimos.
• —
  Uma faixa também é medida. Sob chrome: band, foreground, muted-foreground e status-blocked são medidos em secondary, a cor da faixa, em 4.5.

Exporte e compartilhe um tema

Escolha o tema e toque em Exportar. O Collie salva <id>.collie-theme.json. Um navegador que não consegue salvar arquivos exibe o texto em uma folha, com um botão de cópia. Para criar seu próprio tema a partir de um tema padrão:

1. 01
   Exporte Nightwatch, Daylight, Harbour ou Collie.
2. 02
   Altere id e name. Um id de um tema padrão é recusado.
3. 03
   Edite as cores e as palavras, e exclua qualquer token que você não queira alterar.
4. 04
   Envie o arquivo para seu telefone e importe-o.

Uma exportação grava o menor versão que suporta o conteúdo do tema.

Escreva um tema

Um arquivo possui estas chaves e nenhuma outra. Uma chave desconhecida em qualquer lugar é recusada com seu nome. Este é um arquivo de versão 2 completo: é o Daylight com uma lista mais curta de cores e a paleta completa.

{
  "version": 2,
  "id": "my-day",
  "name": "My day",
  "author": "Sam",
  "light": { "background": "oklch(0.985 0 0)", "primary": "oklch(0.18 0 0)" },
  "dark": { "background": "oklch(0.12 0 0)", "status-blocked": "oklch(0.81 0.13 60)" },
  "fonts": { "ui": "geist", "display": "atkinson" },
  "surface": {
    "radius": "round", "shadow": "lifted", "density": "roomy",
    "weight": "default", "border": "default", "ground": "gradient",
    "chrome": "page", "rows": "cards", "icons": "default", "labels": "sentence"
  },
  "ansi": {
    "0": "#3a332c", "1": "#ff5f56", "2": "#5fd068", "3": "#ffd84a",
    "4": "#5aa9ff", "5": "#e07ce8", "6": "#3fd6d0", "7": "#f2efe9",
    "8": "#8a827a", "9": "#ff8a80", "10": "#7ad683", "11": "#ffeb8a",
    "12": "#8cc4ff", "13": "#f0a6f5", "14": "#6ad8d2", "15": "#ffffff",
    "ink": "#f5f0e8", "ground": "#1a1612"
  }
}

• —
  version é 1 ou 2. Veja Versões. Qualquer outro número é recusado.
• —
  id tem de 1 a 32 caracteres: letras minúsculas, dígitos e hifens, começando com uma letra ou um dígito.
• —
  name tem de 1 a 40 caracteres, e author tem até 60. Nenhum dos dois pode conter um caractere de controle.
• —
  light e dark são objetos de tokens. Forneça uma das metades ou ambas. Uma metade omitida, e qualquer token omitido, assume o valor do tema Collie. Se apenas uma metade define um token, a outra metade recebe o valor do tema Collie para aquele token.
• —
  fonts.ui é opcional: system, grotesk, aldrich, plex, geist ou atkinson.
• —
  fonts.display é opcional e aceita os mesmos seis nomes. Veja Aparência.
• —
  surface é opcional. Todas as chaves nele também são opcionais, e uma chave que você omitir assume a palavra padrão de sua lista. Veja Formato e Aparência.
• —
  ansi é opcional e contém todas as 18 chaves ou nenhuma. Veja Paleta do terminal.
• —
  $schema é permitido e ignorado. O arquivo tem no máximo 64 KiB.

Um valor é #rrggbb, #rrggbbaa ou oklch(L C H) e oklch(L C H / A) em números simples. L vai de 0 a 1, C vai de 0 a 0.5, H vai de 0 a 360 e A vai de 0 a 1 ou uma porcentagem. Nada mais funciona: nenhuma cor nomeada, nenhum rgb(), nenhum var(), nenhum url(). Uma cor em ansi não tem alfa.

Versões

O arquivo indica qual é a sua versão, e o Collie grava a versão mais baixa que suporte o conteúdo do arquivo.

• —
  Um arquivo com um bloco surface, uma face fonts.display ou um bloco ansi deve indicar 2. Um arquivo que indica 1 e contém um deles é recusado.
• —
  Um arquivo sem esses blocos pode indicar qualquer uma das versões. O Collie lê ambas as versões, e uma exportação de tema com apenas cores e fonts.ui indica 1.
• —
  Um arquivo de versão 2 exige o Collie 1.22.0 ou mais recente.
• —
  Um arquivo de versão 1 assume a palavra padrão de cada lista para cada token de surface.

Os 43 tokens

Cada metade aceita qualquer um destes, em quatro grupos.

Formato

Cinco palavras no bloco surface definem o formato dos controles, e cada chave aceita uma palavra de uma lista fechada.

Uma palavra é um nome, nunca um número. Um raio livre ou um espaçamento livre poderia quebrar o limite mínimo de toque ou transformar um controle quadrado em um estádio. A primeira palavra de cada lista é o visual que o aplicativo tinha antes da versão 2.

• —
  Círculos continuam círculos. Uma forma cuja largura seja igual à sua altura, como um ponto de status, não é um nível de canto, então radius não a altera.
• —
  Uma linha marcada segue o raio. Sob sharp, uma linha selecionada ou bloqueada exibe uma barra de 2px na borda esquerda. Sob soft e round, exibe um anel de 2px nos quatro lados e uma sombra suave, porque uma barra esquerda nunca combina com cantos arredondados.
• —
  roomy nunca fica abaixo do padrão. Alvos de toque permanecem em 44px ou maiores. Os ícones e o cão no cabeçalho mantêm o tamanho, então apenas o espaço ao redor deles aumenta.

Aparência

Mais cinco chaves do bloco surface e uma chave de fonte definem o visual da página. Elas seguem a mesma regra de palavras fechadas.

fonts.display define uma das seis fontes para títulos de página e o nome no cabeçalho. Um tema que não define nenhuma desenha seus títulos na fonte, como antes. O Collie busca uma fonte de exibição apenas quando o tema a define.

• —
  Um fundo não desenha nenhum arquivo de imagem. O gradiente e o granulado são construídos a partir das cores do próprio tema. Os painéis do app são opacos, então o fundo aparece nos vãos entre eles.
• —
  O texto da página é medido no fundo. O relatório de contraste verifica a extremidade de um gradiente e a cor da linha do granulado, para que um fundo não oculte o texto.
• —
  Sob um gradiente, as barras mantêm a cor sólida da página. Em um tablet, o cabeçalho e as barras podem parecer uma caixa no topo de uma página que escurece embaixo. Uma palavra não pode mudar isso.
• —
  A barra de status segue uma faixa. Sob chrome: band, a barra de status do navegador assume a cor da faixa, e sob page assume a cor da página.
• —
  rows afeta todos os grupos de listas. Isso inclui a lista dentro do índice de Configurações.

Paleta do terminal

O bloco ansi define para o espelho do terminal suas próprias 16 cores, sua tinta e seu fundo.

O bloco contém todas as 18 chaves ou nenhuma: "0" a "15" para os 16 slots, ink para o texto e ground para o fundo. Uma paleta incompleta colocaria duas paletas em um único painel. Cada cor é #rrggbb ou oklch(), sem transparência.

Nota. Escreva a paleta para o modo escuro. O espelho sempre desenha sobre um fundo escuro, e no modo claro o Collie inverte o espelho inteiro em vez de recolori-lo (por que). O modo claro mostra a imagem espelhada das suas cores. Escolha um ground que se transforme no background claro do seu tema, e o espelho se integra à página em ambos os modos.

Uma cor que falha em um gate é recusada com sua chave identificada. Não é um aviso, porque o terminal é o que você mais lê.

O conjunto brilhante é uma lista fixa: o espelho do Muse trata esses quatro slots como os primeiros planos brilhantes. Os outros 12 slots continuam abaixo da mesma linha, então essa lista se mantém válida na sua paleta.

O que um tema não pode alterar

Um tema altera o valor de uma cor, suas tipografias, o formato dos controles, a sensação da página e a paleta do terminal. Ele não pode alterar mais nada.

• —
  Layout e tamanhos de toque. O layout de um telefone quebra facilmente. Raio, sombra, densidade, espessura e borda são termos fechados, nunca valores livres, e roomy nunca fica menor do que o padrão.
• —
  Tamanhos de fonte e movimento. Um tema define a tipografia e a espessura, não o tamanho, e não pode alterar a forma como as coisas se movem.
• —
  O cão Collie. O cabeçalho, o ícone da tela inicial e a tela de carregamento são iguais em qualquer tema.
• —
  O que um status significa. O ícone e o texto permanecem iguais, portanto um vermelho ou laranja que você definir nunca fará blocked parecer done.
• —
  Valores livres, CSS puro, fontes remotas. Cada chave recebe uma cor ou um termo de uma lista, e as fontes vêm da lista fornecida pelo Collie.

A primeira renderização e a barra de status

Sua escolha aparece na tela desde o primeiro quadro. Um script pequeno faz a leitura antes de o aplicativo carregar, portanto um tema padrão não pisca o visual inicial primeiro. Um tema importado faz o mesmo, com uma exceção. Se um token for definido em apenas uma metade, esse token exibirá a cor padrão por um quadro. O aplicativo valida o tema novamente ao carregar. Se o tema armazenado falhar na validação, ele será descartado, o dispositivo exibirá Collie e o console do navegador mostrará o motivo. A barra de status segue as duas cores de página do tema, ou as duas cores de faixa quando o tema define chrome: band.

Solução de problemas

Estes são os problemas mais frequentes, com a causa e a solução de cada um.

• —
  Um tema exibe a cor padrão em um token. O arquivo omitiu esse token, ou a metade. Tokens ausentes vêm do tema Collie. Adicione o token à metade desejada.
• —
  A fonte não mudou. Um tema aplica a fonte uma única vez, quando você o escolhe. Se você definiu outra fonte em Tipografia depois disso, essa escolha prevalece. Escolha a fonte novamente ou selecione o tema de novo.
• —
  Um termo de formato não tem efeito. O termo pode ser o padrão da lista ou a chave pode estar ausente. Uma chave omitida assume o termo padrão. Verifique a ortografia nas tabelas sob Formato e Aparência.
• —
  O arquivo é recusado e indica ansi. Uma paleta contém todas as 18 chaves, no espaço escuro, e cada cor precisa passar pelo teste. A recusa informa a chave e o número medido.
• —
  O tema desaparece após limpar os dados do navegador. Temas importados existem apenas neste navegador. Importe o arquivo novamente.