Skip to main content

​
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)

​
Component library

​
Count by category (live filesystem + registry, 2026-05-23)

Counts above must be regenerated from 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

​
Templates

37 templates across 14 sub-lanes under snippets/templates/: Each template is exposed via:
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

Composable lifecycle rule: promote local MDX content to a composable only when a second consumer appears. Premature composable extraction creates governance debt.

​
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 #1
  • snippets/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

Baseline metric: style violations went from 3,986 → 0 non-mermaid during the 2026-04 styles governance push. 68 mermaid dark-mode variants accepted (not yet automated). Known token drift: the public 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: JSX tag snippets accept both bare names (Card) and opening-tag prefixes (<Card), so they expand cleanly when typed after an angle bracket. Regenerate after registry changes:

​
Authoring workflow

  1. Check existing components first. Search snippets/components/ and docs-guide/catalog/components-catalog.mdx before creating UI. Most needs are covered.
  2. 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.
  3. New component? Check the framework. Follow component-framework-canonical.mdx – category placement, 7-tag JSDoc, lifecycle state, defensive null-guards.
  4. Keep data out of components. Components import data; they don’t embed it. Integrator components are the exception, marked by @type integrator + @dataSource.
  5. Run staged validation before PR: lpd test --staged + node operations/scripts/validators/components/library/component-layout-governance.js --staged.

​
Authoring contracts (canonical sources)

​
Known gaps

​
4-surface component count drift

Reality: 132 named registry exports across 35 active JSX files + 24 archived = 59 files. Both numbers are correct for different scopes; no surface declares which scope it uses. Fix: replace every hand-authored count with a generator-emitted block sourced from 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 × 2
  • glossary-consolidated × 2
  • glossary-tab × 2
  • openapi-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 counts
  • workspace/thread-outputs/repo-consolidation-deep/SLICE-08-snippets.md – full snippets-tree inventory (410 lines)
Last modified on May 22, 2026