Gaia web components and design patterns documentation plan

by 3 contributors:

In Firefox OS 2.1 and above, the old "shared building blocks" (see Building Firefox OS) that were used to create the Gaia app UIs (and have been reused by many external app developers) are being deprecated in favor of new "Gaia web components". These are built on top of the new web components technology that is supported in Nightly, which provides a much more streamlined, efficient way of creating reusable building blocks for web app UI/functionality.

This project will document Web components, as well as a full set of design patterns for Gaia that need to be documented. These new docs need to go in the App Center Design section.


  • Chris Mills: MDN editor
  • Stephany Wilkes: Main Firefox OS UX contact

Join the project

MDN is built by you, the reader! If you'd like to help make this documentation real, we'd like to hear from you. You may contact the writing team by clicking on their names above, or on our mailing list. If you're a new MDN contributor, please have a look at our contributor guide. You can also join the conversation in our IRC channel, #mdn.


  • Show designers/developers how to use the new set of Gaia web components in their own apps, and Gaia apps.
  • Show designers/developers recommended design patterns for mobile apps.
  • Raise visibility of available Mozilla tools for writing apps.

Target milestones

This work does need to be done fairly urgently. Work should start soon, with regular progress being made. End up work should be Q4 2014.

Note: Each milestone bug should block bug 1054378, which is a tracking/meta bug for this project.

User stories

  • I want to find out the best design patterns to use in my mobile app.
  • I want to use Gaia web components to build the UI of my Gaia / 3rd party app.

Documents needed

Gaia Web components

The plan for the web components is to create a new landing page underneath Apps/Design called Gaia web components (or similar.) This landing page will explain the overall area and show what global setup is needed to use the components, then link to further sub-pages:

  • A page for each web component, explaining how to use the component/its purpose, and showing the HTML/CSS/JS/implementation for each component. If possible, we'll show a live demo of the component in action on each page.
  • A page that includes Casey Yee's Gaia controls app, embedded in an iFrame: this allows developers to play with each component type live, and also install the app on their Firefox OS device so they can get even more of a native showcase for the web components.

Hosting the app to get this up and working will require a little bit of work, and we're currently discussing the best way to do this on the dev-mdn list.

Since this new component set is not going to be backwards compatible, we need to link back to Building Firefox OS, which includes all the information developers need to use the old building blocks set. This can be killed when it becomes completely obsolete.


Gaia design patterns

This part of the work should be simpler. Stephany Wilkes has the complete set of new Gaia design patterns contained in a large PDF document. We need to create a new landing page underneath Apps/Design/ called "Gaia design patterns" (or similar), which will explain the overall area. This will link to several sub-pages, each one explaining a single design pattern.

Each page could perhaps also link to the relevant web component page that implements that design pattern?

Other work needed

The material currently under Apps/Design needs reworking — maybe put all the CSS stuff under a "CSS for apps" section, or similar?

Other notes

From Kevin Grandon, on dev-gaia:

In 2.1 we are running an experiment. Currently most components are located in shared/elements, but the gaia-header is located in an external repository. We are doing this only in 2.1 to see the pros and cons of each approach, and will make a final decision in the 2.2 or 2.3 timeline.

There are pros and cons of each approach, and we are in the data-gathering stage right now. For reference, here is the location of the "gaia-components" repo with a few external repositories:

The current other approach involves keeping components inside of gaia, and exporting them for third party use. I have an example of this here:

Document Tags and Contributors

Contributors to this page: Sheppy, markg, chrisdavidmills
Last updated by: Sheppy,
Hide Sidebar