Stella Nova/Plantillas

Stella Nova ▸ Plantillas

Plantillas

Cómo dar estilo a una plantilla de Casiopea sin romper el tema oscuro ni pelear con el sanitizador de MediaWiki. Está dirigida a quien ajusta el diseño de plantillas existentes o crea plantillas nuevas.

Requiere haber leído Tokens: aquí se da por sabido qué es un token semántico y por qué existen tres capas.

Dónde vive el estilo de una plantilla

Cada plantilla lleva su estilo en una subpágina propia, mediante la extensión TemplateStyles. La ruta canónica en Casiopea es en singular y en español:

Plantilla:X/style.css

Y se invoca desde el wikitexto de la plantilla:

Esto reemplaza a la práctica antigua de acumular reglas en MediaWiki:Common.css. La diferencia no es cosmética: una regla en el CSS global se descarga en todas las páginas de la wiki, aunque solo la use una plantilla, y nadie sabe quién depende de ella. Una hoja de TemplateStyles se carga únicamente donde la plantilla se transcluye, y su ámbito está acotado por MediaWiki al contenido de la página.

Cuando varias plantillas comparten un mismo lenguaje visual, conviene una hoja compartida que todas invoquen, en lugar de duplicar reglas. Precedente en la wiki: Plantilla:Malla Curricular/style.css sirve tanto a las mallas como a los programas, invocada desde ambas plantillas.

La regla de oro

No hardcodear colores. Consumir tokens de la capa semántica, con var(--sn-…) a secas, sin valor de respaldo.

/* mal: color crudo. No respeta el tema y queda ilegible en oscuro */
color: black;
background: #fcfbf7;
border: 1px solid #ddd;

/* bien: token semántico, sin respaldo */
color: var(--sn-ink);
background: var(--sn-paper);
border: 1px solid var(--sn-hairline);

Fíjate en que no lleva un segundo valor dentro del paréntesis. Esta es la parte que sorprende a quien viene de escribir CSS en cualquier otro lado.

Lo que el sanitizador rechaza

MediaWiki no guarda una hoja de TemplateStyles tal cual: la pasa por un sanitizador que descarta lo que no reconoce. Si una regla contiene algo que no admite, la hoja da error y no se guarda —lo que es preferible a que se guarde a medias, pero desconcierta la primera vez—.

Rechazado	Alternativa
var(--x, respaldo)	var(--x) desnudo. Los tokens ya resuelven en la wiki; el respaldo no aporta nada.
light-dark(a, b)	Usar un token semántico que ya voltee, por ejemplo --sn-paper-raised. El volteo es trabajo del skin, no de la plantilla.
:is(…)	Repetir el selector completo.
font-stretch: 90% con porcentaje literal	La clase fw-90 del skin, o font-stretch: var(--tu-propiedad).
División dentro de calc()	Consumir el submúltiplo ya calculado en el skin, como --sn-baseline-half.

Sí acepta, en cambio, ::after, position, align-self, color-mix() y las custom properties. Esto último es gracias a que la wiki tiene instalada TemplateStylesExtender: sin ella el sanitizador descartaría los var() en silencio, que es bastante peor que fallar.

El modo oscuro, en dos líneas

Este es el corazón del asunto y la razón de toda la disciplina anterior. Con color crudo, la plantilla se rompe en tema oscuro; con token semántico, voltea sola.

/* en tema oscuro: texto negro sobre papel oscuro, ilegible */
.person-name { color: black; }

/* la tinta voltea a crema cuando el lector activa el oscuro */
.person-name { color: var(--sn-ink); }

No hay que escribir nada específico para el modo oscuro: basta con usar tokens semánticos. El volteo lo hace el sistema.

El ritmo vertical

La segunda causa de plantillas que se ven bien y sin embargo desalinean la página.

Para el relleno y los márgenes verticales se usa --sn-baseline y sus múltiplos, nunca la escala de espaciado --sn-s-*. La razón es que --sn-s-* está fija en rem y no sigue la preferencia de tamaño de letra del lector, mientras que la línea base sí. Una ficha cuyo relleno vertical use --sn-s-3 se verá correcta en el tamaño por defecto y desalineará la retícula en cuanto alguien suba la letra.

/* mal: el relleno vertical no acompaña al lector */
.ficha { padding: var(--sn-s-3) var(--sn-s-4); }

/* bien: vertical en líneas base, horizontal en la escala de espaciado */
.ficha { padding: var(--sn-baseline-half) var(--sn-s-4); }

Un ejemplo completo

Tomado de una ficha de persona. Arriba, colores crudos; abajo, tokenizado. El aspecto en tema claro es el mismo; la diferencia aparece cuando el lector cambia de tema.

/* ANTES */
.vcard .person-name {
	color: black;
	font-weight: bold;
}
.vcard .title .bio {
	color: #666;
	font-style: italic;
}

/* DESPUÉS */
.vcard .person-name {
	color: var(--sn-ink);
	font-weight: bold;
}
.vcard .title .bio {
	color: var(--sn-ink-soft);
	font-style: italic;
}

Aprovechar lo que ya existe

Antes de escribir CSS conviene comprobar si el skin ya resuelve el caso. Una plantilla puede emitir clases del skin igual que cualquier wikitexto:

• Tabla de ficha: {| class="wikitable plantilla" ya produce la lista vertical de pares clave y valor, sin filetes y con la etiqueta en versalita. No hace falta CSS.
• Columnas: <div class="grid cols-2">. No hace falta declarar un grid propio.
• Retrato circular: img-circle.
• Aviso: sn-notice.
• Botón: wiki-btn.

La lista completa está en Stella Nova/Grilla. Cada clase que se reutiliza es CSS que no hay que mantener.

Qué no hacer

• No usar primitivas como --sn-rojo-500 o --sn-papel-50. Son la paleta interna y se pueden reorganizar; el nombre de rol es el contrato estable. Una plantilla acoplada a la paleta se rompe cuando la paleta cambia.
• No usar #000 ni #fff puros. La tinta es negro cálido y el papel es crema; el blanco y el negro absolutos rompen la atmósfera y el contraste calibrado.
• No usar el carmín para rellenar fondos ni para íconos. Es el único acento agudo del sistema y está reservado al foco y a la marca de posición.
• No transmitir significado solo con color. El rojo de error va acompañado de texto o de un ícono.
• No editar MediaWiki:Common.css para una plantilla concreta. Es justamente lo que se está sacando de ahí.
• No inventar un token nuevo sin conversarlo. El conjunto se mantiene chico a propósito.

Cómo probar

Seis comprobaciones antes de dar por buena una hoja de estilo. Las tres últimas son las que más tiempo ahorran.

1. ¿Todos los colores son var(--sn-…) semánticos, sin respaldo?
2. ¿El relleno vertical usa --sn-baseline* y no --sn-s-*?
3. ¿Hay algún :is(), light-dark() o porcentaje de font-stretch? El sanitizador los va a rechazar.
4. Probar la plantilla transcluida en una página real, no mirando Plantilla:X. El espacio de nombres de plantillas tiene otro layout y miente.
5. Probar en tema oscuro, con ?useskin=stellanova y el conmutador del menú de usuario.
6. Probar con ?debug=true. MediaWiki cachea el CSS con saña y hace creer que un cambio no funcionó cuando en realidad no se ha servido todavía.

Véase también

• Stella Nova — la portada del skin.
• Stella Nova/Tokens — el vocabulario completo de variables.
• Stella Nova/Grilla — las clases que una plantilla puede emitir sin escribir CSS.