Page MenuHomePhabricator

List/visualize a component's design tokens in Storybook
Closed, DuplicatePublic

Description

As a designer, I want to see which design tokens are being used by each design system component in Storybook, so that it helps me to define the tokens for new components and control if the correct ones have been implemented.

This task used T258046 as blueprint.

Acceptance Criteria
  • All component pages in Storybook contain a section/tab(?) where component-level tokens are listed
    • The tokens represented are contextually updated according to component selection by Storybook user (e.g. disabled yes/no)
  • The list contains all design tokens involved

Event Timeline

It is not well reflected in T258046 but this feature, especially the section

The tokens represented are contextually updated according to component selection by Storybook user (e.g. disabled yes/no)

was identified as highly challenging by the dev team at the time (the discussion is certainly in some document but not public), which was the reason for the work package to be moved to a separate ticket.

This is a good example of a task which could benefit a lot from taking a step back into the problem space, describe which users problem is supposed to be solved, and draft an efficient solution from there.

An attempt of an explanation for the (perceived) complication:

What I understand by the task is to only show the tokens which make up the selected state of the component and omit all others.

On a technical level, a component gets told to assume a certain state, which results in specific mark-up (incl. classes) to be rendered, which in turn makes the browser apply certain styles, the values of which are influenced by tokens. In this chain we bridge the boundaries between different technologies (JS, HTML, CSS[, the token format – if not CSS variables]) and programming paradigms (declarative programming) – the component does not really "know" which tokens it "uses" (because it doesn't directly) and even if it did, there is no pre-prepared way to "ask" it. I am not aware of an existing technical solution which could be used to facilitate the task and if it were to be built it would have to be a pretty involved one. Thinking… something with access to a browser engine, scripting and the component+token source – then rendering the component, analyzing the rendered mark-up, collecting the used classes/tags, looking up the style definitions of those in the component styles [somewhat ignoring styles originating from reset/normalize/global], presenting the results in a consistent fashion. It should all be possible within the laws of physics (e.g. in the user's browser) but I doubt it's a good investment.

A relatively simple alternative way of approaching this challenge is through convention. Tokens starting with the component and state name (cf.) are extracted from the token source, and can be displayed and further lookups and presentation can be based on that. The problem is that this approach is also somewhat naive. It assumes that no mistakes are made (e.g. in naming) and no edge cases exist. There is a high risk that the tokens shown are not an exhaustive list of all values which make up the component's style at the time.

I thought writing this down may help surface potential misunderstandings about the goal and allow more people to join the discussion with fresh ideas for solutions.

(FWIW I found this when looking around but I'm not sure what to make of it, did not really dig in)