Authoring standard for gen2 Storybook guide pages in learn-about-swc, guides, and resources. Covers page types, outcome-first leads, numbered steps with checks, journey position, scannable structure, troubleshooting, and the single next step. Use when writing, rewriting, reviewing, or auditing a guide page.
Write gen2 guide pages that a reader can scan, act on, and finish. The standard puts the next action first, keeps the reader's working set small, and makes progress visible. It pairs those principles with Diátaxis page types and the guide patterns in GOV.UK, Polaris, and Carbon.
When to use this skill
Writing a new page in gen2/packages/swc/.storybook/learn-about-swc/, guides/, or resources/
Rewriting or reviewing an existing guide page
Auditing guide pages and scoring them against the checklist
Scope and precedence
Page
Follow
Guide pages in learn-about-swc/, guides/, resources/
This skill
Per-unit component, pattern, and controller docs pages
This skill sets page structure. For mechanics such as sentence case, em dashes, <kbd>, callout format, and WCAG links, follow .ai/rules/text-formatting.md. For voice and tone, follow documentation-standards. Never hard-wrap prose in .mdx files.
Why these rules
Guide readers are mid-task and switching between the docs and their code. Five facts shape the rules:
Working memory is small. Anything off screen is forgotten, so restate position and don't write "as mentioned above."
Knowing isn't doing. Each step names one action and the result to check.
Starting is the hardest part. The first lines say what the reader gets and what they need.
Vague estimates fail. "Quick" and "a few hours" read the same. Use minutes and hours.
Visible progress keeps readers going. A "You should see" check at the end of each section of steps confirms the win.
The standard
1. Declare the page type
Put {/* page-type: <type> */} on the line after <Meta />. Use exactly one type and follow its template in references/page-templates.md.
Type
Reader's goal
Contains
Never contains
tutorial
Learn by doing, first time
One guaranteed path, numbered steps
Choices, alternatives, deep "why"
how-to
Finish a known task
Numbered steps, branches stated up front
Teaching basics, history
reference
Look up a fact
Tables and lists of classes, values, APIs
Steps, opinions, narrative
explanation
Understand a concept or decide
Short sections, comparisons, trade-offs
Step-by-step instructions
If a page needs two types, split it, or keep one type and link to the other page.
2. Lead with the outcome
Directly under the H1, write one sentence that names what the reader gets. Follow it with a short lead list:
For: the audience, such as application developers, contributors, or designers
Time: a concrete estimate, such as "about 10 minutes" (tutorial and how-to only)
Before you start: prerequisites, each one linked (omit when there are none)
Don't open with "This page walks you through", "This guide covers", history, or statistics. The H1 names the outcome or the subject, not the page type.
3. One action per step, one check per section
This rule applies to tutorials and how-tos only. Reference and explanation pages don't have steps.
Steps: each numbered step is one bounded action that starts with an imperative verb. A step never contains "and then" twice. Use the fewest steps that still work.
Check: end each section of steps (a ## Step N: section or a task section) with one sentence that starts You should see and names an observable result.
4. Restate position in a journey
Single-page sequence: title each major section ## Step N: <verb phrase>, and put the step count in the lead's Time item, such as "about 2 hours across 7 steps."
Multi-page journey: add a Journey item to the lead list, such as - **Journey:** Migration, step 3 of 7. The Next step link goes to step 4.
Never ask the reader to remember an earlier page. Link to it instead.
5. Keep it scannable
Headings: one H1 for the page title (the MDX # heading, not <Meta title>), then H2 and H3 only, in sentence case. Tutorial and how-to headings start with a verb ("Set the color scheme"). Reference headings name the thing ("Theme classes"). Explanation headings are noun phrases or questions.
Lists: five items or fewer per group. Group a longer list under H3s, or use a table. Generated content, such as a changelog rendered from CHANGELOG.md, is exempt.
Tables: use one when you compare two or more options across two or more attributes.
Prose: three sentences or fewer per paragraph, 25 words or fewer per sentence.
Code: every block has a language tag and shows only what the step changes.
6. Cut tangents and repetition
Tangents: no "Did you know?" asides, history, or motivation in tutorials and how-tos. Move them to an explanation page and link to it.
Repetition: each fact has one home page. Other pages link to it and don't restate it. For example, the full list of theme classes lives on Theme and scales.
Callouts: use > ⚠️ **Important:** only for something the reader must not skip, at most once per section.
7. Troubleshoot as symptom, cause, and fix
Put troubleshooting in a ## Troubleshooting section just before the last section. Title each H3 with the symptom in the reader's words, then give **Cause:** and **Fix:**. Keep the tone matter-of-fact: no "Uh oh" or "Unfortunately."
When every fix fits on one line, use a table with Symptom, Cause, and Fix columns instead.
8. End with one next step
The last section is ## Next step: one sentence with one link. No recap, "Summary", "Learn more" list, or "Hope this helps."
Exceptions:
Section entry pages, such as Overview, may end with ## Choose your path instead. That's a table of five rows or fewer, and each row pairs a reader goal with one link.
Reference pages with no natural next action, such as Changelog or a link directory like Accessibility resources, may omit Next step.
Voice
These add to documentation-standards and .ai/rules/text-formatting.md; they don't replace them.
Second person, present tense, active voice: "Import the stylesheet," not "The stylesheet should be imported."
No minimizers: cut "just", "simply", "easy", "quick", and "obviously."
No idioms: write the literal action, such as "return to step 2" instead of "circle back."
Hedge only real uncertainty: delete "perhaps" and "might" unless the outcome truly varies, and then say what it depends on.
Link text names the destination:see [Fonts](/docs/guides-customization-fonts--docs), never "click here" or "this page."
Proposed page types for existing guides
A starting point for rewrites. Confirm or change the type during each rewrite.
Type
Pages
tutorial
Get started
how-to
Customization: Getting started, Component styles, Theme and scales, Fonts. Accessibility: Keyboard testing, Screen reader testing, WAVE toolbar testing. Migrate from Gen1 (journey). Build with AI
reference
Global element styling, Dev mode warnings, Accessibility resources, Support and compatibility, Changelog
explanation
Overview (section entry), Gen1 vs Gen2. Accessibility: Overview, Semantic HTML and ARIA, Headings and landmarks, Accessible pattern libraries, ElementInternals and axe-core
Review checklist
Score each item yes or no. A page passes when every item that applies is yes.
Type and lead
{/* page-type: ... */} follows <Meta />, and the page matches that type's template
The first sentence under the H1 names the outcome, with no preamble
The lead list has For, plus Time with a concrete unit for tutorials and how-tos
Every prerequisite is linked in Before you start
Journey pages have a Journey item with "step N of M"
Steps
Tutorials and how-tos only: each step is one action that starts with a verb
Tutorials and how-tos only: each section of steps ends with one You should see check
Single-page sequences use ## Step N: headings and state the step count in Time
Scannability
One H1 for the title, then only H2 and H3 headings, in sentence case, phrased for the page type
No authored list group has more than five items (generated content is exempt)
No paragraph has more than three sentences, and no sentence has more than 25 words
Comparisons are tables, and every code block has a language tag
No tangents, and no fact restated from its home page
Ending and voice
Troubleshooting, if present, uses symptom, cause, and fix
The page ends with ## Next step and one link, ## Choose your path on a section entry page, or nothing extra on a reference page with no next action
No recap, minimizers, idioms, or "click here" links
Mechanics pass .ai/rules/text-formatting.md, with no em dashes and no hard-wrapped prose
Pre-publish test
Read only the lead and the last section. If you know what the page gets you and where to go next, publish.
Examples
references/examples.md has before-and-after rewrites taken from current guide pages: the lead, a step with a check, a tangent, repeated content, troubleshooting, and the ending.
Resources
Diátaxis: tutorial, how-to, reference, and explanation page types
1---2name: guides-authoring3description: Authoring standard for gen2 Storybook guide pages in learn-about-swc, guides, and resources. Covers page types, outcome-first leads, numbered steps with checks, journey position, scannable structure, troubleshooting, and the single next step. Use when writing, rewriting, reviewing, or auditing a guide page.4metadata:5 source: https://skillmd.com/skills/adobe/guides-authoring6---78# Guides authoring910Write gen2 guide pages that a reader can scan, act on, and finish. The standard puts the next action first, keeps the reader's working set small, and makes progress visible. It pairs those principles with [Diátaxis](https://diataxis.fr/) page types and the guide patterns in GOV.UK, Polaris, and Carbon.1112## When to use this skill1314- Writing a new page in `gen2/packages/swc/.storybook/learn-about-swc/`, `guides/`, or `resources/`15- Rewriting or reviewing an existing guide page16- Auditing guide pages and scoring them against the checklist1718## Scope and precedence1920| Page | Follow |21| ---------------------------------------------------------- | ------------------------------------------------------------------ |22| Guide pages in `learn-about-swc/`, `guides/`, `resources/` | This skill |23| Per-unit component, pattern, and controller docs pages | [`stories-documentation`](../stories-documentation/SKILL.md) |24| Per-component `migration-guide.mdx` pages | [`consumer-migration-guide`](../consumer-migration-guide/SKILL.md) |2526This skill sets page structure. For mechanics such as sentence case, em dashes, `<kbd>`, callout format, and WCAG links, follow `.ai/rules/text-formatting.md`. For voice and tone, follow [`documentation-standards`](../documentation-standards/SKILL.md). Never hard-wrap prose in `.mdx` files.2728## Why these rules2930Guide readers are mid-task and switching between the docs and their code. Five facts shape the rules:31321. **Working memory is small.** Anything off screen is forgotten, so restate position and don't write "as mentioned above."332. **Knowing isn't doing.** Each step names one action and the result to check.343. **Starting is the hardest part.** The first lines say what the reader gets and what they need.354. **Vague estimates fail.** "Quick" and "a few hours" read the same. Use minutes and hours.365. **Visible progress keeps readers going.** A "You should see" check at the end of each section of steps confirms the win.3738## The standard3940### 1. Declare the page type4142Put `{/* page-type: <type> */}` on the line after `<Meta />`. Use exactly one type and follow its template in [`references/page-templates.md`](references/page-templates.md).4344| Type | Reader's goal | Contains | Never contains |45| ----------- | ------------------------------ | ----------------------------------------- | --------------------------------- |46| tutorial | Learn by doing, first time | One guaranteed path, numbered steps | Choices, alternatives, deep "why" |47| how-to | Finish a known task | Numbered steps, branches stated up front | Teaching basics, history |48| reference | Look up a fact | Tables and lists of classes, values, APIs | Steps, opinions, narrative |49| explanation | Understand a concept or decide | Short sections, comparisons, trade-offs | Step-by-step instructions |5051If a page needs two types, split it, or keep one type and link to the other page.5253### 2. Lead with the outcome5455Directly under the H1, write one sentence that names what the reader gets. Follow it with a short lead list:5657- **For:** the audience, such as application developers, contributors, or designers58- **Time:** a concrete estimate, such as "about 10 minutes" (tutorial and how-to only)59- **Before you start:** prerequisites, each one linked (omit when there are none)6061Don't open with "This page walks you through", "This guide covers", history, or statistics. The H1 names the outcome or the subject, not the page type.6263### 3. One action per step, one check per section6465This rule applies to tutorials and how-tos only. Reference and explanation pages don't have steps.6667- **Steps:** each numbered step is one bounded action that starts with an imperative verb. A step never contains "and then" twice. Use the fewest steps that still work.68- **Check:** end each section of steps (a `## Step N:` section or a task section) with one sentence that starts `You should see` and names an observable result.6970### 4. Restate position in a journey7172- **Single-page sequence:** title each major section `## Step N: <verb phrase>`, and put the step count in the lead's **Time** item, such as "about 2 hours across 7 steps."73- **Multi-page journey:** add a **Journey** item to the lead list, such as `- **Journey:** Migration, step 3 of 7`. The **Next step** link goes to step 4.7475Never ask the reader to remember an earlier page. Link to it instead.7677### 5. Keep it scannable7879- **Headings:** one H1 for the page title (the MDX `#` heading, not `<Meta title>`), then H2 and H3 only, in sentence case. Tutorial and how-to headings start with a verb ("Set the color scheme"). Reference headings name the thing ("Theme classes"). Explanation headings are noun phrases or questions.80- **Lists:** five items or fewer per group. Group a longer list under H3s, or use a table. Generated content, such as a changelog rendered from `CHANGELOG.md`, is exempt.81- **Tables:** use one when you compare two or more options across two or more attributes.82- **Prose:** three sentences or fewer per paragraph, 25 words or fewer per sentence.83- **Code:** every block has a language tag and shows only what the step changes.8485### 6. Cut tangents and repetition8687- **Tangents:** no "Did you know?" asides, history, or motivation in tutorials and how-tos. Move them to an explanation page and link to it.88- **Repetition:** each fact has one home page. Other pages link to it and don't restate it. For example, the full list of theme classes lives on Theme and scales.89- **Callouts:** use `> ⚠️ **Important:**` only for something the reader must not skip, at most once per section.9091### 7. Troubleshoot as symptom, cause, and fix9293Put troubleshooting in a `## Troubleshooting` section just before the last section. Title each H3 with the symptom in the reader's words, then give `**Cause:**` and `**Fix:**`. Keep the tone matter-of-fact: no "Uh oh" or "Unfortunately."9495When every fix fits on one line, use a table with **Symptom**, **Cause**, and **Fix** columns instead.9697### 8. End with one next step9899The last section is `## Next step`: one sentence with one link. No recap, "Summary", "Learn more" list, or "Hope this helps."100101Exceptions:102103- **Section entry pages,** such as Overview, may end with `## Choose your path` instead. That's a table of five rows or fewer, and each row pairs a reader goal with one link.104- **Reference pages** with no natural next action, such as Changelog or a link directory like Accessibility resources, may omit **Next step**.105106## Voice107108These add to [`documentation-standards`](../documentation-standards/SKILL.md) and `.ai/rules/text-formatting.md`; they don't replace them.109110- **Second person, present tense, active voice:** "Import the stylesheet," not "The stylesheet should be imported."111- **No minimizers:** cut "just", "simply", "easy", "quick", and "obviously."112- **No idioms:** write the literal action, such as "return to step 2" instead of "circle back."113- **Hedge only real uncertainty:** delete "perhaps" and "might" unless the outcome truly varies, and then say what it depends on.114- **Link text names the destination:** `see [Fonts](/docs/guides-customization-fonts--docs)`, never "click here" or "this page."115116## Proposed page types for existing guides117118A starting point for rewrites. Confirm or change the type during each rewrite.119120| Type | Pages |121| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |122| tutorial | Get started |123| how-to | Customization: Getting started, Component styles, Theme and scales, Fonts. Accessibility: Keyboard testing, Screen reader testing, WAVE toolbar testing. Migrate from Gen1 (journey). Build with AI |124| reference | Global element styling, Dev mode warnings, Accessibility resources, Support and compatibility, Changelog |125| explanation | Overview (section entry), Gen1 vs Gen2. Accessibility: Overview, Semantic HTML and ARIA, Headings and landmarks, Accessible pattern libraries, ElementInternals and axe-core |126127## Review checklist128129Score each item yes or no. A page passes when every item that applies is yes.130131### Type and lead132133- [ ] `{/* page-type: ... */}` follows `<Meta />`, and the page matches that type's template134- [ ] The first sentence under the H1 names the outcome, with no preamble135- [ ] The lead list has **For**, plus **Time** with a concrete unit for tutorials and how-tos136- [ ] Every prerequisite is linked in **Before you start**137- [ ] Journey pages have a **Journey** item with "step N of M"138139### Steps140141- [ ] Tutorials and how-tos only: each step is one action that starts with a verb142- [ ] Tutorials and how-tos only: each section of steps ends with one `You should see` check143- [ ] Single-page sequences use `## Step N:` headings and state the step count in **Time**144145### Scannability146147- [ ] One H1 for the title, then only H2 and H3 headings, in sentence case, phrased for the page type148- [ ] No authored list group has more than five items (generated content is exempt)149- [ ] No paragraph has more than three sentences, and no sentence has more than 25 words150- [ ] Comparisons are tables, and every code block has a language tag151- [ ] No tangents, and no fact restated from its home page152153### Ending and voice154155- [ ] Troubleshooting, if present, uses symptom, cause, and fix156- [ ] The page ends with `## Next step` and one link, `## Choose your path` on a section entry page, or nothing extra on a reference page with no next action157- [ ] No recap, minimizers, idioms, or "click here" links158- [ ] Mechanics pass `.ai/rules/text-formatting.md`, with no em dashes and no hard-wrapped prose159160### Pre-publish test161162Read only the lead and the last section. If you know what the page gets you and where to go next, publish.163164## Examples165166[`references/examples.md`](references/examples.md) has before-and-after rewrites taken from current guide pages: the lead, a step with a check, a tangent, repeated content, troubleshooting, and the ending.167168## Resources169170- [Diátaxis](https://diataxis.fr/): tutorial, how-to, reference, and explanation page types171- [GOV.UK: Writing for GOV.UK](https://www.gov.uk/guidance/content-design/writing-for-gov-uk): front-loading, sentence length, and plain English172- [GOV.UK Design System: Step by step navigation](https://design-system.service.gov.uk/patterns/step-by-step-navigation/): numbered journeys across pages173- [Polaris: Actionable language](https://polaris.shopify.com/content/actionable-language): verb-first headings and links174- [Carbon: Writing style](https://carbondesignsystem.com/guidelines/content/writing-style/): concise, scannable product writing175- [Spectrum: Writing for readability](https://spectrum.adobe.com/page/writing-for-readability/)
Run npx get-skill add adobe/guides-authoring in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Authoring standard for gen2 Storybook guide pages in learn-about-swc, guides, and resources. Covers page types, outcome-first leads, numbered steps with checks, journey position, scannable structure, troubleshooting, and the single next step. Use when writing, rewriting, reviewing, or auditing a guide page. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Adobe (@adobe) published this skill. Their other Agent Skills are listed on their SkillMD profile.