Documentation content elements
These rules cover the MDX content elements shared by component and guideline pages. Language and register live in Content voice and tone. Page structure lives in the selected authoring skill’s template.
Description and synopsis
The visible description defines the subject and its main boundary in one or two sentences.
The synopsis is a self-contained retrieval summary. It must:
- Name the subject and its primary job.
- Include at least one distinguishing use case or boundary.
- Name the major decisions covered by the page.
- Remain useful without surrounding frontmatter or prose.
Do not copy the description into the synopsis. scripts/build-agents.ts prefers the synopsis as
the generated agent description.
Rule elements
Use <Rule> only inside a rule category such as WhenToUse or WhenNotToUse.
| Surface | Purpose |
|---|---|
| Inner content | Human-facing need, condition, or boundary |
aiRule | Compact canonical directive for agents |
The two surfaces may express the same decision but must not be verbatim duplicates.
Frame WhenToUse around a user need:
Frame WhenNotToUse around the alternative and its boundary:
Every aiRule must be:
- directive: start with an action such as “Use” or “Avoid”;
- bounded: name the condition or alternative that determines when it applies;
- compact: use one self-contained sentence without markup;
- specific: name the subject or alternative instead of using “it” or “this”.
Prefer “Use X instead of Y when…” over “Do not use Y” because it gives the reader a next action.
Example elements
Use an example when visual or contextual comparison communicates a decision more efficiently than prose. Do not use examples as decoration.
A meaningful <Example> needs coordinated imageSrc, aiCaption, and caption values.
An example may also be a plain illustration of a behaviour or placement with no do or don’t, such
as multi-expand beside single-expand, or a component in a Drawer. Give it a neutral caption
that describes what the image shows. Its aiCaption states Context:, Setup: and Why: and
starts with a Rule: only when the image supports one; do not invent a rule to fit the format.
Image source
Follow the writer workflow for approved assets and image-required.svg placeholders. A proposed
asset must record:
| Field | Content |
|---|---|
| Decision | The rule the image proves |
| Context | The product surface or state |
| Setup | Exact controls, labels, values, and arrangement |
| Comparison | Single, Do/Don’t, or caution |
| Theme | Whether light and dark files are required |
| Filename | Proposed kebab-case path under _images/ |
Image alternative text
Do not set imageAlt when an example has a caption. The component warns when both are present.
When an uncaptained image carries meaning on its own, describe visible content and arrangement in
one literal sentence. Do not begin with “image of”. The aiCaption still carries the full
recommendation.
AI caption
Use this exact order:
| Part | Requirement |
|---|---|
| Rule | State guidance, not merely what the image contains. |
| Context | Name the scenario, surface, state, or decision boundary. |
| Setup | Describe labels, values, controls, and arrangement literally enough for an agent that cannot see the image. |
| Why | State an observable consequence. Avoid circular claims such as “because it is clearer”. |
The field must remain self-contained when extracted from the page. Its Setup: clause also acts
as the commissioning brief for a placeholder image.
Human caption
Write a shorter interpretation for human readers.
| Indicator | Caption opening |
|---|---|
success | Do: ... |
error | Don't: ... |
warning | A neutral caution, not a false hard rule |
For a single correct example, omit the indicator and use a plain caption. Do not set
captionWarning={false} on a meaningful example; that mode is excluded from content review.
Do/Don’t pair
Tables and callouts
Use tables when readers need to compare a stable set of dimensions. Add
[[mds-table__cell--nowrap]] only to cells that must stay on one line.
Use <Notification> only for a verified warning, experimental status, or critical exception. Do
not use a callout as decoration.
Final content check
- Every sentence has one likely interpretation on first read.
- Every instruction has a condition or decision boundary.
- Terms are defined once and used consistently.
- Examples agree with the prose and add information.
- Every rule has a non-duplicative
aiRule. - Every meaningful example has
imageSrc,aiCaption, andcaption, withoutimageAlt. - The synopsis, AI rules, and AI captions make sense outside the page.
- Shared policy is linked instead of duplicated.