| name | codex-style-guide |
| description | The Wikimedia / Codex Style Guide — the design-decision companion to the Codex toolkit. Covers the four design principles (Design with Others, For Curious Humans, Trustworthy, Content First), accessibility, bidirectionality, visual styles (colour usage, typography/readability, icon design, images, illustrations, data visualization), layout guidelines (links vs buttons, forms, content overflow), and content guidelines (voice & tone, writing for copy, machine assistance). Use when making a UX call ("dialog or inline edit?"), choosing colours/type/imagery, laying out a form, writing UI copy, labelling AI-assisted output, or sanity-checking a design. |
| license | MIT |
Codex style guide
This is the design half of Codex — what to design and why. The
toolkit half — what's available and how to call it — lives in
codex-tokens,
codex-components, and
codex-icons;
codex-usage is the practical entry point
that ties them together.
It mirrors the four areas of the upstream Style Guide: Design
Principles, Visual Styles, Layout Guidelines, and Content
Guidelines. Canonical:
https://doc.wikimedia.org/codex/latest/style-guide/design-principles-overview.html.
Everything descends from the Statement of Purpose: "we design with
and for curious humans who rely on trustworthy content."
(https://doc.wikimedia.org/codex/latest/style-guide/statement-of-purpose.html)
The four design principles
Reach for these when you're unsure which of two options to ship.
1. Design with Others
Collaborate openly; include ideas and perspectives beyond your own.
- Is this design the outcome of collaboration?
- Did we listen to and learn from people with different backgrounds?
- Have we learned from the target audience that their needs are met?
2. For Curious Humans
Welcome a universal audience and remove barriers to knowledge.
- Is this design accessible, inclusive, and equitable?
- Does it allow for adaptability based on the person's preferences?
- Is there opportunity for wonder in the experience?
Practical heuristics:
- A reader's primary job is to read; an editor's is to edit.
Each feature should make the primary job easier, not interrupt it.
- Prefer inline affordances over modal flows where reasonable.
- Use progressive disclosure — a few common actions up front,
secondary ones in an overflow menu.
3. Trustworthy
Enable sharing and understanding of trustworthy knowledge while
protecting privacy.
- Are we minimizing the data we collect (in the design and the
process to create it)?
- Are we communicating information explicitly and honestly?
- Does it help users confidently access and share well-sourced,
reliable knowledge?
Show provenance for machine-assisted output rather than hiding it — see
references/machine-assistance.md.
4. Content First
Keep content at the centre; facilitate its comprehension and use.
- Is this prioritizing the most contextually important information?
- Is the content presented in a way that supports clear understanding?
- Does it make it easy to learn from, improve, and share content?
Corollary: minimise chrome. The content is the product — anything
beyond it competes for attention. When in doubt, be conservative; a
non-feature beats a noisy one.
Accessibility & bidirectionality
- Accessibility — aim for WCAG AA: never colour-alone, 4.5:1 / 3:1
contrast, keep focus rings, text alternatives, semantic markup. Detail:
references/accessibility.md.
- Bidirectionality — mirror layout/navigation/directional icons for
RTL; don't mirror URLs, numerals, time, check marks, media, or images.
Per-element rules:
references/bidirectionality.md.
Visual styles
- Colour usage — what colours mean, never-colour-alone, contrast:
references/colors.md.
- Typography — every piece of text uses one of the 9 canonical
styles; that rule has its own skill,
codex-typography. Residual readability
(line length, dynamic text):
references/typography.md.
- Icon design — reduce to essential, universal, neutral, geometric,
20 dp, RTL:
references/icons.md.
- Images — editorial selection:
references/images.md.
- Illustrations — empty states / onboarding, stroke & colour rules:
references/illustrations.md.
- Data visualization — chart anatomy, choosing a chart, palettes,
a11y symbols:
references/data-visualization.md.
Layout guidelines
Content guidelines
How the words in the UI should read, and how to disclose machine output.
Applying these in a design review
Before you call a piece of work done, walk through this checklist:
Upstream sources
