Let's do an "Hello World" example of how our components are written.

Here is what our component will look like:

Hello World

This is an example component which is not used in the Death Star.

You may write stuff in it or play around with it as you wish, but don't forget to clean it up afterwards!

Adding CSS files

All of our components live in css/ui/. Other folders contain base and helper code, explained in more detail in the CSS structure tutorial. Simple components are contained in a single file. Some components are grouped together into a folder: this could be because they form a larger component (like the navigation or tabs) or because they share a purpose (like lists).

All files need to be imported in the css/_imports.scss file. Grouped components expose an index file that imports all files in a given folder (it often contains also variables and mixins specific only to that group). Simple components are reference directly.

// Simple component
@import "ui/tutorial/hello-world";

// Grouped component
@import "ui/navbar/index";

Writing SCSS

Here is the SCSS we wrote for hello-world:

// in css/ui/tutorial/hello-world.scss
@include block(hello-world) {
  padding: 20px;
  border: $border;
  margin-bottom: 10px;
}

@include element(title) {
  border-bottom: $border;
  margin-bottom: $base-spacing-unit;

  h2 {
    color: $c-red;
  }
}

@include element(body) {
  @extend %font--medium;
}

A few things to note here:

  • We used block and element mixins which are explained extensively in the CSS component syntax explained tutorial.
  • We have a set of guidelines for typography, colors and more (check the Guides section in the nav) that you should familiarize yourself before creating a component - not to mention check if a similar component does not already exist and can be extended!
  • Small, common style elements are extracted and can be used across components. These include things like a standard distance for margins, colors or a border (used in our component above). You can find these styles in the guides together with explanations on how they can be used - they could SCSS variables or special CSS classes.

Adding a pattern page

Adding CSS is not enough - we need to add a component page so it's findable. We use Assemble as a static page generator. It will pickup files in the templates folder. To add a page for our component, we only need to place a handlebar template file hello-world.hbs inside the patterns folder.

Add a YAML front matter in the file to set the correct title. Explain what your component is and what are it's options. Put a data-code attribute on your example and it will generate the toggleable code panel.

---
title: Hello World
---

<section>
  <p>This is a hello world example</p>

  <div data-code>
      <div class="hello-world">
        <div class="hello-world__title">
          <h2>Hello World</h2>
  // and so on

The last step will be adding our example to the pattern library navigation. At the moment, this is a manual process - you will need update the templates/partials/pattern-library-nav.hbs file.

Using grunt-scaffold to generate a component

Run grunt scaffold:component to generate almost all of the above. The script will ask you for the component name and will generate almost all of the needed files. At the moment though it will not generate grouped components and will not add it to the navigation.