Something missing? Suggest a change or addition

How to contribute

We hope that this guidebook will become a resource that is collaboratively maintained and improved by the community.

This website is published under an open licence, for anyone to access, use and share. The full source code is available on github.

To help this website grow and adapt to user needs, we are happy to take suggested updates and contributions from the community.

Here are some ways in which you might contribute:

  • suggest a new pattern that we could add to the catalogue
  • suggest an alternative name for an existing pattern
  • submit wording improvements to any of the existing site content, for example to improve the discussion around a specific pattern
  • submit new patterns for us to add to the catalogue, using the template below
  • submit other improvements to the website layout, e.g. to improve accessibility or readability
  • discussing changes submitted or suggested by others in the github project.
  • send us feedback at and tell us what you think of the pattern catalogue and whether you have used it in a project

You can make suggestions or submit content by creating a github issue in the project. Or by submitting a pull request if you are happy using git.

Feel free to also add to the discussion around a suggestion or submission by contributing to the discussion in the list of submitted issues or pull requests.

Pattern Template

All of the patterns in this website use the following template. Use the structure and notes to help you write and submit new patterns.

  • Problem
    • should be a statement, or possibly a question if a statement doesn’t work
    • the problem statement should ‘describe the visible manifestation of something wrong’ and not presuppose the solution
  • Context
    • explains when to use this pattern
  • Solution
    • provides a solution that answers the problem
  • Discussion
    • provide more background and detail to the proposed solution
    • a good discussion will introduce some of the underlying causes for the problem and may add more in-depth ideas around implementation of the solution
    • the discussion might also address edge cases, outliers, or design trade-offs, for example when you might instead apply an alternative pattern
  • Related patterns
    • a short list of related patterns, for example those that are essential to implementing the solution or offer useful variations

To help you draft your patterns, our recommendations are that

  • patterns should be approximately 300 words in length
  • use short sentences, bullet points for lists, chunk the content, and make it skimmable
  • test the fitness of your proposed pattern by checking that the pattern is successful - ie solution matches problem
  • test the usefulness of your proposed pattern by checking that the pattern explains why it is successful and beneficial
  • provide real world examples so we can be sure it is an existing solution, not an idea
  • cross-reference other patterns and include their names in bold with hyperlinks

Something missing? Suggest a change or addition