Agregar CSS personalizado a sitios modernos de SharePoint Online con SPFx

Personalizar la apariencia de un sitio moderno de SharePoint Online con un archivo CSS sigue siendo posible y totalmente compatible si se utiliza SharePoint Framework (SPFx). En este artículo encontrarás un recorrido completo para inyectar y mantener tu customcss.css.

Índice

Resumen del problema

Al intentar aplicar estilos propios en páginas modernas, muchos administradores repiten los pasos que funcionaban en la experiencia clásica (copiar Seattle.master o definir la URL de Alternate CSS). El resultado es siempre el mismo: el vínculo al CSS no se carga y los estilos nunca se aplican. Esto ocurre porque:

Las páginas modernas no consumen páginas maestras (master pages); trabajan sobre su propia plantilla de componentes.
Las configuraciones de diseño clásicas (Alternate CSS URL, Script Editor, Add‑ins antiguos) están explícitamente bloqueadas por Microsoft en sitios modernos.
La única vía admitida para extender la interfaz moderna es el uso de SPFx (SharePoint Framework).

Comprender la limitación clave

Desde 2017 Microsoft promueve un modelo de página que se renderiza desde el servidor con JavaScript pre‑compilado y React. Para evitar roturas, la plataforma impide inyectar recursos no confiables a través de métodos obsoletos. Modificar la master page solo afectará a páginas clásicas —y esas son cada vez menos frecuentes.

Arquitectura recomendada: SPFx Application Customizer

Un Application Customizer es una extensión ligera creada con SPFx que se ejecuta automáticamente en cada carga de página. Su papel aquí será añadir dinámicamente la etiqueta <link rel="stylesheet"> apuntando al archivo CSS que decidas hospedar (Style Library, CDN, Library Assets, etc.).

Paso a paso del proyecto

# 1. Generar la solución
yo @microsoft/sharepoint
✔ What is your solution name?  inject-css
✔ Which type of client-side component to create?  Extension
✔ What type of client-side extension to create?  Application Customizer
✔ What is your Application Customizer name?  InjectCss
✔ Which framework would you like to use?  React

2. Instalar dependencias y compilar

npm install
gulp bundle --ship

3. Empaquetar

gulp package-solution --ship

4. Cargar inject-css.sppkg en el App Catalog

\#    – habilita “Make this solution available tenant‑wide” si quieres

Estructura mínima

src/extensions/injectCss/InjectCssApplicationCustomizer.ts
Contiene la lógica para agregar el enlace CSS.
sharepoint/solution/inject-css.sppkg
Paquete desplegable en el App Catalog.
customcss.css
Hoja de estilos alojada en cualquier biblioteca accesible anónimamente desde el sitio.

Código de la extensión

import { override } from '@microsoft/decorators';
import { BaseApplicationCustomizer } from '@microsoft/sp-application-base';

export interface IInjectCssProperties {
  cssurl: string;
}

export default class InjectCssApplicationCustomizer
  extends BaseApplicationCustomizer\ {

  @override
  public onInit(): Promise\ {
    const url = this.properties.cssurl;
    if (url) {
      const head: HTMLElement | null = document.getElementsByTagName('head')\[0];
      const styleLink: HTMLLinkElement = document.createElement('link');
      styleLink.rel = 'stylesheet';
      styleLink.href = url;
      head?.appendChild(styleLink);
    }
    return Promise.resolve();
  }
}

Despliegue en el App Catalog

Accede a Apps > App Catalog en el Centro de administración SharePoint.
Carga el paquete .sppkg.
Si marcaste la casilla “Make this solution available tenant‑wide”, la extensión quedará activa en todos los sitios. De lo contrario, ve a Site contents > New > App y agrégala por colección.
En la página de “Site Assets” o “Style Library” sube customcss.css. Copia la URL completa y configúrala como propiedad cssurl desde Site Contents > InjectCss – Details > Properties.

Actualizar el CSS en el futuro

Una vez publicada la solución, el trabajo cotidiano se reduce a abrir el archivo customcss.css y modificar estilos:

Sin recompilaciones: mientras mantengas la misma ruta y nombre de archivo, no precisas volver a ejecutar gulp bundle.
Control de caché: SharePoint y los navegadores almacenan de forma agresiva los recursos estáticos. Después de guardar, haz una recarga forzada (Ctrl + F5) o prueba en una ventana privada.
Versionado limpio: agrega comentarios al comienzo del CSS con la fecha y número de versión. Facilita saber qué cambio está desplegado.

Cuándo recompilar la solución

Sólo es necesario recompilar si:

Cambias el nombre del archivo CSS o su ubicación.
Quieres inyectar un segundo bundle de scripts, usar otra CDN, o actualizar la versión de SPFx.

Verificaciones rápidas de diagnóstico

Asegúrate de que la opción Custom Script está permitida visitando /_layouts/15/SharePointDesignerSettings.aspx (solo administradores globales).
Abre las Herramientas de Desarrollador (F12) y revisa en el panel Network que customcss.css se descarga sin errores 404/403.
Usa el panel Elements > Styles para confirmar que tus selectores aplican al DOM final.

Ventajas y desventajas de adoptar SPFx

Ventajas	Desventajas
Alineado con las directrices oficiales para la experiencia moderna.	Requiere un primer ciclo de compilación y despliegue.
Puede activarse a nivel de tenant o por sitio según convenga.	Necesita permisos para cargar paquetes en el App Catalog.
Para cambios futuros basta con editar el CSS; no hay que generar otro paquete.	La solución debe actualizarse si Microsoft introduce cambios mayores en SPFx.

¿Qué hay de nuevo en 2024‑2025? Brand Center y Temas

Microsoft introdujo Brand Center en mayo de 2024. Esta característica permite:

Cargar tipografías corporativas y aplicarlas con un clic en toda la intranet.
Diseñar paletas de colores y logos sin tocar una línea de CSS.

Sin embargo, Brand Center cubre escenarios comunes (colores, fuentes, logos). Cuando necesitas reglas avanzadas —por ejemplo, ocultar bloques específicos, ajustar grid de webparts, o aplicar animaciones— SPFx sigue siendo la vía recomendada. Nada impide combinar ambos mundos: usa Brand Center para la identidad y la extensión SPFx para aquellos estilos finos que no abarca la interfaz.

Buenas prácticas al escribir `customcss.css`

Prefija todos los selectores con clases de alto nivel como .sp-css-inject que apliques a la etiqueta <body>. Evitarás que componentes nuevos de Microsoft se rompan.
Minimiza la especificidad; recurre a variables CSS donde sea posible (ej., --neutralPrimary).
No sobrescribas !important salvo en casos extremos; dificulta el mantenimiento.
Aquí un patrón típico:

/ v1.2 – 2025‑08‑01 /
.sp-css-inject {
  --brand-primary: #005e8a;
  --font-header: "Segoe UI Semibold",sans-serif;
}

.sp-css-inject h1,
.sp-css-inject h2 {
  font-family: var(--font-header);
  color: var(--brand-primary);
}

Pruebas en diferentes dispositivos

Recuerda que SharePoint utiliza un diseño responsive basado en cuadrículas flexibles. Verifica tus cambios en:

Desktop (mínimo 1366 × 768 px).
Tablet (≈ 768 × 1024 px).
Móvil (≈ 375 × 667 px).

La forma más rápida de probar es la vista emulada del navegador (Chrome DevTools > Toggle Device Toolbar).

Automatización del pipeline CI/CD (opcional)

En entornos empresariales es habitual incluir la solución SPFx en un pipeline CI/CD (Azure DevOps, GitHub Actions, Jenkins):

Compilar y validar PRs con gulp test.
Crear artifacts .sppkg.
Desplegarlo al App Catalog mediante el módulo pnp/powershell.
Ejecutar pruebas Playwright sobre una colección de sitios de ensayo.

Conclusiones

La experiencia moderna de SharePoint Online apuesta por componentes desacoplados y seguros. Aplicar CSS personalizado sigue siendo viable, pero únicamente a través de un canal soportado: SharePoint Framework. Un sencillo Application Customizer te da un control total sobre fuentes, colores y cualquier regla avanzada sin sacrificar soporte oficial. Complementa tu solución con Brand Center para los ajustes de marca más sencillos y mantén tu intranet fresca, coherente y 100 % alineada con la hoja de ruta de Microsoft 365.