[SDK] Create ability to determine the affects of a color theme change

[aaronreed708]

Problem/Concern

This issue is to investigate, design and code how to build a dependency tree that can be used to determine the downstream affects of a color theme change.

Some questions that may need to be answered:

• How will the SDK determine what will change if user changes foundational color?
• How will the SDK communicate the affected change information back to the user?
  • What will the structure be?
  • What will the API be?
• How will the SDK calculate the safe values to return to the caller (as part of the communication section above)
• These are for AA and AAA
  • How to indicate this in the API?
• What is the difference between a suggested change and a required change?
  • In the UI of the wireframes it looks like the user can select not to make a suggested change, but why would we suggest a change that a user doesn't need to make in order to stay compliant?
  • If the previously selected value for a theme element was still compliant with the change, then wouldn't we just not include it in the suggested changes to the user?

Proposed Solution

[aaronreed708]

ThemeWCAGChanges.txt

[aaronreed708]

Changing a base color

Deleting a color

[aaronreed708]

Talked with @lwnoble yesterday and got some clarifications as to how the Theme Elements in a ColorTheme should pair with the backgrounds.

• There is one default background for each ColorTheme
  • In the WCAG Change section of the Figma file, where it talks about "Colored Button" or "Colored Hotlink" and mentions that the newly selected color must be contrast tested against the "primary/secondary backgrounds", it should say that it needs to be tested against the "default background".
• A new background will be created as primary, secondary and tertiary Theme Colors are defined
• A user may add more backgrounds using colors and their shades from the color palette. For example, a user could add a background called "Teal".
• When a user specifies the color(s) for a Theme Element (button, icon, gradient text, hotlink), that color needs to be 3.1:1 contrast to the Default background color.
• Theme Element colors will be set for all of the other backgrounds (e.g. primary, secondary, tertiary, teal) but they will have the value of the "on-color" for the background in question.
  • Lise said that really, we could take the color specified by the Theme Element for the Default backgound and test out the -100 and -900 shades of that color against these non-default backgrounds and that should work.
    • I think for now we'll stick to the on-colors just so that the developer can anticipate what the color for the Theme Elements will be for a given background
• In the Design System Changes popups, there may be both a "Suggested Changes" section and a "Required Changes" section.
  • "Suggested Changes" will show suggested new colors for the Theme Elements if the default background changes
  • "Required Changes" will show the potentially new colors for the Theme Elements if a non-default background changes (they will have the value of the "on-color" for the new background color if it is a different on-color than existed for the previous background color)

[aaronreed708]

Started looking at the flow for a colorized button change. This is what I've come up with so far:

Theme Builder Flow for Button Color Change

Flow

1. User selects “colorized” dropdown for button
2. SDK asked to populate 2 dimensional array with color palette shades that have 3.1:1 contrast to default background
3. Dropdown displays shades in color palette that have 3.1:1 contrast against default background of theme
4. User selects shade
5. UI hides dropdown
6. Theme Builder changes value of button property in SDK
7. Button Listener fires in ColorTheme?
   1. SDK validates new value is acceptable against default background?
   2. SDK calculates new “colorized” value for AA dark mode
   3. SDK calculates new “colorized” value for AAA light mode
   4. SDK calculates new “colorized value for AAA dark mode
8. Button becomes un-initialized due to pending changes for AA dark and AAA light and dark, ColorTheme subsequently becomes disabled, pending acceptance of new colors

Display of Required/Suggested Changes

How can we structure the data coming from the SDK that will be displayed by the UI in a modal containing suggested changes that the user will have to accept or reject/cancel?

Class ChangeItem {
  itemLabel : string
  propertyLabel : string
  propertyValue : string
}

Class ChangePair {
  pairLabel : string
  currentItem : ChangeItem
  updateItem : ChangeItem
}

Class UserChange {
  changeLabel : string
  changeDescription : string
  change : ChangePair
}

Class SuggestedChanges {
  changesLabel : string
  suggestedChangesList : ChangePair[]
}

Class SuggestedChangesCollection {
  collectionLabel : string
  userChanges : UserChanges
  suggestedChanges : SuggestedChanges
}

Need to figure out

• In changing Button value scenario, button color has been changed by the user. Color theme detects change, builds suggested change list. Sends suggested changes to registered listeners. But then what?

  • What if listener never acts?
    • ColorTheme would remain disabled because dependencies not set, but how would user figure out a valid value to use? I guess whatever API were used to determine the suggested value would have to be run against each dependency that is blocking the ColorTheme
  • What if multiple listeners and more than one acts and they act in a contradictory way?
    • One approves, one rejects changes. Then what?

• As we can see in the "Changing a base color" example above, The changeItem needs to be flexible enough to be rendered in different ways. It could be a button, could be a gradient, could be a text gradient, could be a hotlink, etc.

  • But how will UI know how to determine which to display?

• How much of the information is in the SDK vs in the UI?

  • Labels
    • Suggested vs Required
    • LightMode vs DarkMode and AA vs AAA
    • Type of element changed
  • Descriptions

Questions

For @lwnoble:

• Will AA dark mode, AAA light and dark mode “colorized” values be re-calculated with each change?
• Will “Suggested Changes” dialog ALWAYS be shown on every change?
  • What about gradients, will it popup a modal when each of “to” and “from” are changed?
• Are AA and AAA separate color themes?
  • User able to make changes to AAA when it is displayed or is it read only, at least for now, like dark mode

[aaronreed708]

What if listener never acts?

• ColorTheme would remain disabled because dependencies not set, but how would user figure out a valid value to use? I guess whatever API were used to determine the suggested value would have to be run against each dependency that is blocking the ColorTheme
  What if multiple listeners and more than one acts and they act in a contradictory way?
• One approves, one rejects changes. Then what?

Been thinking on this. I do not think that this can be handled through notifications generated to the color theme from the properties when the user tries to change them. For example, currently, if the user has filled out a color theme completely and then changes the primary color, the ColorTheme will be notified that the primary color changed and it will zero out the property values for everything potentially affected by that change (also disabling any other properties that have dependencies on those cleared out properties). This means that the ColorTheme, while no longer complete, does not contain any non-compliant values, just uninitialized values. Also keep in mind that currently, the ColorTheme properties like primary color can't be changed once the ColorTheme is saved/activated. So the ColorTheme can not become non-compliant and thus downstream properties like hotlink color or input field background color cannot be non-compliant.

In this future V2 vision, if the primary color changes and we were handling this with notifications to primary property listeners, the user could get into a bad place. With UI only, we could potentially block off avenues for the user so that they couldn't get into the weeds and the UI could force them to regain compliance before continuing (e.g. the accept/reject popup). But Theme Builder SDK is a standalone entity. There may not be a UI, so we can't restrict user paths in this way. So what can we do? Here are some thoughts I've been contemplating.

Possible approaches:

• allow user to change a property as we do now
  • we add listeners to all possible properties that could be affected by that property's change
  • such listener can:
    • clear out properties that would be non-compliant due to the change
    • automatically calculate and set property values that would maintain compliance
      • thus sending notifications to listeners notifying of changed values
        • further listeners could then change THEIR values or clear out other property values as listener desires
• allow user to propose a change (e.g. like CLI tools that can pass -n where no action is actually taken, but caller can see what would have happened if it had run)
  • maybe pass like a batch ID where a listener could gather "required changes" notifications registered against that batch ID.
  • caller could then call again to make the changes using the batch ID
    • what if, for some reason, changes made here result in a detected non-compliance? Possibly because a batchID registered suggested/required change becomes invalid for some reason (e.g. a property value set, that doesn't use batch safeguard, that happens after -n builds batch but before batch is run)
• change V2 ColorTheme class to use different kind of properties whose value setters can only be called by ColorTheme
  • let ColorTheme manage property value changes so that caller who wants to change a property value calls ColorTheme with a proposed change, API returns with set of changes (unfortunately probably a very large structure to account for light and dark modes in AA and AAA) that would maintain compliance
  • user could then call ColorTheme again with this structure to do the changes
    • ColorTheme would re-validate changes before applying them, failing the call if something would still be non-compliant
    • listeners, like in downstream elements such as the InputBackground atom, could still decide to clear out their value if a dependency change renders them non-compliant. Can't assume ColorTheme even knows about them.
      • If an atom or molecule registers as a dependency, maybe it is given the opportunity to return a suggested value to maintain compliance that it could then consume when the property value set occurs

[aaronreed708]

@lwnoble

• So if we have primary set to Green-400 and change it to Blue-400, that doesn't have any affect on the default background, correct? Even if it was initially set to Green-400. It would only change the primary background value, right?
• If I change the primary color from Green-400 to Blue-400, are there any scenarios where there may be a cascading change? In that scenario the user will be presented with suggested changes. If the user accepts any of those suggested changes, could THAT then cause other suggested changes? In V1, changing primary affected the background and if that were changed, that could then change button and icon colors as well as atom colors (like InputBackground). I BELIEVE that all of the dependency rules in V2 as far as suggested changes, they will all be known by the ColorTheme since they will only affect theme elements. Can you think of a case where a suggested change would be necessary for something outside of the ColorTheme? Or is that something that we need to support?