Un thème change l'apparence complète de CubicLauncher : couleurs, typographie, arrière-plan, icônes et détails de l'interface. Il n'y a rien à compiler ni à modifier dans le code du launcher : un thème, ce sont deux fichiers texte et, si vous le souhaitez, quelques images et polices.
Ce guide construit un vrai thème de bout en bout, en étapes courtes, avec un point de contrôle après chacune. À la fin, vous disposez d'un ZIP installable et publié.
- Un éditeur de texte et un programme pour compresser en ZIP.
- Une version récente de CubicLauncher.
- Dix minutes pour le premier thème fonctionnel.
Si vous souhaitez seulement installer un thème conçu par quelqu'un d'autre, consultez Comment installer un thème.
Comment fonctionne un thèmemodifier
Le launcher lit les fichiers du thème, les convertit en variables CSS et les applique à l'interface. C'est pourquoi presque tout se personnalise en déclarant des valeurs, sans écrire de sélecteurs :
Meta.toml → identité : nom, auteur, version, héritage
Definition.toml → apparence : couleurs, arrière-plan, polices, icônes
Inject.css → détails que les variables ne couvrent pas (facultatif)
Layout.css → restructurer l'ossature (facultatif)Chaque clé de Definition.toml produit une variable avec un préfixe fixe. Par exemple, accent = "#8FBF6A" dans [colors] devient --accent, et primary = "#E6EFDC" dans [text] devient --text-primary.
Il existe deux versions du format. Ce guide utilise V2, la version actuelle. La V1 (theme.json) reste prise en charge pour des raisons de compatibilité, mais elle ne permet ni les icônes, ni l'héritage, ni le CSS personnalisé.
Étape 1 — Créer le dossier et le manifestemodifier
Créez un dossier pour votre thème, par exemple bosque, et placez-y un fichier Meta.toml :
name = "Bosque"
author = "votre_pseudo"
version = "0.1.0"
description = "Thème sombre avec accent vert et fond de forêt."
format = 2
api_version = "2.1"Avec ces champs, vous avez déjà un thème valide. format doit valoir exactement 2 et api_version déclare la série de l'API contre laquelle le thème a été écrit : aujourd'hui "2.1".
Ajoutez ensuite Definition.toml avec une seule section vide pour l'instant :
[colors]Compressez le dossier en ZIP et glissez-le dans la fenêtre du launcher.
Point de contrôle : le thème apparaît dans le sélecteur sous le nom Bosque et, lorsque vous l'activez, l'interface reste identique à avant. C'est normal : vous n'avez encore modifié aucune valeur.
Le launcher génère l'identifiant interne à partir de name et author : "Bosque" + "votre_pseudo" est enregistré sous bosque_votre_pseudo dans ~/.cubic/themes/. C'est cet identifiant qui sert à hériter d'un autre thème.
Étape 2 — Définir la palettemodifier
Un thème repose sur cinq couleurs : arrière-plan, surface, texte, accent et bordure. Choisissez-les avant d'écrire quoi que ce soit, pour que le reste soit cohérent.
Ajoutez ces deux sections à Definition.toml :
[colors]
accent = "#8FBF6A"
accent-rgb = "143, 191, 106"
accent-hover = "#A5D182"
accent-text = "#0B120A"
bg-main = "#0B0F0B"
bg-sidebar = "#0F150F"
bg-card = "#131A13"
bg-input = "#080C08"
bg-item-active = "#1B261B"
bg-overlay = "rgba(5, 8, 5, 0.72)"
border-color = "rgba(143, 191, 106, 0.18)"
[text]
primary = "#E6EFDC"
secondary = "#AEBBA2"
muted = "#74806B"Ce que fait chaque clé :
| Clé | Effet |
|---|---|
bg-main | Arrière-plan de la fenêtre. |
bg-sidebar | Arrière-plan de la barre latérale, un cran plus clair que l'arrière-plan. |
bg-card | Cartes, fenêtres modales et panneaux. |
bg-input | Champs de texte, un cran plus sombre. |
accent | Boutons, focus, liens et éléments actifs. |
accent-text | Texte placé au-dessus de l'accent. |
border-color | Bordures et séparateurs. |
Point de contrôle : le launcher change immédiatement. Si une couleur ne s'applique pas, vérifiez que la clé se trouve dans la bonne section et regardez la console : les noms en double génèrent un avertissement de collision.
accent-rgb doit être la même couleur que accent, écrite sous la forme R, G, B sans rgb(). L'interface l'utilise dans rgba(var(--accent-rgb), 0.15) pour les lueurs et les bordures. Si vous l'oubliez, ces détails conservent le blanc d'origine.
surface-rgb fonctionne de la même manière, mais pour les surfaces translucides. Dans un thème sombre, il vaut 255, 255, 255 (par défaut) ; dans un thème clair, il doit valoir 0, 0, 0, sinon les bordures s'éclaircissent au lieu de s'assombrir.
Étape 3 — Ajuster les bordures, les ombres et les mesuresmodifier
La palette étant prête, définissez les formes. Ces sections sont facultatives, mais ce sont elles qui donnent à un thème un aspect abouti plutôt qu'un simple recoloriage :
[borders]
radius = "10px"
radius-sm = "6px"
radius-lg = "18px"
[shadows]
shadow-sm = "0 2px 8px rgba(0, 0, 0, 0.28)"
shadow-md = "0 10px 28px rgba(0, 0, 0, 0.36)"
shadow-lg = "0 18px 52px rgba(0, 0, 0, 0.50)"
[layout]
sidebar-width = "248px"
[spacing]
md = "12px"
lg = "16px"[borders] ajoute le préfixe --border-, [spacing] ajoute --space- et [layout] n'en ajoute aucun : la clé correspond à la variable complète.
Point de contrôle : les coins changent de rayon, les cartes gagnent en profondeur et la barre latérale s'élargit ou se rétrécit.
Étape 4 — Ajouter une image d'arrière-planmodifier
L'arrière-plan est ce qui apporte le plus d'identité. Placez l'image dans le dossier du thème et déclarez-la avec un chemin relatif :
[background]
reference_path = "bg.webp"
image_blur = 12.0
image_opacity = 0.32
mode = "cover"
position = "center"
brightness = 0.45| Clé | Ce qu'elle contrôle | Plage utile |
|---|---|---|
reference_path | Chemin de l'image, relatif au thème. | — |
image_blur | Flou en pixels. | 0 à 24 |
image_opacity | Transparence de la couche. | 0.2 à 0.6 |
mode | Cadrage : cover, contain. | — |
position | center, top, bottom left… | — |
brightness | Luminosité de l'image. | 0.3 à 0.7 |
Plus brightness est bas et plus l'opacité est élevée, plus le texte est lisible mais moins l'image est visible. Le bon équilibre se situe généralement entre 0.35 et 0.5 pour brightness, et autour de 0.35 pour image_opacity.
Point de contrôle : l'image apparaît derrière le contenu, floutée et assombrie, sans gêner la lecture.
L'image ne peut pas dépasser 25 MB et doit être un véritable fichier image. Le launcher vérifie l'en-tête du fichier, pas l'extension : un .png qui est en réalité du texte est rejeté.
Utilisez des chemins relatifs. Les chemins absolus et file: fonctionnent sur votre machine, mais cassent le thème sur toute autre.
Étape 5 — Typographie personnaliséemodifier
Vous pouvez utiliser n'importe quelle police présente dans le paquet. Copiez les fichiers dans fonts/ et déclarez chaque variante :
[[fonts]]
family = "Inter"
src = "fonts/Inter-Regular.woff2"
weight = "400"
style = "normal"
[[fonts]]
family = "Inter"
src = "fonts/Inter-SemiBold.woff2"
weight = "600"
style = "normal"
[typography]
family = "Inter, system-ui, sans-serif"
size_base = "14px"
line_height = "1.5"La règle importante : [typography].family doit mentionner la même famille que celle déclarée dans [[fonts]]. Si le nom ne correspond pas, la police est chargée mais l'interface continue d'utiliser la typographie par défaut.
Point de contrôle : les titres et le texte changent d'aspect. Si rien ne change, vérifiez le nom de la famille et l'existence du chemin src dans le ZIP.
Une ou deux familles suffisent. Au-delà de 12, le sélecteur affiche un avertissement, et le launcher ne charge que les 20 premières variantes.
Étape 6 — Icônesmodifier
Les icônes se déclarent par groupe. La clé finale est groupe:nom, et elle doit correspondre exactement au nom demandé par le composant.
[icons]
preview = "icons/preview.png"
[icons.nav]
settings = "icons/nav/settings.svg"
create = "icons/nav/create.svg"
[icons.ui]
play = "icons/ui/play.svg"preview est l'image qui représente votre thème dans le sélecteur ; il est conseillé d'utiliser une capture du launcher avec le thème appliqué.
Les SVG sont utilisés comme masque : ils sont peints avec la couleur du texte, donc une icône monochrome fonctionne sur les thèmes clairs comme sombres. Les PNG, WEBP et JPG sont dessinés avec leurs propres couleurs.
Point de contrôle : les icônes de la barre latérale changent. Si une icône ne change pas, la clé ne correspond pas au nom réel : la liste complète se trouve dans Référence des tokens.
Étape 7 — Les détails fins avec CSSmodifier
Les variables couvrent presque tout, mais certaines choses ne se règlent qu'avec du CSS : pseudo-éléments, animations, séparateurs. C'est le rôle d'Inject.css.
Déclarez la section dans Definition.toml et créez le fichier :
[inject]
path = "Inject.css"
enabled = true
layer = "theme"/* Inject.css */
[data-part="sidebar"] {
border-right: 1px solid var(--border-color);
}
[data-part="sidebar"] .sidebar-header {
letter-spacing: 0.04em;
text-transform: uppercase;
}L'essentiel réside dans layer :
theme(par défaut) enveloppe votre CSS dans@layer cubic.theme. Il l'emporte sur les styles globaux du launcher, mais perd face aux styles de chaque composant.unlayeredlaisse le CSS sans couche. Il entre en concurrence de spécificité avec tout, y compris les composants. Il est plus puissant et plus fragile.
Point de contrôle : la modification s'applique sans redémarrage. Si vous ne voyez aucun effet, essayez layer = "unlayered" avant de conclure que le sélecteur est incorrect.
Évitez de dépendre des classes générées par Svelte (celles qui se terminent par un hash) et des structures internes. Les attributs data-part sont stables ; le reste peut changer d'une version à l'autre.
Étape 8 — Empaqueter, installer et testermodifier
- Le dossier doit contenir
Meta.tomletDefinition.tomlà la racine, à côté des assets. - Compressez-le en ZIP. Les fichiers peuvent se trouver à la racine du ZIP ou dans un unique dossier conteneur.
- Changez l'extension en
.cbthsi vous souhaitez utiliser le format de paquet de thèmes : c'est le même ZIP sous un autre nom. - Installez-le en le glissant dans la fenêtre du launcher ou depuis Paramètres → Thèmes → Importer un thème.
- Sélectionnez-le dans le sélecteur.
Comment le launcher traite le paquet :
- Il cherche
Meta.tomlà la racine ou dans un dossier conteneur. S'il en trouve plusieurs, il rejette le ZIP. - Si
Meta.tomlettheme.jsoncoexistent, V2 l'emporte. - Un
.zipest d'abord testé comme V1 puis comme V2 ; un.cbthn'est interprété que comme V2. - L'installation est atomique : le paquet est décompressé dans un dossier temporaire puis déplacé vers la destination. Si la validation échoue, rien ne reste à moitié installé.
- La destination est
~/.cubic/themes/<id>/. Réimporter un thème portant le même nom et le même auteur remplace la version précédente.
Tester les modifications sans réimportermodifier
Tant que le thème est actif, le launcher surveille son dossier et le recharge automatiquement. Modifiez les fichiers dans ~/.cubic/themes/<id>/ et observez le résultat en direct : c'est bien plus rapide que de compresser et de réimporter à chaque ajustement.
Le panneau de diagnostic du sélecteur de thèmes signale trois choses qui ne bloquent pas le chargement mais affectent les performances : plus de 12 polices, un CSS de plus de 256 KiB et des arrière-plans de plus de 4096×4096 pixels.
Étape 9 — Publier dans le cataloguemodifier
Les thèmes communautaires vivent dans CubicLauncherDevs/Themes et apparaissent sur cubiclauncher.org/themes.
src/
└── TuAutor/
└── TuTema/
├── theme.md # description du thème
├── vflag.txt # facultatif, réservé au staff : marque le thème comme vérifié
└── V1/
├── Meta.toml
├── Definition.toml
├── bg.webp
├── Showcase.png # facultatif, capture pour le catalogue
└── fonts/- Faites un fork du dépôt.
- Créez
src/TuAutor/TuTema/theme.mdavec une brève description. - Créez
src/TuAutor/TuTema/V1/avecMeta.toml,Definition.tomlet les assets. - Ouvrez une Pull Request.
L'intégration continue optimise les images, génère l'aperçu, téléverse les binaires vers le stockage du catalogue et met à jour themes.json. Les binaires ne sont pas stockés dans Git.
Optimiser le thèmemodifier
Un thème est lu à chaque activation : le launcher analyse les deux manifestes, valide l'arrière-plan en ouvrant le fichier, vérifie chaque icône, résout chaque police et charge le CSS en mémoire. Ensuite, le frontend décode l'image et enregistre les typographies avant d'afficher l'interface complète. Un thème lourd n'est pas plus beau : il met plus de temps à apparaître.
Voici les décisions qui ont le plus d'impact, de la plus forte à la plus faible.
L'arrière-plan : l'image la plus grande et celle qui a le moins besoin de détailsmodifier
L'image est dessinée floutée et avec une faible opacité, si bien que la résolution ne se remarque presque pas. Un arrière-plan de 1600×900 est identique à un 4K après flou, mais pèse huit fois moins et se décode instantanément.
| Pratique | Pourquoi |
|---|---|
| Exportez en WebP avec une qualité de 75–85. | Même rendu qu'un PNG pour une fraction du poids. |
| Réduisez la résolution à 1600×900 ou 1920×1080. | Le flou masque le manque de détails. |
| Visez moins de 500 KB. | La limite est de 25 MB, mais l'objectif réel est autre. |
Floutez l'image dans l'éditeur et utilisez un image_blur faible. | Le flou en direct est recalculé sur toute la fenêtre. |
| Évitez de dépasser 4096×4096. | Le sélecteur prévient en raison de la consommation mémoire au décodage. |
Un image_blur élevé sur une grande image est la combinaison la plus coûteuse : le flou est payé à chaque redessin. Si l'image est déjà floutée, image_blur = 0 donne le même résultat sans coût.
Polices : uniquement ce qui est utilisémodifier
Chaque fichier déclaré est téléchargé, enregistré et appliqué. Une famille avec quatre graisses ajoute quatre fichiers.
- Utilisez WOFF2. C'est le format le plus léger et le mieux pris en charge.
- Déclarez uniquement les graisses dont le thème a réellement besoin : généralement
400et600. - Privilégiez les polices avec un sous-ensemble latin ; une police avec cyrillique, grec et CJK peut peser dix fois plus.
- Deux familles constituent le maximum raisonnable. Une seule, bien choisie, suffit pour presque tout.
Icônes : SVG et uniquement celles qui changentmodifier
Les SVG pèsent quelques KB et se colorent d'eux-mêmes. Les images raster (PNG, WEBP, JPG) sont chargées avec leurs couleurs et pèsent généralement bien plus lourd.
- Remplacez uniquement les icônes qui apportent une identité. Chaque entrée est validée au chargement du thème, même si elle n'est jamais affichée.
- N'incluez pas une icône si l'originale vous convient déjà.
- Si vous utilisez du raster, gardez-le sous 64×64 et 50 KB : la limite est de 2 MB, mais une icône de 2 MB met du temps à apparaître.
CSS : d'abord les variables, ensuite les sélecteursmodifier
Inject.css est chargé et interprété à chaque activation. Tout ce qui peut se régler avec une variable devrait se régler avec une variable.
- Si vous pouvez modifier une couleur, un rayon ou une ombre depuis
Definition.toml, n'écrivez pas de CSS. - Gardez
Inject.csssous 16 KB ; la limite recommandée est de 256 KiB. - N'animez pas
filter,backdrop-filternibox-shadow: ce sont les propriétés les plus coûteuses à redessiner. - Évitez
!important. Si vous en avez besoin, c'est que le sélecteur est mal choisi. - Ne dupliquez pas en CSS ce que fait déjà
Layout.css.
Tokens : ne répétez pas les valeurs par défautmodifier
Chaque variable déclarée est injectée dans une feuille de style. Répéter la valeur par défaut ne change rien et rend le thème plus difficile à lire.
- Déclarez uniquement les tokens qui diffèrent du launcher.
- Si deux clés génèrent la même variable, gardez-en une : l'autre produit un avertissement de collision.
- Pour les variantes de couleur, utilisez
extendsau lieu de copier toute la palette. - Déclarez
--color-scheme("dark"ou"light") dans[others]pour que les barres de défilement et les contrôles natifs suivent le thème.
Objectifs de poidsmodifier
| Ressource | Objectif | Limite technique |
|---|---|---|
| ZIP complet | moins de 3 MB | — |
| Image d'arrière-plan | moins de 500 KB | 25 MB |
| Polices | moins de 300 KB au total | 12 recommandées, 20 chargées |
| Icônes | moins de 20, SVG | 100 préchargées |
Inject.css | moins de 16 KB | 256 KiB recommandé |
| Tokens déclarés | 25 à 40 clés | — |
Comment mesurermodifier
- Regardez la taille du ZIP avant de publier : c'est le chiffre que voit la personne qui le télécharge.
- Le panneau de diagnostic du sélecteur de thèmes signale si l'arrière-plan est trop grand, s'il y a trop de polices ou si le CSS dépasse la taille limite.
- Si le thème met du temps à apparaître lors d'un changement, le problème vient presque toujours de l'image d'arrière-plan ou du nombre de polices.
Exemple completmodifier
Un Meta.toml et un Definition.toml prêts à copier, avec tout ce qui précède. Les assets (bg.webp, fonts/, icons/, Inject.css) sont facultatifs : s'ils manquent, le launcher les ignore et poursuit avec le reste du thème.
# Meta.toml
name = "Bosque"
author = "votre_pseudo"
version = "1.0.0"
description = "Thème sombre avec accent vert et fond de forêt."
format = 2
api_version = "2.1"# Definition.toml
[colors]
accent = "#8FBF6A"
accent-rgb = "143, 191, 106"
accent-hover = "#A5D182"
accent-text = "#0B120A"
bg-main = "#0B0F0B"
bg-sidebar = "#0F150F"
bg-card = "#131A13"
bg-input = "#080C08"
bg-item-active = "#1B261B"
bg-overlay = "rgba(5, 8, 5, 0.72)"
border-color = "rgba(143, 191, 106, 0.18)"
[text]
primary = "#E6EFDC"
secondary = "#AEBBA2"
muted = "#74806B"
[borders]
radius = "10px"
radius-sm = "6px"
radius-lg = "18px"
[shadows]
shadow-sm = "0 2px 8px rgba(0, 0, 0, 0.28)"
shadow-md = "0 10px 28px rgba(0, 0, 0, 0.36)"
shadow-lg = "0 18px 52px rgba(0, 0, 0, 0.50)"
[layout]
sidebar-width = "248px"
[background]
reference_path = "bg.webp"
image_blur = 12.0
image_opacity = 0.32
mode = "cover"
position = "center"
brightness = 0.45
[[fonts]]
family = "Inter"
src = "fonts/Inter-Regular.woff2"
weight = "400"
style = "normal"
[[fonts]]
family = "Inter"
src = "fonts/Inter-SemiBold.woff2"
weight = "600"
style = "normal"
[typography]
family = "Inter, system-ui, sans-serif"
size_base = "14px"
line_height = "1.5"
[icons]
preview = "icons/preview.png"
[icons.nav]
settings = "icons/nav/settings.svg"
create = "icons/nav/create.svg"
[inject]
path = "Inject.css"
enabled = true
layer = "theme"Référence des champsmodifier
Meta.tomlmodifier
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
name | string | Oui | Nom visible. Ne peut pas être vide. |
author | string | Recommandé | Auteur. Affiché en minuscules et fait partie de l'identifiant. |
version | string | Recommandé | Version, idéalement MAJEUR.MINEUR.CORRECTIF. |
description | string | Facultatif | Description sur une ligne pour le catalogue. |
format | entier | Oui | Doit valoir exactement 2. |
api_version | string | Facultatif | Série de l'API : "2.1". Toute valeur 2.x est valide ; une autre valeur génère un avertissement. |
injects_css | booléen | Facultatif | Si false, Inject.css n'est pas chargé. |
extends | string | Facultatif | Identifiant d'un thème V2 installé dont hériter. |
L'identifiant est calculé lors de l'import : minuscules, espaces remplacés par _, et format nom_auteur. Maximum 64 caractères, sans :, / ni barre oblique inverse.
Comment les clés deviennent des variablesmodifier
| Section | Variable générée | Clé d'exemple | Résultat |
|---|---|---|---|
[colors] | --{clé} | accent = "#8FBF6A" | --accent |
[text] | --text-{clé} | primary = "#E6EFDC" | --text-primary |
[borders] | --border-{clé} | radius = "10px" | --border-radius |
[layout] | --{clé} | sidebar-width = "248px" | --sidebar-width |
[shadows] | --{clé} | shadow-md = "0 10px 28px #0006" | --shadow-md |
[backgrounds] | --bg-{clé} | input = "#080C08" | --bg-input |
[backdrop] | --backdrop-blur-{clé} | modal = 8.0 | --backdrop-blur-modal: 8px |
[others] | --{clé} | icon-filter = "invert(1)" | --icon-filter |
[typography] | table fixe | size_base = "14px" | --font-size-base |
[spacing] | --space-{clé} | lg = "16px" | --space-lg |
[motion] | --transition-{clé} | fast = "0.15s" | --transition-fast |
[components.nom] | --component-nom-{clé} | — | Réservé |
[tokens] | littéral | "--bg-image-blur" = "12px" | --bg-image-blur |
Règles de précédence :
- Les sections sont appliquées dans l'ordre du tableau et
[tokens]vient en dernier, donc il l'emporte toujours. - Si deux clés produisent la même variable, la dernière l'emporte et un avertissement
Key collisionest émis.[colors] bg-mainet[backgrounds] mainsont la même variable. [tokens]est la voie pour les variables sans section propre, comme--bg-image-blurou--font-family-mono. La clé doit commencer par--.[components]est converti en variables--component-*, mais aucun composant ne les consomme encore.
Les valeurs sont copiées telles quelles dans le CSS : si le CSS a besoin d'une unité, incluez-la dans la valeur ("12px", pas "12").
Typographymodifier
| Champ | Variable |
|---|---|
family | --font-family |
size_base | --font-size-base |
size_sm | --font-size-sm |
size_lg | --font-size-lg |
size_control | --font-size-control |
size_label | --font-size-label |
weight_normal | --font-weight-normal |
weight_medium | --font-weight-medium |
weight_bold | --font-weight-bold |
line_height | --line-height |
Héritage avec extendsmodifier
Un thème peut hériter des tokens d'un autre thème V2 installé :
name = "Forêt claire"
author = "votre_pseudo"
version = "1.0.0"
format = 2
extends = "bosque_votre_pseudo"extendscontient l'identifiant installé, pas le nom visible. Le préfixeuser:est accepté et ignoré.- Le thème de base doit être installé et être de type V2.
- Profondeur maximale : 8 niveaux. Un cycle constitue une erreur.
- L'enfant l'emporte clé par clé : ce qu'il ne définit pas, il l'hérite.
| Hérité | Non hérité |
|---|---|
colors, text, borders, layout, shadows | fonts |
backgrounds, backdrop, others, tokens | icons |
spacing, motion, components | [inject] |
typography champ par champ | [layout_pack] |
[background] champ par champ | background.reference_path |
Les assets ne sont pas hérités, car les chemins sont relatifs au thème qui les déclare.
Layout packmodifier
Layout.css est chargé à la fin, sans couche, et sert à restructurer l'ossature au moyen d'attributs stables :
[layout_pack]
path = "Layout.css"
enabled = truedata-part | Élément |
|---|---|
app | Conteneur racine. |
sidebar | Conteneur de la barre latérale. |
sidebar-panel | Panneau interne (normal ou compact). |
sidebar-header | En-tête de la barre latérale. |
sidebar-content | Contenu de la barre latérale. |
sidebar-sections | Liste des sections. |
content | Zone principale. |
background-overlay | Couche de l'image d'arrière-plan. |
/* Layout.css — barre latérale flottante */
[data-part="sidebar"] {
margin: 8px;
border-radius: var(--border-radius-lg);
border: 1px solid var(--border-color);
overflow: hidden;
}Limites et validationsmodifier
| Ressource | Limite | En cas de dépassement |
|---|---|---|
| Image d'arrière-plan | 25 MB, image valide | L'arrière-plan est ignoré. |
| Icônes raster | 2 MB, SVG/PNG/WEBP/JPG | L'icône est ignorée. |
| Nombre d'icônes | 100 recommandées | Seules les 100 premières sont préchargées. |
| Polices | 12 recommandées, 20 chargées | Avertissement ; le reste n'est pas chargé. |
Inject.css | 256 KiB recommandés | Avertissement ; il est chargé quand même. |
| Résolution de l'arrière-plan | 4096×4096 | Avertissement pour la mémoire. |
Profondeur de extends | 8 niveaux | Erreur ; le thème ne s'installe pas. |
| Identifiant | 64 caractères | Erreur ; le thème ne s'installe pas. |
Erreurs courantesmodifier
| Message ou symptôme | Cause | Solution |
|---|---|---|
Aucun fichier Meta.toml ni theme.json trouvé | Le ZIP ne contient pas le manifeste à la racine ni dans un dossier conteneur. | Vérifiez la structure du ZIP. |
Meta.toml invalide | TOML mal formé : guillemets non fermés, table répétée. | Validez le TOML avec n'importe quel linter. |
format X non pris en charge ; 2 attendu | format absent ou différent de 2. | Ajoutez format = 2. |
le thème de base 'x' n'est pas installé ou n'est pas V2 | extends pointe vers un identifiant inexistant. | Utilisez l'identifiant d'un thème V2 installé. |
Cycle d'héritage | A → B → A. | Retirez l'un des extends. |
Héritage trop profond | Plus de 8 niveaux. | Aplatissez la chaîne. |
| Les couleurs ne changent pas | Clé dans la mauvaise section ou variable inexistante. | Vérifiez la table de correspondance et la console. |
| Une couleur reste obsolète | Vous avez changé accent mais pas accent-rgb. | Mettez à jour le triplet. |
| L'arrière-plan n'apparaît pas | Chemin incorrect, plus de 25 MB ou fichier qui n'est pas une image. | Utilisez un chemin relatif et une image valide. |
| La police ne s'applique pas | --font-family ne mentionne pas la famille ou src n'existe pas. | Vérifiez family, src et [typography].family. |
| Une icône ne change pas | La clé ne correspond pas à groupe:nom. | Copiez le nom exact depuis la référence. |
Inject.css ne fait aucun effet | [inject] manque ou le sélecteur perd à cause de la couche. | Déclarez [inject] et essayez layer = "unlayered". |
Liste de vérificationmodifier
Avant de partager un thème :
format = 2etnamenon vide.- Le ZIP s'ouvre avec
Meta.tomletDefinition.tomlà la racine ou dans un dossier conteneur. accent-rgbcorrespond àaccent;surface-rgbest cohérent avec le thème clair ou sombre.- Contraste d'au moins 4.5:1 entre
--text-primaryet--bg-main. - L'arrière-plan pèse moins de 25 MB et utilise un chemin relatif.
- Les polices sont incluses dans le paquet, avec une licence compatible, et
--font-familyles mentionne. - Les icônes utilisent des clés
groupe:nomexactes. - Si vous utilisez
extends, le thème de base est de type V2 et installé. - Vous avez testé en fenêtre normale, compacte et maximisée.
- Le thème s'installe de zéro sur une copie propre du launcher.
Concevoir des thèmes avec l'IAmodifier
Un agent peut écrire un thème complet s'il reçoit le format exact, les noms des tokens et les contraintes. Sans cela, il invente des variables qui n'existent pas et le résultat ne s'applique pas. Et sans budget de poids, il a tendance à remplir le thème de ressources inutiles.
Contrat du formatmodifier
Résumé minimal à fournir à un modèle :
- Deux fichiers obligatoires :
Meta.tomletDefinition.toml. Meta.toml:name,author,version,description,format = 2,api_version = "2.1".Definition.toml: sections[colors],[text],[borders],[shadows],[layout],[backdrop],[others],[typography],[spacing],[motion],[tokens].- Préfixes :
[colors]et[layout]sans préfixe ;[text]→--text-,[borders]→--border-,[spacing]→--space-,[motion]→--transition-. accent-rgbetsurface-rgbsont des tripletsR, G, Bsansrgb().- Les valeurs incluent l'unité lorsque le CSS en a besoin.
- Seuls existent les tokens de la référence : on n'invente pas de nouveaux noms.
- Contraste minimal de 4.5:1 pour le texte principal.
Règles d'optimisationmodifier
Un thème généré par IA tend à la surcharge : il déclare les 60 variables alors que seules 20 changent, ajoute un Inject.css inutile et propose un arrière-plan 4K. Ces restrictions l'évitent :
- Minimum viable : uniquement les clés qui modifient le résultat. Si la valeur correspond à celle du launcher, elle n'a pas sa place.
- Pas de CSS sauf demande explicite : tout ce qui se règle avec des tokens se règle avec des tokens.
- Cinq rôles de couleur : arrière-plan, surface, texte, accent et bordure. Rien de plus.
- Aucun asset inventé : ne demandez pas d'images ni de polices que l'utilisateur ne possède pas. S'il faut un arrière-plan, indiquez les dimensions plutôt qu'un fichier.
- Budget de poids : arrière-plan < 500 KB, polices < 300 KB, icônes < 20,
Inject.css< 16 KB. - Ordre stable : toujours les mêmes sections, dans le même ordre, avec un commentaire par section. Ainsi le fichier se vérifie d'un coup d'œil.
Prompt de basemodifier
Crée un thème V2 pour CubicLauncher : propre, minimaliste et optimisé.
Renvoie deux blocs de code, Meta.toml et Definition.toml.
Meta.toml, dans cet ordre :
name, author, version, description, format = 2, api_version = "2.1"
Definition.toml :
- Utilise uniquement ces sections : [colors], [text], [borders], [shadows], [layout],
[typography], [tokens].
- N'écris que les clés qui modifient le résultat. Ne répète pas les valeurs
par défaut et n'ajoute pas de clés que tu n'utiliseras pas.
- Chaque section comporte un commentaire d'une ligne expliquant son intention.
- Ne génère pas de Inject.css, Layout.css ni fichiers d'assets.
Palette, cinq rôles et rien de plus :
fond <couleur>, surface <couleur>, texte <couleur>, accent <couleur>, bordure <couleur>
Règles obligatoires :
- accent-rgb reprend accent sous la forme "R, G, B". surface-rgb vaut "255, 255, 255"
dans les thèmes sombres et "0, 0, 0" dans les clairs.
- Contraste minimal de 4.5:1 entre --text-primary et --bg-main.
- Toutes les valeurs incluent l'unité lorsque le CSS en a besoin (px, rem, s).
- N'invente pas de variables : utilise uniquement des tokens qui existent dans la référence.
- Si tu déclares [background], utilise un chemin relatif et des valeurs prudentes :
image_opacity entre 0.25 et 0.4, brightness entre 0.35 et 0.5, image_blur de 0 à 12.
En dehors des blocs, ajoute trois lignes :
1. Famille typographique recommandée et graisses nécessaires.
2. Dimensions et format idéaux pour l'arrière-plan.
3. Quoi retirer si le thème devient trop lourd.Comment éviter les résultats génériquesmodifier
- Choisissez les couleurs avant le prompt. Un modèle a tendance à renvoyer le même violet sur gris si vous ne lui donnez pas de direction.
- Demandez des rôles, pas des valeurs isolées. « Fond presque noir avec une teinte verte, surfaces désaturées, accent vert lime saturé » produit de meilleurs résultats que « thème vert ».
- Fixez le contraste comme exigence. Sans cette contrainte, les textes secondaires deviennent illisibles.
- Vérifiez les triplets. C'est l'erreur la plus fréquente dans les thèmes générés :
accentchange etaccent-rgbreste blanc. - Itérez sur le fichier, pas sur le prompt. Demandez le thème, installez-le et ajustez des valeurs concrètes ; c'est plus rapide que de réécrire l'instruction.
- Demandez le budget, pas seulement la palette. « Arrière-plan de 1600×900 en WebP, deux graisses d'une seule famille, sans CSS supplémentaire » évite que le résultat arrive avec douze mégaoctets d'assets.