JSON representation for theme

[origami-z]

Catch all issue

Tasks

Beta Give feedback

1. Create JSON representation
2. Generate CSS to replace most of existing theme package content
3. Publish JSON as part of npm release
4. Write documentation how to integrate with 3rd party libraries (e.g. vanilla-extract for Mosaic, theme visualization)
5. Lint tool - help pattern library lint CSS while theming
6. Lint tool - check against Figma library (variables)

Some considerations

• Structural representation (token names + 3 layers) + value references
• Theme vs Theme next (+ data dense, etc.)
• Potential different folder / file structure ?
• Handle deprecation, versioning
• Token naming difference between Figma and CSS
• Figma only variables

Tools

• https://v4.styledictionary.com/
• https://github.com/tokens-studio/graph-engine

Prototype in #3143

References

• $mode proposal Native modes and theming support design-tokens/community-group#210
• resolver counter proposal Native modes and theming support design-tokens/community-group#210 (comment)
• Export salt theme plugin Figma-Plugins-and-Widgets#4
• Token visualization prototype using spectrum tokens

Would have avoided

• Fix foreground secondary color token in Salt theme next #4133
• Some of the line-heights in the text characteristic have been calculated inconsistently #4224
• theme-next.css imports invalid CSS variables #4302
• Fix target characteristic tokens being incorrect in Salt Next #4360
• Fix actionable background token reference #4441
• Fix titanium background token name #4463

[mark-tate]

Latte Goal: review current state, kickoff to understand requirements at EOS

[origami-z]

Oct 17: start in w2, after ag grid work

[origami-z]

Oct 21: scheduled a scope meeting on 28 Oct, start looking at dependencies / feasibility this week (e.g. styled dictionary v4 release DTCG)

[mark-tate]

Lungo Goal:
document what the JSON representation will NOT do

[origami-z]

Met w/ @mark-tate @joshwooding @pseys @dplsek John on Monday

Primary goal for the JSON exercise is for safety and quality control, which would lay the foundation for further expansion for other BYOT requirements

• For Salt, we can check between synchronization Figma and Code. e.g., See “Would have avoided” in GH issue description above.
  • We don't want to change existing process (e.g., editing Figma variables via Figma UI, Figma only variables) until risk and new process of syncing between Figma/Code can be fully understood. So the first step would be creating some "lint" tool to warn the user if anything is different is detected, e.g., as a Figma plugin, custom CSS stylelint
  • We should be able to produce CSS code via JSON, instead of manually construct them like now
  • Further usage could include theme configuration or virtualization tools (e.g., prototype using spectrum tokens)
• For consumers, they can use the file to check their Salt “theming” compliance (with our documentation)
  • One example would be providing CSS linting to consumer's code, e.g., Saslt CSS token validation, deprecation
  • In Figma, this can be used to create / check custom Figma library

This does NOT cover

• Any customization beyond @salt-ds/theme package, e.g., component level overrides.
• Change Salt existing workflow, e.g., how variables are added to Figma

[mark-tate]

Macc Goal: continue effort described in last comment, to be complete by end of quarter

[origami-z]

Done some experiments on 4041-json-theme using style dictionary v4, with DTCG format. A few findings

• Extracted JSON from Figma variables using Export styles plugin
• Trying to keep some structure, e.g. alpha tree of color, which needs custom name transformer salt-ds/name/kebab to handle
• Tried with loading multiple source token files from different modes
  • If loading each mode separately, there is no way to output different modes in the same file like we do today

    salt-ds/packages/theme/css/palette/accent-next.css

    Line 1 in dc5b3b3

    .salt-theme.salt-theme-next[data-mode="light"][data-accent="blue"] {

    salt-ds/packages/theme/css/palette/accent-next.css

    Line 17 in dc5b3b3

    .salt-theme.salt-theme-next[data-mode="dark"][data-accent="blue"] {

  • If loading all tokens from different modes, style dictionary will complain token conflicts and only output 1 mode, even if we can write custom formatter to append to the same file, like how rule in "css-advanced" custom format
  • The next approach would be using proposed $mode block, then write custom formatter to read value from $value (or swapped with different $mode value), then output to the same file. This requires a rewrite from style dictionary's formattedVariables function, which handles naming / output reference, as well as additional options to be passed down to the function (or formatter)

[origami-z]

Spent some time debug internal StyleDictionary code, a few possibilities

1. to use a custom version of formattedVariables (from "style-dictionary/utils"), so some $mode can be used instead of $value when resolving reference
   https://github.com/amzn/style-dictionary/blob/ef7b2f6cea9e820fd50c9c34ba7e2f3898b102af/lib/common/formatHelpers/createPropertyFormatter.js#L167
2. continue using formattedVariables but alter dictionary.tokens so that $value block is replaced with $mode. This is preferred over above, given we can continue using majority of SD code. There is still some risk around this, given we're relying on knowing how SD internal functionary work
3. Looks like the new preprocessors could also work for similar purpose

Continue investigating...

[mark-tate]

Mocha Goal: initial MVP by EOS

[origami-z]

Nov 29 - Make more progress in #4443, with the plan to replace next theme CSS to build from token files.

Found a couple of discrepancies between existing CSS and Figma variables, which needs to be fixed along the way.

[bhoppers2008]

Goal to publish one of the css theme files with the json theme.
Some discrepencies between figma and code with this exercise... ZC to summarise diff this sprint.