Patterns
Patterns are best practice solutions for how a user achieves a goal. They show reusable combinations of components and templates that address common user objectives with sequences and flows.
First steps to contributing
If you’ve designed a pattern that is not currently in Carbon, contributing it back allows others in the community to refine and use your pattern in their projects.
Start by opening a Github issue. Include a detailed description in which you:
- Define your pattern and explain the rationale
- Include mockups and/or prototypes of any fidelity
- Clarify whether it uses existing components, new components, or both
- Include competitive and comparative analysis, and any inspirations from other products
This issue will be the staging ground for the pattern contribution, and you should expect the Carbon core team and the community to weigh in with suggestions.
We encourage you to surface work in progress. If you’re not able to complete all of the parts yourself, someone in the community may be able to help.
How to write a pattern
These guidelines are to help you prepare a complete and comprehensive pattern for submission to the IBM Design System. Depending on the pattern, you may need to make some adjustments to the structure but your pattern should cover all of the aspects outlined below.
We’ve also created a Markdown file that includes this guidance. Alternatively, you can provide your content to us in a Box note.
Overview
This section answers the question: “What problem does this pattern solve?”
- Define the use of your pattern and what it does.
- Explain a user’s needs and how the pattern meets those needs.
Anatomy
Include an image with callouts explaining each part of the pattern.
Show pattern in visual form
When to use
Include a short list describing situations where this pattern could be applied.
For example, use this pattern when:
- Situation 1
- Situation 2
When not to use (optional)
If required, include a short explanation about when not to use this pattern.
The solution
This section explains the pattern in detail. Use a combination of written explanations and visuals to tell the story.
Behaviors, structure, and functionality
- Describe the elements, components, and content that make up the pattern.
- Describe pattern behaviors, including guidance on interactions, and changes in states and content.
- Show the pattern in context. Use visuals throughout your written commentary to illustrate your guidance.
Different patterns require different visuals to best explain the behaviors and hierarchy. Choose the options that make the most sense for the story you are telling. See our production guidelines for information about creating assets for the IBM Design System.
- Use annotated wireframes or sketches to explain the visual hierarchy of components.
- Create high-level user flows to explain the big picture.
- Create a functional prototype if that is the best way to illustrate the pattern’s behavior.
Provide a Sketch file with any symbols you’ve created in the development of this pattern.
Best practices
List out best practices and include any design considerations that help with making choices.
- Do’s
- Dont’s
Other use cases
If there are use cases that require a different solution, include those here with corresponding explanations and visuals. Be sure to explain the reasons for using one solution over another.
Accessibility
Evaluate your pattern to ensure it meets accessibility standards and guidelines, and provide details of compliance.
For example, “Users should be able to TAB into the input field of the search box to begin typing and press ENTER to run the search query.”
Related
Which components did you use when building this pattern? Did you reference other patterns? List them here.
If necessary, clarify any differences between this pattern and related patterns.
References
Help designers understand your process by explaining your rationale for the way you implemented the pattern. Include any research, citations, books or articles that you found helpful.
Feedback
Help us improve this pattern by providing feedback, asking questions, and leaving any other comments on GitHub.