Change 910523 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Update tokens docs and remove warning about Codex status

https://gerrit.wikimedia.org/r/910523

Change 910523 merged by jenkins-bot:

[design/codex@main] docs: Update tokens docs and remove warning about Codex status

https://gerrit.wikimedia.org/r/910523

Change 911932 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v0.9.0 to v0.9.1

https://gerrit.wikimedia.org/r/911932

Test wiki created on Patch demo by ATomasevich (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/9a9f20a61d/w

Change 911932 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.9.0 to v0.9.1

https://gerrit.wikimedia.org/r/911932

Test wiki on Patch demo by ATomasevich (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/9a9f20a61d/w/

Change 946567 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Standardize design tokens and components overview format

https://gerrit.wikimedia.org/r/946567

@bmartinezcalvo / @RHo / @Volker_E I've pushed a patch that does the following:

• Improves the components overview page a bit by creating a new section called "usage" that links to the docs for using components in and out of MediaWiki, and adding links to the sections about designing new or redesigning existing components
• Updates the design tokens overview page to match this format: adds a few more sentence about what design tokens are and how they're documented, adds a new "usage" section, and adds a "resources" section
• Moves the details about the design tokens system to a new page, which is both linked to on the overview page and included in the sidebar

I hope these changes will:

• Make it very clear on the overview pages what the design tokens and components are, how to use them, and how to learn more about the details or contributing
• Continue to make the more detailed info about how the design tokens are structured available, while not overwhelming the average Codex user with it

Please let me know your thoughts!

In T335087#9074469, @AnneT wrote:

@bmartinezcalvo / @RHo / @Volker_E I've pushed a patch that does the following:

• Improves the components overview page a bit by creating a new section called "usage" that links to the docs for using components in and out of MediaWiki, and adding links to the sections about designing new or redesigning existing components
• Updates the design tokens overview page to match this format: adds a few more sentence about what design tokens are and how they're documented, adds a new "usage" section, and adds a "resources" section
• Moves the details about the design tokens system to a new page, which is both linked to on the overview page and included in the sidebar

@AnneT thank you for preparing this. I've reviewed the last changes and I agree with adding a new "Usage" section to explain how to use tokens in code. But, assuming that this documentation will be read by not just developer users but also designers or other users, I wonder if we should:

1. Rename these sections from "Usage" to "Code usage"/"How to use tokens in code". Not sure about the title, but something that clarifies that this section is related just to the code.
2. Should we add a specific section about how to use these tokens in design (e.g. how to enable the Design Tokens library)? If we do this, maybe we should separate the content on this page in "how to use in code" and "how to use tokens in design" (maybe with tabs). cc: @RHo @Sarai-WMDE

@bmartinezcalvo great points; I agree we should include design usage here! I would recommend the following:

• In the "Using Codex" section of the site, we currently have a section in the sidebar called "Developing" that has a "Usage" page that instructs developers how to use the Codex library. I think we should add a section above this called "Designing" and include a "Usage" page (or some other title) that describes how to use the design tokens and components Figma libraries, and anything else you want to include there
• On the design tokens overview page, under "Usage", include a section called "Design" and include a link to the appropriate section of the Designing Usage page
• Same thing for the components overview page

Does that sound ok? I think this is what we originally intended to do when we created the site architecture design. We could also just link directly to the appropriate Figma library from the overview pages if that's all there is to it, but if more setup is involved, I would recommend housing that information on a separate page like we do for developing.

@bmartinezcalvo Excellent point on how to use tokens as designer.
@AnneT Agree with amending the structure into pages. One thing that's confusing right now (more than before) is, we're having Overview>Usage section and Structure>Using tokens section.
On latter, the term “Structure” is not really describing all the contents. Maybe “Implementation” is better?
When trying to come up with a better phrasing for former, I've had two thoughts: “Applying tokens” would be better separation from “Usage”, but we would also apply them in design and more importantly, in Components and Icons the verb is also “use”.
Note that in Icons it's called “Using icons”. I think we should do that in the former pages as well.

Another important point, IMO the whole intro of “Structure>Using tokens“ section until from design to implementation should be moved up under “1. What are design tokens?“

@Volker_E yeah, I wasn't happy with the "Structure" title - it's hard to know what to call that page; it's basically an in-depth explanation of the design of our tokens system. I'm afraid that "Implementation" doesn't quite get that point across either...what about "Implementation details" or something similar?

Maybe the "Using tokens" section on that page can be renamed to "How Codex tokens are used"? That seems to better describe what that section includes, focusing on how tokens are designed to be used, not how to actually use them.

I agree that "Using ___" is better than "Usage," and I can make the change you suggested about moving around content on the Structure page.

@bmartinezcalvo @Volker_E I've updated the patch in the following ways:

• Changed "Usage" to "Using design tokens" and "Using components"
• Added a "Figma" section under each "using" heading that links to the appropriate Figma library
• Changed the title of the new page from "Structure" to "Implementation" (although I call it "Implementation details" in the sidebar)
• Moves the "what are design tokens" section on the Implementation page as Volker specified

View the demo here

Please let me know if this is sufficient for now - if we need to add new pages about using the Figma libraries, I would recommend we do that in a separate task.

@AnneT thank you! Some small things to fix (also commented with @Volker_E during our last DS design sync):

• "Implementation details" page:
  • Rename it to “Definition and Structure”
  • Rename the second section on this page:
    1. What are design tokens?
    2. Tokens in design (rename this section that at the moment is "Using tokens")
    3. Tokens in code
• Apart from this, in Using design tokens > Figma, I would avoid visual references in the text, so I would rephrase to: "View Check the Design Tokens Figma library and enable it in your Figma projects to use all the design tokens that were translated into Figma styles".

Yes, I've revisited the patch this morning and my proposals above would be simplifying the structure even more and connecting the dots (like “From visual styles to tokens” to “From visual styles to tokens in design and code”) for folks skimming the page.
All of above is mentioned as comments on patch.

Thanks @bmartinezcalvo and @Volker_E for the feedback! I've implemented everything in the latest patchset, demo here.

In T335087#9084684, @bmartinezcalvo wrote:

• Apart from this, in Using design tokens > Figma, I would avoid visual references in the text, so I would rephrase to: "View Check the Design Tokens Figma library and enable it in your Figma projects to use all the design tokens that were translated into Figma styles".

I ended up simplifying this a bit to just say "Enable the Design Tokens Figma library in your Figma projects to use all the design tokens that were translated into Figma styles" - hope that's ok!

Change 946567 merged by jenkins-bot:

[design/codex@main] docs: Standardize design tokens and components overview format

https://gerrit.wikimedia.org/r/946567

In T335087#9085160, @AnneT wrote:

Thanks @bmartinezcalvo and @Volker_E for the feedback! I've implemented everything in the latest patchset, demo here.

@AnneT thank you! This is great. Just last small thing related with the text. In the Overview page we are using "Design Tokens" (capitalized initials) and "design tokens" (no capitalized). Could we unify? Apart from this, I feel we use too long links, could we make them smaller? e.g.:

Using design tokens

Figma
Enable the Codex Design Tokens Figma library in your Figma projects to use all the design tokens that were translated into Figma styles.

NPM package
Learn how to use Codex Design Tokens via the @wikimedia/codex-design-tokens package.

In MediaWiki
Learn how to use Codex Design Tokens in MediaWiki.

Resources

• Read about the definition and structure of the Codex Design Tokens system
• Learn how to contribute or request a new design token

@bmartinezcalvo Thanks for reviewing! I will push a patch to shorten the link text as you specified.

For the capitalization: there are 2 places where "Design Tokens" is capitalized:
1: In menus (the header menu and the sidebar menu)
2: The link to the Figma library

Generally speaking, I think we should not capitalize both words, since design tokens are a general thing and not a name or title, and only capitalize the "D" if it's at the beginning of a sentence or in a menu. So, I think the menus should say "Design tokens".

For the Figma library, I capitalized "Design Tokens" because the title of the Figma library is "Design Tokens". That said, I can change this to "Codex design tokens Figma library" if that seems better - let me know what you think!

In T335087#9090510, @AnneT wrote:

@bmartinezcalvo Thanks for reviewing! I will push a patch to shorten the link text as you specified.

For the capitalization: there are 2 places where "Design Tokens" is capitalized:
1: In menus (the header menu and the sidebar menu)
2: The link to the Figma library

Generally speaking, I think we should not capitalize both words, since design tokens are a general thing and not a name or title, and only capitalize the "D" if it's at the beginning of a sentence or in a menu. So, I think the menus should say "Design tokens".

For the Figma library, I capitalized "Design Tokens" because the title of the Figma library is "Design Tokens". That said, I can change this to "Codex design tokens Figma library" if that seems better - let me know what you think!

@AnneT let's unify with "Design tokens" in all places then. I can update the name of the Figma library.

Change 948655 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Standardize capitalization of "design tokens"

https://gerrit.wikimedia.org/r/948655

Change 948656 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Shorten link text on design tokens overview page

https://gerrit.wikimedia.org/r/948656

@bmartinezcalvo sounds good, thanks! I've pushed a patch to make these changes

Change 948655 merged by jenkins-bot:

[design/codex@main] docs: Standardize capitalization of "design tokens"

https://gerrit.wikimedia.org/r/948655

Change 948656 merged by jenkins-bot:

[design/codex@main] docs: Shorten link text on design tokens overview page

https://gerrit.wikimedia.org/r/948656

Merp, I'm not a big fan of the shortening of the link text for pure aesthetics. In assistive technology the pre-patch link content made more sense, for example for users only switching between links in sections.
First one from

Read about the [definition and structure](./definition-and-structure.html) of the Codex design tokens system)

to

Read about the [definition and structure](./definition-and-structure.html) of the Codex design tokens) system

seems acceptable and might have tamed the looks issue as well.

In T335087#9091327, @AnneT wrote:

@bmartinezcalvo sounds good, thanks! I've pushed a patch to make these changes

Thank you @AnneT. I've updated the name in the Figma library to "Design tokens" to unify with the Codex site. So we will also need to update the Figma library names in all links in the Contribution Guidelines. Maybe we need to create a new task for this.

Change 949555 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v0.16.1 to v0.17.0

https://gerrit.wikimedia.org/r/949555

Test wiki created on Patch demo by ATomasevich (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/6188b4e5fe/w

Change 949586 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Use consistent casing for "design tokens"

https://gerrit.wikimedia.org/r/949586

@bmartinezcalvo I just went ahead and opened a patch to use consistent casing anywhere we say "Design tokens Figma library," let me know if it looks ok!

Change 949555 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.16.1 to v0.17.0

https://gerrit.wikimedia.org/r/949555

Change 949586 merged by jenkins-bot:

[design/codex@main] docs: Use consistent casing for "design tokens"

https://gerrit.wikimedia.org/r/949586

Test wiki on Patch demo by ATomasevich (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/6188b4e5fe/w/

In T335087#9097401, @AnneT wrote:

@bmartinezcalvo I just went ahead and opened a patch to use consistent casing anywhere we say "Design tokens Figma library," let me know if it looks ok!

@AnneT this is perfect now and all names match now in both Figma and Codex site. Thank you!

Change 953351 had a related patch set uploaded (by Catrope; author: Catrope):

[mediawiki/core@master] Update Codex from v0.17.0 to v0.18.0

https://gerrit.wikimedia.org/r/953351

Change 953351 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.17.0 to v0.18.0

https://gerrit.wikimedia.org/r/953351