Format: Token taxonomy documentation

[Sidnioulz]

Examples

Rationale

A large part of what we do with design tokens is build a taxonomy, and implicit relations within that taxonomy. We expect our designers to succeed in using the tokens because we documented how to combine taxonomy elements. Displaying the taxonomy would help designers with discovery (they know what choices they get for a given category within the taxonomy).

It may be too much to ask to document the inner workings of a taxonomy (that boils down to being a generic MD/HTML/CMS doc tool), but a page could be generated that draws the taxonomy as inferred from the data. This could be enriched with group description attributes.

Extra metadata would likely be necessary to name groups of categories and provide a general description for their role in the taxonomy.

Challenges

• A tokenset could have an inconsistent taxonomy, which could not be displayed
• Explaining to end users how their taxonomy is inconsistent and why it can't be displayed may be difficult
• It may be hard to find a general layout that works with a wide variety of taxonomies