Cómo aplicar estilos a componentes personalizados

El mecanismo de transformación de tokens de diseño se puede utilizar para aplicar un tema tanto a los componentes de Jutro de configuración base como a los componentes y elementos personalizados específicos de la aplicación.

Para aplicar un estilo a los componentes proporcionados por Jutro Design System, simplemente siga los pasos indicados en esta página. Jutro incluye todas las asignaciones necesarias para que los tokens de diseño funcionen a la perfección con nuestros componentes, por ello, no se requiere configuración adicional.

Puede aplicar un estilo a componentes y elementos personalizados en su aplicación utilizando los siguientes métodos:

Defina los tokens de diseño personalizados, que generarán variables CSS personalizadas para usar en su aplicación.
Asigne tokens de diseño de Jutro (“jds”) a variables CSS personalizadas.
Utilice directamente las variables CSS --JDS- generadas.

Warning: Aspectos que deben tenerse en cuenta a la hora de utilizar asignaciones personalizadas y variables CSS generadas para aplicar estilo a los elementos personalizados.

Si utiliza cualquier token de diseño “jds” en sus asignaciones personalizadas, asegúrese de que el token de diseño correspondiente esté presente durante la generación del tema.
Si hace referencia a alguna variable --JDS- en su código, asegúrese de que el token de diseño correspondiente esté presente durante la generación del tema.
Los tokens de diseño en el espacio de nombres “jds” forman parte de la superficie oficial de la API de Jutro y están cubiertos por la política de cambios sin interrupciones (NBC). Sin embargo, las variables CSS generadas automáticamente a partir de estos tokens (con el prefijo --JDS-) no forman parte de la superficie de la API y no están garantizadas en virtud de la política de NBC.
Cada variable CSS generada solo está disponible si existe un token de diseño que coincida. Para obtener más información, consulte la sección sobre patrón de nomenclatura de token de diseño para variable CSS.
Los componentes de Jutro Design System utilizan variables --JDS- internamente. Estas variables internas pueden cambiar sin que se consideren un cambio importante. Sin embargo, los tokens de diseño “jds” dentro de los componentes (y cómo se aplican) son estables y se acogen a la política de NBC.

Encontrará más información sobre la superficie de la API de Jutro aquí.

Tokens personalizados

Los diseñadores de UX pueden crear un conjunto de tokens personalizados para utilizarlos en la aplicación. Estos tokens personalizados deben agregarse en un espacio de nombres distinto de “jds”, por ejemplo, puede ser “my-custom-application”.

{
  "my-custom-application": {
    "some-component": {
      "color": {
        "background": {
          "value": "{jds.color.background.neutral}",
          "type": "color",
          "description": "Background color for SomeComponent"
        },
        "text": {
          "value": "#fff",
          "type": "color",
          "description": "Text color for SomeComponent"
        }
      }
    }
  }
}

Los tokens de diseño personalizados se pueden agregar en un solo archivo o dividirlo en varios: el mecanismo de transformación de los tokens de diseño en variables CSS transforma todos los tokens de diseño de un directorio específico para que la cantidad de archivos no importe. Estas son las únicas dos reglas:

No puede haber dos tokens con la misma ruta en un directorio.
Todos los tokens a los que se hace referencia también deben definirse en el directorio del tema.

Esto significa que los tokens personalizados pueden hacer referencia a los tokens de diseño de Jutro Design System en sus valores, pero solo si las definiciones de los tokens “jds” también se almacenan en el mismo directorio.

Patrón de nomenclatura de variables CSS

Todos los tokens de diseño se transformarán en variables CSS de acuerdo con la siguiente convención:

Todos los puntos . se reemplazarán por guiones -.
Todas las letras estarán en mayúsculas.
Se añadirán dos guiones -- al principio.

Por ejemplo, un token con la ruta de my-custom-application.some-component.color.background se transformará en --MY-CUSTOM-APPLICATION-SOME-COMPONENT-COLOR-BACKGROUND.

Los tokens de tipografía son una excepción a esta regla. Dado que los tokens de tipografía son tokens compuestos, deben dividirse en unas cuantas variables CSS independientes durante el proceso de transformación. A continuación, se muestra un ejemplo de un token de tipografía:

{
  "my-custom-application": {
    "font": {
      "heading-1": {
        "value": {
          "fontFamily": "'Source Sans 3', 'Helvetica', 'Arial', sans-serif",
          "fontWeight": "600",
          "lineHeight": "40px",
          "fontSize": "32px",
          "letterSpacing": "0",
          "paragraphSpacing": "0",
          "textCase": "none",
          "textDecoration": "none"
        },
        "type": "typography",
        "description": "Font properties for heading 1 text"
      }
    }
  }
}

El token de diseño my-custom-application.font.heading-1 se transformará en las siguientes variables CSS:

--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-FAMILY: 'Source Sans 3', 'Helvetica', 'Arial', sans-serif;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-SIZE: 32px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-WEIGHT: 600;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LETTER-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LINE-HEIGHT: 40px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-PARAGRAPH-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-CASE: none;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-DECORATION: none;

Asignaciones personalizadas

No es necesario crear un conjunto completamente nuevo de tokens de diseño personalizados para generar variables CSS personalizadas; en cambio, puede usar la funcionalidad de agregar asignaciones personalizadas. Para ello, debe crear un nuevo archivo json, por ejemplo customMappings.json, y completarlo con emparejamientos de tokens de diseño/variable CSS. Recuerde que todos los tokens a los que se haga referencia deben estar agregados al directorio de temas especificado.

Ejemplo de asignación:

{
  "--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR": "jds.color.background.error",
  "--CUSTOM-BUTTON-TEXT-COLOR": "jds.color.text.regular"
}

También deberá agregar una nueva entrada custom-mappings a su .themesConfig.json. Encontrará más información sobre .themesConfig.json .themesConfig.json aquí.

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "input-path": "src/tokens/sampleTheme/**/*.json",
      "output-file-name": "tokenOverrides.css",
      "custom-mappings": "src/tokens/customMappings.json"
    }
  }
}

Después de ejecutar el proceso de transformación, las variables definidas en la asignación se agregarán al archivo tokenOverrides.css.

/**
 * Do not edit directly
 * Generated on Mon, 25 Mar 2024 15:35:16 GMT
 */

.themeRoot,
.themeRoot.dynamicRoot {
--JDS-COLOR-BACKGROUND-NEUTRAL: #f0f3f6;
--JDS-COLOR-BACKGROUND-NEUTRAL-HOVER: #dfe5ec;
--JDS-COLOR-BACKGROUND-ERROR: #012345;
--JDS-COLOR-TEXT-REGULAR: #28333f;
...
--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR: var(--JDS-COLOR-BACKGROUND-ERROR);
--CUSTOM-BUTTON-TEXT-COLOR: var(--JDS-COLOR-TEXT-REGULAR);
}

Warning: Guidewire proporciona la asignación de cada token de diseño de Guidewire a la variable CSS de Guidewire. No utilice asignaciones personalizadas para invalidar o modificar variables --JDS-. Las variables CSS no forman parte de la superficie de la API, por eso, cambian según la versión y la asignación personalizada puede interrumpirse.

Note: No todos los estilos de componentes se definen mediante tokens de diseño: algunos componentes utilizan valores codificados de forma rígida o variables CSS con valores codificados de forma rígida (con el prefijo --JDS-). Si necesita modificar alguno de estos estilos que no son tokens, comuníquese con nuestro equipo. Evaluaremos si es necesario crear nuevos tokens de diseño para satisfacer sus necesidades.

Transformaciones personalizadas

En algunos casos, la transformación de un valor de token de diseño en un valor de variable CSS no es directa y requiere cierta lógica específica para obtener el valor o los valores que se van a resolver. Para este propósito, Guidewire proporciona un conjunto de transformaciones predefinidas que abarcan transformaciones básicas de bordes, tipografía, sombras, cálculos, etc. Si necesita que se lleven a cabo transformaciones adicionales, puede escribir una función de transformación personalizada y pasarla al proceso de transformación a través de la entrada custom-transformations en .themesConfig.json. Encontrará más información sobre .themesConfig.json .themesConfig.json aquí.

En el siguiente fragmento de código se muestran ejemplos de transformaciones personalizadas de valor y nombre:

module.exports = {
  customValueTransform: {
    type: 'value',
    transitive: true,
    matcher: token => token.type === 'my-type',
    transformer: token => `"Value of my token: ${token.value}"`
  },
  customNameTransform: {
    type: 'name',
    transformer: token => `CUSTOM-PREFIX-${token.path.join('-').toUpperCase()}`
  }
};

Encontrará más información sobre cómo escribir transformaciones personalizadas en la documentación del diccionario de estilo.

Warning: Las transformaciones personalizadas solo se aplican a tokens personalizados, que son tokens con un prefijo distinto de jds. Si no se definen transformaciones personalizadas que coincidan con un token personalizado determinado, el token se transforma utilizando las transformaciones de Jutro, siempre que Jutro maneje ese tipo de token. No es posible invalidar la transformación de tokens jds.

La siguiente lista contiene los tipos de tokens de diseño que maneja Jutro:

'sizing'
'spacing'
'borderRadius'
'borderWidth'
'fontSizes'
'letterSpacing'
'paragraphSpacing'
'dimension'
'typography'
'boxShadow'
'border'
'composition'
'fontFamilies'
'lineHeights'

Si falta alguna transformación, informe a su representante de Guidewire que la necesita, de modo que se considere agregarla en una versión futura.

Tokens personalizados​

Patrón de nomenclatura de variables CSS​

Asignaciones personalizadas​

Transformaciones personalizadas​

Tokens personalizados

Patrón de nomenclatura de variables CSS

Asignaciones personalizadas

Transformaciones personalizadas