Style Guide
Sure, there are seemingly infinite ways you can customize page content, but try not to get carried away. These guidelines are meant to keep page content and component usage visually consistent across this site, which improves the overall user and reader experience.
Above all else, be consistent.
For a broader overview of all components, check out the Component Palette. For more information about using components in MDX, read our other tutorials on Crafting Technical Content.
Buttons
Buttons communicate actions that users can take.
All buttons should
- Start with an “action” verb
- Use sentence case
- Express what action will occur when the button is clicked
Primary (solid) buttons should be used for highest priority actions.
Secondary (solid) buttons should be used for high priority actions, alongside a primary button.
Outline buttons should be used for medium priority actions alongside primary buttons.
Icons can be added to any button and should be used to visually emphasize a button's action.
Things to avoid:
- Using more than one icon in a button
- Using two of the same kind of button side by side
Buttons vs. Links
Links are mostly used for navigation purposes (as opposed to actions), and usually appear within a sentence or directly following. Links are used to navigate to a different page in the site, navigate to a different site, or jump to an element on the same page.
Lists
Lists are a continuous collection of related text or external links. List items have two parameters, 1-line/2-line and link/no link.
1-line, no link
List item
List item
List item
1-line, link
2-line, no link
List item
Sub content
List item
Sub content
List item
Sub content
2-line, link
List items should start with a capital letter and be written in sentence case.
Things to avoid:
- putting 1-line list items in the same list as 2-line list items, and vice versa.
- putting a list item with no link in the same list as list items with links, and vice versa.
- putting a list inside a call-out, tout, or 2-column comparison.
In the event that you need to list multiple ideas within a 2-column comparison, use a default, unstyled unordered list.
Lists can go inside process steppers and accordions, where it is appropriate to have more content.
List components vs. unstyled, unordered lists
List components should be used for collections of links, events, or other series of related, actionable content.
Unstyled, unordered lists should be used for series of ideas that are directly connected to the text preceding, as seen in this style guide.
Status Banners
Status banners are concise, high-priority alerts that appear at the top of a page. Status banners are meant to catch a user’s attention quickly before proceeding to page content. Status banners can contain optional action items in the form of text buttons.
Status banners should be used for messaging that informs or changes how a user will interact with the entirety of the page’s content, as it is the first thing the user will see (e.g. “Funding is closed” on a page about how to get funding). Think of a status banner as a preface to the page content, or a “before you proceed.”
Status banners should be placed below breadcrumbs and above the page header and be succinct, focused, and only contain one message.
Funding for projects is closed until September 1, 2020
Things to avoid:
- Using status banners inside other components (touts, lists, two-column comparison, chocolate box, etc.)
- Using more than one status banner per page
Callouts
Callouts are highlighted blocks of text used to highlight medium-priority information within a page’s content. Callouts are meant to be helpful without being too disruptive.
Callouts shoud clearly articulate the benefit of the feature and what it does and use icons to help communicate.
This is a callout with the (specified) secondary style and the "search' icon from dai-ui-icons!
Touts
Touts are cards of content used to highlight high or medium priority information. A primary use case for touts is guiding a reader to relevant information on another page.
Working on a bounty
See what's expected of you if you work on a Maker community bounty.
2-column text
Two-column comparisons are a way to organize content that fits into two distinct, mutually exclusive, but related categories, most often for the purpose of comparison. Two-column text helps make important, text-only content more digestible and connected.
Writer
Writers take initial notes, screenshots, and fix notes in post-editing with the availability of the recording.
We recommend at least two people do this role, splitting up the work for the entire summary. Multiple writers have the advantage of supporting each other with formatting, screenshots, and quality assurance on sections that they are not taking the initial notes on.
Reviewer
Reviwers set up the initial working doc, do a full review of the summary after it's produced, quality check for formatting and semantic errors, and also submit the final version of the summary to GitHub and the Forum. Recommended to be done by one person.
Accordion
Accordions are used to organize and condense content that does not need to be displayed on page load. This allows users to opt into seeing expanded based on their headers, which shortens scrolling through nonessential information.
Accordions should generally have three or more "folds." In the case of there being only two folds, a two-column comparison will likely suffice.
An ideal use case for accordions is FAQs, or series of questions and answers.
How should I format the headers of my accordion?
Can I change the icons at the end of my accordion?
Can I include other components inside an accordion?
Process stepper
Process steppers are numbered lists that make important or complicated processes more digestible.
1
Step 1
Make sure the headers and content of every step are formatted the same.
2
Step 2
Add your content! You can nest components inside of here if they further simplify instructions, though be wary of convoluting information with frivolous components.
3
Step 3
Admire your process stepper!