Documentation Guide

Overview

The documentation pages are organized under the docs directory shown below. When adding a new component, tool, or guide to Abyss Docs, create a new markdown.md file under the associated folder.

abyss-docs-web
└── docs
    ├── api
    └── web
        ├── brand
        ├── developers
        ├── hooks
        ├── overview
        ├── tools
        └── ui

Markdown structure

Each markdown file should begin with the following metadata, as an example:

---
id: carousel
category: Content
title: Carousel
description: Displays information through a series of slides.
design: https://www.figma.com/file/tk08Md4NBBVUPNHQYthmqp/Abyss-Design-System?node-id=3578%3A23477
pagination_prev: web/ui/card
pagination_next: web/ui/step-indicator
---

Every doc page is divided into three tabs: Overview, Integration, and Accessibility. Within the body of the markdown file, use these tabs to group sections of information.

<Tab label="Overview">
  **Overview Content**
</Tab>

<Tab label="Integration">
  **Integration Content**
</Tab>

<Tab label="Accessibility">
  **Accessibility Content**
</Tab>

Overview tab

Import statement

Add the import statement for the feature like such:

import { Alert } from '@uhg-abyss/web/ui/Alert';

Component Sandbox

Add Sandbox after the import statement for any components that make sense to have a sandbox. Inputs are controlled props that can be adjusted by the user using the Sandbox features. Organize the inputs alphabetically when possible, starting with the simple properties first. Each input contains prop, type and optionally: options and, defaultValue. To create a Sandbox, use the convention below:

title

children

status

dismissible

showDivider

inline

<Alert title="Alert" status="success">
  Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis.
</Alert>

Property examples

Following the Sandbox, it's important to show the ability of each property separate of the others. We break each one down, giving it a title, description and jsx example showing variants of that specific property. For example, if you wanted to show the three sizes for Button, you'd write:

() => {
  return (
    <Layout.Stack alignItems="left">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </Layout.Stack>
  );
};

Since there are different visual variants of Button, including primary and outline, which use the same sizing convention ('$sm', '$md', and '$lg'), we can combine the two visuals under the one size example by organizing them utilizing the built-in Layout component from the Abyss library. Here's what the combined example looks like:

To follow the complexity of each prop example, use the following rules to properly document the feature:

When organizing the list of examples, they should be ordered from simple to complex starting with size or width
Start each example case with "Use the prop-name property to..." followed by an explanation
For props with a pre-set list of variants, add a sentence listing out the variant options "Variants include variant-1, variant-2", and so on
For props with a default value, add "The default value is set to value"
For the customization example section, include the sentence “If further customization is needed, most styles of component-name can be overridden using css”
Size and width examples should include the list of Abyss style sizes (including the conversion of size to units in the label/text like $web.semantic.sizing.icon.utility.md = 24px), followed by percent, and px
Examples may include: size, width, isDisabled, controlled, uncontrolled, loading, and customization. Take a look at other doc pages for examples of how to best format the component you're documenting

Integration tab

Implementing a props table and classes table for the component, and any sub-components gives users an in-depth view of the component without having to visit the code. (The below example is modified for this template. Please refer to the Alert component for a full list of props and classes).

Follow these rules when creating a Props Table:

Prop name is lowercase
Type is one of the following: boolean, function, array, shape, number, string, number | string
Default value is the default value from the defaultProps list, or null
Description first word is uppercase, followed by a brief description of the props use

Follow these rules when creating a Classes Table:

Class name starts with a period (.), is lowercase and uses dashes to separate words
Description first word is uppercase, followed by a brief description of the class

Integration tab example

Alert Props

Name	Type	Default	Required	Description
ariaLive	"assertive" \| "polite" \| "off"	-	-	Overrides the default aria-live attribute for the Alert, which is 'polite' if status is 'success' or 'info' and is not present if status is 'error' or 'warning'
ariaText	string	-	-	Extra text for accessibility purposes; read before the title
children	string	-		The contents of the Alert
className	string	-	-	CSS class name to apply to each element within the component
css	Abyss.CSSProperties \| Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
cta	{ type: "button"; props: AlertButton; } \| { type: "link"; props: AlertLink; }	-	-	If present, the Alert will display a button or a link
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
describedById	string	-	-	An id to associate the Alert body text with for aria-describedby
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
dismissible	boolean	true	-	If true, the Alert can be dismissed
headingLevel	1 \| 2 \| 3 \| 4 \| 5 \| 6	2	-	The heading level of the Alert title
inline	boolean	false	-	If true, the Alert will be displayed as an inline element
isVisible	boolean	true	-	If true, the Alert will be visible
onClose	React.MouseEventHandler<HTMLButtonElement>	-	-	Callback function executed when the Alert is closed; only used when dismissible is true
showDivider	boolean	true	-	If true, the Alert will show a divider before the close button; Only used when dismissible is true
status	"error" \| "info" \| "warning" \| "success"	'error'	-	The status of the Alert
timestamp	string	-	-	If present, the Alert will display a timestamp
title	string	-	-	The title of the Alert

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Alert.types.ts

Alert Classes

Class Name	Description
.abyss-alert-live-region	Alert aria-live region wrapper element
.abyss-alert-root	Alert root element
.abyss-alert-wrapper	Alert wrapper element
.abyss-alert-icon	Alert icon element
.abyss-alert-content	Alert main content container
.abyss-alert-timestamp-container	Alert timestamp container
.abyss-alert-close-button-container	Alert close button container
.abyss-alert-text-container	Alert text content container
.abyss-alert-title-container	Alert title container
.abyss-alert-title	Alert title element
.abyss-alert-body-text	Alert body text element
.abyss-alert-timestamp	Alert timestamp element
.abyss-alert-cta-container	Alert CTA container
.abyss-alert-cta-button	Alert CTA button element
.abyss-alert-cta-link	Alert CTA link element
.abyss-alert-separator	Alert separator element
.abyss-alert-close-button	Alert secondary button element
.abyss-alert-close-icon	Alert close button icon element

Accessibility tab

This tab is important to be as thorough and in-detail as possible, adhering to the WAI-ARIA design guidelines.

Follow this pattern when creating the Accessibility tab:

Brief description write a description about the component, and link to the WAI-ARIA website page referring to the component
Sandbox allows our A11Y partners to practice assistive technology on the component in a dedicated field
Keyboard interactions table referring to the WAI-ARIA keyboard interactions, create a table with all interactions usable for the specific component
Additional guidance note any additional guidance features of the component, including (but not limited to) Decorative Icons, Loading State, etc.

Accessibility tab example

An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before the page load completes.

Adheres to the WAI-ARIA Alert design pattern.

The Alert Example provided by W3.org demonstrates the Alert Pattern.

Keyboard Interactions

Key	Description
Tab	Moves focus on the next interactive element within the Alert
Shift + Tab	Moves focus to the previous interactive element within the Alert
Enter	When focus is on a button within the Alert, pressing enter will press the button
Space	When focus is on a button within the Alert, pressing space will press the button

Decorative Icons

The brand icon in the Emphasis Banner is considered decorative and does not require a text alternative, though one can be provided if desired.

Close Button Guidance

If the close button is present—which it is by default—it must be keyboard accessible. A keyboard-only user must be able to tab to the button and activate it with the space bar and the enter key. When the Alert is closed, focus must be placed back where it previously was on the page.

ARIA Properties

If status is 'success' or 'info', Alert has the following ARIA properties:

role="status"
aria-live="polite"

If status is 'warning' or 'error', Alert has the following ARIA properties:

role="alert"

BrAT Variant Behaviors

JAWS
- Only announces text
- Does not announce actions or close button
NVDA, VoiceOver
- Both announce all contents, though not roles (link, button)

Common issue: Immediate announcements require adding alerts to page AFTER loading

For an Alert to announce immediately, they must be added AFTER the page content is loaded. This makes them a dynamic update to the page.

The examples here display them on page load. This makes them more like static banners.

Announcing "Alert" (or "Warning", etc.) - Defining alt text for icons

Even in those cases, they will not announce as "Alerts" unless alt text is defined for the icon. Otherwise, only the displayed text will be announced.

Use the ariaText prop to define this text.

Overview​

Markdown structure​

Overview tab​

Import statement​

Component Sandbox​

Property examples​

Integration tab​

Integration tab example​