We have an existing catalog that is automatically generated from the tokens on the Codex documentation site, see https://doc.wikimedia.org/codex/main/design-tokens/color.html and the other entries in the navigation sidebar under "Design tokens". There is also some high-level documentation about what design tokens are and how they're structured at https://doc.wikimedia.org/codex/main/design-tokens/overview.html . These probably need improvement to fulfill all the requirements of this task, but I think they're probably the best starting point and a good source of truth (since they're directly generated from the tokens themselves).

Notes from Conversation on Overlapping Documentation for Design System Tokens:

(Copying my comment here too:)

We should keep both resources. We need to make tokens available in the Codex demo site, so they remain directly and easily accessible for developers. We also need to keep documenting tokens (manually) in Figma because:

• We use the visual representation of tokens to create reusable styles (when possible). For example, each base color token in the design palette is recorded as a reusable color style in Figma. These styles are then consumed by design components in the library.

• This increases findability and consultation for designers, as they can 1. see the design tokens used in context via the mentioned styles (vs. having to check SFCs), 2. access to usage descriptions (which we could/should also document in the token visualization pages in the Codex, of course)

• Some tokens can be reused as components for specification, which supports consistency. For example, documenting the individual spacing tokens from the scale as reusable elements would facilitate the application of system compliant spacing in compositions.

But, it might be worth exploring if there are ways to keep both resources automatically aligned. I never found a solution that really worked, but Figma and its community are growing fast, and design tokens are more and more common. As a con, implementing some sort of automated solution will probably mean that we'll have to redefine our token "publication" workflow, and probably reshape all our current documentation, though.

@DAbad I've been reviewing the Governance&Guidelines tasks with @Sarai-WMDE and we assume this task refers to the documentation of tokens both in the Codex demo and in Figma (T295991). Is this correct?

In T313935#8113738, @DAbad wrote:

Notes from Conversation on Overlapping Documentation for Design System Tokens:

[egardner] I'd vote for the public Codex docs site to be the canonical source of truth – it is auto-generated from the values that are going to be used in actual component code. I'd also say it is more discoverable than the figma files

Just on this specific “vote”: As that's far from the ideal product process, the tokens will be, in the design or “define” (Playbook) part of the process, by majority defined in Figma (/the designer's tool of choice). Only in relative specific exceptions in the code first. What do right now is wrapping system Design over components, that are often already defined elsewhere by and large in our Wikiverse. For a systematic approach we shall end up in that process turned on head.

1. Design requirements defined by product owners, designers and devs, (based on research)
2. design definition of tokens in Figma
3. implementation and 1:1 representation as much as possible in Codex docs

So Figma should be the main source of truth in the ideal world.

Regarding the Requirements specified in this task:

• There is a single source of truth for Design System Design Tokens

We decided to maintain Figma as our main source of truth, and keep visualizing tokens in the Codex demo to support implementation. This makes tokens easy to find by any type of user.

• Links back to relevant visual style guides

The different token categories in Figma include links to the corresponding demo in Codex (see image below for reference). Would it make sense to loop back from the tokens' demo to Figma too?

• Overall Design System Status: Not Started, In Design/Scoping, Ready for Development, In Development, Product Sign-Off, Done, Blocked
• Design Sign-Off: Not started, In progress, Done (all DST designers agree and are in alignment)

The Codex demo only documents finalized/reusable tokens. In the Figma Design Tokens library, we either document tokens that are implemented or clearly indicate it when the documented tokens are work in progress (aka In design, see left image below): all other states are indicated in the cover of the separate work-in-progress exploration files, where tokens are defined before being implemented (image on the right below).

• PHAB Implementation Epic Link (if available)

This is also indicated in the cover of the tokens’ exploration files (see above).

• There is a single source of truth for each user story (aka artifact)

Indeed, the resources satisfy the needs presented by the user stories stated in the description:

• As a designer, I can easily locate what tokens have been created/codified.
• As a developer, I can easily locate which tokens are available. Also which ones are deprecated and their replacements.

• All source of truth documents/artifacts are available via Design System Portal/Wiki

Done in case the demo can be considered that portal. Blocked in case we still need to decide whether the Design System Portal will be created.

Regarding the ACs:

• There is a single source of truth for each user story (aka document)

This is exactly the case. Figma and the demo satisfy the needs of our two specialized target user groups.

• All documentation should link back to a central Design System Portal

Once more, done in case the demo can be considered that portal. Blocked in case we still need to decide whether the DS needs it own portal.

• Documents should be:
• easy to read (limited jargon)
• clear to follow (written as steps, checklists, visual diagrams, etc.)

I think the documentation in both sources makes sure of this, specially thanks to the use of swatches and descriptions.

• Access to documents should NOT be restricted for viewing by target users (aka remove or update permissions as necessary)

The demo site is public, and our Design Tokens Figma library is also visible for anybody with the link.

@ldelench_wmf @DAbad I've checked the acceptance criteria and requirements of this task since almost all them have been already done.

The only one pending to do is this one related with the Wiki portal:

• All source of truth documents/artifacts are available via Design System Portal/Wiki

Once this has been done we could resolved this task.

Thanks for catching this @bmartinezcalvo! Pulling into the sprint board.

All source of truth documents/artifacts are available via Design System Portal/Wiki

I think this resource should be a subpage of https://www.mediawiki.org/wiki/Codex , and we can of course link to it from https://www.mediawiki.org/wiki/Design_Systems_Team/Resources.
@bmartinezcalvo @Volker_E let me know if you feel strongly otherwise.

@ldelench_wmf From my point of view there shouldn't be another page on Codex tokens in the mw.org documentation. More an intro paragraph on the Codex main page linking out to the demos. Otherwise we're only duplicating the great docs of the Codex demos and the maintenance overhead isn't worth it/risk getting out of sync long-term.

In T313935#8551994, @Volker_E wrote:

@ldelench_wmf From my point of view there shouldn't be another page on Codex tokens in the mw.org documentation. More an intro paragraph on the Codex main page linking out to the demos. Otherwise we're only duplicating the great docs of the Codex demos and the maintenance overhead isn't worth it/risk getting out of sync long-term.

Totally agree, we should avoid duplicating our Codex documentation and we should just mention about it in Mediawiki.