GearLab Tools Pattern Library

Proof of concept for the GearLab Tools Pattern Library doc site

Getting started

In a Terminal window, install the dependencies:

yarn

In a Terminal window, run the dev server:

yarn start

This will also watch your files and recompile on changes to any .js or .html files inside src/.

Development

Patterns are documented as FancyComponent instances inside src/app.js. Each FancyComponent is independent of the others and documents a separate use-case of one or more components or patterns. FancyComponent is fancy indeed; it knows how to render its children as literal HTML and how to escape and format that HTML for documentation purposes.

FancyComponent patterns are grouped together under a small number of DocPage components, which are how the side nav gets generated. The doc site code expects to see a route and title property on each DocPage. Each FancyComponent should have an id and title:

    <DocPage route="/foundations" title="Foundations">
      <FancyComponent id="typography" title="Typography">
          <p className="u-medium-text">Lorem ipsum</p>{"\n"}
 
          <p className="u-plain-label">Minim proident ex...</p>
          <h1>The quick brown fox jumps over the lazy dog.</h1>
        </FancyComponent>
    </DocPage>

Note the whitespace literal ({"\n"}) above. This is completely optional and just tells React to insert a newline in the doc HTML snippet (since the actual blank line in the JSX above will be collapsed when React renders the snippet).

Instead of FancyComponents, you can also use vanilla HTML elements inside a DocPage. As long as each on also has its own unique title and a unique id, it will be reflected in the nav structure and rendered like a normal element on the page. Use <section> elements for consistency's sake.

    <DocPage route="/" title="Getting Started">
        <section id="introduction" title="Introduction">
            <h2>Introduction</h2>
            <p>Lorem ipsum dolor sit amet.</p>
        </section>
        <section id="installation" title="Installation">
            <h2>Installation</h2>
            <code>npm install some-code</code>
        </section>
    </DocPage>

The main PatternLibrary component in charge of rendering the doc site parses the components and renders each DocPage.

To define a new component, just add a <FancyComponent> inside one of the DocPage components in src/app.js. You can also add any number of new DocPage components; just make sure to include a route and a title prop on each so that the navigation component knows how to render it and which URL it points to.

Full-page examples

For full-page examples that compose different components such as the login page, we need HTML pages that live outside the regular pattern nav structure. Here's how to add these examples:

Step 1: add a subdirectory under ./docs/examples

Each example gets its own directory inside ./docs/examples. An example can consist of just an index.html inside its own example directory, or it can get as complex as you want it to.

Step 2: Link to your example URL from PatternLibrary

To link to your example, just set up a new link inside the PatternLibrary component itself. Note the one in there for /examples/login already.

Step 3: Add a Netlify redirect

The local dev server that gets spun up with yarn start will serve the route /examples/my-example from the file at /docs/examples/my-example/index.html. However, for serving this on Netlify we need to be more explicit and add this route directly. In the netlify.toml file, add a route for your example before the final [[redirects]] block, so that the last two redirects look like:

[[redirects]]
  from = "/examples/my-example"
  to = "/docs/examples/my-example/index.html"
  status = 200
 
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

CSS Architecture

File Structure/Organization

• Settings (less/settings)

  • variables
  • normalize
  • mixins

• Generic (less/generic)

  • global styles- bare elements (headings, links, base none class name styles)
  • utilities - utilities and/or rules that should trump

• Objects (less/objects)

  • Structural elements such as flexboxgrid

• Components (less/components)

  • Individual component styles

app.less - primary source of all css pieces imported for compilation.

Custom font import would be included at the top of this file before all other less files

Naming Conventions- BEM

.block (primary part/component) .block__element (a child element that depends on block) .block--modifier (a modification to the default block)

NameSpacing

• Utility Classes: .u-utility{ … }
• Javascript Actions: .js-open-model
  • No styles should be associated with these classnames
• State: .is-state or .has-state
  • example: .has-error or .is-active
• Components: .c-btn, .c-nav-bar, .c-stat-card