Un tema cambia el aspecto completo de CubicLauncher: colores, tipografía, fondo, iconos y detalles de la interfaz. No hay que compilar nada ni tocar código del launcher: un tema son dos archivos de texto y, si querés, algunas imágenes y fuentes.
Esta guía arma un tema real de principio a fin, en pasos cortos, con un punto de control después de cada uno. Al final tenés un ZIP instalable y publicado.
- Un editor de texto y un programa para comprimir en ZIP.
- Una versión reciente de CubicLauncher.
- Diez minutos para el primer tema funcional.
Si solo querés instalar un tema hecho por otra persona, mirá Cómo poner un theme.
Cómo funciona un temaeditar
El launcher lee los archivos del tema, los convierte en variables CSS y las aplica sobre la interfaz. Por eso casi todo se personaliza declarando valores, sin escribir selectores:
Meta.toml → identidad: nombre, autor, versión, herencia
Definition.toml → apariencia: colores, fondo, fuentes, iconos
Inject.css → detalles que las variables no alcanzan (opcional)
Layout.css → reestructurar el armazón (opcional)Cada clave de Definition.toml produce una variable con un prefijo fijo. Por ejemplo, accent = "#8FBF6A" en [colors] se convierte en --accent, y primary = "#E6EFDC" en [text] se convierte en --text-primary.
Hay dos versiones del formato. Esta guía usa V2, la actual. La V1 (theme.json) se sigue cargando por compatibilidad, pero no admite iconos, herencia ni CSS propio.
Paso 1 — Crear la carpeta y el manifiestoeditar
Creá una carpeta para tu tema, por ejemplo bosque, y dentro un archivo Meta.toml:
name = "Bosque"
author = "tu_usuario"
version = "0.1.0"
description = "Tema oscuro con acento verde y fondo de bosque."
format = 2
api_version = "2.1"Con esos campos ya tenés un tema válido. format debe ser exactamente 2 y api_version declara la serie de la API contra la que se escribió el tema: hoy "2.1".
Después agregá Definition.toml con una sola sección vacía por ahora:
[colors]Comprimí la carpeta en un ZIP y arrastralo a la ventana del launcher.
Punto de control: el tema aparece en el selector como Bosque y, al activarlo, la interfaz se ve igual que antes. Eso es correcto: todavía no cambiaste ningún valor.
El launcher genera el identificador interno a partir de name y author: "Bosque" + "tu_usuario" se guarda como bosque_tu_usuario en ~/.cubic/themes/. Ese identificador es el que se usa para heredar de otro tema.
Paso 2 — Definir la paletaeditar
Un tema se sostiene con cinco colores: fondo, superficie, texto, acento y borde. Elegilos antes de escribir nada, así el resto sale coherente.
Agregá estas dos secciones a 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"Qué hace cada uno:
| Clave | Efecto |
|---|---|
bg-main | Fondo de la ventana. |
bg-sidebar | Fondo de la barra lateral, un escalón más claro que el fondo. |
bg-card | Tarjetas, modales y paneles. |
bg-input | Campos de texto, un escalón más oscuro. |
accent | Botones, focos, enlaces y elementos activos. |
accent-text | Texto que va encima del acento. |
border-color | Bordes y separadores. |
Punto de control: el launcher cambia de inmediato. Si algún color no se aplica, revisá que la clave esté en la sección correcta y mirá la consola: los nombres repetidos generan una advertencia de colisión.
accent-rgb debe ser el mismo color que accent, escrito como R, G, B sin rgb(). La interfaz lo usa en rgba(var(--accent-rgb), 0.15) para brillos y bordes. Si lo olvidás, esos detalles conservan el blanco original.
surface-rgb funciona igual, pero para las superficies translúcidas. En un tema oscuro vale 255, 255, 255 (por defecto); en un tema claro tiene que ser 0, 0, 0, o los bordes se aclaran en lugar de oscurecerse.
Paso 3 — Ajustar bordes, sombras y medidaseditar
Con la paleta lista, definí las formas. Estas secciones son opcionales, pero son las que hacen que un tema se vea terminado y no como un recoloreado:
[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] agrega el prefijo --border-, [spacing] agrega --space- y [layout] no agrega ninguno: la clave es la variable completa.
Punto de control: las esquinas cambian de radio, las tarjetas ganan profundidad y la barra lateral se ensancha o se angosta.
Paso 4 — Poner una imagen de fondoeditar
El fondo es lo que más identidad aporta. Poné la imagen dentro de la carpeta del tema y declarala con una ruta relativa:
[background]
reference_path = "bg.webp"
image_blur = 12.0
image_opacity = 0.32
mode = "cover"
position = "center"
brightness = 0.45| Clave | Qué controla | Rango útil |
|---|---|---|
reference_path | Ruta a la imagen, relativa al tema. | — |
image_blur | Desenfoque en píxeles. | 0 a 24 |
image_opacity | Transparencia de la capa. | 0.2 a 0.6 |
mode | Encuadre: cover, contain. | — |
position | center, top, bottom left… | — |
brightness | Brillo de la imagen. | 0.3 a 0.7 |
Cuanto más bajo es brightness y más alta la opacidad, más se lee el texto pero menos se ve la imagen. El punto dulce suele estar en brightness entre 0.35 y 0.5 y image_opacity cerca de 0.35.
Punto de control: la imagen se ve detrás del contenido, difuminada y oscurecida, sin tapar la lectura.
La imagen no puede superar 25 MB y debe ser un archivo de imagen real. El launcher verifica la cabecera del archivo, no la extensión: un .png que en realidad es un texto se descarta.
Usá rutas relativas. Las rutas absolutas y file: funcionan en tu máquina, pero rompen el tema en cualquier otra.
Paso 5 — Tipografía propiaeditar
Podés usar cualquier fuente que esté dentro del paquete. Copiá los archivos a fonts/ y declará cada 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 regla importante: [typography].family debe mencionar la misma familia que declaraste en [[fonts]]. Si el nombre no coincide, la fuente se carga pero la interfaz sigue usando la tipografía por defecto.
Punto de control: los títulos y el texto cambian de forma. Si no cambia nada, revisá el nombre de la familia y que la ruta src exista dentro del ZIP.
Una o dos familias alcanzan. Por encima de 12 el selector muestra una advertencia, y el launcher solo carga las primeras 20 variantes.
Paso 6 — Iconoseditar
Los iconos se declaran por grupo. La clave final es grupo:nombre, y tiene que coincidir exactamente con el nombre que pide el componente.
[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 es la imagen que representa tu tema en el selector; conviene que sea una captura del launcher con el tema aplicado.
Los SVG se usan como máscara: se pintan con el color del texto, así que un icono monocromo funciona en temas claros y oscuros. Los PNG, WEBP y JPG se dibujan con sus propios colores.
Punto de control: los iconos de la barra lateral cambian. Si un icono no cambia, la clave no coincide con el nombre real: la lista completa está en Referencia de tokens.
Paso 7 — Detalles finos con CSSeditar
Las variables cubren casi todo, pero hay cosas que solo se resuelven con CSS: pseudo-elementos, animaciones, separadores. Para eso está Inject.css.
Declará la sección en Definition.toml y creá el archivo:
[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;
}La clave está en layer:
theme(por defecto) envuelve tu CSS en@layer cubic.theme. Gana a los estilos globales del launcher, pero pierde frente a los estilos de cada componente.unlayereddeja el CSS sin capa. Compite por especificidad con todo, incluidos los componentes. Es más potente y más frágil.
Punto de control: el cambio se aplica sin reiniciar. Si no ves efecto, probá layer = "unlayered" antes de dar por hecho que el selector está mal.
Evitá depender de clases generadas por Svelte (las que terminan en un hash) y de estructuras internas. Los atributos data-part son estables; el resto puede cambiar entre versiones.
Paso 8 — Empaquetar, instalar y probareditar
- La carpeta debe tener
Meta.tomlyDefinition.tomlen la raíz, junto a los assets. - Comprimila en ZIP. Los archivos pueden quedar en la raíz del ZIP o dentro de una única carpeta contenedora.
- Cambiale la extensión a
.cbthsi querés usar el formato de paquete de temas: es el mismo ZIP con otro nombre. - Instalalo arrastrándolo a la ventana del launcher o desde Ajustes → Temas → Importar tema.
- Elegilo en el selector.
Cómo trata el launcher el paquete:
- Busca
Meta.tomlen la raíz o en una carpeta contenedora. Si encuentra más de uno, rechaza el ZIP. - Si conviven
Meta.tomlytheme.json, gana V2. - Un
.zipse prueba primero como V1 y después como V2; un.cbthsolo se interpreta como V2. - La instalación es atómica: se descomprime en una carpeta temporal y se mueve al destino. Si falla la validación, no queda nada a medias.
- El destino es
~/.cubic/themes/<id>/. Reimportar un tema con el mismo nombre y autor reemplaza la versión anterior.
Probar cambios sin reimportareditar
Mientras el tema está activo, el launcher vigila su carpeta y recarga solo. Editá los archivos en ~/.cubic/themes/<id>/ y mirá el resultado en vivo: es mucho más rápido que comprimir y volver a importar en cada ajuste.
El panel de diagnóstico del selector de temas avisa de tres cosas que no bloquean la carga pero afectan al rendimiento: más de 12 fuentes, CSS de más de 256 KiB y fondos de más de 4096×4096 píxeles.
Paso 9 — Publicar en el catálogoeditar
Los temas comunitarios viven en CubicLauncherDevs/Themes y aparecen en cubiclauncher.org/themes.
src/
└── TuAutor/
└── TuTema/
├── theme.md # descripción del tema
├── vflag.txt # opcional, solo staff: marca el tema como verificado
└── V1/
├── Meta.toml
├── Definition.toml
├── bg.webp
├── Showcase.png # opcional, captura para el catálogo
└── fonts/- Hacé un fork del repositorio.
- Creá
src/TuAutor/TuTema/theme.mdcon una descripción breve. - Creá
src/TuAutor/TuTema/V1/conMeta.toml,Definition.tomly los assets. - Abrí un Pull Request.
La integración continua optimiza las imágenes, genera la vista previa, sube los binarios al almacenamiento del catálogo y actualiza themes.json. Los binarios no se guardan en Git.
Optimizar el temaeditar
Un tema se lee cada vez que se activa: el launcher parsea los dos manifiestos, valida el fondo abriendo el archivo, revisa cada icono, resuelve cada fuente y carga el CSS en memoria. Después el frontend decodifica la imagen y registra las tipografías antes de mostrar la interfaz completa. Un tema pesado no se ve mejor: tarda más en aparecer.
Estas son las decisiones que más impacto tienen, de mayor a menor.
El fondo: la imagen más grande y la que menos detalle necesitaeditar
La imagen se dibuja desenfocada y con opacidad baja, así que la resolución casi no se nota. Un fondo de 1600×900 se ve igual que uno de 4K después del desenfoque, pero pesa ocho veces menos y se decodifica al instante.
| Práctica | Por qué |
|---|---|
| Exportá en WebP con calidad 75–85. | Mismo aspecto que un PNG con una fracción del peso. |
| Bajá la resolución a 1600×900 o 1920×1080. | El desenfoque oculta la falta de detalle. |
| Apuntá a menos de 500 KB. | El límite es 25 MB, pero el objetivo real es otro. |
Desenfocá la imagen en el editor y usá image_blur bajo. | El desenfoque en vivo se recalcula sobre toda la ventana. |
| Evitá más de 4096×4096. | El selector avisa por el consumo de memoria al decodificarla. |
Un image_blur alto sobre una imagen grande es la combinación más costosa: se paga el desenfoque en cada redibujado. Si la imagen ya viene desenfocada, image_blur = 0 da el mismo resultado sin costo.
Fuentes: solo lo que se usaeditar
Cada archivo declarado se descarga, se registra y se aplica. Una familia con cuatro pesos suma cuatro archivos.
- Usá WOFF2. Es el formato más chico y el que mejor soporte tiene.
- Declará solo los pesos que el tema realmente necesita: normalmente
400y600. - Preferí fuentes con subconjunto latino; una fuente con cirílico, griego y CJK puede pesar diez veces más.
- Dos familias es el máximo razonable. Una sola, bien elegida, alcanza para casi todo.
Iconos: SVG y solo los que cambianeditar
Los SVG pesan unos pocos KB y se colorean solos. Los raster (PNG, WEBP, JPG) se cargan con sus colores y suelen pesar mucho más.
- Reemplazá solo los iconos que aportan identidad. Cada entrada se valida al cargar el tema, aunque nunca se muestre.
- No incluyas un icono si el original ya te sirve.
- Si usás raster, mantenelo por debajo de 64×64 y de 50 KB: el límite es 2 MB, pero un icono de 2 MB tarda en aparecer.
CSS: primero variables, después selectoreseditar
Inject.css se carga y se interpreta en cada activación. Todo lo que se resuelve con una variable debería resolverse con una variable.
- Si podés cambiar un color, un radio o una sombra desde
Definition.toml, no escribas CSS. - Mantené
Inject.csspor debajo de 16 KB; el límite recomendado es 256 KiB. - No animes
filter,backdrop-filternibox-shadow: son las propiedades más caras de redibujar. - Evitá
!important. Si lo necesitás, el selector está mal elegido. - No dupliques en CSS lo que ya hace
Layout.css.
Tokens: no repitas los valores por defectoeditar
Cada variable declarada se inyecta en una hoja de estilo. Repetir el valor por defecto no cambia nada y hace más difícil leer el tema.
- Declará solo los tokens que difieren del launcher.
- Si dos claves generan la misma variable, quedate con una: la otra produce una advertencia de colisión.
- Para variantes de color, usá
extendsen lugar de copiar la paleta completa. - Declará
--color-scheme("dark"o"light") en[others]para que las barras de desplazamiento y los controles nativos acompañen al tema.
Objetivos de pesoeditar
| Recurso | Objetivo | Límite técnico |
|---|---|---|
| ZIP completo | menos de 3 MB | — |
| Imagen de fondo | menos de 500 KB | 25 MB |
| Fuentes | menos de 300 KB en total | 12 recomendadas, 20 cargadas |
| Iconos | menos de 20, SVG | 100 precargados |
Inject.css | menos de 16 KB | 256 KiB recomendado |
| Tokens declarados | 25 a 40 claves | — |
Cómo medireditar
- Mirá el tamaño del ZIP antes de publicar: es el número que ve quien lo descarga.
- El panel de diagnóstico del selector de temas avisa si el fondo es demasiado grande, si hay demasiadas fuentes o si el CSS se pasa de tamaño.
- Si el tema tarda en aparecer al cambiar de uno a otro, el problema casi siempre es la imagen de fondo o la cantidad de fuentes.
Ejemplo completoeditar
Un Meta.toml y un Definition.toml listos para copiar, con todo lo de los pasos anteriores. Los assets (bg.webp, fonts/, icons/, Inject.css) son opcionales: si faltan, el launcher los ignora y sigue con el resto del tema.
# Meta.toml
name = "Bosque"
author = "tu_usuario"
version = "1.0.0"
description = "Tema oscuro con acento verde y fondo de bosque."
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"Referencia de camposeditar
Meta.tomleditar
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | Sí | Nombre visible. No puede estar vacío. |
author | string | Recomendado | Autor. Se muestra en minúsculas y forma parte del identificador. |
version | string | Recomendado | Versión, idealmente MAYOR.MENOR.PARCHE. |
description | string | Opcional | Descripción de una línea para el catálogo. |
format | entero | Sí | Debe ser exactamente 2. |
api_version | string | Opcional | Serie de la API: "2.1". Cualquier valor 2.x es válido; otro valor genera una advertencia. |
injects_css | booleano | Opcional | Si es false, Inject.css no se carga. |
extends | string | Opcional | Identificador de un tema V2 instalado del que heredar. |
El identificador se calcula al importar: minúsculas, espacios reemplazados por _, y el formato nombre_autor. Máximo 64 caracteres, sin :, / ni barra invertida.
Cómo se convierten las claves en variableseditar
| Sección | Variable generada | Clave de ejemplo | Resultado |
|---|---|---|---|
[colors] | --{clave} | accent = "#8FBF6A" | --accent |
[text] | --text-{clave} | primary = "#E6EFDC" | --text-primary |
[borders] | --border-{clave} | radius = "10px" | --border-radius |
[layout] | --{clave} | sidebar-width = "248px" | --sidebar-width |
[shadows] | --{clave} | shadow-md = "0 10px 28px #0006" | --shadow-md |
[backgrounds] | --bg-{clave} | input = "#080C08" | --bg-input |
[backdrop] | --backdrop-blur-{clave} | modal = 8.0 | --backdrop-blur-modal: 8px |
[others] | --{clave} | icon-filter = "invert(1)" | --icon-filter |
[typography] | tabla fija | size_base = "14px" | --font-size-base |
[spacing] | --space-{clave} | lg = "16px" | --space-lg |
[motion] | --transition-{clave} | fast = "0.15s" | --transition-fast |
[components.nombre] | --component-nombre-{clave} | — | Reservado |
[tokens] | literal | "--bg-image-blur" = "12px" | --bg-image-blur |
Reglas de precedencia:
- Las secciones se aplican en el orden de la tabla y
[tokens]va al final, así que siempre gana. - Si dos claves producen la misma variable, la última gana y se emite una advertencia
Key collision.[colors] bg-mainy[backgrounds] mainson la misma variable. [tokens]es la vía para variables sin sección propia, como--bg-image-bluro--font-family-mono. La clave debe empezar por--.[components]se convierte en variables--component-*, pero ningún componente las consume todavía.
Los valores se copian al CSS tal cual: si el CSS necesita unidad, incluila en el valor ("12px", no "12").
Typographyeditar
| Campo | 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 |
Herencia con extendseditar
Un tema puede heredar los tokens de otro tema V2 instalado:
name = "Bosque claro"
author = "tu_usuario"
version = "1.0.0"
format = 2
extends = "bosque_tu_usuario"extendslleva el identificador instalado, no el nombre visible. Se acepta el prefijouser:y se descarta.- El tema base debe estar instalado y ser V2.
- Profundidad máxima: 8 niveles. Un ciclo es un error.
- El hijo gana clave a clave: lo que no define, lo hereda.
| Se hereda | No se hereda |
|---|---|
colors, text, borders, layout, shadows | fonts |
backgrounds, backdrop, others, tokens | icons |
spacing, motion, components | [inject] |
typography campo por campo | [layout_pack] |
[background] campo por campo | background.reference_path |
Los assets no se heredan porque las rutas son relativas al tema que las declara.
Layout packeditar
Layout.css se carga al final, sin capa, y sirve para reestructurar el armazón mediante atributos estables:
[layout_pack]
path = "Layout.css"
enabled = truedata-part | Elemento |
|---|---|
app | Contenedor raíz. |
sidebar | Contenedor de la barra lateral. |
sidebar-panel | Panel interno (normal o compacto). |
sidebar-header | Cabecera de la barra lateral. |
sidebar-content | Contenido de la barra lateral. |
sidebar-sections | Lista de secciones. |
content | Área principal. |
background-overlay | Capa de la imagen de fondo. |
/* Layout.css — barra lateral flotante */
[data-part="sidebar"] {
margin: 8px;
border-radius: var(--border-radius-lg);
border: 1px solid var(--border-color);
overflow: hidden;
}Límites y validacioneseditar
| Recurso | Límite | Si se supera |
|---|---|---|
| Imagen de fondo | 25 MB, imagen válida | Se ignora el fondo. |
| Iconos raster | 2 MB, SVG/PNG/WEBP/JPG | Se ignora el icono. |
| Cantidad de iconos | 100 recomendados | Solo se precargan los primeros 100. |
| Fuentes | 12 recomendadas, 20 cargadas | Advertencia; el resto no se carga. |
Inject.css | 256 KiB recomendados | Advertencia; se carga igual. |
| Resolución del fondo | 4096×4096 | Advertencia por memoria. |
Profundidad de extends | 8 niveles | Error; el tema no se instala. |
| Identificador | 64 caracteres | Error; el tema no se instala. |
Errores comuneseditar
| Mensaje o síntoma | Causa | Solución |
|---|---|---|
No se encontró Meta.toml ni theme.json | El ZIP no tiene el manifiesto en la raíz ni en una carpeta contenedora. | Revisá la estructura del ZIP. |
Meta.toml inválido | TOML mal formado: comillas sin cerrar, tabla repetida. | Validá el TOML con cualquier linter. |
format X no soportado; se esperaba 2 | format ausente o distinto de 2. | Agregá format = 2. |
el tema base 'x' no está instalado o no es V2 | extends apunta a un identificador inexistente. | Usá el identificador de un tema V2 instalado. |
Ciclo de herencia | A → B → A. | Quitá uno de los extends. |
Herencia demasiado profunda | Más de 8 niveles. | Aplaná la cadena. |
| Los colores no cambian | Clave en la sección equivocada o variable inexistente. | Verificá la tabla de mapeo y la consola. |
| Un color quedó viejo | Cambiaste accent pero no accent-rgb. | Actualizá el triplete. |
| El fondo no aparece | Ruta incorrecta, más de 25 MB o archivo que no es imagen. | Usá una ruta relativa y una imagen válida. |
| La fuente no se aplica | --font-family no menciona la familia o src no existe. | Revisá family, src y [typography].family. |
| Un icono no cambia | La clave no coincide con grupo:nombre. | Copiá el nombre exacto de la referencia. |
Inject.css no hace efecto | Falta [inject] o el selector pierde por capa. | Declará [inject] y probá layer = "unlayered". |
Lista de verificacióneditar
Antes de compartir un tema:
format = 2ynameno vacío.- El ZIP abre con
Meta.tomlyDefinition.tomlen la raíz o en una carpeta contenedora. accent-rgbcoincide conaccent;surface-rgbes coherente con el tema claro u oscuro.- Contraste de al menos 4.5:1 entre
--text-primaryy--bg-main. - El fondo pesa menos de 25 MB y usa una ruta relativa.
- Las fuentes están dentro del paquete, con licencia compatible, y
--font-familylas menciona. - Los iconos usan claves
grupo:nombreexactas. - Si usás
extends, el tema base es V2 y está instalado. - Probaste ventana normal, compacta y maximizada.
- El tema se instala desde cero en una copia limpia del launcher.
Diseñar temas con IAeditar
Un agente puede escribir un tema completo si recibe el formato exacto, los nombres de los tokens y las restricciones. Sin eso inventa variables que no existen y el resultado no se aplica. Y sin un presupuesto de peso, tiende a llenar el tema de recursos que no aportan.
Contrato del formatoeditar
Resumen mínimo que hay que darle a un modelo:
- Dos archivos obligatorios:
Meta.tomlyDefinition.toml. Meta.toml:name,author,version,description,format = 2,api_version = "2.1".Definition.toml: secciones[colors],[text],[borders],[shadows],[layout],[backdrop],[others],[typography],[spacing],[motion],[tokens].- Prefijos:
[colors]y[layout]sin prefijo;[text]→--text-,[borders]→--border-,[spacing]→--space-,[motion]→--transition-. accent-rgbysurface-rgbson tripletesR, G, Bsinrgb().- Los valores incluyen unidad cuando el CSS la necesita.
- Solo existen los tokens de la referencia: no se inventan nombres nuevos.
- Contraste mínimo 4.5:1 para texto principal.
Reglas de optimizacióneditar
Un tema generado por IA tiende a la sobrecarga: declara las 60 variables aunque solo cambie 20, agrega un Inject.css innecesario y propone un fondo de 4K. Estas restricciones evitan eso:
- Mínimo viable: solo las claves que cambian el resultado. Si el valor coincide con el del launcher, no va.
- Sin CSS salvo pedido explícito: todo lo que se resuelve con tokens se resuelve con tokens.
- Cinco roles de color: fondo, superficie, texto, acento y borde. Nada más.
- Sin assets inventados: no pidas imágenes ni fuentes que el usuario no tenga. Si hace falta un fondo, indicá las medidas en lugar de un archivo.
- Presupuesto de peso: fondo < 500 KB, fuentes < 300 KB, iconos < 20,
Inject.css< 16 KB. - Orden estable: siempre las mismas secciones, en el mismo orden, con un comentario por sección. Así el archivo se revisa de un vistazo.
Prompt baseeditar
Crea un tema V2 para CubicLauncher: limpio, minimalista y optimizado.
Devuelve dos bloques de código, Meta.toml y Definition.toml.
Meta.toml, en este orden:
name, author, version, description, format = 2, api_version = "2.1"
Definition.toml:
- Usa solo estas secciones: [colors], [text], [borders], [shadows], [layout],
[typography], [tokens].
- Escribe únicamente las claves que cambian el resultado. No repitas valores
por defecto ni agregues claves que no vayas a usar.
- Cada sección lleva un comentario de una línea explicando su intención.
- No generes Inject.css, Layout.css ni archivos de assets.
Paleta, cinco roles y nada más:
fondo <color>, superficie <color>, texto <color>, acento <color>, borde <color>
Reglas obligatorias:
- accent-rgb repite accent como "R, G, B". surface-rgb es "255, 255, 255"
en temas oscuros y "0, 0, 0" en claros.
- Contraste mínimo 4.5:1 entre --text-primary y --bg-main.
- Todos los valores llevan unidad cuando el CSS la necesita (px, rem, s).
- No inventes variables: usa solo tokens que existan en la referencia.
- Si declaras [background], usa una ruta relativa y valores conservadores:
image_opacity entre 0.25 y 0.4, brightness entre 0.35 y 0.5, image_blur 0 a 12.
Fuera de los bloques, agrega tres líneas:
1. Familia tipográfica recomendada y pesos necesarios.
2. Medidas y formato ideales para el fondo.
3. Qué recortar si el tema queda pesado.Cómo evitar resultados genéricoseditar
- Elegí los colores antes del prompt. Un modelo tiende a devolver el mismo violeta sobre gris si no le das una dirección.
- Pedí roles, no valores sueltos. "Fondo casi negro con tinte verde, superficies desaturadas, acento verde lima saturado" produce mejores resultados que "tema verde".
- Fijá el contraste como requisito. Sin esa restricción, los textos secundarios quedan ilegibles.
- Revisá los tripletes. Es el error más frecuente en temas generados:
accentcambia yaccent-rgbqueda en blanco. - Iterá sobre el archivo, no sobre el prompt. Pedí el tema, instalalo y ajustá valores concretos; es más rápido que reescribir la instrucción.
- Pedí el presupuesto, no solo la paleta. "Fondo de 1600×900 en WebP, dos pesos de una sola familia, sin CSS extra" evita que el resultado llegue con doce megabytes de assets.