write-example-description

What this skill does

# PatternFly example and demo descriptions

Use this skill when a PatternFly developer needs to write or edit:

1. **Component example descriptions** – the text under each `### Example name` (h3) and above the ` ```ts file='./ExampleName.tsx' ``` ` block in `packages/react-core/src/components/*/examples/*.md`. This content appears on the **React** tab of component pages on PatternFly.org.
2. **Demo descriptions** – the text under each `### Demo name` in `packages/react-core/src/demos`. Demos appear as a separate **Demos** tab on the component/pattern page (alongside React examples, HTML, Design guidelines, and sometimes Accessibility).

Content should be clear, on-brand, and cross-linked where helpful. For **component examples**, use a concept intro only when the example introduces **unique functionality or the primary use** of the component (e.g. Basic); for **variations and follow-on examples**, jump straight to the benefit/implementation (e.g. "To remove the home link…"). See "Lead with the benefit (component examples)" below. The skill can also be used for short intros (e.g. composable blurbs under `## Examples` or an intro under `## Demos`). **Apply this skill only when the user asks** for help writing or editing example or demo descriptions; do not invoke it proactively. After completing a request, you may offer once to check the file for other opportunities.

## Who this is for

- A developer who just added a new example or demo and needs a first draft of the description.
- Anyone closing gaps where examples or demos have no description or only a heading.
- Non-writers who want a strong first draft that can be reviewed by content design later or published as-is when time is limited.

## Workflow

1. **Gather context**
   - Identify the file type: **component examples** (`.../components/*/examples/*.md`) or **demos** (`.../demos/**/*.md`), and the specific example or demo (heading + ts file).
   - Read the example’s or demo’s TSX/implementation if needed to understand what it shows and which props/features are used.
   - Read any existing description and nearby examples/demos in the same MD file for tone and length.

2. **Align with PatternFly content guidelines**
   - Call the **PatternFly MCP** to load current guidance:
     - Use `searchPatternFlyDocs` with `searchQuery: "writing"` (or `"patternfly design guidelines"` or `"content design"`) to find content design resources.
     - Use `usePatternFlyDocs` with `name: "Writing"` (or `"content design"` or the returned resource names/URLs) to fetch:
       - **Brand voice and tone** – friendly, approachable, collaborative, inventive; avoid jargon and fluff.
       - **Best practices** – clear, concise, user-focused; lead with benefit; positive, action-oriented language.
       - **PatternFly design guidelines** – present tense; second person ("you"); active voice; sentence-case headings; descriptive hyperlinks; relative URLs for PatternFly pages. (Note: bolding component names on first use applies to design guidelines pages, not example documentation—do not bold component names in example descriptions.)
       - **Accessibility and localization** – plain language, short sentences, consistent terminology.
   - Apply these when drafting or revising the example or demo description.

3. **Draft the description**
   - **For component examples:** **When the example introduces unique functionality or the primary use** (e.g. Basic): use a **concept intro sentence** ("A [component] gives users…") then **technical implementation sentence(s)**. **When the example is a variation or follow-on** (e.g. "Without home link", "With dropdown"): skip the concept intro and start with the benefit/implementation—e.g. "To remove the home link, use…" or "To add a dropdown to a breadcrumb item, use…". Always lead with the benefit in the first sentence the reader sees; keep concept and implementation in separate sentences when you use a concept intro. Do **not** bold component names in example descriptions.
   - **For demos:** Use the demo-specific structure below (opening sentence + "In this demo:" + bullet list of props/features). Mention what the demo shows and how key props or features are used.
   - In both cases: Use "you" and active voice, and be direct and concise. **Punctuation:** Avoid semicolons. Prefer commas or new sentences to join ideas. Use em dashes occasionally if they improve clarity. Use backticks for prop/attribute names (e.g. `isExpanded`). **Example and demo headings (h3):** Use sentence case—only the first word and proper nouns capitalized (e.g. "Read only", "Expanded with array", "Inline compact with truncation"). **Component names:** Do not capitalize component names unless at the beginning of a sentence. When referring to the React component in a code way, use angle-bracket form: `<ComponentName>`. **Only mention the React component (e.g. `<DataList>`) when multiple components are involved or it helps clarify the sentence**—otherwise just "use `propName`" or "set `propName`" is enough (e.g. "To reduce vertical spacing between rows, use `isCompact`." not "set `isCompact` on `<DataList>`"). In running prose, use lowercase: "the page component," "the notification drawer."
   - Add **cross-links** only when **directly relevant**—e.g. when referencing a specific example of another component, or when the reader would likely want to cross-check. Generally, linking to other components or patterns mentioned in the description is usually relevant. When building component links:
     - **Nested components**: If the target component’s MD file has a `subsection` in its frontmatter, use `/components/<subsection>/<id-lowercase>` (e.g. Form with `subsection: forms` → `/components/forms/form`). Otherwise use `/components/<id-lowercase>` (e.g. `/components/button`, `/components/card`).
     - Use `[Component label](/components/...)` or `/components/.../design-guidelines` when pointing to design/usage.
     - **Pattern**: `[Pattern label](/patterns/pattern-name)`.
     - **Same-page example**: `[link text](#anchor)`. Anchor = heading text lowercased, spaces to hyphens (e.g. `#selectable`, `#cards-as-tiles`).
     - **Content design**: `/content-design/overview` as a generic landing, or specific paths like `/content-design/writing-guides/tooltips`. Paths here can be less consistent; use overview when unsure.
     - **Foundations and styles**: e.g. `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview`.
   - Use **relative** paths only; use descriptive link text (not "click here").

### Lead with the benefit (component examples)

**When to use a concept intro:** If the example is the **first or Basic one** and introduces what the component is, use a concept intro. Sometimes you’ll also want a concept intro for a **later example** when there are **complex implementation details** to share—that’s an option when it helps the reader.

**When to skip the concept intro:** For **variations and follow-on examples** (e.g. "Without home link", "With heading", "With dropdown"), **jump straight to the benefit/implementation**. Start with "To [do x], use…" or "To [achieve y],…" so the reader still sees the outcome first, but don’t repeat what the component is.

**When in doubt:** Prefer the shorter description and one clear benefit sentence.

**With concept intro** (e.g. Basic / primary use):

1. **Concept intro sentence:** What the component displays or does (e.g. "A basic data list displays a structured set of items, each with one or more cells in a row." or "A back to top component gives users a quick way to return to the top of a long page.")
2. **Optional component structure sentence(s):** When it helps clarify, describe the hierarchy using `<ComponentName>` (e.g. "A `<DataListItem>` includes a `<DataListItemRow>` containing one or more `<DataListItemCells>`.")
3. **Technical implementation sentence(s):** How to use props or control behavior (e.g. "In a `<DataListCell>` you can control th