Component Framework — Canonical Taxonomy
Canonical folder structure, per-component file listing, decision rules, and JSDoc standard forsnippets/components/. This is the primary reference for authoring and governing components in the Livepeer Docs v2 library.
Folder Taxonomy
Tier 2 companion files (props-extracted components) live adjacent to their MDX pages, not here:v2/[section]/[page-slug]-data.json— same slug as the page, with-datasuffix. Written at page-authoring time; see@aiDiscoverabilitysection below.
Decision Rules
| # | Folder | Rule |
|---|---|---|
| 1 | elements/ | ”Is it a single visual piece that doesn’t wrap, arrange, or fetch anything?“ |
| 2 | wrappers/ | ”Does it exist to hold, group, or arrange other things?“ |
| 3 | displays/ | ”Does it take content and present it in a formatted way?“ |
| 4 | scaffolding/ | ”Is it part of the page’s outer structure, typically used once?“ |
| 5 | integrators/ | ”Does the content come from outside the repo?“ |
| 6 | config/ | ”Is it a non-component config/theme object?” |
Component Counts
| Category | Components | Sub-niches |
|---|---|---|
| elements | 30 | 10 |
| wrappers | 30 | 7 |
| displays | 17 | 5 |
| scaffolding | 20 | 4 |
| integrators | 20 | 4 |
| config | 1 | — |
| Total | 118 | 30 |
Component JSDoc header standard
Every exported component must include a JSDoc header block with these 7 core tags. Hook-using components additionally require@aiDiscoverability.
No other governance tags should be used — removed tags (@owner, @category,
@tier, @contentAffinity, @decision, @duplicates, @lastMeaningfulChange,
@breakingChangeRisk, @dependencies, @usedIn) must not appear.
Tag reference
| Tag | Required | What it does | Values / format |
|---|---|---|---|
@component | Yes | Component identity | Export name (PascalCase) |
@type | Yes | Layer 1 — what kind of component | elements, wrappers, displays, scaffolding, integrators, config |
@subniche | Yes | Layer 2 — specific sub-concern | Matches folder name: buttons, icons, images, links, text, math, callouts, spacing, social, a11y, containers, cards, lists, steps, accordions, tables, grids, code, video, quotes, diagrams, response-fields, frame-mode, heroes, portals, page-containers, feeds, blog, embeds, video-data |
@status | Yes | Lifecycle state | stable, experimental, deprecated, broken |
@description | Yes | One-line human-readable description | Plain English sentence — what it renders and when to use it |
@dataSource | If integrator | Where external data comes from | none, prop, CoinGecko API, fetch(url), automation/blog, etc. |
@accepts | Yes | Extensibility declaration — what the consumer can customise | Comma-separated: children, style, className, ...rest |
@aiDiscoverability | If hook-using | Companion file requirement for AI/crawler access | snapshot, props-extracted, none |
@param:
Removed tags (must not appear)
| Tag | Reason |
|---|---|
@owner | Ownerless governance — was always docs for every component |
@category | Replaced by @type (aligned with script governance) |
@tier | primitive/composite/pattern — replaced by @type/@subniche |
@contentAffinity | Not queried by anyone in practice |
@decision | All said KEEP — served its purpose during audit |
@duplicates | All resolved during restructure |
@lastMeaningfulChange | Not maintained — git blame is authoritative |
@breakingChangeRisk | All said “low” — not differentiated |
@dependencies | Listed sibling exports, not actual import deps |
@usedIn | Stale immediately — scan-component-imports.js is the live source |
@status values
| Value | Meaning |
|---|---|
stable | Production-ready, actively used in v2 pages |
experimental | Working but API may change |
deprecated | Still exported for backward compat, do not use in new pages |
broken | Non-functional (e.g. empty stubs) — flagged for removal or rewrite |
@accepts values
List which extensibility props the component supports:| Value | Meaning |
|---|---|
children | Accepts child content via React children |
style | Accepts a style prop that merges with internal defaults |
className | Accepts a className prop on the outermost element |
...rest | Spreads remaining props onto the outermost element (id, data-, aria-) |
@aiDiscoverability values
Required on any component that uses React hooks (useState, useEffect, useRef, etc.).
Not required on pure/presentational components.
| Value | Meaning | Companion file location |
|---|---|---|
snapshot | Fetches external data at runtime — content invisible to crawlers/AI without a static counterpart | snippets/data/snapshots/[source-id].json (central, API-scoped, CI-regenerated) |
props-extracted | Renders props-driven data through interactive/paginated UI — full data set not in static HTML | v2/[section]/[page-slug]-data.json (adjacent to the MDX page) |
none | Uses hooks for UI state only (zoom, scroll hint, lazy visibility) — no content hidden from crawlers | No companion needed |
.json files placed alongside .mdx pages in v2/ are served as static assets at their URL path. A file at v2/developers/glossary-data.json is accessible at https://[domain]/v2/developers/glossary-data.json and readable by AI crawlers, agents, and LLM pipelines without any build config.
Write-time obligation: any author or agent writing a page that uses a props-extracted component must create the companion .json alongside the MDX.