McGill Design System (mcgill-ds)

This project contains templates, styles and other resources for the web that adhere to the digital standards of McGill University.

Every release for this repository creates Composer and npm packages that distribute CSS (and related assets like fonts and logos) for use in any project. These assets are also published on unpkg and can be used directly from there in your project.

Changelog

Please see https://gitlab.ncs.mcgill.ca/wsg-public/mcgill-ds/-/blob/main/CHANGELOG.md

Installation

This project is available to install as an npm or composer package. We use our own composer package registry hosted on McGill's GitLab server.

Developers of course can clone this git repository if they want to use the source or create edits or merge requests.

Options

| CSS Options | Description | |---------------------------|--------------------------------------------------------------| | dist/css/mds-scoped.css | Scoped - to avoid conflicts when layering on existing CSS | | dist/css/mds.css | Global - best used for foundational and boilerplate contexts |

To use the Git repository:

See https://gitlab.ncs.mcgill.ca/wsg-public/mcgill-ds/

This repo is public and can be cloned using HTTPS. Cloning with SSH is only possible from within the McGill network, or via the McGill VPN.

To use the Composer package:

composer config repositories.315 composer https://gitlab.example.com/api/v4/group/315/-/packages/composer/
composer require wsg-public/mcgill-ds:VERSION

To use the NPM package:

• Add '@mcgill-wsg/mcgill-ds': 'xxx' (where xxx is your desired version) to your project's package.json file.
• Run npm install

To find ZIP / TAR releases:

See https://gitlab.ncs.mcgill.ca/wsg-public/mcgill-ds/-/releases

Development Tools and Methodologies

This project uses a series of testing strategies and tools to aid development. The main 3 are:

• Storybook for documentation/developing components in isolation
• Jest for unit tests
• Cypress for end-to-end and snapshot testing

Working on this project usually follows a familiar cycle of steps:

• Start Storybook development server. When working on a given component, it's recommended that the development Storybook server be left running so Twig templates can be compiled, CSS can be built and documents updated in real time. Each component should be created or updated in src/components

• Write a unit test. When a given component is ready to be tested (or before, if using test-driven development), a unit test can be written in Jest. See the Jest docs for how to write a Jest unit test, or look in src/components/button/button.test.js for an easy example.

• Write a Cypress test. When a given component is 'done' a Cypress test can be written and added to the suite of Cypress tests that already exist in cypress/integration/. See the Cypress docs for how to write Cypress tests.

The following commands help with each of the above development tasks, and each should be run with the prefix: npm run

| Command | Description | |----------------------|--------------------------------------------------------------------------------------------------------------------------| | dockify:storybook | Storybook development server in Docker (https://localhost:3001) to work on this package and view existing documentation. | | dockify:test:jest | Unit tests (jest/testing-library) against Twig components in Docker. | | dockify:cypress:ci | End-to-end Cypress tests against Storybook in Docker. |

Similar scripts can be found in package.json to run the above tasks outside of Docker, but Docker is preferred as it provides better stability, particularly for Cypress end-to-end and snapshot testing.

Resources

GitLab CI

We use GitLab to host this repository as well as perform our Continuous Integration testing.

This means that for every Merge Request (equivalent to a Pull Request in GitHub) an automated series of tests is run against the new commits.

For instance, the CI 'Pipeline' runs unit tests, Cypress tests, some linting tests and generates some 'artifacts' for review.

If any test fails, the entire pipeline fails and the Merge Request cannot move forward for approval until the problem is fixed.

Merge Requests and Changesets & Releases

This project uses Changesets to help manage versioning and a changeset is required for every Merge Request. Without a changeset the Merge Request will fail and the branch cannot be merged to the Main branch. See the Changesets docs on creating a changeset to include with the MR.

For convenience we have an npm script npm run mr-prep to help with writing a changeset and preparing for a Merge Request.

Hotfixes can be exceptionally created, but that is strongly discouraged.

Additionally, though automated releases handled via Changesets are very useful, sometimes some files may not rise to the status of a release. Files like this README, GitLab CI files etc. As such, a release will not happen unless a package.json file or any 'src/' directory in this repository changes. Finally, if package.json or 'src/' does change, but does not merit a release for some reason, an empty changeset can be created which will prevent a version bump and so prevent a tag and release. Such an empty changeset can be created like this: npx changeset --empty

Storybook

Storybook https://storybook.js.org can be run locally, allowing you to see all of the documented components in one place (useful if you want to work with them!), offering you the chance to see each one in isolation.

The latest version of the Storybook instance is also published publicly to https://docs.designsystem.mcgill.ca/

Icons & Ionicons

This package and the McGill Design System in general use icons from the open-source project Ionicons.

Invision

The McGill Invision app is our designs teams tool to inform what is provided in McGill-DS. Invision also has a handy inspect tool