Moodle Design System

Welcome! Whether you're a designer or a developer, this guide will help you get started and connect you to the essential resources you need.

The Moodle Design System (MDS) is a comprehensive collection of design and development resources aimed at creating a consistent and efficient user experience across all Moodle products starting with the Core LMS. It includes design assets, guidelines, UI components, and code standards to help teams build cohesive and accessible interfaces.

The MDS is a collaborative effort between designers and developers at Moodle HQ and the wider Moodle community and is continuously evolving to meet the needs of users and to incorporate feedback we receive.

Table of Contents

• Design Resources
  • Design Tools
  • Design Assets & Guidelines
• Development Resources
  • Prerequisites
  • Coding Standards
  • Development Tools
• Installation & Usage
  • Quick Start
  • Convert Tokens From ZeroHeight To CSS Variables
  • Testing The Design System
  • Build The Design System
• CHANGELOG
• Contributing & Support
• FAQ
• License

Design Resources

Design Tools

To create and manage our design assets, we use the following tools:

• Figma: A collaborative design and prototyping tool. It's the heart of the design process, allowing designers to work together seamlessly.
• ZeroHeight: A platform for creating and maintaining design systems. It helps document design guidelines and components for easy access by the team.

Design Assets & Guidelines

All design assets and guidelines are centralized in the following resource:

• Moodle ZeroHeight: The central repository for all design assets, including components, styles, and guidelines.

Development Resources

Prerequisites

• Node.js v22.13.0 or higher
• npm
• Git

Coding Standards

Maintaining a consistent code style is essential for collaborative development. Below are the coding standards we follow and tooling used in this repository:

• ESLint and Prettier configurations are included in the repository to help maintain code quality and consistency.
• Commit messages should follow the Conventional Commits@1.0.0 specification.
• Husky is used to manage Git hooks, ensuring that code quality checks are run before commits and pushes.
  • Lint-staged is used to run linters on staged files, ensuring that only the relevant files are checked before committing.
  • Pre-commit and pre-push hooks are set up to run tests and linters automatically.
• Testing is done using Vitest and Storybook's built-in testing capabilities.
• Storybook is configured to run components against accessibility standards using the axe addon with WCAG 2.1 AA standards.

Development Tools

Your development environment is critical. Here are some tools and resources to help you set up your workspace:

• Code Editor: We recommend using VSCode or any other modern code editor that supports JavaScript/TypeScript development.
  • .editorconfig is included to ensure consistent coding styles across different editors and IDEs.
  • Editor configurations for VSCode are provided in the .vscode/ directory.
• Node.js: Ensure you have version 22.13.0 or higher installed.
• NPM: Used to manage project dependencies.
• Storybook: A tool for developing and showcasing UI components in isolation.
• Chromatic: Used for visual testing and review of UI components.
• Style Dictionary: Used to manage and convert design tokens.
• Git: Make sure you have Git installed and are familiar with its basics.
• Continuous Integration (CI): Configured with GitHub Actions to automate testing and deployment.

Installation & Usage

Quick Start

To view the components in action, you can run Storybook locally. This will allow you to see the components in a live environment.

npm install
npm run storybook

Storybook will provide detailed documentation and interactive examples of all components in the design system however, a quick example is shown below:

import { Button } from '@moodlehq/design-system';

export default function App() {
  return <Button
    label="Button"
    variant="primary"
  />;
}

Convert tokens from ZeroHeight to CSS variables

We make use of Style Dictionary to convert design tokens exported from ZeroHeight into CSS variables that can be used throughout the design system and its consumers.

npm install
npm run build-tokens

Testing the Design System

Various test scripts are available to ensure the quality and reliability of the design system components.

You can run these tests using the following commands:

# Install dependencies.
npm install
npx playwright install
# Run unit tests.
npm run test-unit
# Run unit tests with coverage report.
npm run test-unit-coverage
# Run Storybook interaction & accessibility tests .
npm run test-storybook

Build the Design System

To build the design system, run the following commands in your terminal:

npm install
npm run build

The built files will be located in the dist/ directory.

A CHANGELOG is automatically generated for each release using Release Please

GitHub Actions are set up to automatically build the design system on each push to the main branch that has been tagged with a version number.

CHANGELOG

See CHANGELOG for release history and updates.

Contributing & Support

For any contributions, issues, or support, please reach out to the Moodle HQ Design System team through the following channels:

• Submit a ticket on the MDS project on Moodle Tracker
• Join our Matrix channel
• Join the Moodle Design System PAG course

Pull requests are our suggested method for contributing to the design system. Please ensure that your contributions adhere to our contribution guidelines, see CONTRIBUTING.

FAQ

Q: Does this work with Moodle LMS 5.x?
A: Not yet but soon!.

Q: How do I report a bug or request a feature?
A: Please use the MDS project on Moodle Tracker to report bugs or request features.

Q: Will my Moodle instance automatically use the latest Design System release?
A: No, Moodle core and plugins need to explicitly integrate the design system to use it.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.