Saltar al contenido principal

Implementación de la tematización

Jutro viene con un mecanismo de tematización que ayuda a crear un estilo uniforme en toda la aplicación. Mientras que la parte de diseño se realiza a través de tokens de diseño, la aplicación requiere variables CSS para manejar la definición de estilos. Estas variables CSS son el resultado de la transformación de tokens de diseño a variables CSS. También hay algunas opciones de personalización adicionales.

Además, puede utilizar tokens de diseño con componentes personalizados. Debe definir nuevos tokens de diseño para estos componentes personalizados o agregar un archivo de asignación desde los tokens existentes a las nuevas variables CSS para la configuración de transformación. Encontrará más información sobre la aplicación de estilos a componentes personalizados aquí.

Note: El antiguo mecanismo de tematización basado en la definición manual de las invalidaciones de variables CSS --GW- está obsoleto, pero sigue estando disponible y es compatible con los componentes legacy. Consulte una versión de la documentación anterior a la 10.0 para ver más detalles sobre este mecanismo o vaya a la página de tematización heredada para averiguar cómo cambiar al uso de tokens de diseño.

Cómo funcionan la tematización de Jutro​

La tematización de Jutro se implementa como parte de los paquetes NPM @jutro/theme, @jutro/theme-styles y @jutro/design-tokens. Sin embargo, en la mayoría de los casos no es necesario hacer referencia a ellos directamente.

Por lo general, se crea la aplicación con el método start() que proviene de @jutro/app. Este iniciador encapsula su aplicación con un componente raíz <ThemeProvider> que aplica los temas. Si no proporciona ninguna configuración de tema al método start(), se utiliza el tema predeterminado (Empresarial).

La tematización, al nivel de la implementación, se basa en variables CSS de ámbito global, que definen valores CSS comunes para varios aspectos de la apariencia. Algunos se aplican a componentes individuales, mientras que otros se aplican a grupos enteros de componentes. Los valores de estas variables se asignan desde los tokens de diseño definidos durante el proceso de transformación.

Cada una de las variables provistas por Jutro se nombra en una de estas dos convenciones (todo en mayúsculas):


# CSS variables generated from design tokens
--JDS-[<CATEGORY>]-[<PROPERTY>]-[<MODIFIER>]

# legacy option still applied in many components
--GW-[<OPTIONAL-COMPONENT-OR-GROUP-NAME>]-<STYLING-ASPECT>-[<OPTIONAL-VARIANT>]

Ejemplos:

  • --JDS-COLOR-BACKGROUND-BRAND
  • --JDS-COLOR-BACKGROUND-ERROR-SUBTLE
  • --GW-ACCORDION-BORDER-FOCUS
  • --GW-FOCUS-ERROR-COLOR-DARK
Warning: No utilice las variables CSS --JDS- definidas por Guidewire para dar estilo a los componentes personalizados. Las variables CSS generadas a partir de tokens en el espacio de nombres “jds” NO forman parte de la superficie de la API y NO están cubiertas por la política de cambios sin interrupciones (NBC). Esto significa que todas las variables CSS, comenzando por --JDS-, pueden cambiar su nomenclatura/valores entre versiones; por eso, recomendamos encarecidamente no usarlas para dar estilo a las aplicaciones. En su lugar, utilice uno de los métodos antes mencionados aquí.

Qué hacer y qué no hacer con respecto a la tematización​

Si sigue los límites descritos en esta página, su tema será más fácil de mantener y actualizar. A continuación se muestra un resumen de los límites:

  1. Para ajustar los estilos de Jutro de manera global, utilice tokens de diseño.
  2. Utilice solo partes de Jutro Design System que pertenezcan a nuestra superficie de API.
  3. No modifique manualmente ninguna de las definiciones de variables CSS generadas.
  4. No utilice variables CSS --JDS- para aplicar estilo a componentes personalizados; siga los métodos recomendados.
  5. No confíe en ningún detalle de implementación interno de los componentes, incluidas las variables CSS y los nombres de clase, a la hora de definir los estilos.
  6. Nunca utilice la fuerza bruta ni hackee los estilos escribiendo selectores complejos para que coincidan con los componentes de una página. Por ejemplo, no haga coincidir “el primer botón dentro del formulario”.

Personalización de estilos de Jutro y mantenimiento de la capacidad de actualización​

La forma admitida oficialmente para personalizar los componentes de Jutro es el uso de tokens de diseño y el resultado de su transformación en variables CSS.

Si, como resultado de la modificación de un componente, las variables CSS --JDS- que utiliza un componente cambian, Guidewire incluirá las modificaciones necesarias en la configuración del proceso de transformación del token de diseño a variables CSS para permitir la actualización a la versión más reciente sin ningún efecto negativo o intervención manual por parte del consumidor.

Configuración de un tema personalizado para su aplicación​

La mejor manera de invalidar estilos globalmente es crear un tema personalizado. De forma predeterminada, las aplicaciones de Jutro utilizan el tema “Empresarial”. Para cambiar a un tema diferente, haga lo siguiente:

  1. Prepare la configuración de tokens de diseño para el tema personalizado. El proceso se describe en esta página.
  2. Pase el tema correcto para que start funcione en ./src/startApp.js:
import themesConfig from './.themesConfig.json';

start(Jutro, {
        ...
        themeConfig: themesConfig.sampleTheme,
    });

Consulte las páginas de documentación de tokens de diseño para obtener más detalles.

Acceso a temas externos​

Al final, después de todas las transformaciones, la definición del tema se almacena en un archivo tokenOverrides.css (o con cualquier otro nombre dado) que contiene los valores de las variables CSS asignadas a partir de los tokens de diseño. Dado que los enlaces a este archivo CSS se toman de la configuración del tema y se usan como valore href en una etiqueta <link> HTML, puede colocar el archivo CSS en un servidor diferente. En este caso, en su .themesConfig.json, no es necesario especificar input-path, ya que no está ejecutando ninguna transformación de manera local. Bastará con añadir el enlace a su archivo tokenOverrides.css como valor de output-file-name.

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "output-file-name": "https://example.com/theme/tokenOverrides.css"
    }
  }
}

Puede usar esto para lograr los siguientes escenarios:

  1. Compartir el tema personalizado entre diferentes aplicaciones.
  2. Implementar nuevos temas independientemente de la aplicación.

Sin embargo, hay que tener en cuenta que los archivos deben estar disponibles desde el navegador del cliente y que el almacenamiento en caché puede evitar que el navegador del cliente muestre estilos actualizados al instante.

Tenga en cuenta también que los archivos remotos no se migrarán automáticamente durante la actualización.

Cómo personalizar los estilos de una única instancia de un componente de Jutro​

Puede usar una propiedad className para personalizar la apariencia de una instancia individual de un componente Jutro.

  1. Prepare su clase CSS personalizada:
.myCustomButtonStyles {
  background: red;
}
  1. Pásela al componente usando la propiedad className:
import { Button } from '@jutro/component';
import styles from './myStyles.module.scss';

const MyForm = () => {
  // this instance of button is going to have use our red background instead of the default one
  return <Button className={styles.myCustomButtonStyles}>Get insured!</Button>;
};

No intente invalidar los estilos predeterminados de los componentes de Jutro extrayendo los nombres de las clases CSS proporcionadas por Jutro e invalidándolos directamente en sus hojas de estilo. Si hace referencia a una clase de Jutro directamente, sus personalizaciones dejarán de funcionar en caso de que Jutro cambie a un mecanismo de hashing diferente o cambie el nombre de la clase. Los nombres de clase no forman parte de la superficie de la API de Jutro y pueden cambiar entre versiones.

.jut__Button__button {
  //this is WRONG, please do not do this
  background: red;
}

Fuentes, imágenes, archivos estáticos​

Por lo general, todos los recursos estáticos están en su carpeta src/assets. Puede hacer referencia a ellos de las siguientes maneras:

  • Desde plantillas HTML utilizando el prefijo de marcador de posición %PUBLIC_URL%, por ejemplo:

    <img src="%PUBLIC_URL%/<path-to-the-image-under-src-assets>" />

  • Desde código JS (por ejemplo, como parte del componente render()), usando la variable de entorno PUBLIC_URL:

    render() {
        return (
            <img src={`${process.env.PUBLIC_URL}/<path-to-the-image-under-src-assets>`} />
        );
    }

  • Desde archivos CSS mediante una ruta absoluta o relativa: en este caso, el navegador busca los archivos relativos al archivo CSS en el que se especifica el enlace.

Adición de fuentes personalizadas​

Para aplicar una fuente personalizada, colóquela en su carpeta src/assets/fonts e inclúyala en su archivo SCSS.

@font-face {
  font-family: Acme;
  src: url(./assets/fonts/Acme-Regular.ttf);
}

Puede aplicar la fuente a cualquier componente o clase. Si desea reemplazar una fuente de tema, invalide el token de diseño apropiado.

Fuentes en Webpack 5​

Al pasar a Webpack 5, su archivo Theme.scss solo debe almacenar fuentes, como se muestra a continuación:

Theme.scss
$fonts-root: '~@jutro/theme/assets/fonts';

// ------------------------------------
//   GROUNDED CSS MODULES
// ------------------------------------
@import '~@jutro/theme/assets/fonts/fonts';

No recomendamos agregar ninguna otra información a su archivo Theme.scss.

Manejo de las diferencias de temas según los puntos de interrupción​

Jutro no proporciona una función personalizada para manejar las diferencias de temas según los puntos de interrupción, pero puede usar mecanismos CSS integrados, como consultas de medios, si este comportamiento es necesario para su aplicación.

En la próxima sección encontrará un ejemplo de una forma de hacerlo, pero quizás se necesite un método diferente según la naturaleza de la aplicación.

Uso de consultas de medios CSS para manejar diferencias de temas según los puntos de interrupción​

En este método, utilizará consultas de medios CSS para determinar qué conjunto de tokens de diseño está activo en función del ancho de la ventana gráfica y de si se está viendo en un dispositivo con pantalla. Es posible que su caso de uso requiera definir varias situaciones, pero este ejemplo abarca dos:

  • screen and (min-width: 769px). Activo cuando se visualiza en un dispositivo con pantalla y si el ancho es de al menos 769 píxeles.
  • screen and (max-width: 768px). Activo cuando se visualiza en un dispositivo con pantalla y si el ancho es de 768 píxeles o menos.

Resumen de los pasos que se deben seguir:

  1. Defina un tema mediante tokens de diseño para cada situación.
  2. Genere los archivos CSS para sus temas utilizando la CLI de Jutro.
  3. Cree manualmente un archivo CSS que importe los archivos CSS generados y utilice consultas de medios para establecer cuál está activo.
  4. Cree un tema que utilice el archivo CSS creado manualmente.

Aspectos que se deben tener en cuenta sobre el uso de este método​

Con este método, cada vez que se vuelven a generar los temas, el nuevo tema combinado refleja automáticamente los cambios sin ningún otro paso.

  • El conjunto incluye todos los temas que podrían afectar el uso de la red y los tiempos de carga.
  • Si bien requiere la creación manual de un tema, es una acción que se lleva a cabo solo una vez. Si realiza cambios en los temas secundarios, puede volver a ejecutar el comando jutro generate:themes y no tendrá que volver a actualizar el archivo creado manualmente.
  • Esta recomendación se basa en el caso en que ambas definiciones de temas importadas contengan temas completos y no sean solo una invalidación parcial de ciertas variables o valores. Por esta razón, ambas importaciones utilizan la condición de ancho. Esto ayuda en los siguientes casos:
    • Solo un tema está activo para la evaluación de CSS.
    • No hay conflictos en cascada (como un !important en el tema base aplicado sobre el valor establecido en la invalidación de medios).
    • Separación total entre temas.
    • No existe la posibilidad de que el tema base se aplique antes que el tema reactivo si los usuarios tienen conexiones de red lentas o poco confiables.

Instrucciones sobre cómo aplicar este enfoque en una aplicación de Jutro​

  1. Defina sus temas usando tokens de diseño e impórtelos en el archivo .themesConfig.json, como lo haría normalmente. Consulte la documentación sobre transformación a variables CSS para obtener más detalles.
  2. Ejecute el comando jutro generate:themes para generar los archivos con las variables CSS para sus temas, como lo haría normalmente. Consulte la documentación de la CLI para obtener más detalles sobre este comando.
  3. Defina manualmente un nuevo tema en su directorio styles, sin tokens, que combine cada tema de punto de interrupción a través de importaciones en un archivo al que se le asigne un nombre similar a Combined-Themes/combined-themes-design-tokens.css. Por ejemplo, si sus temas tienen los nombres ConsumerDesktop y ConsumerTablet, entonces agregaría el siguiente texto:
styles/Combined-Themes/combined-themes-design-tokens.css
@import url('../Consumer-Desktop/consumer-desktop-design-tokens.css') screen and
  (min-width: 769px);
@import url('../Consumer-Tablet/consumer-tablet-design-tokens.css') screen and
  (max-width: 768px);
  1. Agregue el tema combinado al .themesConfig.json como una invalidación de variables.
  "CombinedThemes": {
  "name": "CombinedThemes",
  "variableOverrides":"styles/Combined-Themes/combined-themes-design-tokens.css"
}
Note:

No es necesario volver a ejecutar jutro generate:themes después, como en el paso 2, porque en el paso 3 creó manualmente el CSS que este tema utiliza.

  1. En su archivo startApp, actualice el argumento themeConfig de la función start para usar su nuevo tema CombinedThemes:
start(Jutro, {
  ...
  themeConfig: themesConfig.CombinedThemes,
  ...
});

Una demostración detallada de este proceso se describe en la misión de aprendizaje sobre cómo agregar temas de punto de interrupción.