Adaptive Color System Refactor

[nicholasrice]

FAST Color Refactor

The issue outlines proposed changes to how the color system works in FAST.

The primary changes are to the data types used by color algorithms, but there are also some necessary changes to the DesignSystemProvider to make the recipe implementations more efficient.

Goals

• Improve performance by minimizing color parsing and stringifying
• Open the system up to use any color model, not just hex codes.
• Associate palette source directly with palette
  • Should avoid confusion of accent-palette and accent-base-color needing to be kept in sync
• Simplify implementation of contrast-based functions and make them easier to leverage
• Color recipes should be more portable by not requiring the entire design-system as an argument - should only expect what data they need.

Non-goals

This proposal doesn't address how recipes get registered to the provider, nor how to replace implementations of recipes used by components for all or some components. #3361 is a better place to discuss those more general features.

New color structures and classes

Swatch

A swatch is a simple color structure representing a color that can be used in CSS. It has the following interface:

interface Swatch {
    /**
     * The relative luminance of the swatch
     */
    readonly relativeLuminance: number; // between 0 and 1
    
    /**
     * A string representing the color that can be used in CSS
     */
    readonly css: string;
    
    /**
     * Returns the contrast ratio between this swatch
     * and a reference swatch
     */
    static contrast(color: Swatch): number; 
}

Palette

A palette is a structure that representing a collection of Swatch objects derived from or related to a single source Swatch. It also provides several methods for finding swatches relative to other swatches.

interface Palette {
    /**
     * The color that the palette is derived from
     */
    readonly source: Swatch;
    
    /**
     * All swatches in the palette
     */
    readonly swatches: Swatch[];
    
    /**
     * Returns a swatch from the palette that most closely matches
     * the contrast ratio provided to a provided reference.
     * 
     * @remarks
     * We need to know where to start searching
     * and which direction to search in - isDarkMode?
     */
    matchContrast(reference: Swatch, contrast: number): Swatch;
    
    /**
     * Returns the index of the palette that most closely matches
     * the relativeLuminance of the provided swatch
     */
    closestIndexOf(reference: Swatch): number;
     
     /**
      * Gets a swatch by index. Index is clamped to the limits
      * of the palette so a Swatch will always be returned.
      */
    get(index: number): Swatch;
}

Color Recipes

The most significant change to color recipes is that they will not memoize the design system object itself, rather the provided arguments.

Additionally, they will all need to be re-factored to use the new data structures.

Provider Changes

DesignTokenResolver

A DesignTokenResolver type will be added. It is a simple structure that is bound to a provider and observes dependent properties. When the properties change, the value field is updated.

interface DesignSystemResolver<T, S> {
  observedProperties: Array<keyof T>; // The properties on the context the resolver cares about
  value: string;
  name: string;
  bind(context: T): void; // Hooks up property observation and sets value
  unbind(context: T): void; // Remove property observation
}

Color recipes will have DesignSystemResolver implementations, where value is updated to be the product of the recipe and the observedProperties are the properties of the DesignSystem that are necessary to calculate the recipe.

When a resolver attaches to a context, all properties in the observedProperties list on the context will be observed with the reaction to observed property changes updating the value field.

observedProperties could probably be an implementation detail, I'm not sure a explicit property is needed

The resolver is bound to the provider, and the provider subscribes to changes to the resolvers's value field. When the value changes, the corresponding CSS Custom Property is updated.