Skip to content

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

Open
@wagnermaciel

Description

@wagnermaciel

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    M3docsThis issue is related to documentationneeds: discussionFurther discussion with the team is needed before proceeding

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions