Diagnostics

Content problems are reported as DS-* codes with a severity. Errors fail reed check and reed build. Warnings do not, unless you escalate them.

Three families: DS-S* structure, DS-D* design and density, DS-A* accessibility. A few checks use plain names instead, listed at the end.

Escalating warnings

--strict-componentsflag

Escalates DS-D* warnings to errors.

--strict-tokensflag

Escalates every warning that is not DS-D*.

The two cover disjoint sets and compose — pass both to fail on everything.

DS-S* — structure. Always errors.

Code	Triggered by
DS-S01	A component has a child its contract disallows — e.g. anything but Card inside CardGroup. The message lists the permitted children.
DS-S02	Fewer element children than the contract’s minimum — e.g. a Steps with one Step, or an empty Frame. A markdown image alone counts as a Frame’s child.
DS-S03	A required prop is missing.
DS-S04	An enum prop has a value outside its allowed set. The message lists the valid values.
DS-S05	A forbidden nesting pair — two components that must not contain one another.
DS-S06	An unknown component: not in the catalog and not locally imported. Usually a typo or a component from another platform.
DS-S07	Component nesting deeper than 4 levels.

DS-D* — design and density. Warnings.

Code	Triggered by
DS-D01	More than 40 component elements on one page.
DS-D02	More than one Banner, more than one Aside, or a Banner that is not the page’s first block.
DS-D03	Adjacent fenced code blocks in different languages — consider CodeGroup (Format code).
DS-D04	An ordered list where every item contains a fenced code block — consider Steps.
DS-D05	Adjacent Accordion elements with no enclosing AccordionGroup.
DS-D06	Adjacent callout-family elements — consider grouping.
DS-D07	An icon prop whose value resolves to no known icon.
DS-D08	A prop from the upstream dialect that Reed’s component cannot represent, and therefore drops.

DS-D03, DS-D04, DS-D05 and DS-D06 are suggestions: the page renders correctly either way. DS-D07 and DS-D08 mean something you wrote is being silently discarded — treat those as real even though they are warnings.

DS-A* — accessibility. Always errors.

Code	Triggered by
DS-A01	An image or <img> with no non-empty alt.
DS-A02	An H1 in the page body — the H1 comes from frontmatter title — or a skipped heading level, such as h2 straight to h4.
DS-A03	An Icon that is the entire content of a link or button, with no accessible label.

These are errors rather than warnings on purpose: each one produces a page a screen reader cannot convey, and none has a legitimate exception worth a flag.

Plain-named codes. Always errors.

These are not DS-* codes. Each one fails reed check and reed build, with no flag to turn it off.

Code	Triggered by
unsupported-upstream-component	The page uses a component that has no equivalent under the configured content.dialect. The fix is either a different component or a different dialect — see Content dialect.
content-page-not-in-navigation	A content page that no navigation entry lists. The message reads content file "<path>" is not referenced by any navigation entry; a page must be listed in docs.json navigation to be built. Add the page to navigation or move it out of the content directory — see Fix a page that is not in navigation.
redirect-source-conflict	A redirects entry whose source is the route of a page in navigation, or the path of a file the build writes, such as /llms.txt. The message names the source and the page or file it collides with — see Redirects.

Reading a diagnostic

  ✗ [DS-S03] content file "api/limits.mdx"'s "ParamField" is missing required prop "name" (contract: ParamField)

Every diagnostic names the file, the component, and the contract it was judged against. The contract name matters when dialect mapping is in play: it tells you which set of rules Reed applied, which is usually the answer when a diagnostic looks wrong.