Merge pull request #1533 from andrewgos/MDS-467-designsystem

[docs] Add documentation on the new design system

Author: andrewnicols

CODEOWNERS

@@ -22,6 +22,9 @@
 /general/app_releases/ @moodle/mobile-developers
 /general/app/ @moodle/mobile-developers
 
+# Design System
+/general/designsystem/ @moodle/design-system
+
 # Content Guideline Owners
 /general/contentguidelines/ @moodle/content-authors
 

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',

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.

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.

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.

sidebars/general.js

@@ -157,6 +157,12 @@ const sidebars = {
             },
         },
     ],
+    designsystem: [
+        {
+            type: 'autogenerated',
+            dirName: 'designsystem',
+        },
+    ],
     contentguidelines: [
         {
             label: 'Content guidelines',