docs: show component tokens default value

[martinboue]

Show default value of component tokens in styling tab to better understand their meanings.
Related issues :

• docs-bug(button): I don't understand how to use most of design tokens #30425
• docs(material/theming): add tokens section to our docs #28933

Why?

It is not always obvious to understand what certain tokens correspond to and what type/unit are expected (color, numeric, ...). For example in the expansion panel component, the container-shape token can be ambiguous, one might expect to set something like ‘rounded’ or 'small' when it is actually a size that is expected (12px by default).

What is often necessary is to inspect the generated code, locate the related CSS property to identify the token used, and then override the token.

Solutions

In order to make the documentation self-sufficient, we could display more context about tokens:

1. A description
2. The default value

Both would be great to add, but 1 needs a lot more work as the description are not available/written yet. This PR adds solution 2.

What this PR contains

In each component styling page, I replaced the "Based on system token" column by a "Default value" column in the tokens table. Why?

• The default value is a useful information to understand a token, and is more precise than the previous column.
• "Based on system token" column was incomplete. For example: the default value --mat-sys-on-surface would be shown as "None" in the old column. The reason is that the default value need to contain "var()" to be detected as a system token.
• We could improve the detection of derivedFrom, but keeping both columns seemed redundant to me as it is fairly easy to identify the token system used in the default value.
• Changed type of Token value to include null which was the case for some tokens (for example: elevated-disabled-container-color in chip component).
• Replaced the system token filter by a default value filter.

Before

After

Going further

• Should I remove derivedFrom attribute from Token interface? It's not used anywhere else.
• The default value is easily readable 95% of the time, but there are cases where this is not ideal. For example the value for button small-ripple-color token is : color-mix(in srgb, var(--mat-sys-on-primary-container) calc(var(--mat-sys-pressed-state-layer-opacity) * 100%), transparent).
  Do we want to improve this? How?
• Most component tokens are based on a system token but I think system tokens also lack context. IMO, we need a complete list of CSS system variables with, as for component tokens, a description and a default value. What do you think?
• Being able to dynamically tweak the tokens value and see the result in real time would be great.

Note: First PR here so please let me know what I can improve :)

[crisbeto]

This PR was merged into the repository. The changes were merged into the following branches:

• main: 1210f51
• 21.2.x: 942cfc1

[martinboue]

Thanks @crisbeto ☺️