Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: added pattern template #255

Merged
merged 5 commits into from
Sep 6, 2019
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions docs/pattern-template.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
title: Pattern title
---

<PageDescription>

Include a short description of your pattern. This header should be longer than one line and no longer than four.

</PageDescription>

<AnchorLinks>
<AnchorLink>Overview</AnchorLink>
<AnchorLink>Behavior guidance</AnchorLink>
<AnchorLink>Assets</AnchorLink>
<AnchorLink>References</AnchorLink>
<AnchorLink>Metadata</AnchorLink>
</AnchorLinks>

### Overview

**Define the use of your pattern with a problem statement.** Explain a user's needs and how the pattern meets those needs. Communicate anything a designer needs to know about the pattern.

**Show a high-level image of the pattern in use.** The pattern should be presented in context and include a caption.

### Behavior guidance

**Include guidance on interactions and states.** Most patterns depend on interactions with components. Include guidance on motion, behavior, and states of the components.

**Use visuals wherever possible.** Show a user's flow through your pattern with images of your product at each step of the way.

### Assets

**Include any resources and references.** Attach and document any page templates, design specifications, and design software assets.

**Document how a user would navigate your pattern.** Provide documentation to make onboarding and use easier.

**Create a functional prototype.** The best way to prove your pattern solves a problem is to let designers test it. A link to the actual implementation is best, and a demo is also valuable.

### References

**Explain any accessibility testing you conducted.** No individual component or pattern can be accessible, but they can be used in an accessible way to create an accessible experience. Include any research and proof you may have in your pattern documentation.

**Include any citations.** Research, books, and articles you found helpful offer legitimacy to your pattern and help designers understand your decisions.

**Offer any development notes you may have.** Many patterns don't require specific developer attention to implement. If you have any developer guidance, include it here.

### Metadata 

**Include a list of components used in the pattern.** Link to where where each component is documented.

**Link to any related patterns.** This may not be the right pattern for a designer's problem, but other closely related patterns might be helpful.

**Link to the maintainer's GitHub profile.** GitHub is the best way to ask questions and provide feedback about the pattern.

**Communicate what happens next.** If there are any outstanding issues or gaps, include those here. Ask for help if you need it, and be transparent about the completeness of the pattern.
2 changes: 1 addition & 1 deletion src/pages/contributions/documentation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Before you get started, take a moment to review our content guidelines. Followin

### Use Markdown

The website is written in Markdown, which makes it easy for anyone to contribute content in a systematic way. If you don't already have a Markdown editor installed, there are plenty of free editors available online.
The website is written in [Markdown](https://gatsby-theme-carbon.now.sh/components/markdown/), which makes it easy for anyone to contribute content in a systematic way. If you don't already have a Markdown editor installed, there are plenty of free editors available online.

Check out Carbon's handy markdown [styling cheatsheet](https://github.com/carbon-design-system/carbon-website/wiki/Markdown-cheatsheet) for how to style content.

Expand Down
2 changes: 1 addition & 1 deletion src/pages/contributions/pattern.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Explain how your pattern will address user needs and solve a problem. Carbon ser

#### 6. Document the pattern

- Document pattern guidelines and usage to be used on the site, being sure to include the context and the rationale for any choices.
- Use the [pattern Markdown template](https://github.com/carbon-design-system/carbon-website/blob/master/docs/pattern-template.mdx) to document pattern guidelines and usage to be used on the site. Be sure to include the context and the rationale for any choices.
- The site [documentation](./documentation) should include your contextual images and step-by-step instructions that allow designers to effectively implement your pattern.

#### 7. Prepare for experimental release
Expand Down