Skip to content

Commit

Permalink
Component contribution accessibility (#3616)
Browse files Browse the repository at this point in the history
* Update index.mdx

added placeholder text for accessibility markdown file

* Update index.mdx

Updated markdown template

* Update index.mdx

Added in links and other content

---------

Co-authored-by: Anna Gonzales <anna.gonzales3@gmail.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
  • Loading branch information
3 people authored Jul 13, 2023
1 parent 2949275 commit cd86c32
Showing 1 changed file with 142 additions and 1 deletion.
143 changes: 142 additions & 1 deletion src/pages/contributing/component/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -837,6 +837,140 @@ leaving any other comments on
[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).
```

### Accessibility template

The accessibility template helps designers and developers ensure components are
accessible. The published information helps users understand all the
accessibility considerations that are baked into Carbon. Refer to our guidance
on creating the
[keyboard interaction visuals](https://github.com/hiraaeth/component-contribution-accessibility/wiki/High-fidelity-keyboard-interaction-visuals).

```markdown
---
title: Component name (you won't need to write this)
description: Component description (you won't need to write this)
tabs: ['Usage', 'Style', 'Code', 'Accessibility']
---

<PageDescription>

<!--
There are 2 stock page descriptions.
Choose the first example if designers need to include annotations in their wireframes to make the component accessible. Choose the second if the component is accessible without additional design decisions.
** If example 2 is used, the Design recommendations section and its anchor link should be removed.

Example 1:
Design annotations are needed for specific instances shown below, but for the
standard [component_name] component, Carbon already incorporates accessibility.

Example 2:
No accessibility annotations are needed for [component_name]s, but keep these considerations in
mind if you are modifying Carbon or creating a custom component.
-->

</PageDescription>

<AnchorLinks>
<AnchorLink>What Carbon provides</AnchorLink>
<!--
Only include Design recommendations if there are actually tasks for a designer to do
-->
<AnchorLink>Design recommendations</AnchorLink>
<AnchorLink>Development considerations</AnchorLink>
</AnchorLinks>

## What Carbon provides

Carbon bakes keyboard operation into its components, improving the experience of
blind users and others who operate via the keyboard. Carbon incorporates many
other accessibility considerations, some of which are described below.

### Keyboard interaction

<!--
This keyboard section introduction text can give details of keyboard operation. For actionable components, begin by talking about the navigation via the tab stop, then discuss common interactions keys. For components with subcomponents, unless there is little interaction for the subcomponent, consider splitting the subcomponent considerations into a separate paragraph, separated by an illustration. Where operation is more complicated, separate headings for Keyboard navigation and Keyboard interaction can exist.Keyboard keys should be referred to with code styling.

Example 1:
-->

Each accordion is a tab stop. `Space` or `Enter` keys expand or collapse
accordions, which are collapsed by default. Interactive elements within expanded
accordions integrate into the tab order automatically.

<!--
Example 2:
Each page link in the breadcrumb is reached by `Tab` and activated by `Enter`. The current
page, if listed in the breadcrumb, is not a link. If the breadcrumb is truncated, the ellipsis button
for the overflow menu is in the tab order. See [overflow menu]((https://carbondesignsystem.com/components/overflow-menu/usage/)) for details on its keyboard operation
-->

<!--
**Images**
Use one image to document keyboard navigation. If the component has limited operation functionality, it may also be incorporated in the same image. Otherwise, the operation should be dealt with in a separate image.
Normally these images go across 8 columns.
images should follow the naming convention (component_name-accessibility-1.png
The ALT text text for the first image can be fairly generic, since the image is just restating information in the prior paragraph.
The caption should likewise summarize something already described in the preceding paragraph. No new information should be given in the caption. Due to technology constraints, keystroke names in the captions are not given any markdown styling.
Example:
![example of breadcrumb keyboard interaction](images/breadcrumb-accessibility-1.png)
<Caption>
The breadcrumb's links are reached by Tab and activated by Enter.
</Caption>
-->
<Row>
<Column colLg={8}>

![example of (componet_name) keyboard interaction](images/component_name-accessibility-1.png)

<Caption>
The (component_name) is reached by Tab and activated by Enter.
</Caption>

</Column>
</Row>

<!--
The Design recommendations section should only be included if annotations are needed
-->

## Design recommendations

Design annotations are needed for the following instances.

<!--
Some of the possible subheadings here include:
- headings
- alignment
- labeling
- meaningful order

Each should have a level 3 heading, a descriptive paragraph and a supporting image.

Example:

### Headings
Carbon accordions are not set as headings by default. For improved accessibility, annotate accordions as headings on the first occurrence in a product. Annotate the heading level of accordions as needed.

-->

## Development considerations

Keep these considerations in mind if you are modifying Carbon or creating a
custom component.

<!--
Provide a bulleted list of implementation considerations for ensuring accessibility. If there is the ability to refernce the IBM toolkit or the ARIA authoring practices, that should be done.

- Use dashed bullets and ensure code is styled as code and consistently appears with the
following symbols: <element>, 'variable' and "value".
- End each bulleted list item with a period.

Example:
- See the [ARIA authoring practices](https://w3c.github.io/aria-practices/#tooltip) for more considerations.

-->
```

## Parts of a component contribution

Component contributions ideally include all of the following parts.
Expand Down Expand Up @@ -930,7 +1064,14 @@ specific repo you intend to contribute to.
</Column>
</Row>

#### 6. Code documentation
#### 6. Accessibility documentation

Use this
[component accessibility documentation](https://github.com/hiraaeth/component-contribution-accessibility/wiki/component-accessibility-documentation)
to document the accessibility considerations to ensure the implemented component
is usable by assistive technologies.

#### 7. Code documentation

Start with our [Code guidance](#code-guidance) template. We recommend reading
through existing code documentation on this site for inspiration.
Expand Down

1 comment on commit cd86c32

@vercel
Copy link

@vercel vercel bot commented on cd86c32 Jul 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.