Website Content Organization

apps/website/src/pages/docs/alert.mdx

@@ -25,36 +25,36 @@ The alert message must be concise, we recommend no more than 256 characters. If
 
 ### Informational
 
+Default style when there is no defined status for the alert. Inform users about events that they should be aware of, but that are not disruptive to their work.
+
 <LiveExample src='Alert.informational.tsx'>
   <AllExamples.AlertInformationalExample client:load />
 </LiveExample>
 
-Default style when there is no defined status for the alert. Inform users about events that they should be aware of, but that are not disruptive to their work.
-
 ### Positive
 
+The positive alert is used to inform the user of a positive status.
+
 <LiveExample src='Alert.positive.tsx'>
   <AllExamples.AlertPositiveExample client:load />
 </LiveExample>
 
-The positive alert is used to inform the user of a positive status.
-
 ### Warning
 
+The warning alert is used to inform the user of something that is not currently disruptive to their work, but may be soon or eventually.
+
 <LiveExample src='Alert.warning.tsx'>
   <AllExamples.AlertWarningExample client:load />
 </LiveExample>
 
-The warning alert is used to inform the user of something that is not currently disruptive to their work, but may be soon or eventually.
-
 ### Negative
 
+Use this only when the system is broken. Leave the technical details behind and explain the problem to the user in an easily understood tone. Mention when the problem might get solved, if it applies.
+
 <LiveExample src='Alert.negative.tsx'>
   <AllExamples.AlertNegativeExample client:load />
 </LiveExample>
 
-Use this only when the system is broken. Leave the technical details behind and explain the problem to the user in an easily understood tone. Mention when the problem might get solved, if it applies.
-
 ### Multilines
 
 All alerts may support multiple lines if necessary. We recommend keeping it brief and keep the message as concise as possible.
@@ -65,22 +65,22 @@ The alert notification can display in two different ways:
 
 ### Inline
 
+An inline alert appears embedded within the copy of the site as a block element. This means that when the user scrolls, the alert scrolls as well.
+
 <LiveExample src='Alert.inline.tsx'>
   <AllExamples.AlertInlineExample client:load />
 </LiveExample>
 
-An inline alert appears embedded within the copy of the site as a block element. This means that when the user scrolls, the alert scrolls as well.
-
 Inline alerts can optionally be dismissible. Once the alert is dismissed, the content below it will shift upwards due to the alert no longer consuming space.
 
 ### Sticky
 
+A sticky alert appears full width stuck at the top of the window frame. That means if the user scrolls, the alert stays at the top of the frame and as the content scrolls underneath it. A sticky alert must always be dismissible. The alert appears above all other UI elements except for toast notifications and modals.
+
 <LiveExample src='Alert.sticky.tsx'>
   <AllExamples.AlertStickyExample client:load />
 </LiveExample>
 
-A sticky alert appears full width stuck at the top of the window frame. That means if the user scrolls, the alert stays at the top of the frame and as the content scrolls underneath it. A sticky alert must always be dismissible. The alert appears above all other UI elements except for toast notifications and modals.
-
 It is up to the development team wether or not the sticky alert should push the rest of the content down or not.
 
 ## Props

apps/website/src/pages/docs/blockquote.mdx

@@ -21,12 +21,12 @@ Blockquotes are used to isolate and highlight a large quotation made by a source
 
 ## Usage
 
+If the citation was pulled from a website, you can provide the URL using the 'cite' tag for best practice purposes, but the blockquote does not provide a hyperlink to that location.
+
 <LiveExample src='Blockquote.footer.tsx'>
   <AllExamples.BlockquoteFooterExample client:load />
 </LiveExample>
 
-If the citation was pulled from a website, you can provide the URL using the 'cite' tag for best practice purposes, but the blockquote does not provide a hyperlink to that location.
-
 ## Props
 
 <PropsTable path={frontmatter.propsPath} />

apps/website/src/pages/docs/button.mdx

@@ -29,97 +29,97 @@ In some cases, buttons can also be used in place of href links to draw special a
 
 ### Default
 
+The default button should be used in most circumstances. If you are unsure as to what button to use, use this button!
+
 <LiveExample src='Button.default.tsx'>
   <AllExamples.ButtonDefaultExample client:load />
 </LiveExample>
 
-The default button should be used in most circumstances. If you are unsure as to what button to use, use this button!
-
 ### High visibility
 
+This is the button to emphasize an action applicable to an area of the page or a [dialog](dialog). High visibility buttons are used to draw the user’s attention to the main action of the page.
+There should only be one high visibility button per area of the user interface.
+
 <LiveExample src='Button.highvisibility.tsx'>
   <AllExamples.ButtonHighVisibilityExample client:load />
 </LiveExample>
 
-This is the button to emphasize an action applicable to an area of the page or a [dialog](dialog). High visibility buttons are used to draw the user’s attention to the main action of the page.
-There should only be one high visibility button per area of the user interface.
-
 ### Call-to-action
 
+The call-to-action button, also referred to as the CTA, is the button that is used for most full page layouts and whole-page overlays (think Next in [stepper](stepper) interactions). This is the biggest and most noticeable button.
+One call-to-action button per visible page is the rule. Treat it as a large, “CLICK HERE” guide for the user.
+
 <LiveExample src='Button.cta.tsx'>
   <AllExamples.ButtonCTAExample client:load />
 </LiveExample>
 
-The call-to-action button, also referred to as the CTA, is the button that is used for most full page layouts and whole-page overlays (think Next in [stepper](stepper) interactions). This is the biggest and most noticeable button.
-One call-to-action button per visible page is the rule. Treat it as a large, “CLICK HERE” guide for the user.
-
 ### Borderless
 
+The borderless button is useful in tighter areas where using a default button would visibly cause too many boxes.
+
 <LiveExample src='Button.borderless.tsx'>
   <AllExamples.ButtonBorderlessExample client:load />
 </LiveExample>
 
-The borderless button is useful in tighter areas where using a default button would visibly cause too many boxes.
-
 The borderless button is often used by actionable icons in relation to another component.
 They are commonly used within [table](table) rows and widgets.
 
 ### Size
 
+There are 3 different sizes available, which can be applied to any button. The medium size is a default and should always be the first choice, unless there are good reasons to use the small or large version.
+
 <LiveExample src='Button.size.tsx'>
   <AllExamples.ButtonSizeExample client:load />
 </LiveExample>
 
-There are 3 different sizes available, which can be applied to any button. The medium size is a default and should always be the first choice, unless there are good reasons to use the small or large version.
-
 ## Button props
 
 <PropsTable path={frontmatter.propsPathDefault} />
 
 ## Split button
 
+Pressing the left side of this button will commit the action. Pressing the right side of the button will open a menu.
+
 <LiveExample src='SplitButton.main.tsx'>
   <AllExamples.SplitButtonMainExample client:load />
 </LiveExample>
 
-Pressing the left side of this button will commit the action. Pressing the right side of the button will open a menu.
-
 ### Props
 
 <PropsTable path={frontmatter.propsPathSplitButton} />
 
 ## Dropdown button
 
+Pressing this button will always open a menu. Upon selecting an option from the menu, the action immediately takes place. The menu button should only be styled as default buttons and borderless buttons.
+
 <LiveExample src='DropdownButton.main.tsx'>
   <AllExamples.DropdownButtonMainExample client:load />
 </LiveExample>
 
-Pressing this button will always open a menu. Upon selecting an option from the menu, the action immediately takes place. The menu button should only be styled as default buttons and borderless buttons.
-
 ### Props
 
 <PropsTable path={frontmatter.propsPathDropdownButton} />
 
 ## Icon button
 
+Icon button gives the icon the correct styling as well as adds some clickable padding within the button, ensuring icons meet the necessary touch target size.
+
 <LiveExample src='IconButton.main.tsx'>
   <AllExamples.IconButtonMainExample client:load />
 </LiveExample>
 
-Icon button gives the icon the correct styling as well as adds some clickable padding within the button, ensuring icons meet the necessary touch target size.
-
 ### Props
 
 <PropsTable path={frontmatter.propsPathIconButton} />
 
 ## Ideas button
 
+The Ideas button is unique and should only be used under certain circumstances. You will need to perform an audit of your application to ensure that the feedback button does not cover / obscure any tools.
+
 <LiveExample src='IdeasButton.main.tsx'>
   <AllExamples.IdeasButtonMainExample client:load />
 </LiveExample>
 
-The Ideas button is unique and should only be used under certain circumstances. You will need to perform an audit of your application to ensure that the feedback button does not cover / obscure any tools.
-
 If the button does obscure anything important, we suggest adding empty space at the bottom of the page so the user can scroll far enough down that the button doesn’t overlap the underlying tools.
 
 ### Props

apps/website/src/pages/docs/checkbox.mdx

@@ -27,54 +27,54 @@ A checkbox is not interchangeable with a [radio](radio). A radio must have at mi
 
 ### Default
 
+The default checkboxes are used to turn on and off one or multiple options.
+
 <LiveExample src='Checkbox.indeterminate.tsx'>
   <AllExamples.CheckboxIndeterminateExample client:load />
 </LiveExample>
 
-The default checkboxes are used to turn on and off one or multiple options.
-
 ### Visibility
 
+Often times checkboxes are used to visibly turn on and off a layer within a view. If the checkboxes are used for visibility you can use the eyeball variant which uses an eyeball icon instead of a checkmark to reinforce that something is being shown or hidden.
+
 <LiveExample src='Checkbox.visibility.tsx'>
   <AllExamples.CheckboxVisibilityExample client:load />
 </LiveExample>
 
-Often times checkboxes are used to visibly turn on and off a layer within a view. If the checkboxes are used for visibility you can use the eyeball variant which uses an eyeball icon instead of a checkmark to reinforce that something is being shown or hidden.
-
 ## Usage
 
 ### With input group
 
+Checkboxes are often paired with the [input group](inputgroup) which gives many additional options.
+
 <LiveExample src='Checkbox.inputgroup.tsx'>
   <AllExamples.CheckboxInputGroupExample client:load />
 </LiveExample>
 
-Checkboxes are often paired with the [input group](inputgroup) which gives many additional options.
-
 ### Indeterminate
 
+When a main option has associated sub-options, parent-child checkboxes are used. They make selecting/unselecting the entirety of a list of options easier if all or neither of them apply to a user’s choice. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.
+
 <LiveExample src='Checkbox.indeterminate.tsx'>
   <AllExamples.CheckboxIndeterminateExample client:load />
 </LiveExample>
 
-When a main option has associated sub-options, parent-child checkboxes are used. They make selecting/unselecting the entirety of a list of options easier if all or neither of them apply to a user’s choice. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.
-
 ### Loading
 
+If the checkbox is performing an action immediately after being checked, it may take the user interface some time before reflecting that change. While waiting for that change to occur you can display a loading checkbox so the user understands that the action taken has yet to be applied.
+
 <LiveExample src='Checkbox.loading.tsx'>
   <AllExamples.CheckboxLoadingExample client:load />
 </LiveExample>
 
-If the checkbox is performing an action immediately after being checked, it may take the user interface some time before reflecting that change. While waiting for that change to occur you can display a loading checkbox so the user understands that the action taken has yet to be applied.
-
 ### Statuses
 
+If you ever need to display the status or severity of a single checkbox, you can apply a status on the checkbox. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
+
 <LiveExample src='Checkbox.statuses.tsx'>
   <AllExamples.CheckboxStatusesExample client:load />
 </LiveExample>
 
-If you ever need to display the status or severity of a single checkbox, you can apply a status on the checkbox. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
-
 ## Props
 
 <PropsTable path={frontmatter.propsPath} />

apps/website/src/pages/docs/nonidealstate.mdx

@@ -48,60 +48,60 @@ Potential causes other than invalid credentials;
 - Page loaded incorrectly;
 - Mistake on the site owner’s side.
 
+A 403 error means the client encountering it is completely forbidden from accessing the page. In this case, the user cannot do much to resolve it, as the resource is accessible only by the authorized parties.
+
 <LiveExample src='NonIdealState.forbidden.tsx' truncate={false}>
   <AllExamples.NonIdealStateForbiddenExample client:load />
 </LiveExample>
 
-A 403 error means the client encountering it is completely forbidden from accessing the page. In this case, the user cannot do much to resolve it, as the resource is accessible only by the authorized parties.
-
 ### Error 500
 
+Also called Internal Server Error, a 500 error code means something went wrong with the website’s server, but it is unable to identify what caused the issue. More often than not, the error is on the user’s side.
+
 <LiveExample src='NonIdealState.internalerror.tsx' truncate={false}>
   <AllExamples.NonIdealStateInternalErrorExample client:load />
 </LiveExample>
 
-Also called Internal Server Error, a 500 error code means something went wrong with the website’s server, but it is unable to identify what caused the issue. More often than not, the error is on the user’s side.
-
 ### Error 502
 
+Error code 502 is a Bad Gateway error. This means the communication between two servers resulted in an error, leading to a deadend. The user has no control over this error as it happens when there is a miscommunication between online servers.
+
 <LiveExample src='NonIdealState.badgateway.tsx' truncate={false}>
   <AllExamples.NonIdealStateBadgatewayExample client:load />
 </LiveExample>
 
-Error code 502 is a Bad Gateway error. This means the communication between two servers resulted in an error, leading to a deadend. The user has no control over this error as it happens when there is a miscommunication between online servers.
-
 ### Error 503
 
+Service Unavailable is the issue you get from a 503 error. It means the online server has encountered a problem because the network is unavailable (internet connection was interrupted), and thus cannot fulfill the request. The user cannot do anything about this issue.
+
 <LiveExample src='NonIdealState.serviceunavailable.tsx' truncate={false}>
   <AllExamples.NonIdealStateServiceunavailableExample client:load />
 </LiveExample>
 
-Service Unavailable is the issue you get from a 503 error. It means the online server has encountered a problem because the network is unavailable (internet connection was interrupted), and thus cannot fulfill the request. The user cannot do anything about this issue.
-
 ### Timed out
 
+For security reasons, certain web sessions will automatically sign a user out when they remain inactive for a few minutes. The user must then renew the session. This process may or may not require that they re-enter their credentials to resume; this is at developer’s discretion.
+
 <LiveExample src='NonIdealState.timeout.tsx' truncate={false}>
   <AllExamples.NonIdealStateTimeoutExample client:load />
 </LiveExample>
 
-For security reasons, certain web sessions will automatically sign a user out when they remain inactive for a few minutes. The user must then renew the session. This process may or may not require that they re-enter their credentials to resume; this is at developer’s discretion.
-
 ### Generic error
 
+Used in any error that isn’t discussed above. This error can also be used if you disagree that an illustration doesn’t properly convey your specific error.
+
 <LiveExample src='NonIdealState.error.tsx' truncate={false}>
   <AllExamples.NonIdealStateErrorExample client:load />
 </LiveExample>
 
-Used in any error that isn’t discussed above. This error can also be used if you disagree that an illustration doesn’t properly convey your specific error.
-
 ### Redirection notice
 
+This one isn’t technically an error, but more of an information page that requires an action from the user. If a clickable link has more than one potential destination, take the user to this page so they can decide where they want to land. A Remember my choice checkbox can be shown below so if the link is used more than once, the user won’t need to select a button every time.
+
 <LiveExample src='NonIdealState.redirect.tsx' truncate={false}>
   <AllExamples.NonIdealStateRedirectExample client:load />
 </LiveExample>
 
-This one isn’t technically an error, but more of an information page that requires an action from the user. If a clickable link has more than one potential destination, take the user to this page so they can decide where they want to land. A Remember my choice checkbox can be shown below so if the link is used more than once, the user won’t need to select a button every time.
-
 If the two destinations offered have the exact same relevance, use hollow buttons for both. If one destination is more likely to be selected than the other based on the user’s goal upon clicking the original link, use a high-visibility button for the most relevant destination, and a hollow button for the other. Always put the high-visibility button on the left.
 
 If the amount of redirection locations exceed 2, you may use an alternative design where the redirection selection is made via a select menu.

apps/website/src/pages/docs/radio.mdx

@@ -23,12 +23,12 @@ A radio is not interchangeable with a [checkbox](checkbox). A radio must have at
 
 ### Statuses
 
+If you ever need to display the status or severity of a single radio, you can apply a status on the radio. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
+
 <LiveExample src='Radio.statuses.tsx'>
   <AllExamples.RadioStatusesExample client:load />
 </LiveExample>
 
-If you ever need to display the status or severity of a single radio, you can apply a status on the radio. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
-
 ## Props
 
 <PropsTable path={frontmatter.propsPath} />

apps/website/src/pages/docs/radiotile.mdx

@@ -11,6 +11,8 @@ import PropsTable from '~/components/PropsTable.astro';
 import LiveExample from '~/components/LiveExample.astro';
 import * as AllExamples from 'examples';
 
+A series of selectable tile components that behave like [radio button](radio). You may include icons to help make each tile more identifiable.
+
 <p>{frontmatter.description}</p>
 
 <LiveExample src='RadioTile.main.tsx'>
@@ -19,8 +21,6 @@ import * as AllExamples from 'examples';
 
 ## Usage
 
-A series of selectable tile components that behave like [radio button](radio). You may include icons to help make each tile more identifiable.
-
 The example below is the condensed version of the radio tiles. They contain only a label and an icon (the icon is optional but recommended if using condensed). If you do not need descriptive text, go with the condensed radio tiles to save space.
 
 Disabled radio tiles can coexit with active tile. A selected tile can also take on the disabled state.