Protocol is a design system for Mozilla and Firefox websites. It establishes a common design language, provides reusable coded components, and outlines high level guidelines for content and accessibility.
Protocol is still an evolving project. Currently, it’s used primarily by the Mozilla Marketing Websites team as the front-end for www.mozilla.org. The long term goal is to provide a robust, unified design system that anyone at Mozilla can use to build an on-brand website.
If you’re interested in using Protocol on your project, let us know and we can help you. You can find us in #protocol-design-system on Mozilla’s Slack (for Mozillians) or in #protocol-design-system on Matrix (open to the public). Also feel free to file an issue on GitHub.
Protocol is built on the Node.js platform and published to NPM, so be sure to have both installed before proceeding.
To use Protocol in your website you can install the core package directly from NPM:
npm install @mozilla-protocol/core --save
Alternatively, you can also download the latest release from GitHub.
Once installed, the relevant CSS, JavaScript, and asset files will be available
in your project under ./node_modules/@mozilla-protocol/core/
.
The core CSS file is bundled as protocol.css
, which contains styling for things
such as basic elements and typography, as well as some global components like
navigation and a footer. Other component and layout CSS is bundled as
protocol-components.css
for convenience.
However, these pre-compiled CSS files include the entire pattern library, which you may not need. We recommend compiling your own styles from the source Sass files, also included in the published package. That allows you to configure Protocol to include just the styles and components you need for each page of your website.
To build Protocol from source and run the documentation site locally, you can clone the repo from GitHub:
$ git clone https://github.com/mozilla/protocol.git
$ cd protocol
$ npm install
Running npm install
will install dependencies. Then:
$ npm run webpack
This will compile the Sass and copy assets into a local folder in preparation to run the server. It also starts a “watch” process that will watch those files and automatically recompile when they change.
In another command line console (and still within the Protocol folder), run:
$ npm start
This will build the site locally and start the development server at http://localhost:3000.
To build the Protocol documentation site for deployment, run:
$ npm run build-docs
We use a Webpack configuration for building the contents of the NPM package ready for publishing. To build the package, run:
npm run build-package
This will install dependencies, lint CSS/JS files, and then build the package
content in the ./package/
directory.
To perform the package build process above and then run front-end JS tests against the processed files:
npm test
Protocol is published to NPM under the @mozilla-protocol/core
namespace/package
name. To publish a release to NPM, use the following steps:
- Before you start make sure the project's CHANGELOG.md is up to date.
- Update the package
version
number in assets/package/package.json (use Semantic Versioning to determine what the new version number should be). - Update the package README assets/package/README.md.
- Update the package
version
number in the root package.json file and then runnpm install
to update thepackage-lock.json
file. - Submit a pull request with your changes (or commit directly to
main
if you have permission). Once the changes have been merged to main: - Tag a new release. You can do this either using Git tag, or directly on the GitHub website.
- Run
npm run build-package && npm test
to run the build script and front-end tests. The package contents will be located in./package/
. - If the build is successful and all tests pass, publish to NPM using
npm publish ./package/
.
Note: the following instructions assume the Mozilla repository is the remote
called origin
.
Each time an updated package is published to NPM, https://protocol.mozilla.org/ should also be updated so the documentation site matches the NPM package features.
- Verify all is good on the staging site.
- Make sure your local
main
branch is up to date. - Push the
main
branch to theprod
branch:git push origin main:prod
.
A notice will be posted in #www-notify on Slack when the push has completed.
For previewing new components before they are merged to main
, two demo instances
are available.
- Push your branch to the
demo1
ordemo2
branches e.g.git push -f origin my-branch-name:demo1
- Your branch will be published:
A notice will be posted in #www-notify on Slack when the push has completed.