Cargando

Cargando...

Saltar al contenido
CubicLauncherDocs

Crear un tema

Guía paso a paso para crear un tema de CubicLauncher desde cero — paleta, fondo, tipografía, iconos, CSS propio, empaquetado y publicación.

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.

Antes de empezar
  • 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:

text
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:

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:

toml
[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.

Nombre e identificador

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:

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:

ClaveEfecto
bg-mainFondo de la ventana.
bg-sidebarFondo de la barra lateral, un escalón más claro que el fondo.
bg-cardTarjetas, modales y paneles.
bg-inputCampos de texto, un escalón más oscuro.
accentBotones, focos, enlaces y elementos activos.
accent-textTexto que va encima del acento.
border-colorBordes 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.

Los dos tripletes que se olvidan

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:

toml
[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:

toml
[background]
reference_path = "bg.webp"
image_blur = 12.0
image_opacity = 0.32
mode = "cover"
position = "center"
brightness = 0.45
ClaveQué controlaRango útil
reference_pathRuta a la imagen, relativa al tema.—
image_blurDesenfoque en píxeles.0 a 24
image_opacityTransparencia de la capa.0.2 a 0.6
modeEncuadre: cover, contain.—
positioncenter, top, bottom left…—
brightnessBrillo 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.

Límites del fondo

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:

toml
[[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.

Cuántas fuentes

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.

toml
[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:

toml
[inject]
path = "Inject.css"
enabled = true
layer = "theme"
css
/* 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.
  • unlayered deja 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.

CSS y actualizaciones

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

  1. La carpeta debe tener Meta.toml y Definition.toml en la raíz, junto a los assets.
  2. Comprimila en ZIP. Los archivos pueden quedar en la raíz del ZIP o dentro de una única carpeta contenedora.
  3. Cambiale la extensión a .cbth si querés usar el formato de paquete de temas: es el mismo ZIP con otro nombre.
  4. Instalalo arrastrándolo a la ventana del launcher o desde Ajustes → Temas → Importar tema.
  5. Elegilo en el selector.

Cómo trata el launcher el paquete:

  • Busca Meta.toml en la raíz o en una carpeta contenedora. Si encuentra más de uno, rechaza el ZIP.
  • Si conviven Meta.toml y theme.json, gana V2.
  • Un .zip se prueba primero como V1 y después como V2; un .cbth solo 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.

Los temas comunitarios viven en CubicLauncherDevs/Themes y aparecen en cubiclauncher.org/themes.

text
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/
  1. Hacé un fork del repositorio.
  2. Creá src/TuAutor/TuTema/theme.md con una descripción breve.
  3. Creá src/TuAutor/TuTema/V1/ con Meta.toml, Definition.toml y los assets.
  4. 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ácticaPor 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 400 y 600.
  • 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.css por debajo de 16 KB; el límite recomendado es 256 KiB.
  • No animes filter, backdrop-filter ni box-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á extends en 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

RecursoObjetivoLímite técnico
ZIP completomenos de 3 MB—
Imagen de fondomenos de 500 KB25 MB
Fuentesmenos de 300 KB en total12 recomendadas, 20 cargadas
Iconosmenos de 20, SVG100 precargados
Inject.cssmenos de 16 KB256 KiB recomendado
Tokens declarados25 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.

toml
# 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"
toml
# 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

CampoTipoObligatorioDescripción
namestringSíNombre visible. No puede estar vacío.
authorstringRecomendadoAutor. Se muestra en minúsculas y forma parte del identificador.
versionstringRecomendadoVersión, idealmente MAYOR.MENOR.PARCHE.
descriptionstringOpcionalDescripción de una línea para el catálogo.
formatenteroSíDebe ser exactamente 2.
api_versionstringOpcionalSerie de la API: "2.1". Cualquier valor 2.x es válido; otro valor genera una advertencia.
injects_cssbooleanoOpcionalSi es false, Inject.css no se carga.
extendsstringOpcionalIdentificador 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ónVariable generadaClave de ejemploResultado
[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 fijasize_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-main y [backgrounds] main son la misma variable.
  • [tokens] es la vía para variables sin sección propia, como --bg-image-blur o --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

CampoVariable
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:

toml
name = "Bosque claro"
author = "tu_usuario"
version = "1.0.0"
format = 2
extends = "bosque_tu_usuario"
  • extends lleva el identificador instalado, no el nombre visible. Se acepta el prefijo user: 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 heredaNo se hereda
colors, text, borders, layout, shadowsfonts
backgrounds, backdrop, others, tokensicons
spacing, motion, components[inject]
typography campo por campo[layout_pack]
[background] campo por campobackground.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:

toml
[layout_pack]
path = "Layout.css"
enabled = true
data-partElemento
appContenedor raíz.
sidebarContenedor de la barra lateral.
sidebar-panelPanel interno (normal o compacto).
sidebar-headerCabecera de la barra lateral.
sidebar-contentContenido de la barra lateral.
sidebar-sectionsLista de secciones.
contentÁrea principal.
background-overlayCapa de la imagen de fondo.
css
/* 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

RecursoLímiteSi se supera
Imagen de fondo25 MB, imagen válidaSe ignora el fondo.
Iconos raster2 MB, SVG/PNG/WEBP/JPGSe ignora el icono.
Cantidad de iconos100 recomendadosSolo se precargan los primeros 100.
Fuentes12 recomendadas, 20 cargadasAdvertencia; el resto no se carga.
Inject.css256 KiB recomendadosAdvertencia; se carga igual.
Resolución del fondo4096×4096Advertencia por memoria.
Profundidad de extends8 nivelesError; el tema no se instala.
Identificador64 caracteresError; el tema no se instala.

Errores comuneseditar

Mensaje o síntomaCausaSolución
No se encontró Meta.toml ni theme.jsonEl ZIP no tiene el manifiesto en la raíz ni en una carpeta contenedora.Revisá la estructura del ZIP.
Meta.toml inválidoTOML mal formado: comillas sin cerrar, tabla repetida.Validá el TOML con cualquier linter.
format X no soportado; se esperaba 2format ausente o distinto de 2.Agregá format = 2.
el tema base 'x' no está instalado o no es V2extends apunta a un identificador inexistente.Usá el identificador de un tema V2 instalado.
Ciclo de herenciaA → B → A.Quitá uno de los extends.
Herencia demasiado profundaMás de 8 niveles.Aplaná la cadena.
Los colores no cambianClave en la sección equivocada o variable inexistente.Verificá la tabla de mapeo y la consola.
Un color quedó viejoCambiaste accent pero no accent-rgb.Actualizá el triplete.
El fondo no apareceRuta 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 cambiaLa clave no coincide con grupo:nombre.Copiá el nombre exacto de la referencia.
Inject.css no hace efectoFalta [inject] o el selector pierde por capa.Declará [inject] y probá layer = "unlayered".

Lista de verificacióneditar

Antes de compartir un tema:

  • format = 2 y name no vacío.
  • El ZIP abre con Meta.toml y Definition.toml en la raíz o en una carpeta contenedora.
  • accent-rgb coincide con accent; surface-rgb es coherente con el tema claro u oscuro.
  • Contraste de al menos 4.5:1 entre --text-primary y --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-family las menciona.
  • Los iconos usan claves grupo:nombre exactas.
  • 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.toml y Definition.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-rgb y surface-rgb son tripletes R, G, B sin rgb().
  • 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

text
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: accent cambia y accent-rgb queda 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.