From 674badff2205f8a218e5e867c4f14be15ace92c5 Mon Sep 17 00:00:00 2001 From: Andrew Gosali Date: Mon, 9 Mar 2026 23:36:41 +0700 Subject: [PATCH] [docs] Add documentation on the new design system --- config/navbar.js | 7 ++++++ general/designsystem.md | 19 ++++++++++++++++ general/designsystem/faq.md | 26 ++++++++++++++++++++++ general/designsystem/getting-started.md | 26 ++++++++++++++++++++++ general/designsystem/overview.md | 29 +++++++++++++++++++++++++ sidebars/general.js | 16 ++++++++++++++ 6 files changed, 123 insertions(+) create mode 100644 general/designsystem.md create mode 100644 general/designsystem/faq.md create mode 100644 general/designsystem/getting-started.md create mode 100644 general/designsystem/overview.md diff --git a/config/navbar.js b/config/navbar.js index 33d1f58d61..51ed409fdf 100644 --- a/config/navbar.js +++ b/config/navbar.js @@ -70,6 +70,13 @@ const navbar = { label: 'Moodle App', docsPluginId: 'general', }, + { + type: 'docSidebar', + position: 'left', + sidebarId: 'designsystem', + label: 'Design System', + docsPluginId: 'general', + }, { type: 'docSidebar', position: 'left', diff --git a/general/designsystem.md b/general/designsystem.md new file mode 100644 index 0000000000..27093fd62a --- /dev/null +++ b/general/designsystem.md @@ -0,0 +1,19 @@ +--- +title: Design system +tags: + - Design System +--- + +Welcome to the Moodle Design System documentation. + +This section provides an introduction to the Design System and links to the key resources for working with it. + +If you are new to this area, begin with the overview to understand the Design System foundations, why they are needed, and how they relate to Bootstrap. + +## Suggested reading path + +1. Start with [Overview](./designsystem/overview.md) for context and guiding principles. +2. Continue with [Getting started](./designsystem/getting-started.md) for setup and adoption resources. +3. Check [FAQ](./designsystem/faq.md) for answers to common implementation and rollout questions. + +If you are looking for practical implementation resources, go directly to [Getting started](./designsystem/getting-started.md). diff --git a/general/designsystem/faq.md b/general/designsystem/faq.md new file mode 100644 index 0000000000..27e4c82710 --- /dev/null +++ b/general/designsystem/faq.md @@ -0,0 +1,26 @@ +--- +title: FAQ +sidebar_position: 3 +tags: + - Design System +--- + +## How is the Design System rollout being phased? + +The current phase is focused on defining and rolling out design tokens first. + +Component development is planned as the next phase, with an aim to begin shipping Moodle Design System components in Moodle 5.3. + +## What practical changes in Moodle Core LMS are expected with the introduction of tokens? + +[MDL-87729](https://moodle.atlassian.net/browse/MDL-87729) will determine this. However, variables and hard-coded values in core Moodle themes will likely be replaced or removed to reference the Design System tokens as the living source of truth. + +## Will MoodleHQ adopt the usage of tokens going forward? + +Yes. We aim to use tokens in new feature development where appropriate. + +The Design System team plans to track adoption over time. Updating existing code falls under the responsibility of product owners within Moodle Core LMS, not the Design System team. Consequently, automated checks for code contributions to Moodle Core LMS may change. + +## Does the Design System support the Moodle App or Moodle Workplace? + +Not yet. This includes Moodle Workplace tenant theming. We have not collaborated with these Moodle products, but aim to do so in the future. diff --git a/general/designsystem/getting-started.md b/general/designsystem/getting-started.md new file mode 100644 index 0000000000..218b231306 --- /dev/null +++ b/general/designsystem/getting-started.md @@ -0,0 +1,26 @@ +--- +title: Getting started +sidebar_position: 2 +tags: + - Design System +--- + +Use the resources below to start working with the Moodle Design System. + +## Setup and installation + +Follow the official setup steps in the [GitHub README](https://github.com/moodlehq/design-system#readme). + +## Releases and changelog + +Track published versions and release notes on [GitHub Releases](https://github.com/moodlehq/design-system/releases) and [NPM package](https://www.npmjs.com/package/@moodlehq/design-system). + +## Issues and bug reports + +For issue reporting guidelines and contribution workflow, see [GitHub CONTRIBUTING](https://github.com/moodlehq/design-system/blob/main/.github/CONTRIBUTING.md). + +## Design documentation + +Browse usage guidance and design documentation at [design.moodle.com](https://design.moodle.com). + +Feedback and suggestions for design-related topics can be submitted using the feedback form there. diff --git a/general/designsystem/overview.md b/general/designsystem/overview.md new file mode 100644 index 0000000000..bcd54546ad --- /dev/null +++ b/general/designsystem/overview.md @@ -0,0 +1,29 @@ +--- +title: Overview +sidebar_position: 1 +tags: + - Design System +--- + +## The Moodle Design System + +The Moodle Design System is a shared foundation of design principles, reusable components, and token-based styling rules for building Moodle interfaces across the ecosystem. + +It gives teams one common reference for how UI should look, behave, and scale across products and features, helping interfaces feel consistently Moodle while improving the platform's long-term maintainability. + +## Why a Design System is needed + +Without a Design System, teams face recurring challenges: + +- Design decisions are not centrally defined, so translating design into code often requires repeated interpretation. +- Similar UI patterns have been implemented differently across Moodle features and releases, making consistency harder to maintain. +- Styling values are maintained in multiple places (files, themes, and overrides), increasing maintenance effort and making updates harder to apply consistently. +- As Moodle LMS and its ecosystem grow, teams and contributors need stronger shared foundations to maintain both speed and consistency. + +Design tokens introduce shared, reusable values that help address these challenges. + +## Relationship with Bootstrap + +The Moodle Design System does not aim to replace Bootstrap. It works alongside Bootstrap by defining Moodle-specific design decisions in one place. + +Instead of scattering hardcoded values across different files and components, we aim to maintain an authoritative set of design tokens. Those tokens can then be applied consistently across Bootstrap-based implementations and Moodle UI code. diff --git a/sidebars/general.js b/sidebars/general.js index 21d9b5bd4a..181a125f97 100644 --- a/sidebars/general.js +++ b/sidebars/general.js @@ -157,6 +157,22 @@ const sidebars = { }, }, ], + designsystem: [ + { + label: 'Design system', + type: 'category', + items: [ + { + type: 'autogenerated', + dirName: 'designsystem', + }, + ], + link: { + type: 'doc', + id: 'designsystem', + }, + }, + ], contentguidelines: [ { label: 'Content guidelines',