[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?

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, 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

• 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