| name | documentation-standards |
| description | When writing documentation in a variety of scenarios, follow the Adobe content writing standards. |
Documentation standards
Understand the Spectrum Design System's content writing standards and expectations at an expert level.
Mindset
You are a technical writer. Documentation is a product, not an afterthought. Write for the reader, not the author — cut anything that doesn't serve them.
When to Use This Skill
- Authoring 2nd-gen Storybook docs pages (per-unit MDX in
<unit>.mdx)
- Writing JSDoc on public APIs (
Component.ts, the meta-level JSDoc above const meta)
- Updating documentation for the 1st-gen documentation site
- Writing any documentation that is shipped to external consumers
- Creating documentation that is internal
- Developing a changeset for a pull request
- Drafting Jira tickets
- Writing a pull request description
Example
🚨 Not following Adobe content standards
ALL VALUES IN THE ITEM ARRAY ARE ASSUMED TO BE HOMOGENOUS BY DEFAULT which means that all of the rendered rows are either delivered as provided or in the case you are leveraging selects rendered with an element however when virtualizing a table with selection it can sometimes be useful to surface rows with ADDITIONAL INTERACTIONS e.g. "Load More Data" Links, and to support that you can optionally include the _$rowType$ brand in your item and the values for this are outlined by the RowType enum and include ITEM (0) and INFORMATION (1) and when _$rowType$: RowType.INFORMATION is provided it instructs the not to deliver an in that row BUT you should be careful when doing this because it might cause issues with your implementation!!!
The SP-ACCORDION Element Contains A List Of Items that can be expanded or collapsed to reveal ADDITIONAL CONTENT or information associated with each item and there can be zero expanded items exactly one expanded item or more than one item expanded at a time depending on the configuration (which is really important!!!) and this list of items is defined by child sp-accordion-item elements that are targeted to the default slot of their sp-accordion parent. however you should note that the configuration can be changed dynamically at runtime and the items will be automatically updated to reflect the new state. But you need to be careful about how you implement this because it might not work as expected in all situations and you should always test your implementation thoroughly before deploying to production.
✅ Following Adobe content standards
All values in the item array are assumed to be homogenous by default. This means all of the rendered rows are either delivered as provided, or, in the case you are leveraging selects, rendered with an <sp-table-checkbox-cell>. However, when virtualizing a table with selection, it can sometimes be useful to surface rows with additional interactions, e.g. "Load more data" links. To support that, you can optionally include the _$rowType$ brand in your item. The values for this are outlined by the RowType enum and include ITEM (0) and INFORMATION (1). When _$rowType$: RowType.INFORMATION is provided, it instructs the <sp-table> not to deliver an <sp-table-checkbox-cell> in that row.
The <sp-accordion> element contains a list of items that can be expanded or collapsed to reveal additional content or information associated with each item. There can be zero expanded items, exactly one expanded item, or more than one item expanded at a time, depending on the configuration. This list of items is defined by child <sp-accordion-item> elements that are targeted to the default slot of their <sp-accordion> parent.
Key patterns
Most often, documentation is written in Markdown (including MDX for Storybook docs pages) or JSDoc (for public APIs).
For 2nd-gen Storybook documentation specifically:
- Per-unit docs page: authored as a Markdown / MDX file (
<unit>.mdx) at the unit's root. This is the docs surface for components, internal components, patterns, and controllers. See stories-documentation for the per-unit MDX authoring template and conventions.
- Public-API JSDoc: authored on
@property, @slot, public methods, dispatched events, etc. in Component.ts. This is read by the Custom Elements Manifest and rendered into Storybook's API table.
- Meta-level JSDoc: a single JSDoc above
const meta: Meta = { ... } in the stories file. Rendered by <Description /> at the top of the docs page.
- Story-level JSDoc (above individual
export const Foo: Story = ...) is not used in 2nd-gen. Prose for each story lives in the per-unit MDX next to the corresponding <Canvas of={Stories.Foo} /> reference.
Markdown syntax reference
Headers
# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header
# Alternative H1
## Alternative H2
Text Formatting
**Bold text**
**Also bold**
_Italic text_
_Also italic_
**_Bold and italic_**
**_Also bold and italic_**
~~Strikethrough~~
`Inline code`
> Blockquote
> Multiple lines
> in blockquote
---
Horizontal rule (also \_\_\_ or \*\*\*)
Lists
Unordered list:
- Item 1
- Item 2
- Nested item 2.1
- Nested item 2.2
- Item 3
Using asterisks:
- Item 1
- Item 2
Using plus:
- Item 1
- Item 2
Ordered list:
1. First item
2. Second item
1. Nested item 2.1
2. Nested item 2.2
3. Third item
Task list (GitHub Flavored Markdown):
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
Links and Images
[Link text](https://example.com)
[Link with title](https://example.com 'Link title')
Reference-style link:
[Link text][reference]
[reference]: https://example.com
Automatic link:
<https://example.com>
<email@example.com>
Reference-style image:
![Alt text][image-ref]
[image-ref]: image.png
Code Blocks
Inline code: `const x = 5;`
Code block with language:
```javascript
function hello(name) {
console.log(`Hello, ${name}!`);
}
```
```python
def hello(name):
print(f"Hello, {name}!")
```
```bash
npm install
npm start
```
Indented code block (4 spaces):
const x = 5;
console.log(x);
Tables
Simple table:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
Aligned columns:
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
| Text | Text | Text |
Minimal table:
Column 1 | Column 2
---------|----------
Data | Data
Data | Data
JSDoc Tags Reference
Resources
