The DSG documentation has been copied into this Notion, and I have added comments wherever text or images need to be updated.

On April 17th, the DS design folks will review the DSG sections and decide which sections we want to add. in Codex for this MVP version Once we decide it, we will update the documentation in Notion if needed.

After the meeting with the DS design folks we have decided the following for the DSG documentation in the MVP version of Codex as Wikimedia Design System:

1. Navigation: we will add a ‘Style guide’ section in Codex’s demo site main navigation and we will add the DSG sections there
2. We will add the following DSG sections:
   • Introduction
   • Design Principles
     • Overview
     • Accessibility (just if we have time)
   • Visual style
     • Color, Typography, Icons, - remove references to “paper and ink”
     • Images (we will need to include some example images)
     • Principles page will not be added as a separate page now, but we will add the content from Principles in the other Visual Style sections (e.g. comment about paper ink in Typography)

Next steps: we will update the Notion with the necessary changes and once it's reviewed and ready we will add this sections in Codex. While we update the documentation, we can start creating the new navigable "Style guide" section in the Codex site header.

Moving to In Design to work on the documentation updates in Notion.

@bmartinezcalvo @RHo great, I'm so excited that we're ready to start adding parts of the DSG to the Codex site! Adding a top-level nav item for the Style Guide makes sense.

That said, we're getting to the point where we have a lot of top-level nav items, and the engineers are in the process of adding a new section of developer documentation as well: Composables. These are JavaScript helper functions that offer bits of reusable functionality that can be used in Vue components. They can be used both within Codex and outside of it, by users of Codex. The docs for composables may not be as important as docs for, say, components, but the composable docs should still be readily available somehow.

One idea I had was moving design tokens, components, icons, and the new composables section to a group of nav items under the heading "Toolkit" (or some other word). This would reduce the size of the menu, while still making these sections easily accessible. You can see a demo of this behavior here. What do you think? This would also make it easy to add a "Patterns" section of the site at some point, without further expanding the top-level nav.

Btw, we would not need to do this as part of this task - I just think we should consider it soon since the top-level nav is getting bigger!

In T333437#8786847, @AnneT wrote:

One idea I had was moving design tokens, components, icons, and the new composables section to a group of nav items under the heading "Toolkit" (or some other word). This would reduce the size of the menu, while still making these sections easily accessible. You can see a demo of this behavior here. What do you think? This would also make it easy to add a "Patterns" section of the site at some point, without further expanding the top-level nav.

@AnneT it makes total sense to me. We should start grouping some elements in the header to reduce cognitive load at first glance and also to avoid the header's menu to be too long. For the name of this grouped section, both "Toolkit" or "Demos" make sense to me.

@bmartinezcalvo awesome! I'll go ahead and open a separate task for that to make sure we can get more feedback from the rest of the team and then implement the change. For this task, I'll just add the top-level Style Guide item and the new style guide pages as outlined in the acceptance criteria.

I've created this Google doc with the sections we decided to move to the MVP version:

• Introduction (proposed to rename this section to "Overview" and rewritten with revisions to refer to Wikimedia Codex Design Style guide)
• Design Principles
  • Overview
  • Accessibility (this section will be included in this MVP just if we have enough time before the Hackathon)
• Visual style
  • Color (updated with the new color names)
  • Typography (updated with the new chosen fonts)
  • Icons (included new images to represent how to create icons and suggested other small edits)
  • Images (included an image to represent those concepts)

*Visual Styles > Principles have not been added as page, but I've included some concepts within Colors and Typography.

@RHo @Sarai-WMDE @KieranMcCann @Volker_E I need you to review the Google doc and the suggested edits to decide if we move with this version. Feel free to edit or include new content.

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

[design/codex@main] docs: Add style guide overview and update language around Codex

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

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

[design/codex@main] docs: Add Visual Styles section of the Style Guide

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

The Overview page and Visual Styles section are under code review and available for preview here!

In T333437#8808953, @AnneT wrote:

The Overview page and Visual Styles section are under code review and available for preview here!

Thanks @AnneT! Just chatting with @Volker_E on the doc and think it would make sense to standardise the long name to Wikimedia Codex Design Style guide , but mostly simplify to style guide in the documentation. I've added the copy changes as suggestions in the google doc to (hopefully) make it easier to update.

Change 911929 merged by jenkins-bot:

[design/codex@main] docs: Add style guide overview and update language around Codex

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

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

[design/codex@main] docs: Add Design Principles section of the style guide

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

Design principles section is up: https://914017--wikimedia-codex.netlify.app/style-guide/design-principles-overview.html

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

[design/codex@main] docs: Add link to Phab task template to style guide overview

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

Change 914397 merged by jenkins-bot:

[design/codex@main] docs: Add link to Phab task template to style guide overview

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

In T333437#8817695, @AnneT wrote:

Design principles section is up: https://914017--wikimedia-codex.netlify.app/style-guide/design-principles-overview.html

Thank you @AnneT. Reviewed this section and the others. I leave you some small things to fix:

1. Style Guide > Overview: Remove the link from "statement of purpose" in the first section.

2. Style Guide > Overview > Our process: There are some missing links within "We follow design principles to provide solutions for visual identity, user interface components, and patterns."

3. Style Guide > Overview > Open to participate: Add the right link in "File a task on our workboard"

4. Design Principles > Overview > Open to collaboration: The caption is missing below the image.

5. Design Principles > Overview > Design for consistency: Same, the caption is missing below the image.

6. Visual Styles > Colors > Utility colors: Since white text on yellow600 is not contrasted enough (just 2.02:1) I would use black text for each column of colors (red600, green600 and yellow600).

7. Visual Styles > Typography > Readability > Dynamic text: The caption is missing below the image.

8. Visual Styles > Typography > Typefaces > Platform-specific fonts: There is an error in the CSS code text since InterLato should be simply Inter

9. Visual Styles > Typography > Use of styles: We could create the heading and paragraph styles with code instead. These images are not well readable there.

10. Visual Styles > Icons > Visual style: the values in the current image are not well visible, could we replace with this image?

11. Visual Styles > Images > Image selection: the current image is a bit pixelated and unbalanced with the text, so I've redesigned it. Could we replace it with this new one?

Thanks for the feedback @bmartinezcalvo! Everything should now be fixed except for this one:

In T333437#8822970, @bmartinezcalvo wrote:

9. Visual Styles > Typography > Use of styles: We could create the heading and paragraph styles with code instead. These images are not well readable there.

I'm going to open a separate patch to do this and will let you know when it's ready!

@AnneT the first 2 images in the "Visual Style > Typography" section was using our previous fonts, so I've redesigned these images with Inter and Source Serif Pro. Could you update them in Codex?

@bmartinezcalvo done in the latest patchset; it'll show up on the test site shortly!

In T333437#8833430, @AnneT wrote:

@bmartinezcalvo done in the latest patchset; it'll show up on the test site shortly!

@AnneT great, thank you!!

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

[design/codex@main] docs: Add coded typography example

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

@bmartinezcalvo Text versions of the typography examples are now up for review! https://917391--wikimedia-codex.netlify.app/style-guide/typography.html#use-of-styles

Change 912368 merged by jenkins-bot:

[design/codex@main] docs: Add Visual Styles section of the Style Guide

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

Change 914017 merged by jenkins-bot:

[design/codex@main] docs: Add Design Principles section of the style guide

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

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

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

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

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

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

https://patchdemo.wmflabs.org/wikis/8333e57f25/w/

Change 918598 merged by jenkins-bot:

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

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

Change 917391 merged by jenkins-bot:

[design/codex@main] docs: Add coded typography example

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

In T333437#8822970, @bmartinezcalvo wrote:

In T333437#8817695, @AnneT wrote:

Design principles section is up: https://914017--wikimedia-codex.netlify.app/style-guide/design-principles-overview.html

Thank you @AnneT. Reviewed this section and the others. I leave you some small things to fix:

1. Style Guide > Overview: Remove the link from "statement of purpose" in the first section.

2. Style Guide > Overview > Our process: There are some missing links within "We follow design principles to provide solutions for visual identity, user interface components, and patterns."

3. Style Guide > Overview > Open to participate: Add the right link in "File a task on our workboard"

4. Design Principles > Overview > Open to collaboration: The caption is missing below the image.

5. Design Principles > Overview > Design for consistency: Same, the caption is missing below the image.

6. Visual Styles > Colors > Utility colors: Since white text on yellow600 is not contrasted enough (just 2.02:1) I would use black text for each column of colors (red600, green600 and yellow600).

7. Visual Styles > Typography > Readability > Dynamic text: The caption is missing below the image.

8. Visual Styles > Typography > Typefaces > Platform-specific fonts: There is an error in the CSS code text since InterLato should be simply Inter

9. Visual Styles > Typography > Use of styles: We could create the heading and paragraph styles with code instead. These images are not well readable there.

10. Visual Styles > Icons > Visual style: the values in the current image are not well visible, could we replace with this image?

11. Visual Styles > Images > Image selection: the current image is a bit pixelated and unbalanced with the text, so I've redesigned it. Could we replace it with this new one?

All this has been fixed so the Design sign-off has ben completed.

Change 927786 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[mediawiki/core@master] Update Codex from v0.11.0 to v0.12.0

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

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

Change 927786 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.11.0 to v0.12.0

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

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

https://patchdemo.wmflabs.org/wikis/8ca78d2715/w/

@AnneT as @Sarai-WMDE commented in this other task, we need to update the monospace stack in the Codex Style guide.

In T309158#8917834, @Sarai-WMDE wrote:

Was about to resolve this task, when I noticed that we're not documenting our monospace stack correctly in Codex's Style guide:

This snippet should be updated to

'Menlo', 'Consolas', 'Liberation Mono', 'Fira Code', 'Courier New', monospace;

We should also add the title "Code" before the snippet to improve understanding.

cc: @CCiufo-WMF should we reopen this task to fix it? Or should we create a new one? We also have T338598 to update the Typography styles in the Style guide, maybe we can fix all there.

I think we can do it as part of T338598: Update Typography guidelines in Codex Style guide. Maybe we can move the content from T309158: Update Wikimedia Design Style Guide with typeface choices there and then close it?

A new task was created to capture the specific Monospace update: T338775: Update Monospace stack documentation in Codex's Style guide. I believe T309158: Update Wikimedia Design Style Guide with typeface choices can be closed.