[docs][material-ui] Add default tokens viewer page #42916

siriwatknp · 2024-07-12T10:56:39Z

~~Blocked by #42839~~

Similar to Joy UI, I think this is a very useful page for exploring the default CSS theme variables.

I have followed (at least) the PR section of the contributing guide.

…-dark-mode-api

mui-bot · 2024-07-12T10:59:22Z

Netlify deploy preview

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 7611735

…aterial-theme-tokens

aarongarciah

Left some comments.

aarongarciah · 2024-07-18T15:33:09Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+{{"component": "modules/material-ui/FontTokensViewer.js"}}
+
+:::success
+Using font variable is an alternative way to `theme.typography` when you cannot access the theme in Javascript.


Using font variable is an alternative way to theme.typography when you cannot access the theme in Javascript.

This applies to every generated CSS variable, not only typography variables, right? Should we move this info to the top of the file, before the "Colors" section?

This applies to every generated CSS variable, not only typography variables, right

Yes, you are right.

Should we move this info to the top of the file, before the "Colors" section?

I think I will just remove it since this page is about listing the default variables. It might be better to add link to a different page for learning how to use them.

aarongarciah · 2024-07-18T15:34:24Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+
+<p class="description">A preview of the default CSS theme variables for built-in light and dark color schemes</p>
+
+The following tokens are generated when using `CssVarsProvider` in your application.


Suggested change

The following tokens are generated when using `CssVarsProvider` in your application.

The following tokens are generated when using [`CssVarsProvider`](/material-ui/customization/css-theme-variables/overview/).

aarongarciah · 2024-07-18T15:36:21Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

@@ -0,0 +1,63 @@
+# Default tokens viewer
+
+<p class="description">A preview of the default CSS theme variables for built-in light and dark color schemes</p>


Observation: it's always weird to read about light/dark color schemes and then see variables unrelated to color.

Good point.

aarongarciah · 2024-07-18T15:43:13Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+
+</codeblock>
+
+## Shadows and overlays


Why "Shadows and overlays"? Aren't these just "shadows"?

Q: are me missing a section in the docs for this in the Customization > Tokens section?

Q: are me missing a section in the docs for this in the Customization > Tokens section?

I've been having some trouble customizing the shadows and couldn't find much about it in the docs. The only page I found was under MUI System, which isn't ideal. I agree that we should have a page for it—especially since we have 25 shadow tokens, the least we could do is show them off 😅

cc @samuelsycamore

Just to be clear, it's out-of-scope of this PR right?

aarongarciah · 2024-07-18T15:46:34Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+
+The demo below is a [Paper](/material-ui/react-paper/) component with different level of elevations in light and dark color schemes:
+
+{{"component": "modules/material-ui/ShadowsOverlaysViewer.js"}}


This section feels a bit weird: in all of the other sections I can see a list of the variables and their default values. I think we should have the list of variables in this section as well.

Yeah, it feel inconsistent to me as well. I will switch back to a table-like format.

aarongarciah · 2024-07-18T15:52:26Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+
+:::
+
+## Spacing


Even if there's only one variable, maybe this section would benefit from having a codeblock like the other sections so users can quickly scan the variables across all sections consistently.

aarongarciah · 2024-07-18T15:54:34Z

docs/src/modules/material-ui/PaletteTokensViewer.js

+      <TokensTable isCopied={isCopied}>
+        <thead>
+          <tr>
+            <th width="60%">Token</th>


Other tables in the page use "CSS variable", which I think makes more sense.

Suggested change

<th width="60%">Token</th>

<th width="60%">CSS variable</th>

aarongarciah · 2024-07-18T15:56:17Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

Should we add a short paragraph to explain how to convert JS dot notation to CSS variables? e.g. theme.palette.common.black → --mui-palette-common-black.

aarongarciah · 2024-07-18T16:01:38Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+```js JS
+theme.spacing(1, 2); // var(--mui-spacing) calc(2 * var(--mui-spacing))
+```
+
+```css CSS
+.some-class {
+  margin: calc(var(--mui-spacing) * 2);
+}
+```


I'm not sure this example is clear. Maybe users expect both snippets to be equivalent, and the first one using the multiple arity version of the function might cause confusion. I'd keep the example to the bare minimum.

aarongarciah · 2024-07-18T16:12:49Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

@@ -0,0 +1,63 @@
+# Default tokens viewer


I'd rename the page from "Default tokens viewer" to "CSS vars viewer" or "Default CSS vars viewer" (or something similar). The former can be more easily confused with the existing "Default theme viewer" page.

Also, a token is not the same as a CSS var. "token" is the concept, something we give a value to and then consume via CSS vars, sx prop, styled callbacks that access the theme, and whatever other consuming method we could have.

zanivan

Overall, I like the idea of having these in the docs, and I believe it's a must. I don't know if this is the best approach, though.

I wonder if this information shouldn't be split into more pages, and each token having its own page under CSS Variables menu item, or live under the existing tokens' pages, in a CSS Variables section instead. As a user, I would expect to find the CSS Variables tokens in the Typography page. The way that's in here, the information feels a bit hidden from the users. cc @samuelsycamore @alelthomas

From a UX standpoint, nested scrolling is never a good thing. I'd go with a different design for these, something like Medusa UI does for colors, and be more 'visual' for the other tokens as well.

Leaving some examples:

Should we discuss this structure on Figma and come up with some explorations before a PR?

zanivan · 2024-07-18T16:51:45Z

docs/data/material/customization/css-theme-variables/default-tokens-viewer.md

+Using font variable is an alternative way to `theme.typography` when you cannot access the theme in Javascript.
+The font variable should be used with the CSS `font` property like this:
+
+```css


I don't think it's related to this PR, but this border radius seems off. I think it's currently like this (12px 12px 6px 12px) to be concentric with the outer radius. However, it ends up looking like it could resize, similar to a TextArea component 🤔

aarongarciah · 2024-07-18T21:11:23Z

Having thought about this a bit more, I think we should give it some more thought and document the CSS vars closer to where we document the theme/tokens. Having two providers (ThemeProvider and CssVarsProvider), because the CSS vars are not available for every user. Still, I think it's doable if we clearly state that CSS vars are only for CssVarsProvider.

We already have the "Tokens" section (with different subsections: palette, typography, etc.) under "Customization". We can explore documenting the CSS vars in those subsections if we don't want to change much the structure now.

I'd also love to see how "Default theme viewer" could somehow display the corresponding CSS vars for the corresponding tokens. It gets tricky because the default theme shape is different depending on the provider.

TL;DR I think we should think about this a bit more instead of adding a new page.

PS: I think it's important that we don't call CSS vars tokens, so we all have the same mental model:

Tokens are defined in the theme: colors, shadows, fonts, etc..
Tokens get transformed into CSS vars (an potentially other formats).
Tokens can be consumed in the form of CSS vars, through styled, sx, etc.

siriwatknp · 2024-07-23T03:35:31Z

@aarongarciah @zanivan Thanks for the comment, I totally agree about revisiting the place to move this info to.

siriwatknp added 30 commits July 1, 2024 17:52

add strategy to extendTheme

9581893

fix extendTheme

a5ac829

attach selector based on strategy

3dd0cbb

remove attribute in favor of strategy

08e7663

support class in InitColorSchemeScript

d3aaa1b

Merge branch 'next' of https://github.com/mui/material-ui into refine…

e9c21a5

…-dark-mode-api

use default config

922515c

update docs

76b7e4b

Merge branch 'next' of https://github.com/mui/material-ui into refine…

cfbc50e

…-dark-mode-api

Merge branch 'next' of https://github.com/mui/material-ui into refine…

ed2a05a

…-dark-mode-api

update docs

29f4059

fix extendTheme

62d3844

fix InitColorSchemeScript

9f76644

fix InitColorSchemeScript

00c7cde

Merge branch 'next' of https://github.com/mui/material-ui into refine…

e2be118

…-dark-mode-api

fix applyStyles and add enableSystem

4c89650

add disableCssColorScheme option

65d1216

fix applyStyles and disableCssColorScheme

73ae9b1

fix default mode

cd9fc22

add test

364c529

fix types

e895ac7

export createPalette

362ba80

fix tests

ab81b0d

fix extendTheme

9f53d7d

wip

3d7949d

remove createPalette

f23729d

update docs

967269b

fix Paper

dc4577c

update docs

b91cd3f

Merge branch 'next' of https://github.com/mui/material-ui into refine…

dbd7b87

…-dark-mode-api

siriwatknp added 10 commits July 11, 2024 19:54

remove enableSystem

684ac0f

fix Joy tutorial

6446b1e

remove defaultColorScheme from CssVarsProvider props

8a320e9

support 'class' and 'data' selector

9cf4e91

update content

27f8f14

trigger build

625bed0

Merge branch 'next' of https://github.com/mui/material-ui into refine…

788e2a4

…-dark-mode-api

fix all

249b13a

minor fix joy docs

a29c08a

add default-tokens-viewer

4c12e75

siriwatknp added docs Improvements or additions to the documentation package: material-ui Specific to @mui/material labels Jul 12, 2024

siriwatknp marked this pull request as draft July 12, 2024 10:56

update content

a02c2a0

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jul 15, 2024

siriwatknp added 3 commits July 18, 2024 13:39

Merge branch 'next' of https://github.com/mui/material-ui into docs/m…

c61c841

…aterial-theme-tokens

fix selector generated for default color scheme

00a1b76

refactor and cleanup

7611735

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Jul 18, 2024

siriwatknp requested review from aarongarciah, zanivan and samuelsycamore July 18, 2024 13:42

siriwatknp marked this pull request as ready for review July 18, 2024 13:42

aarongarciah reviewed Jul 18, 2024

View reviewed changes

zanivan reviewed Jul 18, 2024

View reviewed changes

siriwatknp closed this Jul 23, 2024

siriwatknp mentioned this pull request Jul 23, 2024

[material-ui] Attach selector for default color scheme #43035

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs][material-ui] Add default tokens viewer page #42916

[docs][material-ui] Add default tokens viewer page #42916

siriwatknp commented Jul 12, 2024 •

edited

Loading

mui-bot commented Jul 12, 2024 •

edited

Loading

aarongarciah left a comment

aarongarciah Jul 18, 2024

siriwatknp Jul 23, 2024

aarongarciah Jul 18, 2024

aarongarciah Jul 18, 2024

siriwatknp Jul 23, 2024

aarongarciah Jul 18, 2024

zanivan Jul 18, 2024

siriwatknp Jul 23, 2024

aarongarciah Jul 18, 2024

siriwatknp Jul 23, 2024

aarongarciah Jul 18, 2024

aarongarciah Jul 18, 2024

aarongarciah Jul 18, 2024

siriwatknp Jul 23, 2024

aarongarciah Jul 18, 2024

aarongarciah Jul 18, 2024

zanivan left a comment

zanivan Jul 18, 2024

aarongarciah commented Jul 18, 2024 •

edited

Loading

siriwatknp commented Jul 23, 2024


		<p class="description">A preview of the default CSS theme variables for built-in light and dark color schemes</p>

		The following tokens are generated when using `CssVarsProvider` in your application.

		@@ -0,0 +1,63 @@
		# Default tokens viewer

		<p class="description">A preview of the default CSS theme variables for built-in light and dark color schemes</p>


		The demo below is a [Paper](/material-ui/react-paper/) component with different level of elevations in light and dark color schemes:

		{{"component": "modules/material-ui/ShadowsOverlaysViewer.js"}}


		:::

		## Spacing

[docs][material-ui] Add default tokens viewer page #42916

[docs][material-ui] Add default tokens viewer page #42916

Conversation

siriwatknp commented Jul 12, 2024 • edited Loading

mui-bot commented Jul 12, 2024 • edited Loading

Netlify deploy preview

Bundle size report

aarongarciah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zanivan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aarongarciah commented Jul 18, 2024 • edited Loading

siriwatknp commented Jul 23, 2024

siriwatknp commented Jul 12, 2024 •

edited

Loading

mui-bot commented Jul 12, 2024 •

edited

Loading

aarongarciah commented Jul 18, 2024 •

edited

Loading