Temas y fuentes

plasmoid es dueño de su propio CSS: una hoja de estilos pequeña y legible, impulsada por propiedades personalizadas de CSS, con modos claro y oscuro incorporados. No hay Tailwind, ni framework de CSS, ni paso de compilación más allá del propio plasmoid.

Claro y oscuro

Los colores son variables de CSS con paletas clara y oscura. La elección del lector se aplica antes del primer renderizado mediante un diminuto script en línea, así que no hay un destello del tema equivocado (FOUC). Un conmutador en el armazón cambia y recuerda la preferencia. Con JavaScript desactivado, el sitio respeta el prefers-color-scheme del sistema operativo.

Ambas paletas se verifican para garantizar un contraste de texto adecuado.

Tokens de diseño (tokens.css) — elige un tono u override

Las variables de color viven en un /assets/tokens.css generado, enlazado antes de la hoja de estilos del chrome. Lleva la paleta completa (neutros, acento, la rampa de gradiente de marca --ramp-1…4 + --grad-main, colores de botones y semánticos) para claro y oscuro. El chrome —y cualquier landing que escribas— consumen estos var(--…), así que todo el sitio se tematiza desde un archivo.

Ese archivo se ensambla a partir de una capa base compartida (neutros, semánticos, elevación) más un tono superpuesto (los matices, y las superficies que el tono ajuste).

El valor por defecto incluido

plasmoid es software distribuible, así que el binario incluye exactamente un tono: un default sencillo, neutro y agnóstico de marca (superficies de escala de grises con buen gusto + un acento sereno, claro/oscuro completo). Se ve bien en una página de documentación básica de fábrica, con cero configuración. Eso es todo lo que la mayoría de los proyectos necesitan.

[theme]
palette = "default"   # the built-in neutral tone (this is also the default if omitted)

Trae tu propia biblioteca de temas (themes_dir)

Los tonos más ricos o de marca viven fuera del binario, en un directorio de biblioteca de temas al que apuntas plasmoid. Una biblioteca es simplemente una carpeta con la misma forma que tu docs/: un tokens.base.css y un themes/<tono>.css por cada tono.

[theme]
themes_dir = "../brand"      # relative to this docs dir (absolute paths also work)
palette = "electric-blue"    # resolved from <themes_dir>/themes/electric-blue.css

O pásalos en la línea de comandos (estos anulan la configuración):

plasmoid build --themes-dir ../brand --palette electric-blue

Un --themes-dir relativo se resuelve respecto a tu directorio actual; un [theme] themes_dir relativo se resuelve respecto al directorio de documentación. La biblioteca se lee en tiempo de compilación: sin red, sin @import, totalmente sin conexión y reproducible.

Orden de resolución

Para un palette dado, plasmoid toma el primero que exista:

• capa base: docs/tokens.base.css → <themes_dir>/tokens.base.css → la base incluida
• tono superpuesto: docs/themes/<palette>.css → <themes_dir>/themes/<palette>.css → el default incluido (solo para palette = "default")
• wholesale: un docs/tokens.css completo cortocircuita todo — plasmoid lo emite tal cual (copia el /assets/tokens.css emitido como punto de partida).

Un palette que no se resuelve en ningún sitio es un error de compilación que enumera exactamente dónde buscó plasmoid, y te recuerda que configures themes_dir si aún no lo has hecho.

El contrato de tokens

Una base + un tono juntos deben definir cada variable que el chrome consume. Para escribir un tono personalizado (o una biblioteca completa), establece todos estos para claro, y anula lo que cambie para oscuro (:root[data-theme="dark"] + un espejo @media (prefers-color-scheme: dark)):

Grupo	Tokens
Superficies y texto	--bg, --bg-alt, --bg-elev, --bg-code, --border, --fg, --fg-muted
Acentos	--accent, --accent-fg (texto sobre un relleno de acento), --accent-2
Rampa de gradiente	--ramp-1 … --ramp-4 (más claro → más profundo)
Gradientes compuestos	--grad-main (4 paradas, superficies grandes), --grad-accent (2 paradas)
Botones (sólidos)	--btn-bg, --btn-bg-hover, --btn-bg-active, --btn-fg, --btn-shadow, --btn-shadow-hover, --btn-shadow-soft
Efectos	--glow, --shadow
Estados semánticos	--ok, --warn, --danger

Por convención, la capa base aporta los neutros (superficies/texto), la elevación --shadow y los estados semánticos; cada tono aporta los acentos, la rampa, los gradientes, los botones y --glow (y puede reajustar los neutros para adecuarse a su matiz). Cada tono usa los mismos nombres de token, así que es un reemplazo directo: solo difieren los colores.

Como la landing enlaza el mismo /assets/tokens.css, tu landing y tu documentación permanecen sincronizadas sea cual sea la ruta que elijas.

Fuentes

Las fuentes están alojadas localmente: sin CDN de terceros, sin red en tiempo de compilación. plasmoid incluye una opción por defecto que prioriza la accesibilidad y te permite sustituirla:

[theme]
font_body = "Atkinson Hyperlegible"   # the bundled default
font_mono = "JetBrains Mono"
fonts = "self-hosted"                 # "self-hosted" (default) | "system"

• Opción por defecto incluida. De fábrica, el texto del cuerpo usa Atkinson Hyperlegible (Braille Institute, OFL), una tipografía diseñada para la máxima legibilidad. plasmoid emite su @font-face y su woff2 en /assets/fonts/ (con la licencia), de modo que cada proyecto obtiene una buena tipografía sin ninguna configuración. font-display: swap significa que el texto se renderiza de inmediato con una fuente de reserva y la cambia por la fuente web cuando está lista.
• Trae la tuya. Coloca archivos woff2 en docs/fonts/ con los nombres body, body-bold, body-italic, body-bolditalic (y lo mismo para mono), luego configura font_body/font_mono con los nombres de tus familias. plasmoid conecta el @font-face para ellas y omite la opción por defecto incluida.
• Solo del sistema. Configura fonts = "system" para la opción de cero bytes: sin @font-face, solo tus familias encabezando una sólida pila de reserva del sistema.

En cualquier caso, las familias encabezan una pila de reserva del sistema, así que el texto es legible incluso antes (o sin) cualquier fuente web.

Resaltado de código

Los bloques de código se resaltan en tiempo de compilación en clases de CSS (no estilos en línea), de modo que una única salida HTML resaltada queda tematizada tanto para claro como para oscuro mediante hojas de estilo con alcance acotado. No se envía ningún JavaScript de resaltado de sintaxis al navegador.

```rust
fn main() {
    println!("highlighted at build time");
}
```

Accesibilidad integrada

El armazón generado usa puntos de referencia semánticos, un enlace de salto al contenido que realmente mueve el foco, contornos de foco visibles, aria-current en el elemento de navegación activo y un combobox de búsqueda navegable con el teclado. La accesibilidad forma parte de la salida por defecto, no es un complemento.