API de Leonardo JS

---

La documentación de la API te ayudará a usar @adobe/leonardo-contrast-colors en tu entorno de desarrollo.

Inicio rápido

Instala el paquete:

npm i @adobe/leonardo-contrast-colors
    

Importa el paquete:

CJS (Node 12.x)

const { Theme, Color, BackgroundColor } = requerir('@adobe/leonardo-contrast-colors');
    

ESM (Node 13.x)

import { Theme, Color, BackgroundColor } de '@adobe/leonardo-contrast-colors';
    

Crea y pasa colores y un color de fondo a un nuevo tema (consulta las opciones adicionales a continuación):

dejar gray = nueva BackgroundColor({
          name: 'gris',
          colorKeys: ['#cacaca'],
          ratios: [2, 3, 4.5, 8]
        });

    dejar blue = nueva Color({
          name: 'blue',
          colorKeys: ['#5CDBFF', '#0000FF'],
          ratios: [3, 4.5]
        });

    dejar red = nueva Color({
          name: 'red',
          colorKeys: ['#FF9A81', '#FF0000'],
          ratios: [3, 4.5]
        });

    dejar theme = nueva Theme({colors: [gray, blue, red], backgroundColor: gray, lightness: 97});

    // devuelve los colores del tema como JSON
    dejar colors = theme.contrastColors;
    

Referencia de API

Theme

Función de clase utilizada para generar colores basados en contraste adaptativo. Los parámetros son desestructurados y deben ser llamados de manera explícita.

Parámetro	Escribe	Descripción
colors	Array	Lista de clases de Color para generar colores de tema. Se requiere una única clase de BackgroundColor.
lightness	Número	Valor del 0 al 100 para la claridad deseada del color de fondo del tema generado (número entero)
contrast	Número	Multiplicador para aumentar o disminuir el contraste de todos los colores del tema (el valor predeterminado es 1)
saturation	Número	Valor de 0-100 para disminuir la saturación de todos los colores del tema (el valor predeterminado es 100)
output	Enum	Formato de salida de color deseado

Setters

Setter	Descripción de la salida
Theme.lightness	Establece el valor de claridad del tema
Theme.contrast	Establece el valor de contraste del tema
Theme.saturation	Establece el valor de saturación del tema
Theme.backgroundColor	Establece el color de fondo del tema (crea un nuevo BackgroundColor si se pasa una cadena)
Theme.colors	Establece los colores para el tema (debe pasar Color)
Theme.output	Establece el formato de salida para el tema
Theme.addColor	Agrega un Color al tema
Theme.removeColor	Eliminar un Color del tema
Theme.updateColor	Actualizar un Color a través de sus métodos setter desde el tema

Theme.addColor = color

Agrega un Color a un tema existente

dejar red = nueva Color({
    name: 'red',
    colorKeys: ['#FF9A81', '#FF0000'],
    ratios: [3, 4.5]
});

theme.addColor = red;
    

Theme.removeColor = color

Eliminar un Color de un tema existente. Acepta un objeto con el nombre y valor del Color, o pasando la clase Color en sí.

// Eliminar por nombre de color
theme.removeColor = {name: 'roja'};

// Eliminar a través de la clase Color
const red = nueva Color({
   name: 'red',
   colorKeys: ['#FF9A81', '#FF0000'],
   ratios: [3, 4.5]
});

theme.removeColor = red;
    

Theme.updateColor = {name, property}

Actualiza un Color a través de sus métodos de establecimiento desde el tema. Acepta un objeto con el nombre del color que deseas modificar, seguido de la propiedad y el nuevo valor que deseas modificar.

// Cambia las proporciones de los colores
theme.updateColor = {color: 'red', ratios: [3, 4.5, 7]};

// Cambia el color de los colorKeys
theme.updateColor = {color: 'red', colorKeys: ['#ff0000']};

// Cambia el nombre del color
theme.updateColor = {color: 'red', name: 'Crimson'};
    

Alternativamente, es posible cambiar las 3 propiedades en la misma llamada.

// También es posible cambiar el nombre del color y colorKeys en la misma función.
theme.updateColor = {color: 'red', ratios: [3, 4.5, 7], colorKeys: ['#ff0000'], name: 'Crimson'};
    

Formatos de salida compatibles:

Los formatos de salida disponibles se ajustan a la especificación del Módulo de Color CSS Nivel 4 para las opciones compatibles, como se enumera a continuación:

Opción de salida	Valor de muestra
'HEX' (default)	#RRGGBB
'RGB'	rgb(255, 255, 255)
'HSL'	hsl(360deg, 0%, 100%)
'HSV'	hsv(360deg, 0%, 100%)
'HSLuv'	hsluv(360, 0, 100)
'LAB'	lab(100%, 0, 0)
'LCH'	lch(100%, 0, 360deg)
'CAM02'	jab(100%, 0, 0)
'CAM02p'	jch(100%, 0, 360deg)

---

Color

Función de clase utilizada para definir colores para un tema. Los parámetros se desestructuran y deben ser llamados explícitamente.

Parámetro	Escribe	Descripción
name	String	Nombre definido por el usuario para un color, (por ejemplo, "Azul"). Se utiliza para nombrar los valores de color de salida.
colorKeys	Array of strings	Lista de colores específicos entre los cuales interpolar para generar una escala completa de claridad del color.
colorspace	Enum	El espacio de color en el cual se interpelarán los colores clave.
ratios	Array or Object	Lista de relaciones de contraste objetivo, o un objeto con claves nombradas para cada valor.
smooth	Boolean	Aplica suavizado bezier a la interpolación (falso por defecto)
output	Enum	Formato de salida de color deseado

Setters

Setter	Descripción de la salida
Color.colorKeys	Establece las teclas de color
Color.colorspace	Establece el espacio de color de interpolación
Color.ratios	Establece las proporciones
Color.name	Establece el nombre
Color.suave	Configura la opción de suavizado
Color.output	Establece el formato de salida

Colores de interpolación compatibles:

A continuación se presentan las opciones disponibles para la interpolación en Leonardo:

• LCH
• LAB
• CAM02
• HSL
• HSLuv
• HSV
• RGB

Ratios como un arreglo

Al pasar un arreglo plano de proporciones objetivo, los colores de tu Tema serán generados concatenando el nombre del color (por ej., "Azul") con incrementos numéricos. Los colores con un ratio de contraste positivo con la base (es decir, 2:1) se nombrarán en incrementos de 100. Por ejemplo, gris100, gris200.

Los colores con un ratio de contraste negativo con la base (es decir, -2:1) se nombrarán en incrementos menores a 100 y basados en la cantidad de valores negativos declarados. Por ejemplo, si hay 3 valores negativos [-1.4, -1.3, -1.2, 1, 2, 3], el nombre para esos valores se incrementará en 100/4 (longitud más uno para evitar un valor 0), como gris25, gris50, y gris75.

Por ejemplo:

new Color({
      name: 'blue',
      colorKeys: ['#5CDBFF', '#0000FF'],
      colorSpace: 'LCH',
      ratios: [3, 4.5]
    });

    // Devuelve:
    [
      {
        name: 'blue',
        values: [
          {name: "blue100", contrast: 3, value: "#8d63ff"},
          {name: "blue200", contrast: 4.5, value: "#623aff"}
        ]
      }
    ]
    

Ratios como un objeto

Al definir las proporciones como un objeto con pares de clave-valor, defines qué nombre se mostrará en tu tema de Leonardo.

new Color({
      name: 'blue',
      colorKeys: ['#5CDBFF', '#0000FF'],
      colorSpace: 'LCH',
      ratios: {
        'blue--largeText': 3,
        'blue--normalText': 4.5
      }
    });

    // Devuelve:
    [
      {
        name: 'blue',
        values: [
          {name: "blue--largeText", contrast: 3, value: "#8d63ff"},
          {name: "blue--normalText", contrast: 4.5, value: "#623aff"}
        ]
      }
    ]
    

---

Output examples

Hay dos tipos de salida que puedes obtener de la clase Theme: | Getter | Descripción de la salida | |--------|-----------------------| | Theme.contrastColors | Devuelve un array de objetos de color con pares clave-valor | | Theme.contrastColorPairs | Devuelve un objeto con pares clave-valor | | Theme.contrastColorValues | Devuelve un array plano de valores de color |

Theme.contrastColors

Cada color es un objeto nombrado por un valor definido por el usuario (por ejemplo, name: 'gray'). El array "Valores" consiste en todos los valores de color generados para el color, con las propiedades name, contrast y value:

[
      { background: "#e0e0e0" },
      {
        name: 'gray',
        values: [
          {name: "gray100", contrast: 1, value: "#e0e0e0"},
          {name: "gray200", contrast: 2, value: "#a0a0a0"},
          {name: "gray300", contrast: 3, value: "#808080"},
          {name: "gray400", contrast: 4.5, value: "#646464"}
        ]
      },
      {
        name: 'blue',
        values: [
          {name: "blue100", contrast: 2, value: "#b18cff"},
          {name: "blue200", contrast: 3, value: "#8d63ff"},
          {name: "blue300", contrast: 4.5, value: "#623aff"},
          {name: "blue400", contrast: 8, value: "#1c0ad1"}
        ]
      }
    ]
    

Theme.contrastColorPairs

Formato simplificado como un objeto de pares clave-valor. La propiedad es igual al generado o nombre definido por el usuario para cada valor generado..

{
      "gray100": "#e0e0e0";
      "gray200": "#a0a0a0";
      "gray300": "#808080";
      "gray400": "#646464";
      "blue100": "#b18cff";
      "blue200": "#8d63ff";
      "blue300": "#623aff";
      "blue400": "#1c0ad1";
    }
    

Theme.contrastColorValues

Devuelve todos los valores de color en un arreglo plano.

[
      "#e0e0e0",
      "#a0a0a0",
      "#808080",
      "#646464",
      "#b18cff",
      "#8d63ff",
      "#623aff",
      "#1c0ad1"
    ]
    

---

Leonardo con variables CSS

Aquí hay algunos ejemplos de cómo puedes utilizar a Leonardo para crear o modificar dinámicamente variables CSS para tu aplicación.

Vanilla JS

let varPrefix = '--';

    // Iterate each color object
    for (let i = 0; i < myTheme.length; i++) {
      // Iterate each value object within each color object
      for(let j = 0; j < myTheme[i].values.length; j++) {
        // output "name" of color and prefix
        let key = myTheme[i].values[j].name;
        let prop = varPrefix.concat(key);
        // output value of color
        let value = myTheme[i].values[j].value;
        // create CSS property with name and value
        document.documentElement.style
          .setProperty(prop, value);
      }
    }
    

React

Crea un nuevo componente de tema Theme.js con tus parámetros.:

import * as Leo from '@adobe/leonardo-contrast-colors';

    const Theme = () => {
      let gray = new Leo.BackgroundColor({
        name: 'gray',
        colorKeys: ['#cacaca'],
        ratios: [2, 3, 4.5, 8]
      });

      let blue = new Leo.Color({
        name: 'blue',
        colorKeys: ['#5CDBFF', '#0000FF'],
        ratios: [3, 4.5]
      });

      let red = new Leo.Color({
        name: 'red',
        colorKeys: ['#FF9A81', '#FF0000'],
        ratios: [3, 4.5]
      });

      const adaptiveTheme = new Leo.Theme({
        colors: [
          gray,
          blue,
          red
        ],
        backgroundColor: gray,
        lightness: 97,
        contrast: 1,
      });

      return adaptiveTheme;
    }

    export default Theme;
    

Then import your Theme component at the top level of your application, and pass the Theme as a property of your app:

// index.js
    import Theme from './components/Theme';

    ReactDOM.render(
      <React.StrictMode>
        <App adaptiveTheme={Theme()}/>
      </React.StrictMode>,
      document.getElementById('root')
    );
    

En tu archivo App.js, importa useTheme de css-vars-hook y proporciona lo siguiente dentro de tu función App para dar formato a la salida de Leonardo en la estructura requerida para css-vars-hook.

// App.js
    import {useTheme} from 'css-vars-hook';

    function App(props) {
      const [lightness, setLightness] = useState(100);
      const [contrast, setContrast] = useState(1);

      const _createThemeObject = () => {
        let themeObj = {}
        props.adaptiveTheme.contrastColors.forEach(color => {
          if(color.name) {
            let values = color.values;
            values.forEach(instance => {
              let name = instance.name;
              let val = instance.value;
              themeObj[name] = val;
            });
          } else {
            // must be the background
            let name = 'background'
            let val = color.background;
            themeObj[name] = val;
          }
        })
        return themeObj;
      };

      const theme = useState( _createThemeObject() );

      const {setRef, setVariable} = useTheme(theme);

      return (
        <div
          className="App"
          ref={setRef}
          >
        </div>
      )
    }
    

Para hacer que tu aplicación sea adaptable, incluye una función para actualizar tu tema antes de tu función de retorno:

  function _updateColorVariables() {
        let themeInstance = _createThemeObject();

        for (const [key, value] of Object.entries( themeInstance )) {
          setVariable(key, value);
        }
      };
      // llamar a la función para establecer valores iniciales
      _updateColorVariables();
    

Finalmente, referencia esta función y establece los parámetros del tema cuando tus usuarios interactúen con los componentes deslizables (haz lo mismo para el Contraste):

<label htmlFor="lightness">
      Luminosidad
    </label>
    <input
      value={lightness}
      id="lightness"
      type="range"
      min={ sliderMin }
      max={ sliderMax }
      step="1"
      onChange={e => {
        setLightness(e.target.value)
        props.adaptiveTheme.lightness = e.target.value
        _updateColorVariables()
      }}
    />
    <label htmlFor="contrast">
      Contrast
    </label>
    <input
      value={contrast}
      id="contrast"
      type="range"
      min="0.25"
      max="3"
      step="0.025"
      onChange={e => {
        setContrast(e.target.value)
        props.adaptiveTheme.contrast = e.target.value
        _updateColorVariables()
      }}
    />
    

Soporte para modo oscuro en React

Incluye lo siguiente en tu archivo App.js para escuchar el modo oscuro. Esto pasará un valor de claridad diferente (de tu elección) a Leonardo. Se recomienda restringir el rango de claridad según el modo para evitar rangos inaccesibles y proporcionar una mejor experiencia en general.

const mq = window.matchMedia('(prefers-color-scheme: dark)');
    // Update lightness and slider min/max to be conditional:
    const [lightness, setLightness] = useState((mq.matches) ? 8 : 100);
    const [sliderMin, setSliderMin] = useState((mq.matches) ? 0 : 80);
    const [sliderMax, setSliderMax] = useState((mq.matches) ? 30 : 100);

// Escucha para actualizar cuando cambie el modo del dispositivo del usuario:    mq.addEventListener('change', function (evt) {
      props.adaptiveTheme.lightness = ((mq.matches) ? 11 : 100)
      setLightness((mq.matches) ? 11 : 100)
      setSliderMin((mq.matches) ? 0 : 80);
      setSliderMax((mq.matches) ? 30 : 100);
    });
    

---

¿Por qué no están disponibles todas las relaciones de contraste?

Puede que notes que la herramienta acepta una entrada (relación objetivo) pero, a menudo, devuelve una relación de contraste un poco más alta. Esto se debe a los colores disponibles en el espacio de color RGB y a las matemáticas asociadas con el cálculo de estas relaciones.

Por ejemplo, veamos el azul y el blanco. Azul: rgb(0, 0, 255) Blanco: rgb(255, 255, 255) Relación de contraste: 8.59:1

Si cambiamos cualquier valor en el canal RGB para cualquiera de los colores, la relación cambia: Azul: rgb(0, 1, 255) Blanco: rgb(255, 255, 255) Relación de contraste: 8.57:1

Si 8.58 se introduce como el ratio objetivo con el color inicial azul, la salida no será exacta. Esto se exagera por las diversas interpolaciones de espacio de color.

Dado que el requerimiento de WCAG se define como un requerimiento de contraste mínimo, debería estar bien generar colores que sean un poco más accesibles que el mínimo.

---

Chroma.js

Este proyecto está construido actualmente utilizando Chroma.js con extensiones personalizadas para soportar CIE CAM02. Se añade funcionalidad adicional en Leonardo para mejorar las escalas de croma de modo que ordenen adecuadamente los colores por claridad y corrijan la claridad de la escala en función de HSLuv.

Contribuyendo

¡Se agradecen las contribuciones! Lee la Guía de Contribuciones para más información.

Desarrollo

Puedes ejecutar pruebas y observar los cambios con:

npm run dev
    

Licenciamiento

Este proyecto está licenciado bajo la Licencia Apache V2. Consulta LICENSE para más información.