Skip to main content

Guideline Writing

In this document we share some pointers for writing good guidelines and keeping them consistent with the rest.

Introduction text​

Place an intro text at the beginning of the component's main page, giving an easy-to-scan brief to help understanding its purpose.

Pro tip: try starting your sentence with "The component's purpose is…" or "It enables marketers to…" to get yourself on the right track.

Example:

The Action List component displays a list of related action items, enabling marketers to choose an action in context with immediate effect.

  • Do: Use active voice.

    Use radio button to display each item in a list of options, where marketers have to make a single choice.

  • Do: Use passive voice with persona.

    Radio buttons are used to give marketers a way to select one single choice out of a list of options.

  • Don't: Make the intro text longer than 3–4 sentences.

Guidelines document​

Guidelines are documents which help designing with the component.

Structure​

Describe atoms and other components that build up this component. Naming parts should generally follow naming of the atoms and be aligned with naming in code.

  • Do: Start with [Component name] consists of: and add a numbered list.

Best practices​

Write out everything important about the component, mostly focusing on behaviour.

  • Do: Start with [Component's name] should: and finish the sentence in a bulleted list.

    Radio buttons should:

    • Let the user select only one choice from a list of options.
    • Have their labels positioned on the right side of the selectors.

  • Do: Start with Try to avoid: and finish the sentence in a bulleted list.

    Try to avoid:

    • Sorting items in alphabetical order.
    • A large number of options — use Select instead.

Clarify confusing concepts​

  • Radio button: Select a single choice from a limited set of options.
  • Checkbox: Select or deselect multiple choices from a limited set of options.
  • Select: Select a single item from an expandable dropdown list.

Content guidelines​

Provide guidelines for making content and include positive and negative examples where possible.

Radio button labels should:

  • Start with a capital letter.
    • ✓ Option 1
    • ✗ option 1

Writing style​

Lists​

Give context to a list with a leading sentence ending in a colon.

Sentence-like list items should be punctuated. Word list items should not.

Spelling​

Use American spelling: personalization, color, organize, gray, etc.

Capitalization​

  • Capitalize component names in a sentence like a proper noun.

    Use the Button to enable the marketer to trigger an action.

  • Section headings should use sentence case.

Abbreviations​

  • e.g. (not eg.)
  • i.e. (not IE)
  • etc. (not et.c.)