Temi

Un tema definisce l'aspetto dell'applicazione. Imposta i colori, i caratteri tipografici, la forma dei controlli, la resa grafica della pagina e i colori del terminale. È costituito da un piccolo file JSON. Collie ne include quattro. È possibile importarne altri da file ed esportare qualsiasi tema per duplicarlo e modificarlo. Il tema è un'impostazione specifica del singolo dispositivo, memorizzata in quel browser, e non modifica nulla sul bridge.

Ogni tema ha due parti. La parte chiara è il set di colori per la modalità chiara. La parte scura è il set per la modalità scura. Un colore all'interno di un tema ha un nome, ad esempio background o primary, e tale nome è un token.

I quattro temi

Collie include quattro temi, tre dei quali utilizzano ogni sezione di un file del tema. Ciascuna immagine mostra la Dashboard, in versione chiara a sinistra e scura a destra.

• —
  Collie è l'aspetto originale dell'applicazione. È l'opzione predefinita e selezionandola si disattiva ogni personalizzazione dei temi. Non specifica alcuna forma, stile o tavolozza: ogni voce corrisponde quindi al valore predefinito del relativo elenco.

  !Il tema Collie sulla Dashboard, chiaro e scuro.

• —
  Nightwatch è pensato per l'uso notturno su smartphone durante i turni di reperibilità. La parte scura è nero assoluto con un unico tono ambra attenuato, mentre la parte chiara richiama la carta calda al crepuscolo. Presenta linee squadrate e piatte, tratti marcati, testo in grassetto e una fascia ambra attenuata dietro l'intestazione e le barre. Il terminale adotta una tavolozza ambra su nero assoluto.

  !Il tema Nightwatch sulla Dashboard, chiaro e scuro.

• —
  Daylight è progettato per la luce solare diretta e per ipovedenti. Il testo principale ha un contrasto minimo di 7:1, i bordi sono più definiti e lo stato bloccato è arancione mentre completato è blu, così da distinguerli senza ricorrere a rosso e verde. Presenta angoli arrotondati, righe strutturate come schede in rilievo su una pagina che degrada verso il fondo (più scura in modalità chiara, più chiara in modalità scura) e spaziatura più ampia tra i passaggi. Il terminale adotta una tavolozza vivace ad alto contrasto.

  !Il tema Daylight sulla Dashboard, chiaro e scuro.

• —
  Harbour è pensato per chi lavora costantemente nel terminale. Un blu-grigio freddo con un accento verde acqua, nello stile di Nord e Solarized, con colori del codice simili a quelli di un editor. Presenta angoli smussati, una leggera grana sotto la pagina e icone sottili. Il terminale adotta una tavolozza basata su Solarized.

  !Il tema Harbour sulla Dashboard, chiaro e scuro.

La tabella elenca tutti i valori impiegati da ciascun tema. La prima voce di ogni elenco rappresenta l'aspetto corrente: sharp, default, flat, page, rules e caps. I singoli valori sono descritti in Forma, Aspetto e Tavolozza del terminale.

Scegliere un tema

Scegliendo un tema in Impostazioni → Aspetto, l'intera applicazione cambia all'istante.

La scheda Tema è la prima scheda. Premere su un nome e l'applicazione cambia all'istante. Ogni nome adotta gli angoli e lo spessore del proprio tema, mostrando la forma prima della selezione. La scheda si trova sopra la scheda Aspetto, che contiene Sistema, Chiaro e Scuro. Si tratta di due impostazioni diverse. Il tema definisce i colori, la forma e l'aspetto, mentre Sistema, Chiaro o Scuro definisce quale metà dei colori viene mostrata.

Un tema che specifica un carattere tipografico lo imposta nella scheda Carattere tipografico una sola volta, al momento della selezione del tema. Successivamente prevale la scheda Carattere tipografico: selezionando un altro carattere lì, questo rimane attivo fino a una nuova selezione del tema. Il carattere per i titoli di un tema non fa parte di quella scheda: i titoli lo mantengono. Le caratteri tipografici hanno una sezione dedicata.

I caratteri utilizzati da questi temi includono solo l'alfabeto latino e il blocco Latin Extended-A; pertanto, con tali temi il testo in caratteri cirillici e CJK passa al carattere di sistema (il tema Collie mantiene il relativo carattere cirillico complementare).

Importare un tema

Importare un file .json nella scheda Tema, leggere l'anteprima e toccare Applica.

1. 01
   Nella scheda Tema, toccare Importa e scegliere un file .json.
2. 02
   Collie legge il file e mostra un'anteprima. Vengono mostrati il nome, l'autore, entrambi i lati come campioni, una piccola pagina per ciascun lato, la forma su un campione, i colori del terminale e un report sul contrasto.
3. 03
   Toccare Applica per conservare il tema e applicarlo, oppure Annulla per non conservare nulla.

Un valore avviso è una riga del report sul contrasto, ad esempio "dark: status-blocked chip on card measures 3.9. The floor is 4.5". Indica che il tema risulta difficile da leggere in un punto. Il pulsante Applica rimane attivo, poiché la scelta spetta all'utente.

Un valore rifiuto indica che il file ha violato una regola. Collie elenca le cause, non conserva nulla e non applica nulla. L'elenco mostra al massimo 25 cause, seguite dalla riga "and N more". Un file viene rifiutato per uno qualsiasi dei seguenti motivi:

• —
  Non è un oggetto JSON, oppure supera i 64 KiB.
• —
  Non imposta alcun colore.
• —
  Contiene una chiave sconosciuta, una versione non supportata da Collie, un valore che non è un colore o un carattere non incluso in Collie.
• —
  Un termine relativo alla forma non è compreso nell'elenco, oppure è presente un numero al posto di una parola.
• —
  Contiene un blocco surface, un carattere fonts.display o un blocco ansi, e indica la versione 1.
• —
  Il relativo blocco ansi è privo di una chiave, presenta un colore con canale alfa o non supera un gate con Tavolozza del terminale.
• —
  Presenta un valore non valido per id, name o author, oppure il valore id appartiene a un tema fornito di serie.
• —
  Sarebbe il nono tema importato. Collie rifiuta l'operazione al tocco di Importa, prima di scegliere il file, e di nuovo in corrispondenza di Applica.

Collie esegue un ulteriore controllo al momento di Applica. Un file il cui id è già presente sul dispositivo viene rifiutato con l'indicazione "already imported". È necessario rimuovere prima il vecchio tema o modificare il valore id.

Un tema modifica esclusivamente l'aspetto visivo dell'app. Non può eseguire codice, caricare file o contattare un server.

Un dispositivo può memorizzare fino a otto temi importati. Rimuovi funziona solo quando è attivo un tema importato. Elimina tale tema e l'app torna al tema Collie. Il carattere rimane invariato.

Il report sul contrasto

Il report misura i colori di un tema in entrambe le modalità; una riga non superata costituisce un avviso che è possibile accettare.

La tavolozza del terminale è l'unica eccezione, poiché i relativi gate provocano il rifiuto del file. La tabella elenca le soglie minime per le altre parti. La soglia minima indica un rapporto di contrasto: un valore più elevato corrisponde a una leggibilità migliore.

• —
  Il testo distruttivo è vincolato al valore misurato da Collie quando se ne mantengono i colori. Il rosso chiaro predefinito di Collie sulla propria pagina misura 4,38. Un tema che mantiene entrambi i colori della coppia è vincolato a tale valore e mai sotto 3. Un tema che modifica uno dei due colori è vincolato a 4,5.
• —
  Un gradiente o una grana vengono misurati all'estremità opposta. Il report misura il testo della pagina, i chip, il testo destructive, il testo status-blocked e di nuovo rule alla base del gradiente o sul colore della linea della grana, con le stesse soglie minime.
• —
  Viene misurata anche una fascia. Sotto chrome: band, foreground, muted-foreground e status-blocked sono misurati su secondary, il colore della fascia, a 4,5.

Esportare e condividere un tema

Scegliere il tema, quindi toccare Esporta. Collie salva <id>.collie-theme.json. Un browser che non può salvare un file mostra il testo in un riquadro, con un pulsante di copia. Per creare il proprio tema a partire da uno fornito:

1. 01
   Esportare Nightwatch, Daylight, Harbour o Collie.
2. 02
   Modificare id e name. Un id di un tema predefinito viene rifiutato.
3. 03
   Modificare i colori e i testi, ed eliminare qualsiasi token che non si desidera cambiare.
4. 04
   Inviare il file al proprio telefono, quindi importarlo.

Un'esportazione scrive la versione versione più bassa in grado di contenere il tema.

Scrivere un tema

Un file contiene queste chiavi e nessun'altra. Una chiave sconosciuta in qualunque posizione viene rifiutata con il relativo nome. Questo è un file di versione 2 completo: è Daylight con un elenco di colori più breve e la tavolozza 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 o 2. Vedere Versioni. Qualsiasi altro numero viene rifiutato.
• —
  id è compreso tra 1 e 32 caratteri: lettere minuscole, cifre e trattini, a partire da una lettera o una cifra.
• —
  name è compreso tra 1 e 40 caratteri e author fino a 60. Nessuno dei due può contenere un carattere di controllo.
• —
  light e dark sono oggetti di token. Indicare una metà o entrambe. Una metà omessa, e qualsiasi token omesso, assume il valore del tema Collie. Se solo una metà imposta un token, l'altra metà ottiene il valore del tema Collie per quel token.
• —
  fonts.ui è opzionale: system, grotesk, aldrich, plex, geist o atkinson.
• —
  fonts.display è opzionale e accetta gli stessi sei nomi. Vedere Aspetto.
• —
  surface è opzionale. Anche ogni chiave al suo interno è opzionale; una chiave omessa assume la parola predefinita del rispettivo elenco. Vedere Forma e Aspetto.
• —
  ansi è opzionale e contiene tutte le 18 chiavi oppure nessuna. Vedere Tavolozza del terminale.
• —
  $schema è consentito e viene ignorato. Il file non può superare 64 KiB.

Un valore è #rrggbb, #rrggbbaa oppure oklch(L C H) e oklch(L C H / A) in numeri semplici. L va da 0 a 1, C da 0 a 0,5, H da 0 a 360 e A da 0 a 1 o in percentuale. Nessun altro formato è valido: nessun colore con nome, nessun rgb(), nessun var(), nessun url(). Un colore in ansi non ha il canale alpha.

Versioni

Il file indica la propria versione e Collie scrive la versione più bassa in grado di contenere gli elementi presenti nel file.

• —
  Un file con un blocco surface, un carattere fonts.display o un blocco ansi deve indicare 2. Un file che indica 1 e contiene uno di questi elementi viene rifiutato.
• —
  Un file privo di tali blocchi può indicare l'una o l'altra versione. Collie legge entrambe le versioni e l'esportazione di un tema contenente solo colori e fonts.ui indica 1.
• —
  Un file in versione 2 richiede Collie 1.22.0 o versioni successive.
• —
  Un file in versione 1 applica la parola predefinita di ciascun elenco a ogni token di surface.

I 43 token

Ciascuna metà accetta uno qualsiasi di questi elementi, suddivisi in quattro gruppi.

Forma

Cinque parole nel blocco surface impostano la forma dei controlli, e ciascuna chiave accetta una parola da un elenco chiuso.

Una parola è un nome, mai un numero. Un raggio libero o un passaggio di spaziatura libero potrebbe violare l'area minima di tocco o trasformare un controllo quadrato in uno stadio. La prima parola di ciascun elenco corrisponde all'aspetto dell'applicazione prima della versione 2.

• —
  I cerchi restano cerchi. Una forma con larghezza uguale all'altezza, come un punto di stato, non costituisce un passaggio di arrotondamento, pertanto radius non la modifica.
• —
  Una riga contrassegnata segue il raggio. Con sharp, una riga selezionata o bloccata mostra una barra di 2px sul bordo sinistro. Con soft e round mostra un anello di 2px su tutti e quattro i lati e un'ombra morbida, poiché una barra a sinistra non si abbina mai agli angoli arrotondati.
• —
  roomy non scende mai al di sotto del valore predefinito. I target di tocco rimangono di 44px o superiori. Le icone e il cane nell'intestazione mantengono le proprie dimensioni, quindi cresce solo lo spazio circostante.

Aspetto

Altre cinque chiavi del blocco surface e una chiave per il font impostano l'aspetto della pagina. Seguono la stessa regola delle parole chiuse.

fonts.display definisce uno dei sei caratteri per i titoli di pagina e per il nome nell'intestazione. Un tema che non ne specifica alcuno disegna i titoli con il carattere predefinito, come in precedenza. Collie recupera un carattere per i titoli solo se specificato dal tema.

• —
  Uno sfondo non carica alcun file di immagine. La sfumatura e la grana derivano dai colori del tema stesso. I pannelli dell'applicazione sono opachi, quindi lo sfondo appare negli spazi intermedi.
• —
  Il contrasto del testo della pagina viene calcolato rispetto allo sfondo. rapporto di contrasto controlla l'estremità opposta della sfumatura e il colore delle linee della grana, per impedire allo sfondo di nascondere il testo.
• —
  Sotto una sfumatura, le barre mantengono la tinta unita della pagina. Su un tablet l'intestazione e le barre possono apparire come un blocco nella parte superiore di una pagina che si scurisce verso il basso. Una parola non può modificare questo comportamento.
• —
  La barra di stato segue la fascia. Con chrome: band la barra di stato del browser assume il colore della fascia, mentre con page assume il colore della pagina.
• —
  rows influisce su ogni gruppo di liste. Questo include la lista presente nell'indice di Impostazioni.

Tavolozza del terminale

Il blocco ansi assegna al mirror del terminale i propri 16 colori, il colore del testo e quello di sfondo.

Il blocco deve contenere tutte le 18 chiavi oppure nessuna: da "0" a "15" per i 16 slot, ink per il testo e ground per lo sfondo. Una palette parziale causerebbe la presenza di due palette nello stesso riquadro. Ciascun colore deve essere espresso in formato #rrggbb o oklch(), senza canale alfa.

Nota. Definire la palette per la modalità scura. Il mirror disegna sempre su uno sfondo scuro; in modalità chiara Collie inverte l'intero mirror anziché ricolorarlo (perché). La modalità chiara mostra l'inverso speculare dei colori impostati. Scegliendo un ground che si converte nel background chiaro del tema, il mirror si integra con la pagina in entrambe le modalità.

Un colore che non rispetta un gate viene rifiutato, indicandone la chiave. Non si tratta di un semplice avviso, poiché il terminale è l'elemento letto più spesso.

L'insieme chiaro è un elenco fisso: il mirror di Muse tratta questi quattro slot come primi piani chiari. Gli altri 12 slot restano sotto la stessa soglia, così l'elenco rimane valido per la propria tavolozza.

Cosa non può modificare un tema

Un tema modifica il valore di un colore, i caratteri tipografici, la forma dei controlli, l'aspetto della pagina e la tavolozza del terminale. Non può modificare nient'altro.

• —
  Layout e dimensioni del tocco. Il layout per telefoni è facile da compromettere. Raggio, ombra, densità, peso e bordo sono termini chiusi, mai valori liberi, e roomy non scende mai al di sotto del valore predefinito.
• —
  Dimensioni del testo e movimento. Un tema sceglie un carattere e un peso, non una dimensione, e non può modificare il movimento degli elementi.
• —
  Il cane di Collie. L'intestazione, l'icona della schermata iniziale e la schermata iniziale mantengono lo stesso aspetto con ogni tema.
• —
  Il significato di uno stato. L'icona e il relativo termine restano invariati, così un rosso o un arancione selezionato non fa mai sembrare completato ciò che è bloccato.
• —
  Un valore libero, CSS grezzo, font remoti. Ogni chiave accetta un colore o un termine da un elenco, e i font provengono dall'elenco fornito con Collie.

Il primo rendering e la barra di stato

La scelta applicata appare sullo schermo fin dal primo fotogramma. Un piccolo script la legge prima del caricamento dell'app, evitando che un tema predefinito mostri per un istante i valori iniziali. Un tema importato si comporta allo stesso modo, con un'unica eccezione: se un token è impostato solo in una metà, tale token mostra il colore predefinito per un fotogramma. L'app verifica nuovamente il tema al caricamento. Un tema memorizzato che non supera la verifica viene scartato, il dispositivo mostra Collie e la console del browser ne indica il motivo. La barra di stato segue i due colori di pagina del tema, oppure i due colori di fascia se il tema specifica chrome: band.

Risoluzione dei problemi

Questi sono i problemi più comuni, con le relative cause e soluzioni.

• —
  Un tema mostra il colore predefinito su un token. Il file ha omesso quel token, oppure la metà corrispondente. I token mancanti vengono presi dal tema Collie. Aggiungere il token alla metà desiderata.
• —
  Il carattere tipografico non è cambiato. Un tema imposta il carattere tipografico una sola volta, al momento della selezione. Se in seguito è stato scelto un altro carattere in Carattere tipografico, prevale quest'ultima selezione. Selezionare nuovamente il carattere, oppure selezionare di nuovo il tema.
• —
  Un termine relativo alla forma non produce effetti. Il termine potrebbe essere quello predefinito del relativo elenco, oppure la chiave potrebbe mancare. Una chiave omessa assume il termine predefinito. Verificare la correttezza della voce consultando le tabelle in Forma e Aspetto.
• —
  Il file viene rifiutato e indica ansi. Una tavolozza contiene tutte le 18 chiavi, nello spazio scuro, e ciascun colore deve superare la relativa soglia. Il messaggio di rifiuto indica la chiave e il valore misurato.
• —
  Il tema scompare dopo aver cancellato i dati del browser. I temi importati risiedono solo in questo browser. Importare nuovamente il file.