angular / angular/components

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

Offen
#28,933 2 Kommentare 10 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
docs M3 needs: discussion
Vorherrschende Sprache
TypeScript
Sterne
25k
Forks
6.8k
Ø Merge
1 T. 8 Std.
Gemergte PRs (30 T.)
91

Beschreibung

### 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

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit der betroffenen Autocomplete API-Dokumentationsseite unter material.angular.io/components/autocomplete/api und prüfe, wie die API-Dokumentation von Komponenten organisiert ist. Kläre die offenen Fragen zu Token-Beschreibungen, Terminologie und Platzierung mit dem Team. Als abgeschlossen gilt die Aufgabe, wenn die offengelegten CSS-Tokens in der entsprechenden API-Dokumentation der Komponente auffindbar sind und eine abgestimmte Terminologierichtlinie vorliegt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
angular, typescript
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.