Pf Write Example Description

---
name: pf-write-example-description
description: Write and refine example descriptions for PatternFly.org component and demo pages. Use when authoring or updating the prose in PatternFly example markdown files.
---

# 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

### Step 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.

### Step 2: Load PatternFly content guidelines

Call the **PatternFly MCP** to load current guidance:
- Use `searchPatternFlyDocs` with `searchQuery: "writing"` to find content design resources.
- Use `usePatternFlyDocs` with `name: "Writing"` to fetch brand voice, best practices, design guidelines, and accessibility guidance.
- Apply these when drafting or revising the description.

### Step 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** — see the "Link conventions" table below for path formats.
   - 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 the layout of content by using `isFilled` and `alignRight`.") and any real-use caveats.

**Preferred example (data list Basic):**

```markdown
A basic data list displays a structured set of items, each with one or more cells in a row.

A `<DataListItem>` includes a `<DataListItemRow>` containing one or more `<DataListItemCells>`. In a `<DataListCell>` you can control the layout of content by using `isFilled` and `alignRight`.
```

**Another example (back to top):**

```markdown
A back to top component gives users a quick way to return to the top of a long page. This example sets `isAlwaysVisible` so the control is visible in the short demo. In a real page, the control should appear after the user scrolls 400px.
```

**Without concept intro** (variation / follow-on): Start with "To [benefit], use…" and **do not name the React component unless multiple components are involved or it clarifies**. Prefer "use `propName`" over "set `propName` on `<ComponentName>`."

```markdown
To reduce vertical spacing between rows, use `isCompact`.
```

```markdown
To remove the home link from the breadcrumb, use [prop or approach].
```

Use the same "To [benefit], use…" shape for variation examples; only omit the concept intro sentence so you don’t repeat the concept on every example.

**Avoid / Prefer:**

- **Avoid:** "Use isCompact to reduce spacing." **Prefer:** "To reduce vertical spacing between rows, use `isCompact`."
- **Avoid:** "Passing `isBordered` to an Avatar will add a border." **Prefer:** "To add a border to an avatar and further separate it from the background, use `isBordered`."

### Demo description structure

For **demos**, prefer this format so readers know what the demo shows and how it’s built:

1. **Opening sentence:** Lead with what the demo shows—**vary the phrasing**. Options include a short descriptive sentence (e.g. "A basic notification drawer opens from the masthead and displays a list of notifications.") or user-focused ("You can [achieve X] by [approach]."). Avoid repeating "This demo demonstrates" across demos.
2. **"In this demo:" or "This demo includes:"** followed by a bullet list. Each item can tie a prop or feature to what it does, or describe an element in the demo:
   - "The `propName` prop is used to [effect]." / "A `ref`, which is passed to [thing] and used with the [component]'s `onExpand` callback to [effect]."
   - "[Thing] with [details], in both [state A] and [state B] states."

Example (descriptive style):

```markdown
A basic notification drawer opens from the masthead and displays a list of notifications.

This demo includes:

- A `ref`, which is passed to the notification drawer and used with the page component's `onNotificationDrawerExpand` callback to move focus into the drawer when it opens.
- Notification items with a header and body, in both "read" and "unread" states.
```

Use lowercase for component names in prose ("the page component"); use `<ComponentName>` when referring to the React component in a code way (e.g. "pass `ref` to the `<Page>` component").

Keep bullets concise; use backticks for prop/component names. **Length:** A very simple demo may need only an opening sentence (no bullets). Other demos may have multiple sentences and lists of 5+ bullets—that’s fine. What matters is capturing the **unique aspects** of the demo, **why the demo matters**, and **what it is showing to users**. Cross-link to components or patterns when directly relevant (same rules as component examples).

### Step 4: Present and iterate
   - **Share the suggested description in raw markdown** (e.g. in a fenced code block or clearly formatted block) so the user can easily copy and paste. Write the example description in markdown (links, backticks for props, etc.).
   - Ask the user to either:
     - **Accept** the suggestion (then insert it into the MD file), or
     - **Request changes** by saying what they don’t like (e.g. too long, wrong emphasis, different link).
   - If they request changes, revise and show again; repeat until they accept or are satisfied.
   - Optionally, once done: "Do you want me to check this file for other opportunities?" (e.g. other examples missing descriptions). Do not over-suggest this; ask at most once per interaction.

### Step 5: Apply the final text
   - **Component examples:** Insert or replace the description after the `### Example name` line and before the ` ```ts file='./...' ``` ` block.
   - **Demos:** Insert or replace the description after the `### Demo name` line and before the ` ```ts file='./...' ``` ` block (demos may use `isFullscreen` on the code block).
   - **Rewriting vs updating:** If the user is **rewriting** (replacing) existing content, the new description can **override** existing content, including tables—but **make the user aware** that you removed or replaced something (e.g. "I replaced the previous paragraph and the table with the description below."). If they are **updating or adding** (not doing a full rewrite), tack the new content on where appropriate; do not replace existing prose or tables unless they asked for a rewrite.
   - If the user would like content design review, suggest they tag the content designer for review (no need to add PR labels; a brief note is enough).

## MD structure reference

**Component examples** (`packages/react-core/src/components/*/examples/*.md`):

```markdown
### Example heading

**If primary/unique (e.g. Basic):** [Concept intro: "A [component] gives users [benefit]."] [Technical implementation sentence(s).] **If variation/follow-on:** [Start with "To [benefit], use…" or "To [do x],…"; no concept intro.] Optional [cross-link](/components/other) if relevant.

```ts file='./ExampleName.tsx'
```
```

**Demos** (`packages/react-core/src/demos/**/*.md`):

```markdown
## Demos

Optional intro paragraph under ## Demos (e.g. focus management note).

### Demo heading

[Varied opening: e.g. "A basic [thing] opens from… and displays…" or "You can [xyz] by [abc]."]

This demo includes:

- [Bullet tying prop/feature to effect, or describing element.]
- [Bullet…]

```ts file='./examples/DemoName.tsx' isFullscreen
```
```

- Descriptions are optional but recommended; some examples and demos have none.
- Same-file anchors (component examples): from the exact heading text, lowercased, spaces → hyphens (e.g. "Cards as tiles" → `#cards-as-tiles`).

## Link conventions (PatternFly.org)

| Target | Path form | Example |
|--------|-----------|--------|
| Component (no subsection) | `/components/<id-lowercase>` | `/components/card`, `/components/button` |
| Component (with subsection in frontmatter) | `/components/<subsection>/<id-lowercase>` | `/components/forms/form`, `/components/menus/menu` |
| Component design guidelines | `/components/.../design-guidelines` | `/components/tooltip/design-guidelines` |
| Component accessibility | `/components/.../accessibility` | `/components/alert/accessibility` |
| Pattern | `/patterns/<name>` | `/patterns/primary-detail` |
| Same-page example | `#anchor` | `#selectable`, `#cards-as-tiles` |
| Content design (generic) | `/content-design/overview` | Use when linking to content design generally |
| Content design (specific) | `/content-design/...` | `/content-design/writing-guides/tooltips` |
| Foundations and styles | `/foundations-and-styles/...` | `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview` |

Determine component paths by checking the target component’s MD frontmatter for `subsection` (e.g. `subsection: forms` → `/components/forms/form`). Design guidelines and some writing guides live in patternfly-org; the docs site exposes the paths above.

## Quality checks

Before suggesting the description:

- [ ] When in doubt, prefer the shorter description and one clear benefit sentence.
- [ ] No semicolons in descriptions. Prefer commas or new sentences (em dashes occasionally).
- [ ] Matches brand voice (friendly, clear, no jargon, "you" and active voice).
- [ ] Example and demo headings (h3) in sentence case (first word and proper nouns only). Component names: lowercase in prose unless starting a sentence; use `<ComponentName>` when referring to the React component as code. Do not bold component names in example or demo descriptions.
- [ ] **Component examples:** Concept intro only for unique/primary-use examples (e.g. Basic); optional component-structure sentence using `<ComponentName>` when it helps; variation examples start with "To [benefit], use…" and omit component name unless multiple or clarifying. Props in backticks.
- [ ] **Demos:** Varied opening; "In this demo:" or "This demo includes:" with bullet list of props/features and what they do.
- [ ] Cross-links only where directly relevant; use subsection for nested components.
- [ ] Relative URLs only; descriptive link text.
- [ ] Suggested text shared in raw markdown so the user can copy and paste.

## Optional: when the user hasn’t specified a file or example

If the user asks for help with "example descriptions" or "demo descriptions" but doesn’t point to a file or example:

- Ask which file they want to work on (component examples path or demos path) and which example or demo (heading or ts file name).
- Optionally list examples or demos in that file that are missing descriptions so they can choose.