[RFC] Adopting CSS variables documentation

[siriwatknp]

This RFC list the overview of the new pages related to CSS variables that will be added to the docs.

Side Navigation

The pages will be listed under experimental apis

• CSS variables
  • Overview (page)
    • Introduction: Explain the motivation, and the why. What are the benefits and how it works.
    • Trade-offs
    • Mental model: Explain the differences between the existing theming approach and the CSS variables way. Ex. don't use a conditional expression to use color between modes.
  • Usage (page): the demos of new APIs.
  • Customization (page)
    • Theming: How to customize the theme, adding new tokens, and what tokens are automatically generated (including typescript module augmentation).
    • Perfect dark mode: How to set up the app to have a perfect dark mode with some gotchas and warning.
    • Using theme tokens: Different ways to use variables from the theme. eg. in styled, system props in sx.
  • Migrating to CSS theme variables (page): A step-by-step guide for existing project to adopt CSS variables

If you have more ideas, feel free to comment and discuss.

[mnajdova]

The proposed structure look 👌 I would maybe also add sections about How to setup perfect dark mode

[danilo-leal]

If each of these is meant to be a single page, I'm afraid it can be too overwhelming?! it's a lot of new pages to be added!
How about we merge Overview and Mental model into one page, then Tutorial, Theming, Perfect dark mode into another (all related to how-tos), and finally Migrate to CSS vars, and Using theme tokens into another?!

That way, we'd be adding only 3 pages－not counting the API documentation.

[siriwatknp]

How about we merge Overview and Mental model into one page

Sounds good.

Tutorial

I am not sure about this, usually the tutorial should be one page but maybe we don't even need the tutorial at this point. (I will move tutorial to least priority and revisit once we have other pages again)

Theming, Perfect dark mode into another (all related to how-tos)

Sure, I put them under Customization, do you have a better name?

finally Migrate to CSS vars

I notice that we have Migration group in the sidebar, maybe the page should be under it? cc @samuelsycamore

[samuelsycamore]

I notice that we have Migration group in the sidebar, maybe the page should be under it? cc @samuelsycamore

That's an interesting question @siriwatknp. I'm thinking that a "Migrating to CSS vars" page should probably live next to the other CSS vars pages. The Migration section, in my eyes, should just be for upgrading major versions.