Component Governance Framework

Canonical reference for how components are classified, built, documented, and maintained in snippets/components/.

Component Governance Framework

Repository: livepeer/docs, docs-v2 branch
Scope: snippets/components/ — the governed component library
Platform: Mintlify (MDX-based)
Version: 1.0
Date: 7 March 2026
Author: Wonderland (Alison Haire) / Claude collaboration
Source deliverables: D1–D6 of the Component Governance Framework plan

Quick Start

You’re a contributor. You want to build, use, or modify a component. Here’s everything you need in 60 seconds.

Find a component

Use the Component Registry or the published Component Library pages. Every component has a status badge, props table, and copy-paste example.

Use a component

Import with the full explicit path in your MDX page:

import { CustomDivider } from '/snippets/components/elements/spacing/Divider.jsx'

<CustomDivider />

Mintlify requires full paths with file extensions. No barrel imports. Inter-component imports via absolute /snippets/ paths are permitted — the importing component handles its own dependencies, so the consuming MDX page does not need to re-import sub-components used internally. Circular imports are not allowed. Shared non-visual runtime logic may be kept inline in the exported component or imported from a colocated non-component .js helper module.

Decide which category

Follow the decision tree (first match wins):

1. Fetches, embeds, or binds to external/third-party data? → integrators/
2. Part of the page’s outer structure, typically used once? → scaffolding/
3. Takes content and presents it in a formatted way? → displays/
4. Exists to hold, group, or arrange other things? → wrappers/
5. Single visual piece — no wrapping, no arranging, no fetching? → elements/

Build a new component

1. Create your .jsx file in the correct category folder.
2. Use arrow function syntax (export const X = () => ...).
3. Add the full JSDoc block (6 governance fields + @aiDiscoverability if hook-using + @param per prop + @example).
4. Use var(--lp-*) CSS tokens for all colours. No hardcoded hex. No ThemeData.
5. Add defensive rendering — guard all props, never throw. A crash kills the entire page.
6. Create an example in {category}/examples/{file}-examples.mdx.
7. Write unit tests in operations/tests/unit/components/{category}/{file}.test.js.
8. Verify visually in both light and dark mode via mintlify dev.
9. Commit. Pre-commit validates JSDoc, regenerates the registry, and checks styling rules.

Component checklist (full)

JSDoc
  □ All 6 governance fields present (+ @aiDiscoverability if hook-using)
  □ @param for every prop
  □ @example with primary usage

Props
  □ camelCase names
  □ Boolean props: is/has prefix
  □ Handler props: on prefix
  □ Defaults in destructuring
  □ children for slot content, named props for data
  □ Spread last (...rest)
  □ Required props: no default. Optional: always have default.

Composition
  □ Inter-component imports use absolute `/snippets/` paths only
  □ No circular imports between `.jsx` component files
  □ Shared runtime logic for MDX-facing components stays inline or comes from a colocated `.js` helper import
  □ Renders correctly standalone and inside Mintlify globals

Styling
  □ Colours use var(--lp-*) tokens
  □ No ThemeData, no hardcoded hex, no !important
  □ Dark/light mode works (tokens + Tailwind dark:)

Error Handling
  □ Null-safe prop access throughout
  □ Required props guarded — returns null if missing
  □ Array operations guarded: (items ?? []).map()
  □ Try-catch wraps complex logic
  □ console.warn on degradation
  □ Never throws

Accessibility
  □ Semantic HTML elements
  □ Images have alt text
  □ [If interactive] ARIA attributes present
  □ [If interactive] Keyboard operable

Testing
  □ Visual verification: light and dark mode
  □ Browser test coverage: page renders
  □ Unit tests: valid props, no props, null data, missing required

1. Classification & Purpose Model

1.1 Category Taxonomy

Six categories. Every component belongs to exactly one.

Category	Folder	Purpose
Elements	elements/	Standalone visual atoms — icons, text, callouts, links, images, math, dividers, a11y
Wrappers	wrappers/	Containers that hold, group, or spatially arrange other components
Displays	displays/	Renderers for authored content — code, video, diagrams, quotes, response fields
Scaffolding	scaffolding/	One-per-page structural skeleton — heroes, portals, frame-mode overrides
Integrators	integrators/	Fetches, embeds, or binds to external data — feeds, embeds, video, APIs
Config	config/	Non-component configuration objects (e.g. theme, colour maps)

1.2 Decision Tree

Classify by answering in order. First match wins.

Q1: Fetches, embeds, or binds to external/third-party data?
    YES → INTEGRATORS

Q2: Part of the page's outer structure, typically used once?
    YES → SCAFFOLDING

Q3: Takes content and presents it in a formatted way?
    YES → DISPLAYS

Q4: Exists to hold, group, or arrange other things?
    YES → WRAPPERS

Q5: Default → ELEMENTS

Order rationale: Integrators and Scaffolding are checked first because they’re the most constrained (fewest false positives). Displays catches formatting/rendering components. Wrappers catches spatial arrangement. Elements is the default atom.

1.3 Library Boundary

Inside: snippets/components/ and its six category subdirectories. Every exported component here is governed.

Outside (not governed by this framework):

Pattern	Governed by
Mintlify globals (Card, Tabs, Accordion, etc.)	Mintlify platform
MDX composables (snippets/composables/)	Composable Content Structure — see Section 12
Data snippets (snippets/data/)	Data integration layer

Mintlify enforces that all importable JSX lives under /snippets/. No “section-local components” are possible outside this path.

1.5 Data & Props Surface

Prop inputs are documented via @param tags on each exported component. For integrators, @dataSource identifies the external pipeline or API. See Section 5.2 for the full 6-field schema.

2. Repo Structure & Documentation Architecture

2.1 Folder Layout

snippets/components/
├── elements/          # Visual atoms — icons, text, links, callouts, math, spacing
│   ├── icons/
│   ├── links/
│   ├── spacing/
│   └── ...
├── wrappers/          # Containers that group or arrange other components
│   ├── cards/
│   ├── grids/
│   ├── tables/
│   └── ...
├── displays/          # Content renderers — code, video, diagrams, quotes
│   ├── code/
│   ├── media/
│   └── ...
├── scaffolding/       # One-per-page structure — heroes, portals, frame-mode
│   ├── frame-mode/
│   └── ...
├── integrators/       # External data — feeds, embeds, APIs
│   ├── embeds/
│   └── ...
├── config/            # Non-component configuration objects
└── x-archive/         # Superseded files (retained until final cleanup)

Sub-niche folders within each category. One examples/ subdirectory per category where the category uses runnable examples.

2.2 Naming Conventions

Element	Convention	Example
Files	PascalCase .jsx (canonical)	FrameMode.jsx, HeroGif.jsx
Exports	PascalCase, named, arrow function	export const PageHeader = () => ...
Example files	kebab-case -examples.mdx	frame-mode-examples.mdx

2.3 File Granularity

Grouped files with per-export JSDoc. Related components share a file. Each export gets its own 6-field JSDoc block. Non-exported helpers are implementation details.

2.4 Import Paths

Full explicit paths. Mintlify requires file extensions. No barrel imports.

import { CustomDivider } from '/snippets/components/elements/spacing/Divider.jsx'
import { StyledTable, TableRow } from '/snippets/components/wrappers/tables/Tables.jsx'

2.5 Documentation Architecture

JSDoc (SOT for metadata + props)
    ↓
docs-guide/config/component-registry.json (generated by pre-commit)
    ↓
Published MDX pages (generated, LLM editorial + template fallback)

Per-folder READMEs are deprecated. The registry and published pages are the two documentation surfaces.

2.6 Registry

Single JSON at docs-guide/config/component-registry.json. Generated by pre-commit hook when files in snippets/components/ are staged. Contains all 6 enforced governance fields per component plus derived fields (file, importPath). Script: operations/scripts/generators/components/library/generate-component-registry.js.

3. Styling Architecture & Standards

3.1 Three-Layer Hierarchy

Layer 1: Mintlify Theme (docs.json) — platform colours, layout, dark mode toggle
Layer 2: style.css (repo root) — --lp-* CSS custom properties, Mintlify overrides
Layer 3: Component styles — consume tokens, scoped vars if documented

Components consume var(--lp-*) tokens. They rarely define new variables (only for computed/dynamic values, with documentation).

3.2 Token Namespace

All tokens use --lp- prefix: --lp-color-*, --lp-spacing-*, --lp-font-*, --lp-radius-*, --lp-shadow-*, --lp-z-*.

Every --lp-color-* token has both light and dark values defined in style.css.

3.3 Banned Patterns (Pre-commit Blocks)

Pattern	Why
ThemeData	Deprecated, causes bugs
Hardcoded hex/rgb	Breaks dark mode, prevents centralised updates
!important	If you need it, the hierarchy is wrong

3.4 Advisory Patterns (Code Review Flags)

Pattern	Guidance
Static inline style={}	”Could this be a var(--) token?”
Direct Mintlify class overrides	Should go through style.css, not component JSX

3.5 Dark/Light Mode

Concern	Mechanism
Colour values	var(--lp-color-*) tokens — automatic light/dark swap
Visibility/layout toggles	Tailwind dark: classes (dark:hidden, hidden dark:block)
JS theme detection	Never. No reading document.documentElement in components.

3.6 Mintlify Override Registry

Overrides in style.css are documented technical debt. Each entry tracks: what’s overridden, which Mintlify limitation necessitates it, introduction date, review date, owner, status. Reviewed quarterly against Mintlify release notes.

4. Component Development Standards

4.1 Props Conventions (7 Rules)

1. camelCase prop names
2. is/has prefix for booleans (isCompact, hasIcon)
3. on prefix for handlers (onClick, onToggle)
4. Defaults in destructuring (({ variant = 'default' }) => ...)
5. children for slot content, named props for data
6. Spread last (<div className={...} {...rest}>)
7. Required props: no default. Optional: always have default.

4.2 Composition

Inter-component imports are permitted via absolute /snippets/ paths. The importing component handles its own dependencies — the consuming MDX page does not need to re-import sub-components used internally by a component. Circular imports are not allowed.

Same-file references are also allowed (co-located components share scope).

4.3 Accessibility

All components: Semantic HTML, alt text on images, heading hierarchy, descriptive link text.

Interactive components (SearchTable, CardCarousel, ShowcaseCards, CopyText, DownloadButton, ScrollBox): additionally require ARIA roles/attributes, keyboard operability (Tab, Enter/Space, Escape), and visible focus indicators.

4.4 Error Handling (Mandatory)

Mintlify has no error boundary per component. A component crash kills the entire page. Defensive rendering is non-negotiable.

Rule	Implementation
Null-safe prop access	Optional chaining, default values
Guard required props	Return null + console.warn if missing
Guard arrays	(items ?? []).map(...)
Try-catch complex logic	Wrap computed values, data transforms
Console.warn on degradation	console.warn('[ComponentName] reason')
Never throw	Catch internally, degrade gracefully

MDX-facing component rule: if a .jsx file is imported directly by a routable MDX page, exported components in that file must not rely on private file-scope helpers. Keep defensive logic inline in the exported component or import it from a colocated non-component .js helper module. Do not hoist the logic into top-level private locals inside the .jsx file.

4.5 Testing (Three Tiers)

Tier	What	How	Required for
Visual verification	Light + dark mode rendering	Manual, mintlify dev	All components
Browser tests	Page renders without error	CI, existing infrastructure	All used components
Unit tests	Props, edge cases, defensive rendering	CI, operations/tests/unit/components/	All components

Core unit test cases (every component): renders with valid props, renders with no props, handles null/undefined data, handles missing required props, handles invalid prop types.

5. Documentation & Example Standards

5.1 JSDoc Template

Every exported component carries this block:

/**
 * @component ComponentName
 * @category elements
 * @subcategory icons
 * @status stable
 * @description One-line purpose statement.
 *
 * @param {string} [variant='default'] - Visual variant. One of: 'default', 'compact'.
 * @param {boolean} [isCompact=false] - Compact rendering mode.
 *
 * @example
 * <ComponentName />
 * <ComponentName variant="compact" />
 */

@dataSource is additionally required for all components in integrators/. All other governance fields are required for every export.

5.2 Metadata Schema (6 Fields + 1 Conditional, Enforced)

#	Tag	Type	Values
1	@component	string	PascalCase export name
2	@category	enum	elements · wrappers · displays · scaffolding · integrators · config
3	@subcategory	string	Sub-folder name within the category
4	@status	enum	stable · experimental · deprecated · broken · placeholder
5	@description	string	One-line purpose
6	@dataSource	string	External pipeline/API (integrators only; none for others)
7	@aiDiscoverability	enum	snapshot · props-extracted · none — required on any hook-using component (useState, useEffect, etc.); omit on pure/presentational components

@aiDiscoverability declares whether a component hides content from crawlers and AI pipelines at runtime, and where its static companion file lives:

• snapshot → external-fetch component; companion at snippets/data/snapshots/[source-id].json (CI-regenerated)
• props-extracted → interactive/paginated UI; companion at v2/[section]/[page-slug]-data.json (author obligation, adjacent to MDX)
• none → hooks used for UI state only; no content hidden; no companion needed

5.3 Props Table Format (Published Docs)

Prop	Type	Default	Required	Description
href	string	—	Yes	Destination URL
icon	string	'livepeer'	No	Brand icon

Generated from @param tags. Five columns.

5.4 Examples

One rendered MDX example per exported component in {category}/examples/{file}-examples.mdx. Copy-paste ready with import statement. Required for stable components only.

5.5 Published Docs Generation

Fully automated. Zero human maintenance.

1. Registry generation (pre-commit): JSDoc → component-registry.json
2. Docs generation (manual/chained): registry + @param + @example + OpenRouter LLM → published MDX pages
3. LLM failure fallback: template-generated prose from metadata (deterministic)

5.6 Deprecation

/**
 * @status deprecated
 * @deprecated Use GotoCard instead. Scheduled for removal Q3 2026.
 * @see GotoCard
 */

Published docs show deprecation banner. Component section moved to bottom of category page.

6. Lifecycle & Governance

6.1 Lifecycle States

State	Meaning	Badge
stable	Production-ready, tested, documented	Green
experimental	Usable, API may change	Yellow
deprecated	Scheduled for removal, replacement identified	Red
broken	Known defect, do not use	Red
placeholder	Stub/empty, not functional	Grey

6.2 Transitions

Free transitions — any state to any state. Update @status in JSDoc. Document reason in commit message. Registry captures the change automatically.

6.3 Governance Taxonomy

Category-level. One governance label per folder.

The current metadata field is owner, but it is taxonomy, not reviewer assignment or gatekeeper authority. Historical GitHub review maps may remain archived for reference, but tests, generated registries, and repair commands are the active contract.

6.4 Modification Rules

No immutability rule. Automated validation and the existing test infrastructure (58-script suite, 17 CI workflows, pre-commit hooks, browser tests) are the gates. Human review is collaborative, not ownership-based.

6.5 Deprecation & Removal

Usage-gated. A deprecated component is removed only when @usedIn is empty — no pages reference it. The registry tracks consumers. Published docs surface remaining consumers as migration prompts.

7. Enforcement Summary

What’s enforced, where, and how.

What	Enforced by	Blocks commit?
6 JSDoc governance fields present	Pre-commit validation (generate-component-registry.js --strict)	Yes
@param coverage matches props	Pre-commit validation	Yes
@category matches folder	Pre-commit validation	Yes
@status is valid enum	Pre-commit validation	Yes
@deprecated present when status=deprecated	Pre-commit validation	Yes
No ThemeData	Pre-commit regex scan	Yes
No hardcoded hex/rgb	Pre-commit regex scan	Yes
No !important	Pre-commit regex scan	Yes
Registry regeneration	Pre-commit auto-generation	Auto-staged
Static inline styles	Copilot code review	No (advisory)
Mintlify class overrides	Copilot code review	No (advisory)
Props conventions	Code review (human + Copilot)	No
Accessibility (ARIA)	Code review + unit tests	Partially
Defensive rendering	Unit tests	Yes (CI)
Page-level rendering	Browser tests	Yes (CI)
Visual light/dark mode	Manual verification	No

8. Generation Pipeline

8.1 Registry Generation

Trigger:  pre-commit (staged files in snippets/components/)
Script:   operations/scripts/generators/components/library/generate-component-registry.js
Input:    all JSDoc blocks in snippets/components/**/*.jsx
Output:   docs-guide/config/component-registry.json (auto-staged)
Errors:   missing/invalid fields → commit blocked

8.2 Published Docs Generation

Trigger:  manual or chained after registry update
Script:   operations/scripts/generators/components/documentation/generate-component-docs.js
Input:    registry + @param + @example + examples/ MDX files
Process:  OpenRouter LLM for editorial prose, template fallback on failure
Output:   7 published MDX pages per locale (overview + per-category) across 4 locales
Caching:  LLM output cached per component hash

9. Decision Register (All 33 Decisions)

D1: Classification & Purpose Model

#	Decision	Choice
1	Category taxonomy	Six: Elements, Wrappers, Displays, Scaffolding, Integrators, Config
2	Compositional model	Metadata only — sub-niche folders, no compositional tier tag
3a	Metadata location	JSDoc block in each JSX file
3b	Metadata schema	6 enforced fields (down from aspirational 14)
4	Decision mechanism	Decision tree — ordered yes/no, first match wins
5	Library boundary	snippets/components/ only

D2: Repo Structure & Documentation Architecture

#	Decision	Choice
1	Naming conventions	camelCase files, PascalCase exports
2	File granularity	Grouped files with per-export JSDoc
3	Canonical docs home	Hybrid — JSDoc SOT for metadata, published MDX SOT for editorial
4	Registry format	Single JSON at docs-guide/config/component-registry.json
5	Generation pipeline	Pre-commit hook auto-regeneration
6	Examples convention	Co-located examples/ per category
7	Import paths	Full explicit paths (Mintlify constraint)

D3: Styling Architecture & Standards

#	Decision	Choice
1	Style system authority	Layered — components may define scoped vars if documented
2	Forbidden patterns	Strict ban (3) + advisory (2)
3	Dark/light mode	CSS tokens + Tailwind dark: utility
4	Inline styles	Advisory flag sufficient
5	Design tokens	Rationalise and document with --lp-* namespace
6	Mintlify override policy	Override registry — documented, justified, review-dated

D4: Component Development Standards

#	Decision	Choice
1	Props conventions	Standard 7 rules
2	Composition	Inter-component imports via absolute /snippets/ paths; no circular imports
3	Accessibility	Semantic HTML + ARIA for interactive components
4	Error handling	Defensive rendering mandatory — page crash prevention
5	Testing	Visual + browser + unit tests (three tiers)

D5: Documentation & Example Standards

#	Decision	Choice
1	JSDoc scope	6 governance fields + @param + @example
2	Props table format	Standard 5-column
3	Example requirements	Minimal — one per component, copy-paste ready
4	Published docs	LLM-generated (OpenRouter) + template fallback, zero maintenance
5	Deprecation docs	@deprecated + @see pointer

D6: Lifecycle & Governance Model

#	Decision	Choice
1	Lifecycle states	Five: stable, experimental, deprecated, broken, placeholder
2	Transitions	Free — any to any, documented in commit
3	Governance taxonomy	Category-level metadata; reviewer routing is not the contract
4	Immutability	No rule — code review + tests are the gate
5	Deprecation process	Usage-gated removal — only when @usedIn is empty

10. Upstream Dependencies

This framework consumes but does not redefine:

Document	What it provides
Page Taxonomy (SOT-00)	10 page types — components map via @contentAffinity
Content Taxonomy	Structural patterns per page type — components are the rendering layer
Composable Content Structure	Four reuse patterns — this framework governs UI components only
Mintlify Considerations	Platform constraints: /snippets/ paths, absolute import paths, arrow function syntax

11. Completed Work (D8 + D9)

The following were open items at framework inception and are now complete as of 2026-03-20:

• ✅ All components classified and migrated to new taxonomy (elements/wrappers/displays/scaffolding/integrators/config)
• ✅ All JSDoc governance fields populated on every governed export (6-field schema enforced by --strict)
• ✅ generate-component-registry.js operational — generates docs-guide/config/component-registry.json
• ✅ generate-component-docs.js operational — generates published MDX pages per locale
• ✅ Pre-commit hook enforces JSDoc fields and auto-stages registry
• ✅ Published component library pages regenerated for all 4 locales
• ✅ Import paths updated across all MDX pages after folder restructure
• ✅ ThemeData removed from all components
• ✅ Duplicate components resolved and archived

Remaining (deferred to CONTENT-STRUCTURE Phase 5.1):

• component-layout-decisions.mdx update — see Section 12.3 below; unblocked as of 2026-03-21

12. Composable Content Layer

12.1 Three-Layer Architecture

Components (snippets/components/) are the middle layer of a three-layer content architecture:

Layer	Location	What it is	Governed by
Data	snippets/data/, v2/[section]/[page-slug]-data.json	Structured data consumed by components	AI Discoverability framework
Components	snippets/components/	JSX rendering units	This document
Composables	snippets/composables/	Portable MDX section blocks	Composable Content Structure

Platform constraint (Decision D4): JSX inter-component imports are permitted via absolute /snippets/ paths, but circular imports are not allowed. Composables are .mdx files because they compose multiple components with authored prose. MDX can freely import JSX components; JSX can import other JSX via absolute paths.

12.2 Composable Section Library

As of 2026-03-21, snippets/composables/ contains 8 composable section blocks:

Composable	Tier	Page types
related-resources-section.mdx	1	All — mandatory footer
steps-section.mdx	1	instruction, tutorial, start, build
prerequisites-section.mdx	1	instruction, tutorial, start
accordion-faq-section.mdx	1	reference (compendium), concept
accordion-glossary-section.mdx	1	reference (compendium), concept
accordion-troubleshooting-section.mdx	1	reference (compendium), instruction
overview-intro-section.mdx	2	All — optional opening block
validation-section.mdx	2	instruction, tutorial, start

Each composable includes a @composable governance header (purpose, pageTypes, variables, notes) and uses {/* */} comments to show optional sub-elements inline at point of use.

Lifecycle rule: Content starts local to a page. Promote to snippets/composables/ only when a concrete second consumer appears.

12.3 @contentAffinity

@contentAffinity is a deferred JSDoc field (field #8 on the aspirational schema, deferred in prior sessions) that declares which page types a component is appropriate for.

Status: Not yet enforced. Page taxonomy is now locked (15 purpose values, 10 pageType values), making this field unblocked.

Proposed syntax:

/**
 * @contentAffinity  start, build, instruction
 */
export const StepsWizard = () => ...

When to add it: When a component’s appropriate page types are non-obvious from its name and category. Not required on universal components (CustomDivider, CardGroup equivalents). Required on scaffolding/, integrators/, and page-specific displays/.

Enforcement: Add to --strict mode in generate-component-registry.js as part of CONTENT-STRUCTURE Phase 5.1.