Subdirección de las Tecnologías de la Información y Comunicaciones

Área de Gobernanza y Calidad

Versión

Normativa front guia implementacion themes en distintos ámbitos Vigente Versión: 1.0.1 Estado: ACTIVO Entrada en vigor desde: 1 jun 2023 Obligado cumplimiento desde: Sept-2023	Normativa front guia implementacion themes en distintos ámbitos PRE-RELEASE Versión: 1.0.0 Estado: RELEASE Entrada en vigor desde: 28 nov 2022 Obligado cumplimiento desde: -

Tabla de Contenido

Cumplimiento Normativo

Las normas expuestas son de obligado cumplimiento. La STIC podrá estudiar los casos excepcionales los cuales serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad según correspondencia y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC.

La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto.

En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica.

Contacto Arquitectura: l-arquitectura.stic@juntadeandalucia.es

Histórico de cambios

Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución. Ordenándose de mas recientes a menos recientes, prestando especial cuidado a las cabeceras de la tablas dónde se indican las fechas de entrada en vigor y versión.

Versión	Pre-release	Alcance
v01r00	15 jun 2022	Versión inicial del documento
v01r01	16 may 2024	Deprecadas las partes en las que se redefinen variables
v01r01	5 mar 2025	Adaptacion al scaffolding de vite

1. Introducción

Esta guía técnica aporta información sobre cómo realizar el desarrollo de los distintos themes en los ámbitos establecidos:

Ámbito STIC (Ámbito corporativo): Ubica su SSUI en un ámbito corporativo concreto. Al adoptar los mecanismo de theming en su aplicación se garantiza la reutilización de los aspectos estéticos de las SSUI.
Ámbito de Negocio : Delimita su SSUI en un ámbito funcional concreto, no sólo marcado por las necesidades de su negocio, sino también por la especialización en un determinado segmento de negocio de los agentes que harán la interacción con la SSUI.
Ámbito de Aplicación (Ámbito Funcional): Delimita su SSUI en el ámbito de una aplicación.

1.1 Nomenclatura

Los nombres de los componentes, deberían seguir el siguiente esquema:

Si es un componente genérico (átomo, molécula, organismos estructurales, template-generales) su nomenclatura será la siguiente: wc-<área_de_negocio>-<nombre_componente>
Si es un componente de negocio (organismo de negocio, template de aplicación, página) su nomenclatura será la siguiente: wc-<área_de_negocio>-<app>-<nombre_componente>

<area_de_negocio> se sustituirá por las siguientes letras:

Horizontales - sshh
Asistencial - asis
Recursos Humanos - rrhh
Eco-financiero - ecofin
STIC - stic

NO SE QUE HACEMOS EN UN DOCUMENTO SOBRE EL THEME HABLANDO DE LA NOMENCLATURA DE LOS COMPONENTES

2. Sistema de diseño

De manera general se define un sistema de diseño como un conjunto de reglas y normas que el equipo de una organización establece internamente y que les permite trabajar de forma alineada a través de un lenguaje común.

El Sistema de Diseño STIC proporciona pautas, componentes y plantillas para el desarrollo homogéneo de las aplicaciones del SAS.

Los objetivos del Sistema de Diseño STIC son los siguientes:

Consistencia: Homogeneizar el impacto visual de las distintas aplicaciones del SAS, de modo que todas ellas guarden cierta coherencia con las demás aplicaciones a nivel de usuario, obteniendo los siguientes beneficios:

Eficiencia: Mediante un conjunto de componentes unificado, la aplicación y el desarrollo extensivo de componentes es mucho más sencillo, aumentando la velocidad a la que los proveedores de productos generan nuevas aplicaciones y componentes, y se reduce la duplicación de estos.

3. Theme

3.1 Introducción

El theme es la instancia técnica del sistema de diseño. Mediante el mismo se logra la homogeneización visual de todos los componentes, pudiéndose extender para adaptarlo a nuestros diseños particulares.

3.1.1 Objetivos

El principal objetivo del theme es definir una api de diseño y desarrollo con la cual lograr que todas las aplicaciones/componentes creados en la STIC tengan una visualización homogénea.

3.1.2 Componentes theme

Como se ha visto anteriormente en punto 1, se tendrán tres tipos de componentes theme:

Theme STIC: Theme corporativo que será la base de todos los themes creados, y que se usará como referencia de los mismos.
Theme de Negocio: En caso que se quiera customizar los valores de la variables del theme STIC para nuestra área de negocio se creará este theme.
Theme de Aplicación: En caso que se quiera customizar los valores de la variables del theme STIC para nuestra aplicación se creará este theme.

3.2 Theme STIC

Theme STIC nos proporciona una serie de variables custom CSS a través de su API con los que homogeneizar los estilos de todos los componentes/aplicaciones desarrollados.

3.2.1 Organización

El theme STIC se organiza en una serie de carpetas y archivos para facilitar su comprensión y desarrollo, y cuya estructura es la siguiente:

De dicha estructura, destacan los siguientes carpetas/ficheros:

			Definición
src			Carpeta que contiene todo el código fuente del theme
	css		Carpeta que contiene todos los ficheros referentes a las variables custom CSS del theme
		legacy	Carpeta en la que se incluyen todos los ficheros de la versión 1.0 del theme, y que serán eliminados en la versión 2.0
		border-sd.css.ts	Fichero que incluye todas las variables relacionadas con los bordes definidos por el sistema de diseño
		color-sd.css.ts	Fichero que incluye todas las variables relacionadas con los colores definidos por el sistema de diseño
		dimension-sd.css.ts	Fichero que incluye todas las variables relacionadas con las dimensiones definidas por el sistema de diseño
		font-sd.css.ts	Fichero que incluye todas las variables relacionadas con la tipografía definida por el sistema de diseño
		grid-sd.css.ts	Fichero que incluye todas las variables relacionadas con el layout definido por el sistema de diseño
		opacity-sd.css.ts	Fichero que incluye todas las variables relacionadas con la opacidad definida por el sistema de diseño
		overlay-sd.css.ts	Fichero que incluye todas las variables relacionadas con la superposición definida por el sistema de diseño
		shadow-sd.css.ts	Fichero que incluye todas las variables relacionadas con la sombra definida por el sistema de diseño
		shape-sd.css.ts	Fichero que incluye todas las variables relacionadas con las formas definidas por el sistema de diseño
		sizing-sd.css.ts	Fichero que incluye todas las variables relacionadas con las dimensiones definidas por el sistema de diseño
		spacing-sd.css.ts	Fichero que incluye todas las variables relacionadas con el espaciado definido por el sistema de diseño
		state-layer-sd.css.ts	Fichero que incluye todas las variables relacionadas con el sistema de interacción definido por el sistema de diseño
		zindex-sd.css.ts	Fichero que incluye todas las variables relacionadas con la profundidad definida por el sistema de diseño
	stic-theme.ts		Incluye la clase exportable del theme
stories			Carpeta que contiene los ficheros de las stories de storybook del theme

3.2.2 Uso

En esta sección se describirán los diferentes usos del theme según su utilización en una aplicación o componente, distinguiendo los casos de usos en los mismos, y explicando su instalación y configuración en cada uno de ellos.

3.2.2.1 Cómo usar el theme en una aplicación

1) Casos de uso : Se distinguen tres casos de uso del theme dentro de una aplicación:

Caso de uso 1: Aplicaciones desarrolladas solo con web components
En la aplicaciones desarrolladas solo con web components solo se deberá realizar la carga del theme (Variables Custom CSS) dentro de la aplicación. El consumo de dichas variables se realizará directamente en los componentes.
Paso	Descripción	Enlace
P1	Instalación del theme	Ir al contenido
P2	Carga del theme	Ir al contenido

Caso de uso 2: Aplicaciones que usan web components dentro de otros desarrollos en los que no se usaban web components
El uso de web components en una aplicación que utiliza elementos HTML implica la instalación del componente stic-theme. Todos los desarrollos anteriores tendrán definidos unos estilos, de manera inline o con fichero(s) CSS, y para no crear conflicto con ellos, será la aplicación la encargada de gestionar dichos estilos redefiniendo todos los tags html que se usen en el theme.
Paso	Descripción	Enlace
P1	Instalación del theme	Ir al contenido
P2	Carga del theme	Ir al contenido
P3.1	Configuración si se usan estilos INLINE	Ir al contenido
P3.2	Configuración si se usan ficheros CSS (Typescript)	Ir al contenido
P4	Definición DEPRECADO	Ir al contenido
NOTA P4	La definición se limita incluir la clase stic-theme dentro del tag body del HTML de nuestro desarrollo.

Caso de uso 3: Aplicaciones sin web components
Si no se tienen web components no es necesario, por normativa, aplicar el theme, por lo que el desarrollo anterior podrá continuar con sus estilos de la manera que lo hacía anteriormente. En el caso que se quiera incluir el theme para usar las variables que ofrece:
Paso	Descripción	Enlace
P1	Instalación del theme	Ir al contenido
P2	Carga del theme	Ir al contenido

3.2.3 Customización

En esta sección se explica cómo customizar el theme de la STIC en todos los ámbitos disponibles, ya sea para modificar los valores de sus variables como para crear variables nuevas.

3.2.3.1 Cuando customizar

La creación de un theme de negocio/aplicación es necesaria cuando por requisito de diseño o bien necesito modificar alguno de los valores de las variables expuestas o bien necesito crear alguna variable que no exista el el theme.

La base técnica para realizar esta customización puede encontrarse en el siguiente repositorio: scaffolding-vite

Pasos para crear un theme
Los pasos necesarios para crear un theme se detallan a continuación. En cada paso, en caso que se necesario, se especificando dos soluciones, una por cada ámbito posible: Negocio / Aplicación
Paso	Descripción	Enlace
P1	Descargar el repositorio	Ir al contenido
P2	Instalación del theme	Ir al contenido
P3	Extender theme STIC	Ir al contenido
NOTA P3	Modificar el fichero ./src/Wc<nombre_theme>Theme.ts y, en él, realizar las importaciones del tema de la STIC para poder extenderlo (se usará CamelCase para el nombre de la clase)

Customización de variables
Paso	Descripción	Enlace
P1	Customizar variables	Ir al contenido
NOTA P1	Crear el fichero ./src/css/<tipo_css>.ts y, en él, incluir las variables a modificar y sus valores.

Creación de variables

En el caso justificado de tener que crear nuevas variables para exponerlas en nuestro theme creado, se procederá de la siguiente manera:

Paso

Descripción

Enlace

P1

Creación de nuevas variables dentro de los distintos ámbitos

Ámbito de negocio

Ir al contenido

Ámbito de aplicación

Ir al contenido

4. Ayuda técnica para la implementación

Instalación del Theme

npm install @sas/wc-stic-theme

Carga del Theme

// Patrón - Carga de un theme creado en el ámbito de negocio
<body>
  ...
  <script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';
    import { STIC<nombre_area_negocio>Theme } from '@sas/wc-stic-<nombre_area_negocio>-theme';

    new STICTheme().loadHeadStyles();
    new STIC<nombre_area_negocio>Theme().loadHeadStyles();
  </script>  
</body>


// Patrón - Carga de un theme creado en el ámbito de aplicación
<body>
  ...
  <script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';
	// Si existe el theme del área de negocio
    import { STIC<nombre_area_negocio>Theme } from '@sas/wc-stic-<nombre_area_negocio>-theme';

    import { STIC<nombre_aplicacion>Theme } from '@sas/wc-stic-<nombre_aplicacion>-theme'; 

    new STICTheme().loadHeadStyles();
    // Si existe el theme del área de negocio
    new STIC<nombre_area_negocio>Theme().loadHeadStyles();

    new STIC<nombre_aplicacion>Theme().loadHeadStyles();
  </script>  
</body>

// Ejemplo de carga - Theme STIC
<body>
  ...
  <script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';

    new STICTheme().loadHeadStyles();
  </script>  
</body>

// Ejemplo de carga - Theme área de Negocio (RRHH)
<body>
  ...
  <script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';
    import { STICRRHHTheme } from '@sas/wc-stic-rrhh-theme';

    new STICTheme().loadHeadStyles();
    new STICRRHHTheme().loadHeadStyles();
  </script>  
</body>

// Ejemplo de carga - Theme aplicación (Gerhonte - RRHH)
<body>
  ...
  <script type="module">
    import { STICTheme } from '@sas/wc-stic-theme';
    import { STICRRHHTheme } from '@sas/wc-stic-rrhh-theme';
    import { STICGehonteTheme } from '@sas/wc-stic-gerhonte-theme';

    new STICTheme().loadHeadStyles();
    new STICRRHHTheme().loadHeadStyles();
    new STICGehonteTheme().loadHeadStyles();
  </script>  
</body>

Configuración - Estilos INLINE

// Patrón - Configuración mediante estilos inline
<!doctype html>
<html lang="en">

  <head>
    ...
    <style>
      ...
       .theme-stic <tag_html>{
         <propiedad_css>: var(--theme-<tipo_css>-<nombre_theme_tag_html>-<propiedad_css>);
       }  
    </style>
  </head>

  <body>
    ...
  </body>

</html>

// Ejemplo - Configuración mediante estilos inline (tag H1)
<!doctype html>
<html lang="en">

  <head>
    ...
    <style>
      ...
       .theme-stic h1{
         font-size: var(--theme-typography-headline1-font-size);
       }  
    </style>
  </head>

  <body>
    ...
  </body>

</html>

Configuración - Fichero CSS

// Patrón - Configuración mediante fichero CSS (TS)
import { css } from "lit";
...
  AppTheme.cssBase = css `
    .theme-stic <tag_html>{
      <propiedad_css>: var(--theme-<tipo_css>-<nombre_theme_tag_html>-<propiedad_css>);
    } 
  }
...
`;

// Ejemplo - Configuración mediante fichero CSS (tag H1)
import { css } from "lit";
...
  AppTheme.cssBase = css `
     .theme-stic h1{
         font-size: var(--theme-typography-headline1-font-size);
     }   
  }
...
`;

Definición

...
<body class="stic-theme">
  ...
</body>
...

Contenido deprecado

El siguiente contenido (Redefinición de variables Custom CSS) está marcado como deprecado y no deberá usarse.

Redefinición de variables Custom CSS

// Patrón - Redefinición de variables Custom CSS
static cssBase: CSSResult = css`
    :host {
      ...
        --<nombre-componente>-<tipo_css>-<propiedad_css>: var(--theme-<propiedad_css>);
      ...
`;

// Ejemplo - Redefinición de variables Custom CSS - componente boton - propiedad shape top left
static cssBase: CSSResult = css`
    :host {
      ...
        --stic-button-shape-top-left: var(--theme-shape-small);
      ...
`;

Sobrescritura de valores

// Patrón - Sobreescritura de valores
static cssBase: CSSResult = css`
    ...
    :host <tag_html>{
      ...
        <propiedad_css>: var(--<nombre_componente>-<nombre_theme_tag_html>-<propiedad_css>, var(--theme-<tipo_css>-<nombre_theme_tag_html>-<propiedad_css>));
      ...
    }
`;

// Ejemplo - Sobreescritura de valores aplicada al tag H1 en la propiedad font-size
static cssBase: CSSResult = css`
    ...
    :host h1{
      ...
     	font-size: var(--stic-radio-button-headline1-font-size, var(--theme-typography-headline1-font-size));
      ...
    }
`;

Instalación del Theme (Dependencia de desarrollo)

npm install @sas/wc-stic-theme --save-dev

Creación del Theme (Ámbito de Negocio)

git clone http://git.sas.junta-andalucia.es/gobernanza/ArchivosDeDesarrollo/nodejs/scaffolding-vite.git

Creación del Theme (Ámbito de Aplicación)

// Patrón - Creación de una aplicación
sas-cli wc:create <nombre_app>-theme

// Ejemplo - Creación de la aplicación gerhonte
sas-cli wc:create gerhonte-theme

Extender Theme STIC

// Patrón - Extender Theme STIC
import { STICTheme } from '@sas/wc-stic-theme';

export class Stic<nombre_theme>Theme extends STICTheme {
  ...
}

// Ejemplo 1 - Extender Theme STIC desde el área de Negocio RRHH
import { STICTheme } from '@sas/wc-stic-theme';

export class SticRRHHTheme extends STICTheme {
  ...
}

// Ejemplo 2 - Extender Theme STIC desde la aplicacion TSV
import { STICTheme } from '@sas/wc-stic-theme';

export class SticTSVTheme extends STICTheme {
  ...
}

Customizar Variables

// Patrón - Customización de variables

import { STICTheme } from '@sas/wc-stic-theme';
import { css, CSSResult, CSSResultOrNative } from 'lit';

export class Stic<nombre_theme>Theme extends STICTheme {
  
  themeStyles(): Array<CSSResultOrNative> {
    return [...super.themeStyles(), <listado_const_theme>];
  }
}

export const <tipo_css>Theme: CSSResult = css`
  :root {
    <variable_theme_stic>: <nuevo_valor>;
  }
`

// Ejemplo - Customización de una variable de color para el ámbito de negocio de RRHH

import { STICTheme } from '@sas/wc-stic-theme';
import { css, CSSResult, CSSResultOrNative } from 'lit';

export class SticRRHHTheme extends STICTheme {

  themeStyles(): Array<CSSResultOrNative> {
    return [...super.themeStyles(), colorTheme];
  }
  
}

export const colorTheme: CSSResult = css`
  :root {
    --color-background-action-primary-default: #ff0000;
    --color-text-action-primary-on-dark: #ffff00;
  }
`;

// Ejemplo - Customización de una variable de color para el ámbito de la aplicación TSV

import { STICTheme } from '@sas/wc-stic-theme';
import { css, CSSResult, CSSResultOrNative } from 'lit';

export class SticAppNameTheme extends STICTheme {

  themeStyles(): Array<CSSResultOrNative> {
    return [...super.themeStyles(), colorTheme];
  }
  
}

export const colorTheme: CSSResult = css`
  :root {
    --color-background-action-primary-default: #ff0000;
    --color-text-action-primary-on-dark: #ffff00;
  }
`;

Crear nuevas variables en el ámbito de Negocio

// Patrón - Creación de variables en el ámbito de Negocio
--<área_de_negocio>-theme-<propiedad_css>: <valor>;

// Ejemplo - Creación de una variable en el ámbito de Negocio RRHH
--rrhh-theme-shape-small: 8px;

Crear nuevas variables en el ámbito de Aplicación

// Patrón - Creación de variables en el ámbito de Aplicación
--<área_de_negocio>-<app>-theme-<propiedad_css>: <valor>;

// Ejemplo - Creación de una variable en el ámbito de Aplicación Gerhonte (RRHH)
--rrhh-gerhonte-theme-shape-small: 10px;

Redefinición de Variables en el ámbito de Negocio

// Patrón - Redefinición de variables en el ámbito de Negocio
--theme-<propiedad_css>: var(--<área_de_negocio>-theme-<propiedad_css>, var(--theme-<propiedad_css>))

// Ejemplo - Redefinición de una variable en el ámbito de Negocio RRHH
--theme-shape-small: var(--rrhh-theme-shape-small, var(--theme-shape-small));

Contenido deprecado

El siguiente contenido (Redefinición de Variables en el ámbito de Aplicación (caso 1)) está marcado como deprecado y no deberá usarse.

Redefinicion de Variables en el ámbito de Aplicación (caso 1)

// Patrón - Redefinición de variables en el ámbito de Aplicación y estando definido el theme del área de Negocio
--<área_de_negocio>-theme-<propiedad_css>: var(--<área_de_negocio>-<app>-theme-<propiedad_css>, var(--<área_de_negocio>-theme-<propiedad_css>))

// Ejemplo - Redefinición de variables en el ámbito de Aplicación Gerhonte y estando definido el theme del área de Negocio (RRHH)
--rrhh-theme-shape-small: var(--rrhh-gerhonte-theme-shape-small, var(--rrhh-theme-shape-small));

Contenido deprecado

El siguiente contenido (Redefinicion de Variables en el ámbito de Aplicación (caso 2)) está marcado como deprecado y no deberá usarse.

Redefinicion de Variables en el ámbito de Aplicación (caso 2)

// Patrón - Redefinición de variables en el ámbito de Aplicación y NO estando definido el theme del área de Negocio
--theme-<propiedad_css>: var(--<área_de_negocio>-<app>-theme-<propiedad_css>, var(--theme-<propiedad_css>))

// Ejemplo - Redefinición de variables en el ámbito de Aplicación Gerhonte y NO estando definido el theme del área de Negocio (RRHH)
--theme-shape-small: var(--rrhh-gerhonte-theme-shape-small, var(--theme-shape-small));

Árbol de páginas

Subdirección de las Tecnologías de la Información y Comunicaciones

Área de Gobernanza y Calidad

Versión

Versión: 1.0.1

Estado: ACTIVO

Entrada en vigor desde: 1 jun 2023

Obligado cumplimiento desde: Sept-2023

Versión: 1.0.0

Estado: RELEASE

Entrada en vigor desde: 28 nov 2022

Obligado cumplimiento desde: -

Tabla de Contenido

Cumplimiento Normativo

Histórico de cambios

1. Introducción

1.1 Nomenclatura

2. Sistema de diseño

3. Theme

3.1 Introducción

3.1.1 Objetivos

3.1.2 Componentes theme

3.2 Theme STIC

3.2.1 Organización

3.2.2 Uso

3.2.2.1 Cómo usar el theme en una aplicación

3.2.3 Customización

3.2.3.1 Cuando customizar

4. Ayuda técnica para la implementación

Árbol de páginas

🏷 Implementación del theme en los distintos ámbitos

Subdirección de las Tecnologías de la Información y Comunicaciones

Área de Gobernanza y Calidad

Versión

Versión: 1.0.1

Estado: ACTIVO

Entrada en vigor desde: 1 jun 2023

Obligado cumplimiento desde: Sept-2023

Versión: 1.0.0

Estado: RELEASE

Entrada en vigor desde: 28 nov 2022

Obligado cumplimiento desde: -

Tabla de Contenido

Cumplimiento Normativo

Histórico de cambios

1. Introducción

1.1 Nomenclatura

2. Sistema de diseño

3. Theme

3.1 Introducción

3.1.1 Objetivos

3.1.2 Componentes theme

3.2 Theme STIC

3.2.1 Organización

3.2.2 Uso

3.2.2.1 Cómo usar el theme en una aplicación

3.2.3 Customización

3.2.3.1 Cuando customizar

4. Ayuda técnica para la implementación