Use build-free CSS as source of truth for themes

[mimarz]

We want to explore the possibility for using CSS as source of truth for themes.

Goal

The goal is to be closer to native, have better CSS implementations and make it easier for users to configure (and override) Designsystemet along with custom variables.

We want users to be able just use a CSS file and configure it with ds variables and use it with our other building blocks without a build step.

Only when other formats or extensions are needed a build step would be required (such as design-tokens, types, tailwind theme file etc)

Thoughts

• General idea is one css file per theme, denoted by a marker for auto recognition, my-theme.ds-theme.css
• Themebuilder will generate the css config.
• Multiple *.ds-theme.css will count as themes of the same system.
  - Running cli with just designsystemet with pickup css file and populate remaining values.
• Multiple output formats, we may need a config file for declaring outputs, feat(cli): new way to run 🏃🏻‍♂️ #5416
  - Use js so that users can manipulate, say banner with date values.
• Outputs
  • Standalone tailwind
  • Unitless for mobile (json)
  • W3C design-tokens (json)
  • Figma plugin -> Figma variables
  • Maybe separate css file for data-color, data-color-scheme etc?

Hurdles:

• Single css file per theme makes copy-paste to figma-plugin tedious if you have multiple themes.
• For Figma, themes must have same amount of colors and color names. Harder to enforce with css. Maybe CLI can throw a warning/error when parsing multiple theme files.
• No type or schema safety for names.
• In css config users must type correctly long ds-color variable names.
• Collections in design-tokens and Figma variables must still be defined somewhere

Drafts

config file with a new input if other output forms are needed.

{
  "input": [
     "./digdir.ds-theme,css",
     "./altinn.dstheme.css"
   ],
  "output": [
    "design-tokens",
    "types", 
    { "type":"css", "tailwind":"v4" }
   ]
}

:root {
  --ds-my-custom-prop: 1em;
  
  /* User defines new color withing semantic color scale
   * npx designsystemet will read semantic color variables 
   * and populate missing variables
  */
  --ds-color-my-first-color-background-default: #0062BA;


  --ds-color-my-second-color-base-default: #0D7A5F;
  --ds-color-my-second-color-base-contrast: #0D7A5F;
  --ds-color-my-second-color-base-subtle: #0D7A5F;
  --ds-color-my-second-color-base-hover: #0D7A5F;

  --ds-color-my-third-color-base-default: light-dark(#5B3FA0, #a697cc);
  --ds-color-my-third-color-base-contrast: light-dark(#5B3FA0, #a697cc);
  --ds-color-my-third-color-base-subtle: light-dark(#5B3FA0, #a697cc);
  --ds-color-my-third-color-base-hover: light-dark(#5B3FA0, #a697cc);
}

/* Either separate file or block in same file with auto-generated content from CLI */ 
/* DESIGNSYSTEMET: DO NOT EDIT BELOW */
[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}[data-color="main"]{--ds-color-base-default: var(--ds-color-my-first-color-base-default)}
/* DESIGNSYSTEMET: DO NOT EDIT ABOVE */

[Barsnes]

My honest take on this is that this feels like over-engineering.
JSON works fine, and also makes it easier for non-css applications to use this. There might be people who want colors generated for mobile apps, where they won't have any css.
We also won't be able to give a schema to users like in JSON, meaning there will be no editor hints to get help from.

[eirikbacker]

For all people who want colors for mobile apps, they can have a CSS file to generate JSON. Now, all people who want CSS needs JSON, so we are actually just flipping the table - using the origin format that most consumers need ☺️ Also, with CSS as the source of truth, it is easier to resonate about what we are actually generating, instead of guessing what the variable names will become, and adding custom banners #3486 or adding custom properties they want themselves is as simple as editing the file. I think this can be a good direction, bringing us closer to the file format most are familiar with ☺️

[mimarz]

Some thoughts after being on vacation for 3 weeks.

• I wish we also had support for js config, like tsdown,rolldown, vite etc does.
• We will still need the current JSON schema for themes when parsing, validating and populate the "css config".
• Maybe matter of opinion but JSON feels easier to get an overview for the colors defined than multiple lines in css?
• JSON is type safe with hints using schema (given you edit in json file).
• CSS config will be brittle with typo (given you edit in css file).
• CSS config make its cleaner to add single custom variables, not that adding this in a separate file is a problem.
• CSS config = todays CSS file with magic
• Autopopulating thing in css file can become cumbersome if users/formatterts start moving stuff.
• There are other improvements we can do in current themes schema (and themebuilder) for making it easier to use.
  • light-dark support
  • Simpler overrides under color?
  • With our Figma plugin we can also simplify design-tokens.
  • Our CSS file generation can be improved.
  • Make it easier to understand colors can be override in themebuilder gui.
• The JSON config and CSS config can co-exist.
  • Maybe something like if *.ds-theme.css exists then themes in json config is ignored.
  • Making a parsers for the CSS config to JSON themes schema should be quick so we can test this
    concept quick
  • https://color-palette-generator-eds-prod.radix.equinor.com
• JSON is still best to use for Figma plugin (unless we replicate the themebuilder in there).
• Where do we stand with design-tokens now? Using style dictionary we support users adding their own tokens with our build, but its overwritten when they run create, which is counterintuitive. 🤔
• We can drop style dictionary and make our own transpilers, but this comes at the risk for support of custom design-tokens and token studio. I would however liker to explore this.
• We have support for only generating CSS file today (from json config).
• I still think we should test our the css config approach, but maybe fix some other underlying stuff first and then enrich the configuration experience with CSS config.

[mimarz]

Something I dreamt about last night.

We could also have an input prop, which supports json and/or css.

Something like.

"input": [
  "theme1.css", 
  { "theme2": "color": { "accent": "#12345" } },
  "theme3.json"
]

"input": {
  "theme1": "theme1.css", 
  "theme2": "color": { "accent": "#12345" },
  "theme3": "theme3.json"
}

[eirikbacker]

hehe, this is going too far :D
but regarding the concept; I think a single, understandable, verify-able, and readable format is most important, and also ensuring we do not have more ways to Rome, or more code in our code base than necessary, so I think I'd rather have a single format we land on :)

[mimarz]

hehe, this is going too far :D but regarding the concept; I think a single, understandable, verify-able, and readable format is most important, and also ensuring we do not have more ways to Rome, or more code in our code base than necessary, so I think I'd rather have a single format we land on :)

I agree wholeheartedly on the predicates :)

The more I think about it the more I lean towards still having todays approach with a config file but improving how its defined/used as well as output formats. No matter how we turn it, we need that config schema. The generated CSS file can be used as a "config file" today if you want imho.

In short:

• Enable feat(cli): one config #5099.
• Themebuilder provides css file or json config file for download/use.
• Improve Themebuilder UX for defining custom colors.
• Expand on colors schema for config file.
  • support for overrides and custom color variables under colors
• Support js/ts config file variants.
• Clean up/improve the generated css file
  • light-dark, other improvements mentioned
• We do have the Figma plugin which will make it easier to control the output as this has in the past been shaped by how Token Studio "needs" it be formatted for importing correctly.

[mimarz]

Move this to discussion as this is something we want to do in the future, but needs more investigation and experimenting. No prioritised as of now, but something we can keep in the back of our mind when working with updating themebuilder, cli and figma plugin.

So far:
We move defaults to zod schema and let it handle validation and populate defaults, which will make it easier to go from config to other formats, instead of via design-tokens, which was a limitation before. #5357

@eirikbacker did also spike on using postcss for parsing css file and its resolving expressions which looked very promising. This could be a great replacement for style-dictionary as our config -> css transpiler, not to mention probably much more performant. In doing so, we would indirectly have support for css -> config. #5394

[eirikbacker]

• Experiments in feat(css): postcss-parse-data-color #5394 shows we need to discuss:
  • Should we do light-dark() or the current --ds-color-*--(light|dark) convention (a postcss plugin alleady exists for handling light-dark compatiblity, and it can be configured to use [data-color-scheme])
  • How should we handle calculations using wv like clamp() for fluid sizing?
  • Defining custom colors, should we support both --ds-color-my-special-color: tomato | light-dark() or is it better to align with --ds-color-my-special-color--(light|dark)?
  • Today, the user can do --ds-color-**neutral**-surface-default to use specific color from another color scale without changing data-color on this element. This will not be possible unless we require a buildstep, as the new convention is [data-color] { --ds-color: * }. Is this fine? should we do something else? I personally think it is important to strive towards a solution that aligns 1:1 with pure web spec, so build step is not required - just used for compatibility or external usage like mobile token generation etc.

Also for context:
Both color(from) and light-dark() are baseline features, but they have less support:

• color(from) = 95.16% support in Norway – I think that’s too low, since the entire design actually breaks when the colors don't work; hence the PostCSS plugin that calculates the final hex value 🙌
• light-dark() = 78.23% support in Norway – one could argue that this is a feature, but we need a solid fallback, which requires quite a few extra CSS properties 😌