From 33d8a2a91c7ae7b87f0cdd5e14487b82943496be Mon Sep 17 00:00:00 2001 From: Jeremy White Date: Mon, 16 Sep 2024 16:59:52 -0400 Subject: [PATCH] feat(style-guide): added more summaries --- docs/reference/style-guide.mdx | 43 ++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/reference/style-guide.mdx b/docs/reference/style-guide.mdx index 28082250e..0056bbb38 100644 --- a/docs/reference/style-guide.mdx +++ b/docs/reference/style-guide.mdx @@ -173,6 +173,8 @@ Components in Docusaurus need to be imported before they can be used. Some compo ### ActionCard and PrimaryCTA/SecondaryCTA +ActionCard components are used to display a card with a title, description, and a call to action. These 'actions' are typically anchors that link to other pages. + ``` ``` @@ -203,6 +207,8 @@ Components in Docusaurus need to be imported before they can be used. Some compo ### AtmosWorkflow +The AtmosWorkflow component is used to embed Atmos workflows into the documentation. These are workflows that can be run from the Atmos CLI, but often have important details and could be run as a sequence of steps instead. You can use this component to not only document the workflow, but also expose the sequence of commands it uses for better describing how the workflow works. + ``` @@ -214,6 +220,8 @@ Components in Docusaurus need to be imported before they can be used. Some compo ### CardGroup +CardGroup is used to display a group of cards in a row. Cards are mostly helpful for controlling text flow and mobile presentation where content should reflow rigidly. + ``` @@ -230,14 +238,18 @@ Components in Docusaurus need to be imported before they can be used. Some compo ### CategoryList +CategoryList is used to display a list of pages in a category. This is useful for showing a list of tutorials or other related pages. + ``` - + ``` - + ### CollapsibleText +The collapsible text component can display an excerpt of a large body of text, helping conserve scroll space and allowing a reader to skim over the content. Note: this is really for a large body of text, and will likely not show a significant effect on smaller amounts (i.e. < 3 paragraphs of text). + ``` [body of content] @@ -252,6 +264,8 @@ Components in Docusaurus need to be imported before they can be used. Some compo ### Definition +The Definition component can show a term and, when clicked, also its definition. + ``` ``` @@ -263,6 +277,8 @@ If you need to make a new term, add it to the glossary first. ### DismissibleDialog +DismissibleDialog components can be used for showing content that should only be needed once (like a notification during page events). + ``` This is the content of the dialog. @@ -275,6 +291,8 @@ If you need to make a new term, add it to the glossary first. ### DocCardList +DocCardList components are used for listing related content as clickable cards. + ``` ` component can be used without `items` ### Intro +Intro components are used to introduce a section of content. They create a `div` with the `intro` class. You can use styles to make these stand out more and help draw the reader in to summaries. + ``` This is the content of the intro. @@ -325,6 +345,8 @@ It's worth noting that the `` component can be used without `items` ### KeyPoints +Keypoints components style an unordered list. They'll wrap content in a `key-points` class and create a heading for the title. + ``` - 'Reusable Terraform "Root" Modules for AWS' @@ -339,6 +361,8 @@ It's worth noting that the `` component can be used without `items` ### Note +Notes are designed to be less distracting than admonitions, but still draw attention to important information. Use them for expressing nuance. + ``` This is the content of the note. @@ -351,6 +375,8 @@ It's worth noting that the `` component can be used without `items` ### PillBox +Pillboxes are purely decorative, wrapping text in a pill-shaped box. They can be used to draw attention to a topic or to create a visual break in the content. + ``` Here's a new topic ``` @@ -359,6 +385,8 @@ It's worth noting that the `` component can be used without `items` ### Slider +A Slider will take over the content and sidebar of a page, turning it into a slideshow. Slides are defined by the `` component. This component does not play well with any other compnents that affect or consume the sidebar and other navigation data. + ``` @@ -378,6 +406,8 @@ Slider's can't be demonstrated in a normal page since they take over the table o ### Steps +Steps components can style a list of steps. While you should use lists for organizing most content, prefer to use `Steps` when describing an operation or process. + ``` @@ -408,6 +438,8 @@ Slider's can't be demonstrated in a normal page since they take over the table o ### Tabs +Tabs are used for hiding content based on a context, such as steps in an install or configuration of a service. They should be used when users can either ignore details that are out of context, or for organizing the scope of information on a topic. + ``` @@ -428,9 +460,12 @@ Slider's can't be demonstrated in a normal page since they take over the table o +**Note**: Setting the `queryString` prop to a unique value will allow the tabs to be bookmarked. This can help with navigation, syncing other tabs on the same page, or linking from other pages. + ### TaskList Task lists turn any ordered or unordered list into an interactive checklist that saves its state in the local browser cache. + ``` @@ -450,6 +485,8 @@ Task lists turn any ordered or unordered list into an interactive checklist that ### Terminal +Terminals are a decoration which streses when a command is being run in a terminal. They are not interactive, but can be used to show a sequence of commands. + ``` @@ -468,6 +505,8 @@ Task lists turn any ordered or unordered list into an interactive checklist that +**Note**: Contents are only wrapped, so they should be in a code block if you want monospace text. + ## Conformance and Best Practices - Do not use `
` for spacing. Instead, update the CSS