Skip to main content

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:

<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​

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.

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.

Table of Contents