Skip to main content

Contributing to Patterns

The following guidelines help you to contribute to Atlas’ patterns documentation.

Page Structure​

When you create a new pattern documentation page, use the following page structure:

<PageIntro>

## Purpose

## Anatomy

### Composition

### Child Componenents

### Variants

#### Variant A

#### Variant B

[...]

## Usage

## Behavior

### Behavior A

### Behavior B

[...]

## Examples

### Example A

### Example B

[...]
Outline of a Pattern documentation page

PageIntro​

This is a single introductionary paragraph describing the purpose of the pattern as briefly as possible. Use the <PageIntro> (documentation-)component to display your intro paragraph. Ideally, this paragraph should answer the reader’s question ”is this the correct pattern for my problem“.

<PageIntro>

  A page intro is a prominent introduction paragraph.

</PageIntro>
note

Please note that you need to include the leading and trailing extra line breaks, otherwise the MDX inside won’t render. This will be fixed with the upcoming release of MDX 2.

Purpose​

Use this section to further elaborate on the pattern’s purpose from the user- and designer/developer perspective.

Anatomy​

Composition​

This is where you describe the different parts of this composition (eg. header, body, footer, …). Use the <FigmaEmbed> (documentation-)component to embed a Figma artboard for visual reference.

If the pattern is rather loosely defined in terms of possible content, you may also include specifications for spacings and measurements in the visual example.

Ultimately, this section should answer the reader’s questions “How is this pattern composed“ and “Which parts are required, which parts are optional“. Think of it as simple building instructions.

Child Components​

Here you can list the set of possible components which the pattern may contain.

Variants​

If needed, list the different variants of your pattern here. Use a headline for each variant if it improves the structure of your page.

Usage​

This section is where you provide guidelines for layout and placement. Especially here, illustrations for Dos & Don’ts are helpful.

Behavior​

Describe how the pattern reacts to user interaction and different content. You want to answer questions like “How can users interact with this pattern (eg. resizing, expanding & collapsing, etc.)“ and “How does this look with a very long title or a lot of other content (eg. scroll on overflow, truncation)“.

Best Practices​

Add additional guidelines here which do not fit into any of the other sections. A series of Do & Dont illustrations might be a suitable format.

Examples​

Here you can provide code examples to copy & paste which developers can then further modify.

Make sure that there is also an artboard in Figma which ideally displays the same examples which designers can copy & paste and then further modify. To learn more, see the section Pattern Designs in Figma below.

note

You do not need to include every section listed here on your pattern documentation page. You may leave the ones out which do not apply, but you must not change the order of the sections.

You may also take a look at the existing Patterns documentation pages like eg. Tile for reference.

Pattern Designs in Figma​

All pattern examples and illustrations for documentation are inside Documentation Figma File, which you can find in the Atlas project.

Patterns Index​

On the page Patterns Index, we list examples for patterns — eg. different variations of Tiles. Each example must be placed on an individual artboard.

Patterns Documentation​

The page Patterns Documentation contains all sorts of other illustrations which we need for documentation, from pattern anatomy illustrations to do & donts.

Embed Figma Artboards on Documentation Pages​

Embeds and Branches

Figma scopes embed URLs to branches. This means that you probably only want to embed artboards directly from the master branch. This way you also make sure that the embeds display the latest updates.

You can embed any artboard onto documentation pages via Figma. To do so:

  1. In Figma, select the Frame you want to embed
  2. Click the share button in the toolbar
  3. Press Copy Link
  4. Now you have the complete sharing URL in your computer’s clipboard

When you edit a documentation page, you can embed the frame now. To do that, use the <FigmaEmbed> component. In the very beginning of your page, right after the metadata, make sure you have this line:

---
id: some id
title: some title
---

import { FigmaEmbed } from '../../src/components/FigmaEmbed';

Now, at the very place where you wish to embed the artboard, include this line:

<FigmaEmbed embedUrl="xxx" width="yyy" height="zzz" />

You can paste the embed url which you copied from Figma below. It will look like this:

https://www.figma.com/file/TEHijB0j0gxT9AVKInGuSo/Documentation?node-id=2%3A2

Your code should look like this:

<FigmaEmbed
  embedUrl="https://www.figma.com/file/TEHijB0j0gxT9AVKInGuSo/Documentation?node-id=2%3A2"
  width="768"
  height="544"
/>

Whenever you make changes to this Figma file, the embed on the page will automatically update!