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
    └── mobile
        ├── brand
        ├── developers
        ├── hooks
        ├── tools
        └── ui

Markdown Structure

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

---
id: card
category: Layout
title: Card
description: A single or multi-section container used to display content related to a single subject.
design: https://www.figma.com/file/wCMblLsq9TxAQvKzY3EfCt/branch/Sk3MrHYxjT39TKDzDU5LBc/Abyss-Mobile?node-id=12334%3A61355
---

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/mobile';

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. Each input contains prop, type and optionally: options and, defaultValue. To create a Sandbox, use the convention below:

heading

paragraph

variant

<Alert heading="Completed Health Screen:" paragraph="Review of your results are ready.">
  <Alert.Button>Go To Results</Alert.Button>
</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 sizes for Button, you'd write:

<Button size="small">Small</Button>
<Button size="large">Large</Button>

Since there are multiple visual variants of Button, which use the same sizing convention (small & large) we can combine the 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:

<Layout.Stack grow>
    <Button type="filled" variant="brand">
      Filled Brand
    </Button>
    <Button type="filled" variant="neutral">
      Filled Neutral
    </Button>
    <Button type="filled" variant="destructive">
      Filled Destructive
    </Button>
</Layout.Stack>

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 by passing style props to abyss-component-name. See the class table on each component for more details”
• Size and width examples should include the list of Abyss style sizes
• 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 Button 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
• Description first word is uppercase, followed by a brief description of the props use

Follow these rules when creating a Classes Table:

• Class name is lowercase and uses dashes to separate words
• Description first word is uppercase, followed by a brief description of the class

Example of Integration Tab

Accessibility Tab

This tab is important to be as thorough and in-detail as possible, adhering to the WAI-ARIA design guidelines. Check out the accessibility documentation on React Native for guidance during development.

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.

Example of Accessibility Tab

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 page load completes.

Adheres to the Alert WAI-ARIA design pattern.

Decorative Icons

In the alert below, since the word “Warning” appears next to the icon, the icon is considered decorative and must be ignored by assistive technology. The icon does not need to meet the 3:1 minimum contrast requirement against its adjacent color.

Close Button Guidance

Keyboard operation: if the “close” button is used on the alert, 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.

Note: per the WAI ARIA specification, when the “alert” role is used, the user should not be required to close the alert. In this case, it is assumed that the close button is provided as a convenience and the user is not explicitly required to close the alert.