зеркало из https://github.com/mozilla/protocol.git
Update contributing doc, add usage docs, general doc tidying (#807)
Co-authored-by: Reem H <42309026+reemhamz@users.noreply.github.com>
This commit is contained in:
Craig Cook
GitHub
Родитель
0c6e24bb06
Коммит
dc55263fdd
144
README.md
144
README.md
|
|
@ -1,12 +1,21 @@
|
|||
# Protocol
|
||||
# Mozilla Protocol
|
||||
|
||||
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 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.
|
||||
|
||||
https://protocol.mozilla.org/
|
||||
|
||||
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](https://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.
|
||||
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](https://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](https://chat.mozilla.org/) (open to the public). Also feel free to [file an issue on GitHub](https://github.com/mozilla/protocol/issues).
|
||||
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](https://chat.mozilla.org/)
|
||||
(open to the public). Also feel free to
|
||||
[file an issue on GitHub](https://github.com/mozilla/protocol/issues).
|
||||
|
||||
|
||||
|
||||
|
|
@ -14,44 +23,141 @@ If you’re interested in using Protocol on your project, let us know and we can
|
|||
|
||||
## Getting Started
|
||||
|
||||
Protocol is built on the [Node.js](https://nodejs.org/) platform and published to [NPM](https://www.npmjs.com/), so be sure to have both installed before proceeding.
|
||||
Protocol is built on the [Node.js](https://nodejs.org/) platform and published
|
||||
to [NPM](https://www.npmjs.com/), so be sure to have both installed before
|
||||
proceeding.
|
||||
|
||||
## Installation
|
||||
|
||||
To use Protocol in your website you can install the core package directly from NPM:
|
||||
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](https://github.com/mozilla/protocol/releases/latest) from GitHub.
|
||||
Alternatively, you can also [download the latest release](https://github.com/mozilla/protocol/releases/latest)
|
||||
from GitHub.
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, the relevant CSS and JS files will be available in your project under `./node_modules/@mozilla-protocol/core/`.
|
||||
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. Component and layout CSS is bundled as `protocol-components.scss` for convenience.
|
||||
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.
|
||||
|
||||
**Note**: The original source (.scss) files are also included in the published package. You may want to consider compiling your own CSS to include only what you need for each page of your website, in order to further optimize for performance.
|
||||
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.
|
||||
|
||||
## Building From Source
|
||||
## Make it Run
|
||||
|
||||
To build Protocol from source including the documentation site, you can clone the repo from GitHub:
|
||||
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-docs
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Running `npm start` will install dependencies, build your toolkit, and start the development server at <http://localhost:3000>.
|
||||
This will build the site locally and start the development server at
|
||||
<http://localhost:3000>.
|
||||
|
||||
## Further Documentation
|
||||
## Building the website
|
||||
|
||||
- [Project Structure](docs#project-structure)
|
||||
- [Build Process](docs#build-process)
|
||||
- [Publishing](docs#publishing-to-npm)
|
||||
- [Deployment](docs#deployment)
|
||||
- [Acknowledgements](docs#acknowledgements)
|
||||
To build the Protocol documentation site for deployment, run:
|
||||
|
||||
```
|
||||
$ npm run build-docs
|
||||
```
|
||||
|
||||
## Building the NPM package
|
||||
|
||||
We use a [Webpack](https://webpack.js.org/) 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.
|
||||
|
||||
## Running tests
|
||||
|
||||
To perform the package build process above and then run front-end JS tests against
|
||||
the processed files:
|
||||
|
||||
```
|
||||
npm test
|
||||
```
|
||||
|
||||
## Publishing to NPM
|
||||
|
||||
Protocol is published to NPM under the `@mozilla-protocol/core` namespace/package
|
||||
name. To publish a release to NPM, use the following steps:
|
||||
|
||||
1. Before you start make sure the project's [CHANGELOG.md](https://github.com/mozilla/protocol/blob/main/CHANGELOG.md)
|
||||
is up to date.
|
||||
2. Update the package `version` number in [assets/package/package.json](https://github.com/mozilla/protocol/blob/main/assets/package/package.json)
|
||||
(use [Semantic Versioning](https://semver.org/) to determine what the new version number
|
||||
should be).
|
||||
3. Update the package README [assets/package/README.md](https://github.com/mozilla/protocol/blob/main/assets/package/README.md).
|
||||
4. Run `npm install` to update the package-lock.json file.
|
||||
5. Submit a pull request with your changes (or commit directly to `main` if you
|
||||
have permission). Once the changes have been merged to main:
|
||||
6. Tag a new release. You can do this either using [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging),
|
||||
or directly on the [GitHub website](https://github.com/mozilla/protocol/releases/latest).
|
||||
7. Run `npm test` to run the build script and front-end tests. The package contents
|
||||
will be located in `./package/`.
|
||||
8. If the build is successful and all tests pass, publish to NPM using `npm publish ./package/`.
|
||||
|
||||
## Deployment
|
||||
|
||||
Note: the following instructions assume the Mozilla repository is the remote
|
||||
called `origin`.
|
||||
|
||||
### Pushing to production
|
||||
|
||||
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.
|
||||
|
||||
1. Verify all is good on the [staging site](https://protocol-stage.moz.works/).
|
||||
2. Make sure your local `main` branch is up to date.
|
||||
3. Push the `main` branch to the `prod` branch: `git push origin main:prod`.
|
||||
|
||||
A notice will be posted in #www-notify on Slack when the push has completed.
|
||||
|
||||
### Pushing to demo
|
||||
|
||||
For previewing new components before they are merged to `main`, two demo instances
|
||||
are available.
|
||||
|
||||
1. Push your branch to the `demo1` or `demo2` branches e.g.
|
||||
`git push -f origin my-branch-name:demo1`
|
||||
2. Your branch will be published:
|
||||
- https://demo1--mozilla-protocol.netlify.com/
|
||||
- https://demo2--mozilla-protocol.netlify.com/
|
||||
|
||||
A notice will be posted in #www-notify on Slack when the push has completed.
|
||||
|
|
|
|||
|
|
@ -9,20 +9,32 @@ The components, pages, and websites we create should be:
|
|||
|
||||
### Meaningful
|
||||
|
||||
Design should reinforce the meaning of content, not distract from it. We prioritize worthwhile communication over decoration. If an aspect of the design doesn’t enhance the content, we should remove it.
|
||||
Design should reinforce the meaning of content, not distract from it. We prioritize
|
||||
worthwhile communication over decoration. If an aspect of the design doesn’t
|
||||
enhance the content, we should remove it.
|
||||
|
||||
### Flexible
|
||||
|
||||
Our designs must adapt to changing conditions. Components in this design system should accommodate some unpredictability and not impose too many restrictions. There will be different types and amounts of content, different window sizes, and different layouts. Choose flexibility over precision.
|
||||
Our designs must adapt to changing conditions. Components in this design system
|
||||
should accommodate some unpredictability and not impose too many restrictions.
|
||||
There will be different types and amounts of content, different window sizes, and
|
||||
different layouts. Choose flexibility over precision.
|
||||
|
||||
### Accessible to all
|
||||
|
||||
We create sites to welcome the widest possible audience, free of obstacles. Be mindful of the broad range of human abilities and disabilities, as well as the variety of devices, browsers, and networks people use to access our sites.
|
||||
We create sites to welcome the widest possible audience, free of obstacles. Be
|
||||
mindful of the broad range of human abilities and disabilities, as well as the
|
||||
variety of devices, browsers, and networks people use to access our sites.
|
||||
|
||||
### Global
|
||||
|
||||
Our sites serve a global audience and should translate well across nations, cultures, and languages. Green might not always mean go, symbols and idioms have very different meanings to different people, fonts and text will vary and reflow. Plan for a wide reach and design for localization.
|
||||
Our sites serve a global audience and should translate well across nations,
|
||||
cultures, and languages. Green might not always mean go, symbols and idioms have
|
||||
very different meanings to different people, fonts and text will vary and reflow.
|
||||
Plan for a wide reach and design for localization.
|
||||
|
||||
### Useful
|
||||
|
||||
We strive to meet the real needs of the people visiting our sites. At the same time we must meet our own needs as site creators. Any component in this design system should prove useful or it doesn’t belong here.
|
||||
We strive to meet the real needs of the people visiting our sites. At the same
|
||||
time we must meet our own needs as site creators. Any component in this design
|
||||
system should prove useful or it doesn’t belong here.
|
||||
|
|
|
|||
|
|
@ -5,31 +5,47 @@ name: Brand Themes
|
|||
|
||||
Protocol supports two distinct brands: Mozilla and Firefox.
|
||||
|
||||
The Mozilla brand is distinguished by the Zilla Slab typeface and a limited color palette, mostly black and white. The Firefox brand uses the Metropolis typeface and is generally more colorful overall.
|
||||
The Mozilla brand is distinguished by the Zilla Slab typeface and a limited color
|
||||
palette, mostly black and white. The Firefox brand uses the Metropolis typeface
|
||||
and is generally more colorful overall.
|
||||
|
||||
Our CSS framework achieves the different themes by assigning variables to several style properties, then drawing from different sets of variables to apply different styling based on which brand is represented on the page. These variables are collected into maps and we then use functions in SCSS to swap to a different map based on a single theme variable:
|
||||
Our CSS framework achieves the different themes by assigning variables to several
|
||||
style properties, then drawing from different sets of variables to apply different
|
||||
styling based on which brand is represented on the page. These variables are
|
||||
collected into maps and we then use functions in SCSS to swap to a different map
|
||||
based on a single theme variable:
|
||||
|
||||
```scss
|
||||
$brand-theme: 'mozilla';
|
||||
```
|
||||
(Note: this kind of theming is also possible with [custom properties in native CSS](https://developer.mozilla.org/docs/Web/CSS/--*), but Protocol still needs to support older browsers so we use SCSS variables.)
|
||||
|
||||
Protocol defaults to the Mozilla brand “out of the box.” If you use the packaged, pre-compiled CSS, you’ll have everything you need for a Mozilla-branded website without needing to compile the SCSS yourself. We still recommend doing your own compiling so you can import just the components you need.
|
||||
(Note: this kind of theming is also possible with [custom properties in native CSS](https://developer.mozilla.org/docs/Web/CSS/--*),
|
||||
but Protocol still needs to support older browsers so we use Sass variables, at
|
||||
least for now.)
|
||||
|
||||
If you want to produce a Firefox-branded website you'll need to compile the Protocol SCSS and change the `$brand-theme` variable:
|
||||
Protocol defaults to the Mozilla brand “out of the box.” If you use the packaged,
|
||||
pre-compiled CSS, you’ll have everything you need for a Mozilla-branded website
|
||||
without needing to compile the Sass yourself. We still recommend doing your own
|
||||
compiling so you can import just the components you need.
|
||||
|
||||
If you want to produce a Firefox-branded website you’ll need to compile the
|
||||
Protocol Sass and change the `$brand-theme` variable:
|
||||
|
||||
```scss
|
||||
$brand-theme: 'firefox';
|
||||
```
|
||||
|
||||
- [An example of the Mozilla theme](/demos/theme-mozilla.html)
|
||||
- [An example of the Firefox theme](/demos/theme-firefox.html)
|
||||
|
||||
## Type scales
|
||||
|
||||
Protocol uses a modular type scale with a range of predefined font sizes to maintain consistency and avoid sizing text willy nilly in designs. Scale sizes and line heights are defined as part of the brand theme, and each brand has a slightly different scale. [See our page on Typography](/fundamentals/typography.html#type-scale) for more info and examples.
|
||||
Protocol uses a modular type scale with a range of predefined font sizes to maintain
|
||||
consistency and avoid sizing text willy nilly in designs. Scale sizes and line
|
||||
heights are defined as part of the brand theme, and each brand has a slightly
|
||||
different scale. [See our page on Typography](/fundamentals/typography.html#type-scale)
|
||||
for more info and examples.
|
||||
|
||||
Additionally, there are two different scales available: a standard scale with large titles, appropriate for most general websites (like marketing sites, blogs, etc) and a condensed scale with smaller sizes more suitable for web applications.
|
||||
Additionally, there are two different scales available: a standard scale with
|
||||
large titles, appropriate for most general websites (like marketing sites, blogs,
|
||||
etc) and a condensed scale with smaller sizes more suitable for web applications.
|
||||
|
||||
Protocol defaults to the standard (big titles) type scale:
|
||||
|
||||
|
|
@ -37,7 +53,8 @@ Protocol defaults to the standard (big titles) type scale:
|
|||
$type-scale: 'standard';
|
||||
```
|
||||
|
||||
You can activate the condensed type scale by setting a variable when you compile the SCSS:
|
||||
You can activate the condensed type scale by setting a variable when you compile
|
||||
the Sass:
|
||||
|
||||
```scss
|
||||
$type-scale: 'condensed';
|
||||
|
|
@ -45,12 +62,18 @@ $type-scale: 'condensed';
|
|||
|
||||
## Component themes
|
||||
|
||||
In addition to the global themes for brand and type scale, we have a few standard component-level theming classes you can use. Smaller components intended to appear in groups (like Cards and Pictos) shouldn't be themed individually, but can appear in a larger container with the theme class applied to the entire group.
|
||||
In addition to the global themes for brand and type scale, we have a few standard
|
||||
component-level theming classes you can use. Smaller components intended to appear
|
||||
in groups (like Cards and Pictos) shouldn't be themed individually, but can appear
|
||||
in a larger container with the theme class applied to the entire group.
|
||||
|
||||
### Dark theme
|
||||
|
||||
Many components have an inverse color variant that applies a dark background color with light foreground colors, invoked with the `mzp-t-dark` theme class.
|
||||
Many components have an inverse color variant that applies a dark background color
|
||||
with light foreground colors, invoked with the `mzp-t-dark` theme class.
|
||||
|
||||
### Section backgrounds
|
||||
|
||||
There's a basic `mzp-t-background-alt` class that applies a secondary background color to most elements or components, especially useful for alternating sections of a page.
|
||||
There’s a basic `mzp-t-background-alt` class that applies a secondary background
|
||||
color to most elements or components, especially useful for alternating sections
|
||||
of a page.
|
||||
|
|
|
|||
|
|
@ -5,13 +5,18 @@ title: Typography
|
|||
## Typefaces
|
||||
Protocol comes with three fonts: Zilla Slab, Metropolis, and Inter.
|
||||
|
||||
Mozilla branded websites use Zilla Slab for titles and Inter for body text. Don't use Zilla Slab for body text.
|
||||
Mozilla branded websites use Zilla Slab for titles and Inter for body text. Don’t
|
||||
use Zilla Slab for body text.
|
||||
|
||||
Firefox branded websites use Metropolis for titles and Inter for body text. Don't use Metropolis for body text.
|
||||
Firefox branded websites use Metropolis for titles and Inter for body text. Don’t
|
||||
use Metropolis for body text.
|
||||
|
||||
### Inter
|
||||
|
||||
Inter is an open source, sans-serif font designed by [Rasmus Andersson](https://rsms.me/inter/). This is our standard type face for body copy in both Firefox and Mozilla brands. If you need to declare it specifically (such as to override some other inherited font) you can use the mixin `@include font-base;`.
|
||||
Inter is an open source, sans-serif font designed by [Rasmus Andersson](https://rsms.me/inter/).
|
||||
This is our standard type face for body copy in both Firefox and Mozilla brands.
|
||||
If you need to declare it specifically (such as to override some other inherited
|
||||
font) you can use the mixin `@include font-base;`.
|
||||
|
||||
* [Download from https://rsms.me/inter/](https://rsms.me/inter/)
|
||||
|
||||
|
|
@ -27,13 +32,20 @@ Inter is an open source, sans-serif font designed by [Rasmus Andersson](https://
|
|||
|
||||
### Zilla Slab</h3>
|
||||
|
||||
Zilla Slab is our custom typeface for the Mozilla brand. We use it for our wordmark and as a display font for headlines on Mozilla branded sites. It’s a contemporary slab serif based on Typotheque’s Tesla. Zilla Slab is a free, open source font available for download.
|
||||
Zilla Slab is our custom typeface for the Mozilla brand. We use it for our wordmark
|
||||
and as a display font for headlines on Mozilla branded sites. It’s a contemporary
|
||||
slab serif based on Typotheque’s Tesla. Zilla Slab is a free, open source font
|
||||
available for download.
|
||||
|
||||
Zilla Slab is primarily a display font and should only be used on large text like headings. As a general rule, type set in Zilla Slab should stand out. Avoid stacking two sizes of Zilla Slab one on top of the other. Pair headings in Zilla Slab with subheadings in Inter.
|
||||
Zilla Slab is primarily a display font and should only be used on large text like
|
||||
headings. As a general rule, type set in Zilla Slab should stand out. Avoid
|
||||
stacking two sizes of Zilla Slab one on top of the other. Pair headings in Zilla
|
||||
Slab with subheadings in Inter.
|
||||
|
||||
You can declare Zilla Slab explicitly with the mixin `@include font-mozilla;`.
|
||||
|
||||
Don't italicize Zilla Slab. Protocol only includes regular and bold versions of this font.
|
||||
Don’t italicize Zilla Slab. Protocol only includes regular and bold versions of
|
||||
this font.
|
||||
|
||||
* [Download from Github](https://github.com/mozilla/zilla-slab/releases/latest)
|
||||
* [Use on Google Fonts](https://fonts.google.com/specimen/Zilla+Slab)
|
||||
|
|
@ -51,13 +63,19 @@ Don't italicize Zilla Slab. Protocol only includes regular and bold versions of
|
|||
|
||||
### Metropolis
|
||||
|
||||
Metropolis is a free, open source font used for headlines on marketing and product web experiences. It's a geometric sans-serif font by Chris Simpson, very similar in style and character to Firefox Sharp Sans, the proprietary font used to create logo lockups for Firefox products (**do not use Firefox Sharp Sans as a webfont**).
|
||||
Metropolis is a free, open source font used for headlines on marketing and product
|
||||
web experiences. It’s a geometric sans-serif font by Chris Simpson, very similar
|
||||
in style and character to Firefox Sharp Sans, the proprietary font used to create
|
||||
logo lockups for Firefox products (**do not use Firefox Sharp Sans as a webfont**).
|
||||
|
||||
Use Metropolis for large text like headings. As a general rule, type set in Metroplis should stand out. Avoid stacking two sizes of Metropolis one on top of the other. Pair headings in Metropolis with subheadings in Inter.
|
||||
Use Metropolis for large text like headings. As a general rule, type set in
|
||||
Metroplis should stand out. Avoid stacking two sizes of Metropolis one on top of
|
||||
the other. Pair headings in Metropolis with subheadings in Inter.
|
||||
|
||||
You can declare Metropolis explicitly with the mixin `@include font-firefox;`.
|
||||
|
||||
Don't italicize Metropolis. Protocol only includes regular and bold versions of this font.
|
||||
Don’t italicize Metropolis. Protocol only includes regular and bold versions of
|
||||
this font.
|
||||
|
||||
* [Download from Fonts Arena](https://fontsarena.com/metropolis-by-chris-simpson/)
|
||||
|
||||
|
|
@ -73,7 +91,8 @@ Don't italicize Metropolis. Protocol only includes regular and bold versions of
|
|||
|
||||
## Type Scale
|
||||
|
||||
We limit the number of text sizes to a predetermined set, to maintain consistency and avoid sizing text willy nilly in designs.
|
||||
We limit the number of text sizes to a predetermined set, to maintain consistency
|
||||
and avoid sizing text willy nilly in designs.
|
||||
|
||||
<div id="specimen-type-scale" class="docs-specimen">
|
||||
<span class="docs-scale-sample docs-scale-sample-title-2xl">Title 2XL</span>
|
||||
|
|
@ -91,20 +110,30 @@ We limit the number of text sizes to a predetermined set, to maintain consistenc
|
|||
<span class="docs-scale-sample docs-scale-sample-body-xs">Body XS</span>
|
||||
</div>
|
||||
|
||||
The title sizes are 3XS through 2XL. Of these, the most commonly used are SM, MD, LG, and XL. Use the XS, 2XS, and 3XS title sizes sparingly for labels and UI elements, and the 2XL title size sparingly to make an especially bold statement.
|
||||
The title sizes are 3XS through 2XL. Of these, the most commonly used are SM, MD,
|
||||
LG, and XL. Use the XS, 2XS, and 3XS title sizes sparingly for labels and UI
|
||||
elements, and the 2XL title size sparingly to make an especially bold statement.
|
||||
|
||||
We use three sizes of regular body copy: MD, LG and XL. Use MD for normal, default body text and LG when you need slightly larger text to stand out, like the introduction to an article. The XL body size is useful for taglines or subtitles, but not for long passages of text. There are two sizes of smaller body text: SM and XS, used sparingly for supporting text like footnotes or disclaimers, never for main body copy.
|
||||
We use three sizes of regular body copy: MD, LG and XL. Use MD for normal, default
|
||||
body text and LG when you need slightly larger text to stand out, like the
|
||||
introduction to an article. The XL body size is useful for taglines or subtitles,
|
||||
but not for long passages of text. There are two sizes of smaller body text: SM
|
||||
and XS, used sparingly for supporting text like footnotes or disclaimers, never
|
||||
for main body copy.
|
||||
|
||||
### Themes
|
||||
|
||||
Protocol includes different branded themes for Mozilla and Firefox, and each theme uses different fonts with a slightly altered scale. Titles set in Zilla Slab for the Mozilla brand are slightly larger than their Firefox equivalents, adjusting for Zilla Slab being overall a smaller display font.
|
||||
|
||||
* [Mozilla theme type scale](#todo)
|
||||
* [Firefox theme type scale](#todo)
|
||||
Protocol includes different branded themes for Mozilla and Firefox, and each theme
|
||||
uses different fonts with a slightly altered scale. Titles set in Zilla Slab for
|
||||
the Mozilla brand are slightly larger than their Firefox equivalents, adjusting
|
||||
for Zilla Slab being overall a smaller display font.
|
||||
|
||||
### Condensed Type Scale
|
||||
|
||||
As you can see above, the standard Protocol type scale features big sizes for headings and titles appropriate for most general websites (like marketing sites, blogs, etc). Protocol also includes an alternative, condensed scale with smaller sizes more suitable for web applications.
|
||||
As you can see above, the standard Protocol type scale features big sizes for
|
||||
headings and titles appropriate for most general websites (like marketing sites,
|
||||
blogs, etc). Protocol also includes an alternative, condensed scale with smaller
|
||||
sizes more suitable for web applications.
|
||||
|
||||
<div id="specimen-type-scale-condensed" class="docs-specimen">
|
||||
<span class="docs-scale-sample docs-scale-sample-title-2xl">Title 2XL</span>
|
||||
|
|
@ -124,7 +153,7 @@ As you can see above, the standard Protocol type scale features big sizes for he
|
|||
|
||||
### Code
|
||||
|
||||
We use SCSS mixins to declare these font sizes:
|
||||
We use Sass mixins to declare these font sizes:
|
||||
|
||||
```scss
|
||||
@include text-title-2xl;
|
||||
|
|
@ -142,6 +171,12 @@ We use SCSS mixins to declare these font sizes:
|
|||
@include text-body-xs;
|
||||
```
|
||||
|
||||
Those mixins include media queries to adjust the sizes at key breakpoints. Text gets bigger as the viewport gets bigger. You can resize your window to see this in action on the samples above or on the [demo page](#todo).
|
||||
Those mixins include media queries to adjust the sizes at key breakpoints. Text
|
||||
gets bigger as the viewport gets bigger. You can resize your window to see this
|
||||
in action on the samples above or on most of our components.
|
||||
|
||||
The sizing mixins in turn use another mixin to convert a pixel size to <code>rem</code> for output, assuming a 16px root size (the default in graphical browsers). Because we use <code>rem</code> for font sizing all of our declared sizes are really just suggestions and the end user can resize as they see fit. Text sizes are always variable so design accordingly.
|
||||
The sizing mixins in turn use another mixin to convert a pixel size to `rem` for
|
||||
output, assuming a 16px root size (the default in graphical browsers). Because
|
||||
we use `rem` for font sizing all of our declared sizes are really just suggestions
|
||||
and the end user can resize as they see fit. Text sizes are always variable so
|
||||
design accordingly.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,9 @@
|
|||
status: draft
|
||||
---
|
||||
|
||||
Colors are defined as named tokens so they can be consistent throughout Protocol. When using these colors in CSS, use the token rather than the hex value. Avoid using colors outside this palette unless you have a good reason.
|
||||
Colors are defined as named tokens so they can be consistent throughout Protocol.
|
||||
When using these colors in Sass, use the token variable rather than the hex value.
|
||||
Avoid using colors outside this palette unless you have a good reason.
|
||||
|
||||
{{#each palettes}}
|
||||
<h2 class="docs-palette-title">{{ @key }}</h2>
|
||||
|
|
|
|||
|
|
@ -1,11 +1,7 @@
|
|||
---
|
||||
status: draft
|
||||
---
|
||||
|
||||
[Design tokens](https://medium.com/eightshapes-llc/25dd82d58421) are named entities
|
||||
that store visual design information. These are used in place of hard-coded values
|
||||
(such as hex values for color or pixels for spacing) in order to maintain a scalable,
|
||||
consistent system for UI development.
|
||||
(such as hex values for color or pixels for spacing) in order to maintain a
|
||||
scalable, consistent system for UI development.
|
||||
|
||||
## Border radii
|
||||
|
||||
|
|
@ -52,11 +48,17 @@ equivalent to the tokens `$color-ink-90`, `$color-blue-90`, and `$color-ink-90`.
|
|||
</tbody>
|
||||
</table>
|
||||
|
||||
## Colors
|
||||
|
||||
Protocol has a broad coloe palette, each with a token variable. See the
|
||||
[Color page](/docs/fundamentals/color) for the complete list.
|
||||
|
||||
## Spacing units
|
||||
|
||||
Protocol has two types of tokens used for spacing units (margins and padding). The `$spacing-*`
|
||||
tokens are smaller and generally intended for tighter spacing within components. The `$layout-*`
|
||||
tokens are larger and intended for more generous spaces between components.
|
||||
Protocol has two types of tokens used for spacing units (margins and padding).
|
||||
The `$spacing-*` tokens are smaller and generally intended for tighter spacing
|
||||
within components. The `$layout-*` tokens are larger and intended for more
|
||||
generous spaces between components.
|
||||
|
||||
<table class="docs-tokens-table">
|
||||
<thead>
|
||||
|
|
@ -79,9 +81,9 @@ tokens are larger and intended for more generous spaces between components.
|
|||
|
||||
## Content widths
|
||||
|
||||
These are used to set the width of various content containers at different responsive
|
||||
breakpoints. They’re based on common device screen widths with some allowances for outer
|
||||
margins between the content and viewport edge.
|
||||
These are used to set the width of various content containers at different
|
||||
responsive breakpoints. They’re based on common device screen widths with some
|
||||
allowances for outer margins between the content and viewport edge.
|
||||
|
||||
<table class="docs-tokens-table">
|
||||
<thead>
|
||||
|
|
@ -104,8 +106,8 @@ margins between the content and viewport edge.
|
|||
|
||||
## Screen widths
|
||||
|
||||
These are used in media queries to set breakpoints at which layouts can adjust to
|
||||
fit different devices and browser windows.
|
||||
These are used in media queries to set breakpoints at which layouts can adjust
|
||||
to fit different devices and browser windows.
|
||||
|
||||
<table class="docs-tokens-table">
|
||||
<thead>
|
||||
|
|
@ -171,8 +173,8 @@ Usage: `@media #{$mq-md} { ... }`
|
|||
</table>
|
||||
|
||||
The font name "X-LocaleSpecific" can be used as an alias to define an alternative
|
||||
font for specific languages, especially those with non-Latin alphabets. For example,
|
||||
in a style sheet served only to pages in Arabic:
|
||||
font for specific languages, especially those with non-Latin alphabets. For
|
||||
example, in a style sheet served only to pages in Arabic:
|
||||
|
||||
```scss
|
||||
@font-face {
|
||||
|
|
|
|||
|
|
@ -1,11 +1,49 @@
|
|||
---
|
||||
title: Using Protocol
|
||||
title: Using Protocol on Your Website
|
||||
label: Overview
|
||||
status: draft
|
||||
---
|
||||
|
||||
How to use Protocol on your website.
|
||||
Protocol is built on the [Node.js](https://nodejs.org/) platform and published
|
||||
as an [NPM package](https://www.npmjs.com/package/@mozilla-protocol/core), so be
|
||||
sure to have both installed before proceeding.
|
||||
|
||||
It's an NPM package. Add it as a dependency in a package.json file.
|
||||
## Installation
|
||||
|
||||
It uses Sass (in SCSS format) so you'll need a compiler.
|
||||
To use Protocol in your website with minimal fuss you can install the core package
|
||||
directly from NPM:
|
||||
|
||||
```
|
||||
npm install @mozilla-protocol/core --save
|
||||
```
|
||||
|
||||
Alternatively, you can also [download the latest release](https://github.com/mozilla/protocol/releases/latest)
|
||||
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
|
||||
may be a lot more than you need 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.
|
||||
|
||||
## Compiling Protocol
|
||||
|
||||
Styling is written in Sass using the SCSS syntax. Protocol styles are fragmented
|
||||
into separate [Sass partials](https://sass-lang.com/guide#topic-4) so you can
|
||||
import just the parts you need and keep your CSS files light. You can do this on
|
||||
a per-page basis so each page gets its own stylesheet for just the components
|
||||
needed on that page. Or you can take a hybrid approach with a global stylesheet
|
||||
for general styling and common components as well as separate, per-page stylesheets
|
||||
for components and page-specific styling as needed.
|
||||
|
||||
The `protocol.scss` file is an example of a global Protocol-based stylesheet. It
|
||||
sets a few common variables and imports fonts and base styles. Modify your own
|
||||
version of that file to configure Protocol for your site.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,132 @@
|
|||
---
|
||||
title: The Protocol CSS Framework
|
||||
label: Protocol CSS
|
||||
status: draft
|
||||
---
|
||||
|
||||
When you compile Protocol Sass as part of your project’s build process, you’ll
|
||||
also have access to all the mixins, functions, and [design tokens](/docs/fundamentals/design-tokens)
|
||||
that style Protocol components.
|
||||
|
||||
## Mixins
|
||||
|
||||
Protocol relies on numerous [Sass mixins](https://sass-lang.com/documentation/at-rules/mixin)
|
||||
to simplify and standardize repetitive code. Some are fairly simple shortcuts and
|
||||
others do more complex work. We won’t list them all here, but we’ll describe a
|
||||
few of the more notable ones. All our mixins are in `/includes/_mixins.scss` or
|
||||
in separate files in the `/includes/mixins/` folder. You’ll find even more
|
||||
documentation as comments directly in the source files.
|
||||
|
||||
### Text sizes
|
||||
Protocol uses a modular type scale with a range of predefined font sizes, and to
|
||||
maintain the consistency of that scale we rely on mixins for all of our text
|
||||
sizing. See [our page on typography](/docs/fundamentals/typography) for more info
|
||||
and examples.
|
||||
|
||||
```scss
|
||||
@include text-title-lg;
|
||||
```
|
||||
|
||||
Different themes have slightly different type scales so this mixin draws its
|
||||
output from the defined brand theme. See [our page on themes](/docs/fundamentals/brand-themes)
|
||||
for more info and examples.
|
||||
|
||||
### bidi
|
||||
The bidi mixin (short for “bi-directional”) is used to declare both left-to-right
|
||||
and right-to-left values for a CSS property together, and output appropriate
|
||||
declarations for each. This makes it easier to support right-to-left languages –
|
||||
such as Hebrew and Arabic – while keeping both styles in the same place. Whenever
|
||||
you’re floating or aligning something to one side, you might prefer to use the
|
||||
bidi mixin to reverse that direction for other languages. Refer to
|
||||
`/includes/mixins/_bidi.scss` for more documentation and usage.
|
||||
|
||||
```scss
|
||||
@include bidi(((float, left, right),));
|
||||
```
|
||||
|
||||
### at2x
|
||||
at2x is a helpful mixin for applying a high-resolution background image, for
|
||||
display on high definition screens (a.k.a. “retina”). It automatically outputs
|
||||
the standard resolution background image with the high-resolution version in a
|
||||
media query, along with the `background-size` property to scale it. Both image
|
||||
files should be in the same folder and have matching names, with the high
|
||||
resolution version suffixed with “high-res”, e.g. `example.png` and
|
||||
`example-high-res.png`
|
||||
|
||||
```scss
|
||||
@include at2x('/img/example.png', 100px, 100px);
|
||||
```
|
||||
|
||||
### light-links
|
||||
The light-links mixin inverts link colors in elements/components with dark
|
||||
backgrounds.
|
||||
|
||||
```scss
|
||||
@include light-links;
|
||||
```
|
||||
|
||||
### white-links
|
||||
The white-links mixin explicitly sets link colors (in all pseudo-class states) to
|
||||
white. This is useful for some elements/components with dark backgrounds where
|
||||
the regular inverted link colors might be undesirable, typically for utilitarian
|
||||
components like a footer.
|
||||
|
||||
```scss
|
||||
@include white-links;
|
||||
```
|
||||
|
||||
### Themes
|
||||
|
||||
Protocol supports [multiple brand themes](/docs/fundamentals/brand-themes), namely
|
||||
the Mozilla and Firefox brands. Themes work by defining sets of variables in Sass
|
||||
maps in the `/includes/_themes.scss` file, and those variables are fetched via
|
||||
the `get-theme()` function. That function determines which set of variables to
|
||||
draw from based on the declared brand theme, thus any themeable property in CSS
|
||||
can have different values for different brands.
|
||||
|
||||
```scss
|
||||
.mzp-c-my-component {
|
||||
background-color: get-theme('background-color');
|
||||
color: get-theme('body-text-color');
|
||||
|
||||
.mzp-c-my-component-title {
|
||||
color: get-theme('title-text-color');
|
||||
font-family: get-theme('title-font-family');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the `get-theme()` function for any themeable properties, especially basic
|
||||
colors for foreground (text) and backgrounds. Note that most colors have an
|
||||
“inverse” counterpart to use in dark style variants. Refer to `/includes/_themes.scss`
|
||||
for the actual values for each brand theme, but here are the variable names in a
|
||||
handy list:
|
||||
|
||||
```text
|
||||
background-color
|
||||
background-color-alt
|
||||
background-color-alt-inverse
|
||||
background-color-inverse
|
||||
body-font-family
|
||||
body-text-color
|
||||
body-text-color-alt
|
||||
body-text-color-alt-inverse
|
||||
body-text-color-inverse
|
||||
button-font-family
|
||||
link-color
|
||||
link-color-hover
|
||||
link-color-hover-inverse
|
||||
link-color-inverse
|
||||
link-color-visited
|
||||
link-color-visited-hover
|
||||
link-color-visited-hover-inverse
|
||||
link-color-visited-inverse
|
||||
title-font-family
|
||||
title-text-color
|
||||
title-text-color-inverse
|
||||
```
|
||||
|
||||
Text sizes are also defined as theme variables, allowing different brands to have
|
||||
slightly different type scales. Don’t use the `get-theme()` function for text
|
||||
sizing; use the text size mixins instead. The mixins already draw from the theme
|
||||
variables but come with baked-in responsive styling as well.
|
||||
|
|
@ -1,23 +1,21 @@
|
|||
---
|
||||
title: Contributing to Protocol
|
||||
label: Overview
|
||||
status: outdated
|
||||
---
|
||||
|
||||
Protocol, like everything else Mozilla makes, is [open source](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Introduction).
|
||||
We welcome contributions from people like you. Yes, you, whoever you are
|
||||
reading this, can do something to make Protocol better and more useful,
|
||||
no matter your skill level or area of interest.
|
||||
We welcome contributions from people like you. Yes, you, dear reader, can help us
|
||||
make Protocol better and more useful, no matter your skill level or area of interest.
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
The easiest way to help is to report bugs. Let us know if something isn't
|
||||
doing what you think it should do and we can try to fix it.
|
||||
The easiest way to help is to report bugs. Let us know if something isn’t doing
|
||||
what you think it should do and we can try to fix it.
|
||||
|
||||
To report an error you’ve discovered in Protocol, [submit an issue on Github](https://github.com/mozilla/protocol/issues/new/choose/)
|
||||
with a detailed description of the error and steps to reproduce. If possible,
|
||||
include a link to a live example and/or a screenshot of the bug in effect.
|
||||
Also be sure to mention the browser (and version) and operating system.
|
||||
include a link to a live example and/or a screenshot of the bug in effect. Also
|
||||
be sure to mention the browser (and version) and operating system.
|
||||
|
||||
You should search for similar issues in case it’s already been reported. In
|
||||
some cases a bug may have been fixed but the fix may not have been deployed,
|
||||
|
|
@ -31,13 +29,13 @@ using the appropriate issue template. Please try to fill out this template
|
|||
as thoroughly as you can. This will help the team understand the request
|
||||
and triage issues more effectively.
|
||||
|
||||
## Contributing code
|
||||
## Contributing Code
|
||||
|
||||
Aside from reporting bugs or requesting features, an even more direct way to
|
||||
contribute to Protocol is to write code.
|
||||
|
||||
Protocol is a design system, though the exact meaning of the term “design system” is
|
||||
hard to pin down. For our purposes, a design system comprises the entirety of
|
||||
Protocol is a design system, though the exact meaning of the term “design system”
|
||||
is hard to pin down. For our purposes, a design system comprises the entirety of
|
||||
guidelines, assets, and resources for producing websites in a specific style or
|
||||
brand identity. It includes a style guide, a pattern library of coded components,
|
||||
and the actual assets – fonts, graphics, CSS frameworks, JavaScript libraries –
|
||||
|
|
@ -48,66 +46,70 @@ assemble into a web page, and its soul is the CSS framework that styles those
|
|||
components. We’re probably straining that metaphor but you get the point;
|
||||
Protocol is made of code.
|
||||
|
||||
The Protocol design system comprises a CSS framework and a library of
|
||||
markup patterns for web page components. There's a bit of JavaScript for a few
|
||||
interactive things, but for the most part Protocol is static HTML and CSS.
|
||||
The Protocol design system comprises a CSS framework and a library of markup
|
||||
patterns for web page components. There’s a bit of JavaScript for a few interactive
|
||||
things, but for the most part Protocol is static HTML and CSS.
|
||||
|
||||
The pattern library lives at [protocol.mozilla.org](https://protocol.mozilla.org)
|
||||
and its source code lives at [github.com/mozilla/protocol](https://github.com/mozilla/protocol/).
|
||||
That code repository is also where the Protocol CSS framework lives, as well as
|
||||
all the system documentation (including this page).
|
||||
|
||||
To write code for Protocol you'll actually be working on the Protocol website itself.
|
||||
|
||||
To write code for Protocol you’ll actually be working on the Protocol website
|
||||
itself.
|
||||
|
||||
### Installing the Protocol site locally
|
||||
|
||||
We've done our best to make the barrier of entry to contributing code to
|
||||
We’ve done our best to make the barrier of entry to contributing code to
|
||||
Protocol as low as possible. You can do some work directly through github
|
||||
without actually installing Protocol locally, but if you want to do any complex
|
||||
coding you'll need to set up a local development environment.
|
||||
coding you’ll need to set up a local development environment.
|
||||
|
||||
* You'll need a GitHub account.
|
||||
* You’ll need a GitHub account.
|
||||
* [https://github.com/join](https://github.com/join)
|
||||
* [https://help.github.com/articles/set-up-git/](https://help.github.com/articles/set-up-git/)
|
||||
* You'll need to install Git.
|
||||
* You’ll need to install Git.
|
||||
* [https://git-scm.com/downloads](https://git-scm.com/downloads)
|
||||
* [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* You'll need to install Node and npm.
|
||||
* You’ll need to install Node and npm.
|
||||
* [https://docs.npmjs.com/downloading-and-installing-node-js-and-npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
|
||||
|
||||
With those prerequisites met:
|
||||
|
||||
1. Fork the [Protocol GitHub repository](https://github.com/mozilla/protocol/) to your personal account.
|
||||
1. Fork the [Protocol GitHub repository](https://github.com/mozilla/protocol/)
|
||||
to your personal account.
|
||||
* https://help.github.com/articles/fork-a-repo/
|
||||
2. Clone that remote repo to your computer.
|
||||
* https://help.github.com/articles/cloning-a-repository/
|
||||
3. On your computer’s command line, navigate to the folder to which you just cloned the Protocol repo.
|
||||
4. Within that folder, run `npm start`. This will install all the dependencies and launch a local server.
|
||||
3. On your computer’s command line, navigate to the folder to which you just
|
||||
cloned the Protocol repo.
|
||||
4. Within that folder, run `npm install`. This will install all the dependencies.
|
||||
5. Next run `npm run webpack-docs`. 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.
|
||||
6. In another command line console (and still within the Protocol folder), run
|
||||
`npm start`. This will start your local server.
|
||||
|
||||
You now have a local instance of the Protocol site running on your
|
||||
computer. You can load the site in a browser at http://localhost:3000.
|
||||
As you edit files they will update automatically and you can see your
|
||||
changes "live" on your local development environment.
|
||||
You now have a local instance of the Protocol site running on your computer. You
|
||||
can load the site in a browser at http://localhost:3000. As you edit files they
|
||||
will update automatically and you can see your changes “live” on your local
|
||||
development environment.
|
||||
|
||||
The pattern library uses [Gulp](https://gulpjs.com/) to automate tasks.
|
||||
The `npm start` command is a shortcut to installing and starting up the
|
||||
site the first time, but you may not want to rerun the installation process
|
||||
every time you sit down to work on Protocol. Once you’ve got it installed
|
||||
you can skip the installation step and run `gulp` directly to build the
|
||||
site and start the server, or `gulp --dev` to start the server with file
|
||||
watching (so it rebuilds and refreshes automatically with every file change).
|
||||
Sass and component files will reload automatically as you change them, but
|
||||
documentation pages written in Markdown are only processed at startup, so they
|
||||
require restarting the Fractal server to see the changes.
|
||||
|
||||
1. Make whatever edits you need to make, ideally in a fresh branch.
|
||||
* https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging
|
||||
* https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
|
||||
2. When you're done, commit your changes and push them to your GitHub remote repository.
|
||||
2. When you’re done, commit your changes and push them to your GitHub remote
|
||||
repository.
|
||||
* https://help.github.com/articles/pushing-to-a-remote/
|
||||
3. Submit a pull request from your fork to the Mozilla repo.
|
||||
* https://help.github.com/articles/creating-a-pull-request-from-a-fork/
|
||||
|
||||
You can also [make some edits directly on github.com](https://help.github.com/en/articles/editing-files-in-another-users-repository)
|
||||
without installing the site locally. For that you don't even have to install
|
||||
You can also [make some edits directly on github.com](https://help.github.com/articles/editing-files-in-another-users-repository)
|
||||
without installing the site locally. For that you don’t even have to install
|
||||
Git or Node, you just need a GitHub account. This is fine for updating docs or
|
||||
minor tweaks that don’t need extensive testing or review, but for any serious
|
||||
coding you really should have a local instance running so you can see your work
|
||||
|
|
@ -115,139 +117,94 @@ as it progresses.
|
|||
|
||||
### File structure
|
||||
|
||||
Once you’ve cloned the Protocol repository, you should spend some time
|
||||
browsing through the folders in your local copy (or on Github) to
|
||||
familiarize yourself with the general structure of the project. You’ll
|
||||
have to drill down a bit to reach the really good stuff but the top-level
|
||||
root folder looks something like:
|
||||
Once you’ve cloned the Protocol repository, you should spend some time browsing
|
||||
through the folders in your local copy (or on Github) to familiarize yourself
|
||||
with the general structure of the project. You’ll have to drill down a bit to
|
||||
reach the really good stuff but the top-level root folder looks something like:
|
||||
|
||||
```text
|
||||
protocol
|
||||
├── assets (Sass, JavaScript, and font files; this is what gets published with the package)
|
||||
├── bin (scripts that deploy the site to the server)
|
||||
├── dist (where source files are built locally for serving [not found in git])
|
||||
├── docs (documentation for Drizzle, the tool that drives the Protocol site)
|
||||
├── gulpfile.js (scripts that build and process the pattern library and CSS framework)
|
||||
├── src (the real source of the site; this is the meat of Protocol)
|
||||
└── tests (automated test scripts)
|
||||
├── components (the HTML components)
|
||||
├── docs (documentation pages [including this one])
|
||||
├── static (media assets for display on the Protocol website, but not part of Protocol itself)
|
||||
├── tests (automated test scripts)
|
||||
└── theme (the custom theme for the Protocol website)
|
||||
```
|
||||
|
||||
There are a few other files in the project root, most of which are pretty
|
||||
boring, but the most interesting is `CHANGELOG.md` that contains a historical
|
||||
record of Protocol.
|
||||
There are a few other files in the project root, mostly configurations for the
|
||||
documentation site and the build process, but one file to take note of is `CHANGELOG.md`
|
||||
that contains a historical record of Protocol.
|
||||
|
||||
The real meat of Protocol is in the `src` folder, and this is where you’ll do
|
||||
most of your work.
|
||||
|
||||
```text
|
||||
src
|
||||
├── assets (fonts, images, scripts, and styles)
|
||||
├── data (reference data used for examples)
|
||||
├── pages (content that supplements the pattern library such as demos and documents [including this one])
|
||||
├── patterns (the HTML components)
|
||||
├── static (media assets for display on the pattern library site, but not part of Protocol itself)
|
||||
└── templates (templates for the pattern library website)
|
||||
```
|
||||
|
||||
At this level the most interesting folders are probably `patterns` and `assets`,
|
||||
where the aforementioned heart and soul of Protocol can be found, respectively.
|
||||
Let’s start with `patterns`.
|
||||
|
||||
We’ve chosen to organize our pattern library following the atomic design metaphor,
|
||||
which consists of breaking a web page down into its smallest component parts,
|
||||
which can then be combined and assembled in different configurations, adding
|
||||
more parts in increasing complexity to arrive at the complete page. In our
|
||||
`patterns` folder you’ll find separate folders for `atoms`, `molecules`, `organisms`,
|
||||
and `templates`.
|
||||
|
||||
The files in these folders represent the actual Protocol components. They’re
|
||||
snippets of HTML that, when combined with the CSS that styles them, can be assembled
|
||||
to build a web page. All of the Protocol components can be found in the `patterns`
|
||||
folder, and all of the related CSS is in `assets` (we’ll do a deeper dive into that folder
|
||||
shortly).
|
||||
The files in the `components` folder represent the actual Protocol components.
|
||||
They’re snippets of HTML that, when combined with the CSS that styles them, can
|
||||
be assembled to build a web page. All of the Protocol components can be found in
|
||||
the `components` folder, each organized into subfolders, and all of the related
|
||||
CSS and JavaScript is in `assets` (we’ll do a deeper dive into that folder shortly).
|
||||
|
||||
## Component patterns
|
||||
|
||||
The component pattern examples are built with [Handlebars](https://handlebarsjs.com/guide/),
|
||||
a simple templating language that is mostly plain HTML with some added enhancements.
|
||||
Each component resides in its own Handlebars template file (using the extension `.hbs`),
|
||||
which includes a bit of front matter in a YAML format along with the component
|
||||
markup. All of this is processed into plain HTML and rendered to show a live
|
||||
example of the component alongside the component markup and the front matter
|
||||
for added documentation.
|
||||
The Protocol documentation uses [Fractal](https://fractal.build) and component
|
||||
templates are build with with [Nunjucks](https://mozilla.github.io/nunjucks/), a
|
||||
templating language that is mostly plain HTML with some added enhancements. Each
|
||||
component resides in its own Nunjucks template file (using the extension `.html`)
|
||||
along with a `readme.md` file (written in [Markown](https://daringfireball.net/projects/markdown/)
|
||||
format) with notes and documentation for that component. Many have an accompanying
|
||||
configuration file written in [YAML](https://yaml.org/) providing
|
||||
[contextual data](https://fractal.build/guide/core-concepts/context-data.html)
|
||||
and defining [component variants](https://fractal.build/guide/components/variants.html).
|
||||
|
||||
Here’s a minimal example of a Protocol component in Handlebars format:
|
||||
All of this gets processed and rendered to show a live example of the component
|
||||
with all its variants and added documentation.
|
||||
|
||||
```hbs
|
||||
---
|
||||
name: Button
|
||||
description: |
|
||||
This is an example of a button.
|
||||
---
|
||||
Here’s a minimal example of a Protocol component:
|
||||
|
||||
```twig
|
||||
<button class="mzp-c-button">Button</button>
|
||||
```
|
||||
|
||||
The top section between the `---` is the _front matter_, comprising at minimum
|
||||
a name but it can also include a description, links to examples or resources,
|
||||
notes, tips, no-nos (what not to do), component status, and sorting order.
|
||||
Beyond providing a single example of a component, by using a templating language
|
||||
like Nunjucks, these can be embedded in other component templates (and documents)
|
||||
using `{% include %}` or Fractal’s `{% render %}` helper. Each component can be
|
||||
addressed by its unique “handle” (based on the file name or defined in a
|
||||
configuration file):
|
||||
|
||||
Below the front matter is the component markup, just a simple button in this case.
|
||||
When the website is built, these Handlebars templates are rendered into formatted web
|
||||
pages. Each pattern displays the rendered and styled component, the HTML snippet
|
||||
that produces it, and the front matter notes that document it. Browse around the
|
||||
Protocol site to see this for yourself.
|
||||
|
||||
Handlebars does a bit more than plain HTML. Every component pattern becomes a
|
||||
reusable object that can be embedded into another Handlebars template as a _partial_:
|
||||
helper:
|
||||
|
||||
```hbs
|
||||
\{{> patterns.atoms.button}}
|
||||
```twig
|
||||
{% render '@button' %}
|
||||
```
|
||||
|
||||
For more complex cases, we can also define patterns with content _blocks_ allowing
|
||||
us to pass content into the pattern with the `\{{#embed}}` helper. For example, our
|
||||
button might contain a block called `label`:
|
||||
For greater flexibility we can also define context variables in a component,
|
||||
allowing us to pass data into the template when the component is rendered elsewhere.
|
||||
For example, our button might contain a variable called `label`:
|
||||
|
||||
```hbs
|
||||
<button class="mzp-c-button">
|
||||
\{{#block "label"}}
|
||||
Button
|
||||
\{{/block}}
|
||||
</button>
|
||||
```twig
|
||||
<button class="mzp-c-button">{{ label }}</button>
|
||||
```
|
||||
|
||||
When we embed that pattern in another template we can replace the block with
|
||||
different content:
|
||||
When we render that component in another template we can replace the variable
|
||||
with different content:
|
||||
|
||||
```hbs
|
||||
\{{#embed "patterns.atoms.button"}}
|
||||
\{{#content "label"}}Click Me!\{{/content}}
|
||||
\{{/embed}}
|
||||
```twig
|
||||
{% render '@button', { label: 'Click Me!' } %}
|
||||
```
|
||||
|
||||
Each component occupies its own folder and some folders contain multiple
|
||||
components as a collection. The site automatically concatenates all the templates
|
||||
within a folder into a single page during the build process. A component folder
|
||||
can optionally contain a `collection.yaml` file with metadata about the collection.
|
||||
This is obviously an abbreviated introduction but hopefully it will help you get
|
||||
started. Look through the various components in Protocol for more robust examples
|
||||
and refer to the [Fractal documentation](https://fractal.build/guide/components/)
|
||||
for more about how components and component variants are created and configured.
|
||||
|
||||
This is obviously an abbreviated introduction to our Handlebars components but
|
||||
hopefully it will help you get started. Look through the various patterns in Protocol
|
||||
for more robust examples and refer to the [Handlebars documentation](https://handlebarsjs.com/guide/)
|
||||
to learn more about how it works.
|
||||
|
||||
## The Protocol CSS framework
|
||||
## The Protocol CSS Framework
|
||||
|
||||
Along with the HTML snippets that give Protocol components their structure,
|
||||
Protocol also comprises a CSS framework to give it style. Our framework is built
|
||||
with [Sass](https://sass-lang.com) as a pre-processor, and we author Sass using
|
||||
the [SCSS](https://sass-lang.com/documentation/syntax#scss) syntax.
|
||||
Protocol also comprises a [CSS framework](/docs/usage/framework) to give it style.
|
||||
Our framework is built with [Sass](https://sass-lang.com) as a pre-processor, and
|
||||
we author Sass using the [SCSS](https://sass-lang.com/documentation/syntax#scss)
|
||||
syntax.
|
||||
|
||||
You can find our Sass files in the `assets/sass` folder. The `demos` and `docs` subfolders
|
||||
contain styles for Protocol demo pages and the Protocol website, respectively, but the
|
||||
real Protocol framework is in the `protocol` folder. This is where you’ll find all the
|
||||
CSS that styles Protocol components as well as the variables, mixins, and functions
|
||||
that make it all possible.
|
||||
You can find our Sass files in the `assets/sass/protocol` folder. This is where
|
||||
you’ll find all the CSS that styles Protocol components as well as the variables,
|
||||
mixins, and functions that make it all possible.
|
||||
|
||||
```
|
||||
sass/protocol
|
||||
|
|
@ -261,16 +218,17 @@ sass/protocol
|
|||
│ ├── forms
|
||||
│ ├── mixins
|
||||
│ ├── _functions.scss
|
||||
│ ├── _themes.css
|
||||
│ └── _lib.scss
|
||||
├── _theme-config.scss
|
||||
| ├── _lib.scss
|
||||
| ├── _mixins.scss
|
||||
│ └── _themes.scss
|
||||
├── templates
|
||||
├── protocol-components.scss
|
||||
└── protocol.scss
|
||||
```
|
||||
|
||||
As usual, it’s a good idea to explore the files and folders here to get the lay of
|
||||
the land. We try to include helpful comments in each .scss file to explain what all
|
||||
the different pieces do and how to use them so a lot of our documentation lives
|
||||
It’s a good idea to explore the files and folders here to get the lay of the land.
|
||||
We try to include helpful comments in each `.scss` file to explain what all the
|
||||
different pieces do and how to use them so a lot of our documentation lives
|
||||
directly within the source code.
|
||||
|
||||
Our styles are fragmented across numerous files in order to keep things more
|
||||
|
|
@ -278,13 +236,16 @@ self-contained and organized, and to help prevent conflicts when several people
|
|||
work simultaneously on different things (when more than one person is trying to
|
||||
edit the same file at the same time they’ll inevitably step on each other’s work).
|
||||
|
||||
The `base` folder has all the basic, general-purpose styling for common HTML elements.
|
||||
The `components` folder holds the styling for individual Protocol components. And
|
||||
the `includes` folder holds the supporting mixins and functions that power the entire
|
||||
framework. Each of these folders in turn hold other files that import and collect the
|
||||
smaller fragments. Almost all of our individual SCSS files are [Sass partials](https://sass-lang.com/guide#topic-4),
|
||||
prefixed with an underscore. They’re intended to be imported into another file when
|
||||
the Sass is compiled; they don’t all turn into separate CSS files of their own.
|
||||
The `base` folder has all the basic, general-purpose styling for common HTML
|
||||
elements. The `components` folder holds the styling for individual Protocol
|
||||
components. The `templates` folder holds styling for page and component layouts.
|
||||
And the `includes` folder holds the supporting mixins and functions that power
|
||||
the entire framework.
|
||||
|
||||
Each of these folders in turn hold other files that import and collect the smaller
|
||||
fragments. Almost all of our individual SCSS files are [Sass partials](https://sass-lang.com/guide#topic-4),
|
||||
prefixed with an underscore. They’re intended to be imported into another file
|
||||
when the Sass is compiled; they don’t all turn into separate CSS files of their own.
|
||||
|
||||
## Styling a component
|
||||
|
||||
|
|
@ -301,13 +262,15 @@ named `_item.scss` (this is not an actual Protocol component):
|
|||
margin: $spacing-lg 0;
|
||||
}
|
||||
```
|
||||
Even in this minimal example there’s a lot happening, and almost none of it is plain
|
||||
CSS. If you’re familiar with Sass/SCSS already this will look more familiar, but if
|
||||
you’re not let’s dig a bit deeper.
|
||||
|
||||
Even in this minimal example there’s a lot happening, and almost none of it is
|
||||
plain CSS. If you’re familiar with Sass/SCSS already this will look more familiar,
|
||||
but if you’re not let’s dig a bit deeper.
|
||||
|
||||
```scss
|
||||
@import '../includes/lib';
|
||||
```
|
||||
|
||||
First, we import the Protocol library file, `includes/_lib.scss`. Since that file
|
||||
is a Sass partial we don’t need the underscore prefix or the file extension, just
|
||||
referencing the relative path and filename is enough. That library file in turn
|
||||
|
|
@ -318,181 +281,68 @@ import that library at the very top.
|
|||
```scss
|
||||
.mzp-c-item {
|
||||
```
|
||||
|
||||
Next we get to the proper component styles, starting with a class selector. All of
|
||||
our classes follow a [standard naming convention](/docs/naming-convention.html).
|
||||
our classes follow a [standard naming convention](/docs/contributing/naming).
|
||||
They’re namespaced with `mzp` to avoid conflicts with any other styling or libraries
|
||||
with which they may need to coexist, followed by a `c` prefix indicating that this
|
||||
is a component.
|
||||
with which they may need to coexist, followed by a `c` prefix indicating that
|
||||
this is a component.
|
||||
|
||||
```scss
|
||||
@include text-title-md;
|
||||
```
|
||||
The first style declaration is a Sass mixin that sets the font-size for the element.
|
||||
We use mixins for font sizes to maintain a standardized type scale, and the mixins
|
||||
also include media queries to make the sizes responsive to the viewport size; bigger
|
||||
screens get bigger text. These sizing mixins are defined in `includes/mixins/_typography.scss`.
|
||||
See [our page on typography](/fundamentals/typography.html) for more about our type scale.
|
||||
|
||||
The first style declaration is a Sass mixin that sets the font-size for the
|
||||
element. We use mixins for font sizes to maintain a standardized type scale, and
|
||||
the mixins also include media queries to make the sizes responsive to the viewport
|
||||
size; bigger screens get bigger text. These sizing mixins are defined in
|
||||
`includes/mixins/_typography.scss`. See [our page on typography](/docs/fundamentals/typography)
|
||||
for more about our type scale.
|
||||
|
||||
Next we declare the text color using a variable. Protocol has an extensive color
|
||||
palette, all assigned to named variables so every occurance of a given color will
|
||||
always be the exact same value (`$color-ink-80` is a dark purplish black). You can
|
||||
see [our entire color palette](/fundamentals/color.html) for all the different options.
|
||||
always be the exact same value (`$color-ink-80` is a dark purplish black). You
|
||||
can see [our entire color palette](/docs/fundamentals/color) for all the different
|
||||
options.
|
||||
|
||||
```scss
|
||||
margin: $spacing-lg 0;
|
||||
```
|
||||
|
||||
The next line sets margins above and below the element, once again using a named
|
||||
variable instead of an explicit value. Assigning variables to spacing units means
|
||||
we ensure consistency throughout the system, and also lets us change the value of
|
||||
such a variable in one place and it will automatically propagate to every other part
|
||||
of Protocol. The `$spacing-lg` variable is `24px` but if we want to change that to
|
||||
`20px` we would only have to make that change once.
|
||||
such a variable in one place and it will automatically propagate to every other
|
||||
part of Protocol. The `$spacing-lg` variable is `24px` but if we want to change
|
||||
that to `20px` we would only have to make that change once.
|
||||
|
||||
### Tokens
|
||||
### Design Tokens
|
||||
|
||||
The example above shows a Sass variable used as a margin value. We call variables
|
||||
like these _design tokens_ and they’re more than just variables. Design tokens are
|
||||
a way to document the lowest level design attributes and share them throughout a
|
||||
complex system, and even across multiple systems. We use tokens as much as possible
|
||||
in place of hard-coded values, especially for colors and units of measure. Whenever
|
||||
you need a basic value in CSS, see if there’s already a token for it. You can see
|
||||
[a list of all the design tokens in Protocol](/fundamentals/tokens.html).
|
||||
like these _design tokens_ and they’re more than just variables. Design tokens
|
||||
are a way to document the lowest level design attributes and share them throughout
|
||||
a complex system, and even across multiple systems. We use tokens as much as
|
||||
possible in place of hard-coded values, especially for colors and units of measure.
|
||||
Whenever you need a basic value in CSS, see if there’s already a token for it.
|
||||
You can see [a list of all the design tokens in Protocol](/docs/fundamentals/design-tokens).
|
||||
|
||||
Tokens are also a partial abstraction of the value they represent. Assigning a name
|
||||
to a token also implies a particular purpose a step removed from its specific value.
|
||||
A token like `$spacing-md` represents "a medium unit of space" and we don't necessarily
|
||||
need to think about exactly how many pixels that is, we only know it's a bit larger
|
||||
than small and a bit smaller than large. For now we've decided that a medium space is
|
||||
`16px`, but that could easily change to `12px` or `20px` because "medium" is relative.
|
||||
Avoid misusing a token as an alias for its specific value since the whole point is
|
||||
that the value can change.
|
||||
Tokens are also a partial abstraction of the value they represent. Assigning a
|
||||
name to a token also implies a particular purpose a step removed from its specific
|
||||
value. A token like `$spacing-md` represents “a medium unit of space” and we don’t
|
||||
necessarily need to think about exactly how many pixels that is, we only know
|
||||
it’s a bit larger than small and a bit smaller than large. For now we’ve decided
|
||||
that a medium space is `16px`, but that could easily change to `12px` or `20px`
|
||||
because “medium” is relative. Avoid misusing a token as an alias for its specific
|
||||
value since the whole point is that the value can change.
|
||||
|
||||
Also avoid misusing a token to fill in a value for something it wasn't made for. For
|
||||
example, the token `$spacing-md` is intended for spacing within or between elements.
|
||||
Don't use it set the height of an image or width of a border or size of a font (unless
|
||||
there's a very good reason to do so).
|
||||
Also avoid misusing a token to fill in a value for something it wasn’t made for.
|
||||
For example, the token `$spacing-md` is intended for spacing within or between
|
||||
elements. Don’t use it set the height of an image or width of a border or size
|
||||
of a font (unless there’s a very good reason to do so).
|
||||
|
||||
(Side note: The `$spacing-*` tokens are smaller units, mostly for interior spacing
|
||||
inside components or between close elements. The `$layout-*` tokens are larger,
|
||||
intended for wider gaps between components on the page.)
|
||||
|
||||
Protocol's design tokens [reside in their own repository](https://github.com/mozilla/protocol-tokens)
|
||||
Protocol’s design tokens [reside in their own repository](https://github.com/mozilla/protocol-tokens)
|
||||
and are [published as their own package](https://www.npmjs.com/package/@mozilla-protocol/tokens).
|
||||
|
||||
### Mixins
|
||||
|
||||
Protocol relies on numerous [Sass mixins](https://sass-lang.com/documentation/at-rules/mixin)
|
||||
to simplify and standardize repetitive code. Some are fairly simple shortcuts and
|
||||
others do more complex work. We won’t list them all here, but we’ll describe a few
|
||||
of the more notable ones. All our mixins are in `/includes/_mixins.scss` or in
|
||||
separate files in the `/includes/mixins/` folder. You’ll find even more documentation
|
||||
as comments directly in the source files.
|
||||
|
||||
#### Text sizes
|
||||
Protocol uses a modular type scale with a range of predefined font sizes, and to
|
||||
maintain the consistency of that scale we rely on mixins for all of our text sizing.
|
||||
See [our page on typography](/fundamentals/typography.html) for more info and examples.
|
||||
|
||||
```scss
|
||||
@include text-title-lg;
|
||||
```
|
||||
|
||||
Different themes have slightly different type scales so this mixin draws its output
|
||||
from the defined brand theme. See [our page on themes](/fundamentals/themes.html)
|
||||
for more info and examples.
|
||||
|
||||
#### bidi
|
||||
The bidi mixin (short for “bi-directional”) is used to declare both left-to-right and
|
||||
right-to-left values for a CSS property together, and output appropriate declarations
|
||||
for each. This makes it easier to support right-to-left languages – such as Hebrew and
|
||||
Arabic – while keeping both styles in the same place. Whenever you’re floating or
|
||||
aligning something to one side, you might prefer to use the bidi mixin to reverse that
|
||||
direction for other languages. Refer to `/includes/mixins/_bidi.scss` for more
|
||||
documentation and usage.
|
||||
|
||||
```scss
|
||||
@include bidi(((float, left, right),));
|
||||
```
|
||||
|
||||
#### at2x
|
||||
at2x is a helpful mixin for applying a high-resolution background image, for display
|
||||
on high definition screens (a.k.a. “retina”). It automatically outputs the standard
|
||||
resolution background image with the high-resolution version in a media query, along
|
||||
with the `background-size` property to scale it. Both image files should be in the same
|
||||
folder and have matching names, with the high resolution version suffixed with “high-res”,
|
||||
e.g. `example.png` and `example-high-res.png`
|
||||
|
||||
```scss
|
||||
@include at2x('/img/example.png', 100px, 100px);
|
||||
```
|
||||
|
||||
#### light-links
|
||||
The light-links mixin inverts link colors in elements/components with dark backgrounds.
|
||||
|
||||
```scss
|
||||
@include light-links;
|
||||
```
|
||||
|
||||
#### white-links
|
||||
The white-links mixin explicitly sets link colors (in all pseudo-class states) to white.
|
||||
This is useful for some elements/components with dark backgrounds where the regular
|
||||
inverted link colors might be undesirable, typically for utilitarian components like a
|
||||
footer.
|
||||
|
||||
```scss
|
||||
@include white-links;
|
||||
```
|
||||
|
||||
### Themes
|
||||
|
||||
Protocol supports [multiple brand themes](/fundamentals/typography.html), namely the Mozilla
|
||||
and Firefox brands. Themes work by defining sets of variables in Sass maps in the
|
||||
`/includes/_themes.scss` file, and those variables are fetched via the `get-theme()` function.
|
||||
That function determines which set of variables to draw from based on the declared brand theme,
|
||||
thus any themable property in CSS can have different values for different brands.
|
||||
|
||||
```scss
|
||||
.mzp-c-my-component {
|
||||
background-color: get-theme('background-color');
|
||||
color: get-theme('body-text-color');
|
||||
|
||||
.mzp-c-my-component-title {
|
||||
color: get-theme('title-text-color');
|
||||
font-family: get-theme('title-font-family');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the `get-theme()` function for any themeable properties, especially basic colors for
|
||||
foreground (text) and backgrounds. Note that most colors have an "inverse" counterpart
|
||||
to use in dark style variants. Refer to `/includes/_themes.scss` for the actual values
|
||||
for each brand theme, but here are the variable names in a handy list:
|
||||
|
||||
```
|
||||
background-color
|
||||
background-color-alt
|
||||
background-color-alt-inverse
|
||||
background-color-inverse
|
||||
body-font-family
|
||||
body-text-color
|
||||
body-text-color-alt
|
||||
body-text-color-alt-inverse
|
||||
body-text-color-inverse
|
||||
button-font-family
|
||||
link-color
|
||||
link-color-hover
|
||||
link-color-hover-inverse
|
||||
link-color-inverse
|
||||
link-color-visited
|
||||
link-color-visited-hover
|
||||
link-color-visited-hover-inverse
|
||||
link-color-visited-inverse
|
||||
title-font-family
|
||||
title-text-color
|
||||
title-text-color-inverse
|
||||
```
|
||||
|
||||
Text sizes are also defined as theme variables, allowing different brands to have slightly
|
||||
different type scales. Don't use the `get-theme()` function for text sizing; use the text
|
||||
size mixins instead. The mixins already draw from the theme variables but come with baked-in
|
||||
responsive styling as well.
|
||||
|
|
|
|||
|
|
@ -11,14 +11,25 @@ After that, we follow a [SMACSS](https://smacss.com/book/categorizing)-based
|
|||
naming convention with a set of prefixes to put rules into a few different
|
||||
categories:
|
||||
|
||||
* `c-` for component names. Expect a lot of this one, e.g. `.mzp-c-card`, `.mzp-c-button`.
|
||||
* `t-` for theme styles, when a component has one or more alternative styles, e.g. `.mzp-t-dark`, `.mzp-t-product-firefox`.
|
||||
* `l-` for layout-related styles, e.g. `.mzp-l-content`, `.mzp-l-grid-third`. These are essentially presentational names, mostly used for container elements.
|
||||
* `u-` for utility styles, which have a broad scope and can be powerful overrides, e.g. `.mzp-u-inline`, `.mzp-u-title-md`. These are presentational so should be rare. Prefer mixins in a style sheet over classes in HTML.
|
||||
* `qa-` used as selector hooks for tests (unit tests, integration tests, etc.). These classes are not meant as styling hooks; no CSS should be applied to any `qa-` classes!
|
||||
* `is-` to indicate a current state, e.g. `.mzp-is-active`, `.mzp-is-collapsed` (typically assigned by JS and not hard-coded).
|
||||
* `has-` to indicate that a component contains some other component, when the parent gets some styling to accommodate the child, e.g. `.mzp-has-submenu`, `.mzp-has-image`.
|
||||
* `js-` used as a behavior hook for JavaScript, e.g. `.mzp-js-sticky`, `.mzp-js-collapsible`, `.mzp-js-toggle`. Indicates potential for a change of state and usually shouldn’t have any styling.
|
||||
* `c-` for component names. Expect a lot of this one, e.g. `.mzp-c-card`,
|
||||
`.mzp-c-button`.
|
||||
* `t-` for theme styles, when a component has one or more alternative styles,
|
||||
e.g. `.mzp-t-dark`, `.mzp-t-product-firefox`.
|
||||
* `l-` for layout-related styles, e.g. `.mzp-l-content`, `.mzp-l-grid-third`.
|
||||
These are essentially presentational names, mostly used for container elements.
|
||||
* `u-` for utility styles, which have a broad scope and can be powerful overrides,
|
||||
e.g. `.mzp-u-inline`, `.mzp-u-title-md`. These are presentational so should be
|
||||
rare. Prefer mixins in a style sheet over classes in HTML.
|
||||
* `qa-` used as selector hooks for tests (unit tests, integration tests, etc.).
|
||||
These classes are not meant as styling hooks; no CSS should be applied to any
|
||||
`qa-` classes!
|
||||
* `is-` to indicate a current state, e.g. `.mzp-is-active`, `.mzp-is-collapsed`
|
||||
(typically assigned by JS and not hard-coded).
|
||||
* `has-` to indicate that a component contains some other component, when the
|
||||
parent gets some styling to accommodate the child, e.g. `.mzp-has-submenu`, `.mzp-has-image`.
|
||||
* `js-` used as a behavior hook for JavaScript, e.g. `.mzp-js-sticky`,
|
||||
`.mzp-js-collapsible`, `.mzp-js-toggle`. Indicates potential for a change of
|
||||
state and usually shouldn’t have any styling.
|
||||
* `a-` for CSS animation names, e.g. `mzp-a-fade-in`, `mzp-a-slide-from-right`.
|
||||
|
||||
Our names are all lowercase and hyphen-separated or “kebab-case,” e.g.
|
||||
|
|
@ -43,8 +54,8 @@ Example:
|
|||
</div>
|
||||
```
|
||||
|
||||
Component names should be semantically meaningful, descriptive of the element's content,
|
||||
purpose, or function, not only its presentation.
|
||||
Component names should be semantically meaningful, descriptive of the element’s
|
||||
content, purpose, or function, not only its presentation.
|
||||
|
||||
```scss
|
||||
// NO - Presentational
|
||||
|
|
@ -63,9 +74,9 @@ adding presentational classes in your markup.
|
|||
|
||||
### Sizes
|
||||
|
||||
We use a "T-shirt" convention when we need to describe sizes, e.g. "lg" for large
|
||||
and "sm" for small. In this t-shirt scale system, the default should be the medium
|
||||
"md" size and you can scale up or down from there.
|
||||
We use a “T-shirt” convention when we need to describe sizes, e.g. “lg” for large
|
||||
and “sm” for small. In this t-shirt scale system, the default should be the medium
|
||||
“md” size and you can scale up or down from there.
|
||||
|
||||
```scss
|
||||
.mzp-t-size-2xl { ... }
|
||||
|
|
@ -77,10 +88,9 @@ and "sm" for small. In this t-shirt scale system, the default should be the medi
|
|||
.mzp-t-size-2xs { ... }
|
||||
```
|
||||
|
||||
Note that when we need multiple Xes we opt for a numeral. This avoids confusion or
|
||||
ambuguity in the event we need to reference some extreme size. "5xl" is more readable
|
||||
than "xxxxxl".
|
||||
|
||||
Note that when we need multiple Xes we opt for a numeral. This avoids confusion
|
||||
or ambuguity in the event we need to reference some extreme size. “5xl” is more
|
||||
readable than “xxxxxl”.
|
||||
|
||||
### Resources
|
||||
|
||||
|
|
|
|||
|
|
@ -3,17 +3,17 @@ title: CSS Coding Guide
|
|||
label: CSS Guide
|
||||
---
|
||||
|
||||
Coding style can be really personal and everyone has their own opinions
|
||||
and preferences. But when we work as a team on a shared codebase it's
|
||||
invaluable to agree to some basic rules. The CSS in Protocol should be
|
||||
written consistently no matter who wrote it.
|
||||
Coding style can be really personal and everyone has their own opinions and
|
||||
preferences. But when we work as a team on a shared codebase it’s invaluable to
|
||||
agree to some basic rules. The CSS in Protocol should be written consistently
|
||||
no matter who wrote it.
|
||||
|
||||
## Terminology
|
||||
|
||||
Just so we all know what we’re talking about, a CSS *rule* comprises one
|
||||
or more *selectors* followed by a *declaration block* consisting of one
|
||||
or more *declarations*. A declaration comprises a *property* and a *value*
|
||||
(some properties accept multiple values).
|
||||
Just so we all know what we’re talking about, a CSS *rule* comprises one or more
|
||||
*selectors* followed by a *declaration block* consisting of one or more
|
||||
*declarations*. A declaration comprises a *property* and a *value* (some
|
||||
properties accept multiple values).
|
||||
|
||||
A rule in CSS looks like:
|
||||
|
||||
|
|
@ -27,29 +27,28 @@ selector {
|
|||
|
||||
Use the shortest, least specific selector required to do the job.
|
||||
|
||||
Favor classes over IDs. IDs in CSS aren’t expressly forbidden, just
|
||||
strongly discouraged. Using ID selectors can lead to specificity wars
|
||||
requiring ever more powerful selectors to override previous styling. A
|
||||
better option is an attribute selector like `[id='widget']` which selects
|
||||
the element by its ID but has the same specificity as a class. Everybody
|
||||
wins.
|
||||
Favor classes over IDs. IDs in CSS aren’t expressly forbidden, just strongly
|
||||
discouraged. Using ID selectors can lead to specificity wars requiring ever more
|
||||
powerful selectors to override previous styling. A better option is an attribute
|
||||
selector like `[id='widget']` which selects the element by its ID but has the
|
||||
same specificity as a class. Everybody wins.
|
||||
|
||||
Avoid qualifying classes with type selectors. It slows down performance
|
||||
and makes classes less portable. E.g. `.widget` is better than `div.widget`.
|
||||
Avoid qualifying classes with type selectors. It slows down performance and makes
|
||||
classes less portable. E.g. `.widget` is better than `div.widget`.
|
||||
|
||||
### Minimal nesting
|
||||
|
||||
We use SCSS as a pre-processor. Nested rules are converted into descendent
|
||||
selectors in the generated style sheet. The deeper the nesting, the more
|
||||
complex and specific the final selector will be. Don’t nest rules unless
|
||||
necessary for context and specificity, and don’t nest rules just to group
|
||||
them together (use comments to label sections of the style sheet for grouping).
|
||||
We use Sass as a pre-processor. Nested rules are converted into descendent
|
||||
selectors in the generated style sheet. The deeper the nesting, the more complex
|
||||
and specific the final selector will be. Don’t nest rules unless necessary for
|
||||
context and specificity, and don’t nest rules just to group them together (use
|
||||
comments to label sections of the style sheet for grouping).
|
||||
|
||||
All the style declarations for the parent element should come before any
|
||||
nested rules.
|
||||
All the style declarations for the parent element should come before any nested
|
||||
rules.
|
||||
|
||||
Include a blank line before each nested rule to separate it from the
|
||||
rule or declaration above it.
|
||||
Include a blank line before each nested rule to separate it from the rule or
|
||||
declaration above it.
|
||||
|
||||
```scss
|
||||
// NO - This is horrible
|
||||
|
|
@ -119,14 +118,14 @@ rule or declaration above it.
|
|||
```
|
||||
|
||||
When possible, limit line lengths to 80 characters. It improves readability,
|
||||
minimizes horizontal scrolling, makes it possible to view files side by side,
|
||||
and produces more useful diffs with meaningful line numbers. There will be
|
||||
exceptions such as long URLs or gradient syntax but most declarations should
|
||||
fit well within 80 characters even with indentation.
|
||||
minimizes horizontal scrolling, makes it possible to view files side by side, and
|
||||
produces more useful diffs with meaningful line numbers. There will be exceptions
|
||||
such as long URLs or gradient syntax but most declarations should fit well within
|
||||
80 characters even with indentation.
|
||||
|
||||
Long, comma-separated property values – such as multiple background images,
|
||||
gradients, transforms, transitions, webfonts, or text and box shadows – can
|
||||
be arranged across multiple lines (indented one level from their property).
|
||||
gradients, transforms, transitions, webfonts, or text and box shadows – can be
|
||||
arranged across multiple lines (indented one level from their property).
|
||||
|
||||
```scss
|
||||
.selector {
|
||||
|
|
@ -144,10 +143,11 @@ be arranged across multiple lines (indented one level from their property).
|
|||
|
||||
### Comments
|
||||
|
||||
Use `//` for comments in Sass instead of `/* */`, including multi-line comment blocks.
|
||||
Our configuration is set to strip `//` comments when the CSS is compiled and minified,
|
||||
but will allow `/* */` comments to pass through. There's usually no need to include
|
||||
developer comments in minified CSS sent to browsers, so it just adds extra bytes.
|
||||
Use `//` for comments in Sass instead of `/* */`, including multi-line comment
|
||||
blocks. Our configuration is set to strip `//` comments when the CSS is compiled
|
||||
and minified, but will allow `/* */` comments to pass through. There’s usually
|
||||
no need to include developer comments in minified CSS sent to browsers, so it
|
||||
just adds extra bytes.
|
||||
|
||||
An exception is special comments to override linting rules, which require the
|
||||
`/* */` formatting.
|
||||
|
|
@ -160,7 +160,7 @@ An exception is special comments to override linting rules, which require the
|
|||
}
|
||||
```
|
||||
|
||||
In a long style sheet it's not a bad idea to add dividing lines (with two blank
|
||||
In a long style sheet it’s not a bad idea to add dividing lines (with two blank
|
||||
lines before it) to help set sections apart visually.
|
||||
|
||||
```scss
|
||||
|
|
@ -188,5 +188,6 @@ lines before it) to help set sections apart visually.
|
|||
* Use percentages for fluid-width elements.
|
||||
* Use rems for `font-size` because it respects user preferences.
|
||||
* Use [unitless `line-height`](http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/)
|
||||
in conjunction with `font-size`; it acts as a multiplier of font size. E.g. `line-height: 1.5`.
|
||||
in conjunction with `font-size`; it acts as a multiplier of font size. E.g.
|
||||
`line-height: 1.5`.
|
||||
* Use milliseconds for timing, e.g. `500ms` not `.5s`.
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
}
|
||||
|
||||
.Browser-panel .Prose {
|
||||
code:not([class='hljs']) {
|
||||
code:not([class*="hljs"]) {
|
||||
background-color: #f8f8f8;
|
||||
border-radius: $border-radius-xs;
|
||||
color: #000080;
|
||||
|
|
|
|||
|
|
@ -60,4 +60,12 @@
|
|||
& :not(hr) + h2 {
|
||||
margin-top: 1em;
|
||||
}
|
||||
|
||||
code:not([class*="hljs"]) {
|
||||
background-color: #f8f8f8;
|
||||
border-radius: $border-radius-xs;
|
||||
color: #000080;
|
||||
outline: 1px solid rgba(0, 0, 0, .05);
|
||||
padding: 0 .5ch;
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче