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

Área de Gobernanza y Calidad

Versión

Tabla de Contenido

Cumplimiento Normativo

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.

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.
• Ámbito de Componente (Ámbito del SSUI): Es el ámbito que define su SSUI, cualquier elemento dentro de ella forma parte del SSUI en cuestió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

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.

El Sistema de Diseño STIC se basa en las directivas de  Material Design, adaptando sus pautas a las normativas a seguir en el SAS para el desarrollo de aplicaciones web.

Material Design v2 es un sistema de diseño creado por Google en distintos lenguajes, pero el que nos impacta es la parte web. Ofrece una serie de componentes e indicaciones sobre el diseño y personalización de estos, a cerca de su entorno, interacción, características propias de los componentes... y todo esto trasladado a la visión de UX/UI para mejorar la interactuación con el usuario en nuestras aplicaciones, intentando equilibrar el impacto visual entre todas 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.

El Sistema de Diseño STIC basa su construcción en el paradigma  Atomic Design. Para más información acerca del paradigma Atomic Design puede consultar su  sección dentro de nuestra normativa de front.

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 l@s siguientes carpetas/ficheros:

color.css.ts (Colores)

La aplicación de un modelo de color para el theme ha pasado por varias fases. En una primera fase se aplicó el modelo de color Hexadecimal. Posteriormente se pasó al modelo de color RGBA ya que se necesitaba aplicar transparencia sobre los colores, cosa que con el modelo hexadecimal no se podía. En una tercera fase se decidió usar el modelo de color HSL frente al modelo RGBA ya que HSL nos permite la creación de colores sólidos aplicando una opacidad (mediante la luminosidad), mientras que con RGBA no se podía lograr esto ya que la aplicación de la opacidad sobre el color en RGBA se logra mediante la transparencia, no obteniendo colores sólidos. [hsl( hue ,  saturation ,  lightness )]. Puede encontrar más información en normativa → sección theming → color.

En este fichero hay definidos dos bloques:

• Un primer bloque interno a este fichero (cuyas variables no pueden modificarse) en el que se incluyen lo que se ha llamado colores base, formado por variables custom CSS con los dos primeros valores de modo HSL (las correspondientes a hue y saturation)
  • por ejemplo: --theme-hsl-color-primary-base: 170 , 43% ;
• Un segundo bloque en el que se definen las variables expuestas por el theme en la parte de color, y que están compuestas por los colores definidos en el primer bloque y por las variables de luminiscencia, creadas en el fichero shared.css.ts
  • por ejemplo: --theme-color-primary: hsl ( var ( --theme-hsl-color-primary-base ), var ( --theme-hsl-color-luminance-500 ));

shape.css.ts (Formas)

Este fichero incluye un bloque con las variables usadas en el ámbito de las formas del theming, cada una de ellas usadas para las distintas categorías establecidas dentro de esta parte (más información en  normativa → sección theming → formas).

• por ejemplo: --theme-shape-small: 4px ;

state.css.ts (Formas)

Este fichero incluye un bloque con las variables custom css usadas en el ámbito de los estados del theming, organizados por cada uno de los estados disponibles [Disabled, Hover, Focus, Selected, Activated, Pressed, Dragged] (más información en normativa → sección theming → estados).

Las variables correspondientes al color (estado disabled) se definen de la misma forma que las definidas en el archivo color.css.ts, mientras que las variables correspondientes a la elevación usan las variables creadas en fichero shared.css.ts dentro del bloque de estados, y correspondientes a los distintos dp (elevation - shadows) definidos.

• ejemplo color: --theme-state-disabled-color: hsl ( 0 , 0% , var ( --theme-hsl-color-luminance-900 ));
• ejemplo elevación: --theme-state-hover-elevation: var ( --dp-4 );

Carpeta typo (Tipografías)

En la tabla anterior se ha hecho referencia a dos ficheros concretos que son la base de esta carpeta, pero en esta sección se va a comentar sobre los distintos bloques que forman parte de los ficheros de los distintos elementos tipográficos (más información en normativa → sección theming → tipografías).

Se tienen dos casos de usos posibles:

• Si el elemento tipográfico no tiene tag por defecto definido en HTML (por ejemplo, actionable - typo.actionable.css.ts)
  • En este caso solo se incluye un bloque en el que se definen todas las variables expuestas en el mismo, junto con los valores por defecto para ese elemento tipográfico.
• Si el elemento tipográfico tiene tag por defecto definido en HTML (por ejemplo, body - typo.actionable.css.ts)
  • En este caso se tendrían dos bloques:
    • Un primer bloque en el que se definen todas las variables expuestas en el mismo, junto con los valores por defecto para ese elemento tipográfico.
    • Un segundo bloque en el que se aplican dichas variables sobre las propiedades CSS que identifican al elemento tipográfico.

shared.css.ts (Compartidos)

Este fichero incluye varios bloques con las variables custom css usadas en los otros ficheros, de modo de se podrán compartir entre los mis mos :

• Un primer bloque de apoyo al color, que incluye las variables de luminiscencia disponibles
  • por ejemplo: --theme-hsl-color-luminance-0: 0% ;
• Un segundo bloque de apoyo a las tipografías, que incluye las variables de peso disponibles
  • por ejemplo: --theme-typo-weight-thin: 100 ;
• Un tercer bloque de apoyo a los estados, que incluye las variables de elevación (dp) disponibles
  • por ejemplo: --dp-0:   0px 0px 0px 0px hsla ( 0 , 0% , var ( --theme-hsl-color-luminance-0 ), 0.14 ), 0px 0px 0px 0px hsla ( 0 , 0% , var ( --theme-hsl-color-luminance-0 ), 0.12 ), 0px 0px 0px 0px hsla ( 0 , 0% , var ( --theme-hsl-color-luminance-0 ), 0.2 );

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:

3.2.2.2 Cómo usar el theme en un componente

1) Casos de uso: El único caso de uso posible es aquel en el que se tenga que aplicar el theme sobre web components.

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.

Como se dijo anteriormente, el theme de la STIC se usa para poder consumir las variables definidas en él. Al heredar todas las variables del theme de la STIC, solo se tendrán que incluir en el theme creado las variables que se necesiten sobrescribir, y las que no se incluyan tomarán el valor que tienen del theme de la STIC.

4. Ayuda técnica para la implementación

npm install @sas/wc-stic-theme

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

    new WcSTICTheme().loadHeadStyles();
    new WcSTIC<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 { WcSTICTheme } from '@sas/wc-stic-theme';
	// Si existe el theme del área de negocio
    import { WcSTIC<nombre_area_negocio>Theme } from '@sas/wc-stic-<nombre_area_negocio>-theme';

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

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

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

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

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

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

    new WcSTICTheme().loadHeadStyles();
    new WcSTICRRHHTheme().loadHeadStyles();
  </script>  
</body>

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

    new WcSTICTheme().loadHeadStyles();
    new WcSTICRRHHTheme().loadHeadStyles();
    new WcSTICGehonteTheme().loadHeadStyles();
  </script>  
</body>

// 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>

// 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);
     }   
  }
...
`;

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

// 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);
      ...
`;

// 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));
      ...
    }
`;

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

sas-cli wc:create theme

// 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

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

export class Wc<nombre_theme>Theme extends WcSTICTheme {
  ...
}

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

export class WcRRHHTheme extends WcSTICTheme {
  ...
}

// Patrón - Customización de variables
import { css, CSSResult } from "lit";

export const theme<tipo_css>: CSSResult = css`
  :root {
    --theme-<tipo_css>-<propiedad>: <nuevo_valor>;
  }
`

// Ejemplo - Customización de una variable del tipo color
import { css, CSSResult } from "lit";

export const themeColor: CSSResult = css`
  :root {
    --theme-color-primary: hsl(0, 100%, 70%);
  }
`

// 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;

// 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;

// 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));

// 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));

// 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));