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
  • Development Tools
  • Coding Standards
• Installation & Usage
  • Prerequisites
  • 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

Development Tools

Key tools for contributing to the design system:

• Code Editor: Any modern editor supporting JavaScript/TypeScript. VSCode is recommended with pre-configured settings in .vscode/ directory. EditorConfig ensures consistent styles across all editors.
• Storybook: Interactive component development and documentation environment.
• Chromatic: Visual regression testing and UI review platform.
• Style Dictionary: Design token management and transformation.
• GitHub Actions: CI/CD pipeline for automated testing and deployment.

Coding Standards

This repository follows these standards:

• Code Quality: ESLint and Prettier for consistent code style.
• Security: OpenSSF Best Practices and OpenSSF Scorecard compliance.
• Commits: Conventional Commits 1.0.0 specification.
• Git Hooks: Husky with lint-staged, pre-commit, and pre-push hooks.
• Testing: Vitest for unit tests, Storybook for component development and interaction testing.
• Accessibility: WCAG 2.2 AA compliance via axe accessibility addon.

Installation & Usage

Prerequisites

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

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 '@moodlehq/design-system/css';

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

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

Fonts

The recommended typeface for Moodle Design System is Roboto. The package does not bundle font files. Provide Roboto in your application:

Option 1: Google Fonts CDN

<link
  href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap"
  rel="stylesheet"
/>

Option 2: Self-hosted Place font files in your project and add @font-face declarations:

@font-face {
  font-family: 'Roboto';
  src: url('./fonts/Roboto-VariableFont_wdth,wght.woff2') format('woff2');
  font-weight: 100 900;
  font-style: normal;
}

@font-face {
  font-family: 'Roboto';
  src: url('./fonts/Roboto-Italic-VariableFont_wdth,wght.woff2') format('woff2');
  font-weight: 100 900;
  font-style: italic;
}

Consuming Tokens Only

The design system supports standalone token integration without components. Tokens are available in both CSS and SCSS formats:

// CSS tokens
import '@moodlehq/design-system/tokens/css';

// SCSS tokens
import '@moodlehq/design-system/tokens/scss';

Note: SCSS tokens use flat values rather than variable references. This is an intentional design decision due to limitations in Style Dictionary's built-in scssVariables formatter, which does not support @use imports for cross-file variable references. While a custom formatter could address this, it would also need to handle proper variable hoisting and sorting, requiring significant ongoing maintenance.

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 GitHub Issue
• 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 for more information.

FAQ

Q: Does this work with Moodle LMS 5.x?
A: We are aiming for integration with Moodle LMS 5.2.

Q: How do I report a bug or request a feature?
A: Please use GitHub Issues to report bugs or request features.

Q: Will my Moodle instance automatically use the latest Design System release?
A: This will depend on the upcoming integration we are looking into. You will likely need to update your Moodle instance once we integrate into LMS.

License

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