Styleguides - A Quick Intro

Styleguides are a reference library for developers and designers to help make the application experience consistent and predictable. They also surface challenges early so future work can follow already established best practices.

Below is a basic styleguide with my thoughts on key decisions to consider to avoid pitfalls as your site scales up.


Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6
  1. Header tags play an important role in SEO and you don't want to conflate those decisions with stylistic choices.
  2. It's useful to reset the browser's default heading styles for that reason
  3. You can add a class such as heading--1 to h1 and style against the class
  4. It's recommended to not use classes such as "h1" to avoid confusion
Typography Styles & Buttons
Title Text
Subtitle Text

Standard paragraph text

Another paragraph of standard text

Title Text
Subtitle Text

Standard paragraph text

Another paragraph of standard text

  1. This is one of the most common layouts of text with an eyebrow, title, subtitle, and a paragraph of text followed by button(s).
  2. This pattern of text is used with any combination of elements to display a myriad of content.
  3. Buttons are usually primary, secondary, and action oriented.
  4. Links are similar to buttons but with lower emphasis.
  5. Some common examples would be a primary being dark with light text, secondary being the inverse (light background with dark text), and action links being underlined or having a suffixed icon.
  6. Button and anchor tags should be interchangeable, or anchor tags should use role="button" when appropriate. This accounts for instances where href="#" would be used instead, because of the impact to the accessibility experience.
  7. When creating buttons, consider using an inner span and the inline-flex display property on the parent. This allows for better styling of multi-line buttons, such as when content is translated.
  1. A color palette should be designed around a color scheme. The 4 major ones are monochromatic, adjacent, triad, and tetrad.
  2. Color schemes bring together a collective theme and play an important psychological role in the perception of the experience.
  3. There are multiple free online color palette generators that will create the palettes for you using a base color.
  1. SVGs only.
  2. Use mask, mask-size, and background color CSS properties to change SVG color dynamically.
  3. CSS mask requires a vendor prefix as of today. Manually add vendor prefixes or automatically insert them with your build pipeline.
  4. Unless the icon provides additional context, you might want to set aria-hidden="true" to the icon. Instead, add a descriptive aria-label to the original button for screen readers.