angular / angular/components

docs(material/theming): add tokens section to our docs

Open
#28,933 2 comments 10 reactions 0 assignees View on GitHub
docs M3 needs: discussion
Dominant language
TypeScript
Stars
25k
Forks
6.8k
Avg merge
1d 8h
Merged PRs (30d)
91

Description

### Documentation Feedback

Add documentation to material.angular.io to list the tokens that our components expose.

#### Design

There are still some open questions that the team should discuss.

- Should we write a description for each token?
- Critiques:
- A unique description for every token may be too much data thrown at the user which the user might mentally filter out when looking through our docs.
- Many tokens are self-explanatory. It seems silly to write `"selected-checkmark-color": The color of the checkmark when the checkbox is selected`.
- A more useful approach may be to provide a subsection that explains terminology that is obscure to most users. For example, the section could describe the following:
- What `state-layer` commonly refers to.
- Listing the different states - `active`, `pressed`, etc. Material has [a page dedicated to this](https://m2.material.io/design/interaction/states.html#usage) we could also link to.
- Where should this token list live?
- IMO under the "API" tab for each component makes the most sense.

This design satisfies the following pain point for our users:

- CSS variables are difficult to identify / discover.

### Affected documentation page

https://material.angular.io/components/autocomplete/api

Contributor guide

Open the contributing guide

Research direction

Start with the affected Autocomplete API documentation page at material.angular.io/components/autocomplete/api and review how component API documentation is organized. Resolve the open questions about token descriptions, terminology, and placement with the team. Done means the exposed CSS tokens are discoverable in the appropriate component API documentation, with agreed terminology guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
angular, typescript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.