Git Product home page Git Product logo

protocol's Introduction

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.

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. 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.

Current npm package version. Total downloads on npm. Pull requests welcome!

Getting Started

Protocol is built on the Node.js platform and published to NPM, 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:

npm install @mozilla-protocol/core --save

Alternatively, you can also download the latest release from GitHub.

Usage

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.

Make it Run

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.

Building the website

To build the Protocol documentation site for deployment, run:

$ npm run build-docs

Building the NPM package

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.

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 is up to date.
  2. Update the package version number in assets/package/package.json (use Semantic Versioning to determine what the new version number should be).
  3. Update the package README assets/package/README.md.
  4. Update the package version number in the root package.json file and then 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, or directly on the GitHub website.
  7. Run npm run build-package && 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.
  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:

A notice will be posted in #www-notify on Slack when the push has completed.

protocol's People

Contributors

0xflotus avatar aaronshivers avatar alexgibson avatar amychurchwell avatar anand-371 avatar angelafrancisco avatar craigcook avatar dependabot[bot] avatar errolyn avatar globau avatar glogiotatidis avatar iinh avatar jgmize avatar johngruen avatar katiechurchwell avatar liamnewmarch avatar lucashbg avatar maureenlholland avatar maxxcrawford avatar michaelmccombie avatar mozilla-github-standards avatar nathan-barrett avatar pmac avatar reemhamz avatar rraue avatar stephaniehobson avatar thejeffreytaylor avatar tikhsup avatar wlach avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

protocol's Issues

Content Formatting

Including, but not limited to:

  • Standard notation for dates, places, links, buttons, etc
  • Character count guidance
  • Content length guidance
  • General formatting guidelines for content creators to assist work product is useful and usable for implementation

Name this thing

Naming things is hard.

I've been kind of avoiding it, hoping the perfect name would come along and suggest itself organically. But in so avoiding the naming I have somehow also prevented a name from suggesting itself. By deliberately not naming it I've come up totally blank when trying to think of a good name. We just keep talking about "the system" and that's just not going to work long term.

We're now at the point that we need to be able to refer to things more specifically. E.g. this system currently contains a modified copy of the Pebbles framework taken from Bedrock, but this copy of Pebbles is already very different from the original. It can no longer accurately be called Pebbles, it needs something to make it distinct and separate. If only because we have to name the folder. We can't really start integrating system styles into Bedrock because there would be collisions with pre-existing Pebbles.

So let's start to put real thought into choosing a name for the system, its accompanying CSS framework, and even the system tool itself now that it's deviated significantly from Drizzle.

A few suggested names already are "Protocol" (which was the code name for the design concept that became the new Mozilla logo) and "Spark" (which I think came from something Chris Beard said in the plenary at the Austin all-hands in 2017).

I would love to make it some semi-obscure pop-culture reference if possible but that needn't be a requirement, just a strong desire for some extra awesomeness and whimsy.

Display CSS associated with components

At present we only show the HTML for a given component but we should also show the associated (S)CSS. We can look at other systems and tools for ideas.

It could be baked into the component template, or a separate file bundled with the component might keep things tidier. But then we need to keep that in sync with its duplicate within the CSS framework. Fractal shows CSS and bundles it with the component markup.

If we can find a way to point to the one true source that might be ideal... perhaps just a "css" field in the front-matter with a filepath? Then we'll need to add some build functionality that fetches and parses that for display.

Run tests & build script in CI

We should get some automated linting and tests running against new pull requests's via CI, such as Travis or CircleCI. This could include the following:

  • Lint CSS via Stylelint.
  • Lint JS via ESLint.
  • Run the main Protocol build script to make sure it doesn't error.

Homepage discussion

I thought I'd open this for discussion re: breaking down tasks for incorporating the homepage into Protocol sized components:

https://www.mozilla.org/en-US/?v=a

Here's an initial list of tasks I can think of, but please add any other suggestions / thoughts:

  • Identify any new atoms, molecules, organisms on the page (group activity).
  • Update design tokens.
  • Update sketch files / design assets in Abstract (?).
  • Refactor card component in bedrock to a Protocol molecule (4 variations of card styles).
  • Refactor card layout in bedrock to use Protocol spacing.
  • Refactor bedrock page to use Protocol type scale.
  • Refactor newsletter component to use Protocol form styles.
  • Add download button style to Protocol? (Fixing bug https://bugzilla.mozilla.org/show_bug.cgi?id=1444376)
  • Update link styles.
  • PR(s) to update home page in bedrock to use Protocol.
  • Voice & tone, copy, formatting docs
  • Doc sprint?

Once we're happy with what we have, we can add them to the board and set up some milestones.

Accessibility guidelines

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 should document general a11y guidelines for components.

Fonts are 404 once consumed by other sites

The Protocol @font-face declarations reference fonts located in /static/, which is a folder not copied across to NPM as it contains assets for the static docs site. This means when we pull Protocol into bedrock, the fonts are currently 404 as they reference a folder which doesn't exist.

https://github.com/mozilla/protocol/blob/master/src/assets/sass/protocol/includes/fonts/_zilla-slab.scss#L10-L11

There are a couple of ways we could fix this:

  • Copy the fonts over in our build script and switch to using relative paths. This is tidy, but may have the following issues:
    • It makes the NPM package very large as we need to bundle the fonts.
    • Sites may want to host fonts separately to their CSS & JS (e.g. a CDN, or Google Fonts).
    • Unless we're careful, we could end up loading fonts twice (e.g. global nav & footer still use Pebbles).
  • The other option I can think of is not to include the @font-face declarations directly inside Protocol. Instead, we could have a separate file that sites could edit individually, pointing to where they host their fonts. This is more messy, but possibly more flexible as sites can edit the location.

Thoughts? /cc @craigcook @michaelmccombie

Formatting

  • Remove ES5 syntax and replace with ES6 syntax
  • Remove CamelCase gulp tasks
  • Resolve space/tab issues

Writing style guide

Document some rules for grammar, spelling, capitalization, punctuation, etc, as well as guidelines for voice and tone and overall content strategy.

Use PostCSS

Look into adding PostCSS, specifically for auto-prefixer and mqpacker

Provide non-concatenated JS files in the build

Currently the build process concatenates JS files into a single protocol.js bundle. Whilst this may be ok for some sites that don't have their own asset pipeline, so sites like bedrock we probably want to cherry-pick which JS libs to include on a per page basis. We should ensure individual JS files are copied across to ./dist/assrts/js/, as well as the bundle.

Link preview article cards

It would be great if we could take the cards we created for the homepage and re-purpose them as link previews. Here's a poorly written codepen with an example of this feature.

article-card-preview

Localization guidelines

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.

We should document some basic dos and don'ts around designing for l10n.

Define general layout stuff

In olden days of yore, way back in 2016, we used a 12 column floated grid system with a span() mixin to set widths based on how many columns a box should span when it floated left. We have CSS Grid now, and honestly it always felt like the 12 column system was too printerly (when do you ever have something one column wide?). We'll still need to float things for older browsers but can use grid for modern ones.

So far we've been talking about getting away from a many-column system and thinking more in terms of plain old box sizes with a few standard units like "quarter", "third", "half" etc along with standard gutter widths. We could define these as variables/tokens and possibly some mixins but we haven't really dug into the particulars yet. So let's dig into it.

Consume protocol-layout design tokens

We need to pull in the protocol-assets design tokens for consumption within Protocol.
We also need to refactor any existing layout variables to refer to the new tokens.
This npm package include our spacing units, breakpoints, and grid settings

Add ESLint config

Protocol currently lists ESLint in it's dev dependencies, but we haven't yet configured any set of rules. We should do this so we can get ESLint running in CI.

Make the CSS framework consumable

Need to work out a distribution process that doesn't require downloading the whole system site, just the Sass framework. Then to figure out versioning and distributing updates.

Establish naming conventions

We'll need to give individual components useful and meaningful names as we define them, but we also need to settle on a naming convention for classes and IDs in CSS.

  • BEM is popular but ugly (I really hate the double hyphens and double underscores, and hate the mixing of hyphens and underscores together even more).
  • SMACSS is somewhat lacking in human readability.
  • ITCSS is intriguing but poorly documented, warrants further study.
  • OOCSS is the original but maybe others have improved on its syntax since.

And maybe we come up with something of our own scheme. Perhaps based on a combination of what we like from the above, or a modification of a syntax we mostly like just without the things we don't.

Remove dependency on `@cloudfour/gulp-tasks`

We're only using a few of the @cloudfour/gulp-tasks gulp tasks, and they are all pretty simple code-wise. I think we can probably remove this dependency and port the tasks we do use. Not a high priority though.

Compile components into separate CSS files

Currently components are all imported into protocol.scss, creating a monolith CSS file that contains lots of things:

https://github.com/mozilla/protocol/blob/master/src/assets/sass/protocol/protocol.scss#L17-L21

To improve page performance, we probably want to only import components that are being actively used on a given page, so we should separate protocol.scss to just the base elements.

We probably also want to compile each component as an individual CSS file as part of the build process, so sites can pick & choose easily.

Create a Sketch library

We'll need a shared Sketch library for designers to mock up pages with system components. We'll need to figure out how best to distribute it and keep it up to date.

404 image references when building from source via NPM

When running ./manage.py collectstatic in bedrock the build fails with the following error:

Post-processing 'protocol/css/protocol.css' failed!
ValueError: The file 'img/cta-arrow.svg' could not be found

This seems to be because of a reference to an image that not copied across in the build script:

https://github.com/mozilla/protocol/blob/master/src/assets/sass/protocol/components/_card.scss#L93

We should probably move this out of /static/img/ and into /assets/img/, so we can bundle the required images via NPM. We should check for any other images also.

Update the design of the article page template

A template for an article page was created by @craigcook and a sketch file of an article page was created by @vincejoyiv. Both are based on the Mozilla Security page. Some design decisions were made in that Sketch file that need to be translated in to the template.

We aren't redesigning the Mozilla Security page, instead we are desiging a page template that contains text-based content and local navigation.

Not every design decision made in Sketch will be translated in to Protocol, we want to ensure that the decisions being made are for the health of the system and not to satisfy a one-off instance.

This work will involve a decent amount of discussion, refactoring, and redesigning things in Sketch. When this task is completed the Sketch file and the template should look nearly identical.

Determine browser support levels

As we begin developing real components and especially face issues of page layout and JavaScript we need to think about minimum browser support. A few thoughts:

  • IE8 and lower don't support a lot of CSS features we now take for granted. On mozilla.org we opted to just stop serving full CSS to those browsers and serve lte IE8 a separate minimal stylesheet that just offers basic typography. Shall we do the same with Protocol? It just means creating that minimal style and writing up some guidelines for the conditional comments. Probably need to add the HTML5 shiv as well.

  • IE9 doesn't support matchMedia without a polyfill. If we make use of matchMedia in Protocol components (which we very well could), do we include that polyfill or do we just ignore IE9?

  • vendor prefixes ... we've talked about using PostCSS and autoprefixer but should decide how far back in time we want to go.

And then there's Grid... we should use it as much as possible but there will be places where it's not practical and/or redundant to build the same layout twice. In other places we could just use grid and let older browsers get a simpler, linear layout. It's going to be a case-by-case thing much of the time but we might want to establish some general guidelines.

Consume protocol-assets design tokens

We need to pull in the protocol-assets design tokens for consumption within Protocol.
We also need to refactor any existing assets to refer to the new tokens.

A11y (Accessibility)

Place holder for now, but things like:

  • Design best practices
  • content best practices
  • Screen reader guidelines
  • considerations for mobile
  • W3C guidelines referencing

Document naming convention and CSS style guide

SMACSS-based naming using these prefixes:

  • is- to indicate a current state e.g. is-active, is-collapsed (typically assigned by JS, not hard-coded).
  • has- to indicate that a component contains some other specific component (think of it like a meta-state) e.g. has-submenu, has-image (may not be used very often).
  • js- used as a behavior hook for for JavaScript, indicates potential for a state-change but usually doesn't have any styling specific styling other than behavior-based, e.g. js-sticky, js-collapsible.
  • l- For layout-related styles e.g. l-grid-half (or something like that, we need to figure out our layout stuff; see #10).
  • t- For theme styles, when a component has a alternative styles, e.g. t-dark
  • c- For component names. Expect a lot of this one, e.g. c-card
  • u- For utility styles, which have a broad scope and can be powerful overrides, e.g. u-inline (could get really presentational, let's be mindful here).
  • qa- For testing (should have no styling, this is really just so scripts can find elements and we may not even use it much)

Also using a mzp namespace prefix, e.g. .mzp-c-card for a Mozilla Protocol card component.

Display optional front-matter on component collections

Out of the box, there's no way to add a top-of-page intro to a component collection, except as part of the first component. I'd like to have the option of including a general overview of the entire collection. This could be a separate index template or maybe a field in the collection.yaml

Error Page Treatment Discussion

Given what we intend to achieve with the new design system, let's create a roadmap for updating our 404 and other error pages.

Remove unused dependencies

There may be some dependencies that that we're no longer / not currently using. We should probably remove them from the project if so (they can always be added back later).

  • babel-core
  • babel-eslint
  • babel-loader
  • babel-preset-es2015
  • gulp-gh-pages

Uglify Discussion

Per Alex's comment "Is uglify something we should handle in this project, or leave to sites that consume Protocol? (I could lean either way here, but perhaps something worth a discussion)."

Remove Bower and replace Bower dependencies

Per Alex's comment - "Unless we have a really good reason to support it, I'd suggest we not publish this to Bower. While it's maintained as far as bug fixes go, even the maintainers try to enourage npm/yarn these days. It's unlikely to get many new features, and is already way behind npm."

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.