Documentation Index
Fetch the complete documentation index at: https://na-36-merge-docs-v2-dev-draft-into-docs-v2-clean-20260525.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
UI System
A governed authoring surface on top of Mintlify. Contributors get a typed component library, copy-ready page templates, portable composables, a --lp-* design-token system with light/dark fidelity, and editor snippet expansion for every component and template. The presentation layer is held together by four governance spines – components, styles, content/voice, page composition – each with its own framework, validator, and repair command.
The net effect: fast authoring with consistent rendering, dark/light theme fidelity, WCAG-compliant focus behaviour, and zero hardcoded colour drift. The fleet-wide style remediation in early 2026 cut non-mermaid styling violations from 3,986 to 0.
UI surfaces (live, 2026-05-23)
| Surface | Where | Purpose | Canonical governance |
|---|
| Component library | snippets/components/ | 132 registry exports across 35 active JSX files + 24 archived files (59 file count) | component-framework-canonical.mdx |
| Templates | snippets/templates/ | 37 page + block + docs-guide templates across 14 sub-lanes | snippets/guide.mdx + docs-guide/catalog/ui-templates.mdx |
| Composables | snippets/composables/ | 8 Tier-1 portable composables + 73 per-tab MDX fragments under pages/ | snippets/guide.mdx + content/component governance |
| VS Code snippets | .vscode/*.code-snippets (5 files) | 312 snippets: 23 frontmatter + 25 Mintlify built-ins + 113 + 125 custom + 26 templates | Generated from component-registry.json via generate-ui-templates.js |
| Design tokens | style.css (664 lines) | Global Mintlify CSS, --lp-* namespace with light/dark pairs, theme overrides, utility layer | styles-engineering-guide.mdx |
| Assets | snippets/assets/ | 236 files (~101.5 MB): logos, media, diagrams, OG images | snippets-assets-policy.mdx |
| Data | snippets/data/ | 13 sub-folders + 4 root files (contracts, releases, exchanges, social feeds, showcase, etc.) | Per-family integrator scripts; see Data Integrations |
Component library
Count by category (live filesystem + registry, 2026-05-23)
| Category | Live .jsx files | Registry exports | Folder |
|---|
elements/ | 10 | 27+ | Buttons, links, icons, callouts, dividers, spacing primitives |
wrappers/ | 3 | 30+ | Cards, tables, containers, accordions, lists |
displays/ | 10 | 17–20 | Code blocks, video, diagrams, response fields, quotes |
scaffolding/ | 3 | 20 | Page-level layouts, heroes, frame-mode headings, portals |
integrators/ | 8 | 18–20 | Blog feeds, CoinGecko, GitHub releases, social feeds |
config/ | 1 | 1 | Shared UI config (MermaidColours) |
x-archive/ | 24 | n/a | Archived components retained for review or compatibility |
docs-guide/config/component-registry.json – they will drift unless wired to a generator. See Known gaps for the 4-surface count drift (the most-flagged UI bug across audits).
Component framework rules
- 6-category folder taxonomy with first-match-wins decision tree
- 7-tag JSDoc header standard:
@component · @type · @subniche · @status · @description · @accepts · @dataSource/@aiDiscoverability (conditional)
- Pre-commit JSDoc validator + auto-regenerated
component-registry.json
- Defensive rendering rule: a component crash kills the entire page render – null-guards are mandatory
- Lifecycle states (in
@status): stable, experimental, deprecated, broken, placeholder
- Public-facing component-library tab at
v2/resources/documentation-guide/component-library/ with per-category landing pages – generated by generate-component-docs.js
- VS Code snippet expansion for every registry export
Validators + generators
| Script | Purpose |
|---|
operations/scripts/validators/components/library/component-layout-governance.js | Validates page composition against per-pageType component contracts |
operations/scripts/generators/components/library/generate-ui-templates.js | Regenerates components-catalog.mdx, templates-catalog.mdx, ui-templates.mdx, the 5 .code-snippets files, and the public component-library/ tab |
operations/scripts/generators/components/library/generate-component-docs.js | Public component-library tab regeneration |
Templates
37 templates across 14 sub-lanes under snippets/templates/:
| Family | Examples |
|---|
| Page templates | overview, how-to, tutorial, reference, FAQ, troubleshooting, portal, landing-frame, OpenAPI-endpoint, multi-view-setup |
| Block templates | comparison matrix, comparison table, related-pages cards, related-pages CTA |
| Docs-guide templates | feature map, framework page, policy page, tooling reference page, script catalog, component catalog |
Generated section. This section is synchronised by operations/scripts/generators/components/library/generate-ui-templates.js. Do not edit the generated block by hand.Run node operations/scripts/generators/components/library/generate-ui-templates.js --write to refresh from snippets/templates/**.
Composables
| Tier | Where | What |
|---|
| Tier 1 (8 governed section blocks at root) | snippets/composables/ | related-resources-section, steps-section, prerequisites-section, accordion-faq, accordion-glossary, accordion-troubleshooting, overview-intro, validation-section |
| Per-tab fragments | snippets/composables/pages/<tab>/*.mdx | 73 files: about, gateways, gpu, home, internal, shared, unclassified, plus standalone (ecosystem.mdx, media-kit.mdx, roadmap.mdx, showcase.mdx, trending-topics.mdx) |
Composables governance violations (live, 2026-05-23)
- All 8 Tier-1 composables sit in
composables/pages/unclassified/ – the composables tree itself violates classification rules
snippets/composables/showcase-data.json is a data file in a components tree – violates snippets/guide.mdx Rule #1snippets/composables/pages/gateways/ is registered but empty- 662 KB
contractAddressesData.jsx is parked under composables/ – should live under snippets/data/contract-addresses/
Design tokens + style governance
| Surface | What it governs |
|---|
style.css (664 lines) | Global Mintlify CSS; --lp-* namespace with light/dark pairs; legacy aliases (--accent, --text) mapped to canonical tokens; 3-layer hierarchy (Mintlify theme → style.css → component styles); WCAG focus-visible enforcement |
styles-engineering-guide.mdx | Canonical style rules; 10 sections; pixel-spacing + brand tokens; design-token contract |
operations/scripts/audits/content/style/style-and-language-homogenizer-en-gb.js | UK English + style consistency audit; 6 categories + 14 auto-fix capabilities + --verify regression check |
dispatch-brand.yml | Weekly brand sweep (cron Mon 06:30 UTC); manual repair opens a PR via peter-evans/create-pull-request@v7 |
style-guide.mdx at v2/resources/documentation-guide/copy-style/style-guide.mdx still leads with deprecated --accent aliases – the engineering guide marks them deprecated but the public guide hasn’t been updated. --lp-color-text-muted flagged as borderline WCAG AA (4.2:1 on white) – needs darker default or documented exemption.
VS Code snippets (312)
5 files generated from component-registry.json + the canonical taxonomy:
| File | Count | Scope |
|---|
.vscode/mdx.code-snippets | 23 | Frontmatter blocks (with audience/pageType/status/purpose dropdowns + auto-filled lastVerified date); page scaffolds; reusable MDX patterns |
.vscode/mintlify.code-snippets | 25 | Mintlify built-ins (Card, Tabs, Steps, Accordion, etc.) |
.vscode/components.code-snippets | 113 | Custom Livepeer components |
.vscode/lp-components.code-snippets | 125 | Legacy component aliases retained for backward compatibility |
.vscode/templates.code-snippets | 26 | Full page templates by pageType + pageVariant |
Card) and opening-tag prefixes (<Card), so they expand cleanly when typed after an angle bracket.
Regenerate after registry changes:
node operations/scripts/generators/components/library/generate-ui-templates.js --write
Authoring workflow
- Check existing components first. Search
snippets/components/ and docs-guide/catalog/components-catalog.mdx before creating UI. Most needs are covered.
- Start from a template. If a page-type template exists at
snippets/templates/pages/, use the VS Code snippet (e.g. lp-overview, lp-howto) or copy the file.
- New component? Check the framework. Follow
component-framework-canonical.mdx – category placement, 7-tag JSDoc, lifecycle state, defensive null-guards.
- Keep data out of components. Components import data; they don’t embed it. Integrator components are the exception, marked by
@type integrator + @dataSource.
- Run staged validation before PR:
lpd test --staged + node operations/scripts/validators/components/library/component-layout-governance.js --staged.
Authoring contracts (canonical sources)
| Contract | Where it lives | Enforced by |
|---|
| Component classification + JSDoc + lifecycle | component-framework-canonical.mdx | Pre-commit JSDoc validator + auto-regenerated registry |
| Component governance (duplicate authority – see Known gaps) | component-governance.mdx | (retiring per D-DG-08) |
| Page taxonomy (pageType, audience, purpose enums) | docs-guide/frameworks/content-writing.mdx | Per-page review pipeline Cat 1 |
| Page composition (template + section structure) | docs-guide/frameworks/checks-framework.mdx (consolidated 2026-05-23; prior page-composition-framework.mdx retired) | Per-page review pipeline Cat 5 |
| Voice + copy + heading rules | docs-guide/standards/voice-and-copy.mdx | Cat 2, Cat 3 of per-page review |
| Authoring standard | docs-guide/standards/authoring-standard.mdx | Quality bar at publication gate |
| Frontmatter spec | docs-guide/standards/frontmatter.mdx | Cat 1 |
| Naming conventions | docs-guide/standards/naming-conventions.mdx | Pre-commit naming check |
| Snippets root governance | snippets/guide.mdx | Snippets taxonomy rules (data vs components vs composables vs assets) |
| Mintlify platform constraints | docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md | Per-page review Cat 5 + render gate |
Known gaps
4-surface component count drift
| Surface | Claim | What it counts |
|---|
docs-guide/features/ui-system.mdx (this page, prior version) | 59 | JSX file count (35 active + 24 archive) |
docs-guide/frameworks/component-framework-canonical.mdx count table | 118 | Hand-authored count |
v2/resources/documentation-guide/component-library/overview.mdx | 117 | Public-facing export count |
docs-guide/config/component-registry.json | 132 | Generator-produced export count (the truth) |
component-registry.json. Add a CI assertion that fails when any .mdx contains a literal count diverging from the registry. Same fix applies to ui-system.mdx, component-framework-canonical.mdx, and the public component-library overview.
Wrapper-vs-display category/folder mismatch
Six components are tagged category: wrappers in the registry but live under snippets/components/displays/...:
- AccordionGroupList, BasicList, CardCarousel, DisplayCard, DynamicTable
(plus one or two more flagged in SLICE-02.) Either move the files to snippets/components/wrappers/ OR update @type in their JSDoc to displays. Then rerun pre-commit registry generation.
Registry generator bug
Per SLICE-08: snippets/snippets-registry.mdx lines 868-878 mis-label all displays/* subfolders as “wrappers subtree”. The wrapper-vs-display drift above traces back to this generator bug.
Template duplicates
4 byte-identical template pairs:
source-of-truth × 2glossary-consolidated × 2glossary-tab × 2openapi-endpoint-page × 2
Plus singular/plural example MDX drift. The catalog generator does not deduplicate.
Composables in unclassified/
All 8 Tier-1 composables sit in composables/pages/unclassified/ – flagrant governance violation in the composables tree itself. Move to a classified subdir per snippets/guide.mdx Rule #2.
Data files in composables tree
662 KB contractAddressesData.jsx parked under composables/. Plus 3 other data files. Violates snippets/guide.mdx Rule #1 (data files belong under snippets/data/).
page-taxonomy-framework.mdx and page-composition-framework.mdx are scratch notes
Both sit under docs-guide/frameworks/ but are not real frameworks:
page-composition-framework.mdx is a literal MDX template scaffold with placeholder description “Describe page-structure-template”page-taxonomy-framework.mdx has no frontmatter and contains typo’d field labels (Decription:)
Per the canonical content-writing.mdx + this page, both should be rewritten as real frameworks (sourcing from v2/orchestrators/_workspace/canonical/Frameworks.mdx) or moved to _workspace/.
component-governance.mdx is a duplicate authority
Per locked D-DG-08, docs-guide/frameworks/component-governance.mdx is retired in favour of component-framework-canonical.mdx. The file still exists at the active path. Cleanup: propagate refs, add redirects, queue governed deletion.
Public style-guide leads with deprecated aliases
v2/resources/documentation-guide/copy-style/style-guide.mdx references --accent aliases as primary tokens. The engineering guide marks them deprecated. Refresh the public surface or document the alias rule explicitly.
--lp-color-text-muted borderline WCAG AA
Contrast ratio 4.2:1 on white – below the 4.5:1 AA threshold for body text. Either darken the default or document a per-use exemption.
Cleanup queue (13 files)
- 11
.DS_Store files across snippets/ subdirectories
- 1
.legacy-duplicate.json file
- 1 zero-byte template file
All flagged in SLICE-08 inventory; purge via the governed deletion path.
Catalog freshness drift
docs-guide/catalog/templates-catalog.mdx + ui-templates.mdx last regenerated 2026-04-03 – 50 days stale. components-catalog.mdx embeds raw componentTableData export with the comment {/* should not be here. */} – author noted the data block doesn’t belong inline. No CI workflow forces regeneration on snippets/templates/ or snippets/components/ change.
24 archived components have no removal schedule
snippets/components/x-archive/ holds 24 archived JSX files. No documented schedule for delete vs keep-as-compatibility-alias. Triage each: DELETE or KEEP-AS-ALIAS (with @status deprecated + removal date).
.vscode/livepeer-legacy.code-snippets.bak still tracked
35 KB backup file. Replaced by lp-components.code-snippets + templates.code-snippets. Purge candidate.
components.code-snippets (113) + lp-components.code-snippets (125) overlap
Both generated from component-registry.json. Maintaining two snippet files with overlapping prefixes is governance debt. Either declare a scope-split (e.g. lp-* = legacy aliases) or merge to one.
- Component Framework Canonical – 6-category taxonomy + 7-tag JSDoc + decision tree + lifecycle states
- Styles Engineering Guide –
--lp-* design tokens + theme contract + 3,986→0 metric history
- Component Governance Policy – locked component decisions
- Snippets / Assets Policy – what goes under
snippets/ and what doesn’t
- Content Writing Pipeline – page taxonomy (the source for pageType + audience + purpose enums)
- Checks Framework – Cat 5 (Layout + Components) + per-pageType specific checks
- Components Catalog – generated component listing
- UI Templates – generated template inventory with
<Tree> view
snippets/guide.mdx – snippets root governance (data vs components vs composables vs assets)docs-guide/config/component-registry.json – the source of truth for component countsworkspace/thread-outputs/repo-consolidation-deep/SLICE-08-snippets.md – full snippets-tree inventory (410 lines)
