Styles Engineering Guide

Internal engineering reference. For the user-facing style guide, see the Documentation Style Guide.

Pipeline Architecture

The styles governance system follows the repo’s standard pipeline pattern: Config → Script → Data → Display → Enforcement.

┌─────────────────────────────────────────────────────┐
│  P1 (pre-commit)                                     │
│  audit-styles.js --staged --exit-code                │
│  → blocks commits with NEW high-severity violations  │
├─────────────────────────────────────────────────────┤
│  P3 (PR check)                                       │
│  audit-styles.js --json --exit-code                  │
│  → gates PR merge                                    │
├─────────────────────────────────────────────────────┤
│  P5 (weekly cron)                                    │
│  remediator-brand-repair-style-tokens.yml → full audit report            │
│  → artifact upload for review                        │
├─────────────────────────────────────────────────────┤
│  P6 (on-demand)                                      │
│  remediator-brand-repair-style-tokens.yml → manual dispatch              │
│  → audit OR remediate-dry-run OR remediate-write     │
│  → remediate-write creates PR via peter-evans         │
└─────────────────────────────────────────────────────┘

Scripts Reference

Audit Validator

Path: tools/scripts/validators/styles/audit-styles.js Purpose: Scans MDX and JSX files for 6 categories of style violations. Usage:

# Full audit with report
node tools/scripts/validators/styles/audit-styles.js --verbose --json

# Staged files only (for pre-commit)
node tools/scripts/validators/styles/audit-styles.js --staged --exit-code

# Filter to specific category
node tools/scripts/validators/styles/audit-styles.js --category inline-style-mdx --verbose

# Specific files
node tools/scripts/validators/styles/audit-styles.js --files v2/about/mental-model.mdx --verbose

Categories:

ID	Severity	What it detects
`inline-style-mdx`	high	`style={{}}` in MDX (causes layout shift)
`legacy-token`	medium	`var(--accent)` instead of `var(--lp-color-accent)`
`hardcoded-hex-mdx`	medium	Hex colours outside code blocks in MDX
`literal-spacing`	low	Literal rem/px values instead of `--lp-spacing-*` tokens
`mermaid-hardcoded`	medium	Mermaid init directives not matching standard signature
`outline-removal`	high	`outline: none` or `outline: 0` (WCAG violation)

Context awareness: Skips code blocks, inline code, frontmatter, and mermaid blocks. Uses relative paths for exclude matching (safe in worktrees). Report output: workspace/reports/styles/styles-audit-report.json

Remediator

Path: tools/scripts/remediators/styles/remediate-styles.js Purpose: Safe, deterministic auto-fixes for style violations. Idempotent (running twice produces zero changes). Usage:

# Preview fixes
node tools/scripts/remediators/styles/remediate-styles.js --dry-run

# Apply fixes
node tools/scripts/remediators/styles/remediate-styles.js --write

# Fix specific category only
node tools/scripts/remediators/styles/remediate-styles.js --write --category legacy-token

# Fix specific files
node tools/scripts/remediators/styles/remediate-styles.js --write --files snippets/components/display/quote.jsx

What it fixes (14 capabilities):

Type	Before	After	Scope
`legacy-token`	`var(--accent)`	`var(--lp-color-accent)`	JSX
`outline-removal`	`outline: "none"`	`outline: "revert"`	JSX
`mermaid-hardcoded`	Custom init directive	Standard MermaidColours init	MDX
`hardcoded-hex`	`"#3CB540"`	`"var(--lp-color-accent)"`	JSX + MDX
`literal-spacing`	`"1rem"`, `"4px"`	`"var(--lp-spacing-4)"`, `"var(--lp-spacing-px-4)"`	JSX
`flex-center-to-component`	`<div style={{display: "flex", justifyContent: "center"}}>`	`<FlexContainer justify="center">`	MDX
`flex-column-to-component`	`<div style={{display: "flex", flexDirection: "column"}}>`	`<FlexContainer direction="column">`	MDX
`centered-fit-to-component`	`<div style={{...width: "fit-content", margin: "0 auto"}}>`	`<CenteredContainer preset="fitContent">`	MDX
`span-divider-to-component`	`<span style={{display: "block", borderBottom: ...}} />`	`<InlineDivider margin="1rem 0" />`	MDX
`bordered-div-to-component`	`<div style={{border: "1px solid ...", borderRadius: "8px"}}>`	`<BorderedBox variant="accent">`	MDX
`styledsteps-fallback`	`var(--accent-dark, #18794E)`	`var(--lp-color-accent-strong)`	MDX
`icon-label-to-customcardtitle`	`<span style={{...flex...}}><Icon.../> Text</span>`	`<CustomCardTitle variant="tab" icon="X" title="Text" />`	MDX
`bold-text-to-subtitle`	`<span style={{color: "var(--hero-text)", fontWeight: "bold"}}>`	`<Subtitle variant="changelog">`	MDX
`date-label-to-subtitle`	`<div style={{fontSize: "0.8rem", fontWeight: 700}}>`	`<Subtitle variant="changelog">`	MDX

Verification (--verify flag):

# Apply fixes + verify no regressions
node tools/scripts/remediators/styles/remediate-styles.js --write --verify

When --verify is passed with --write:

After applying fixes, re-runs audit on modified files only
Checks MDX files for parse issues (conflict markers, missing import blank lines)
If any check fails, reverts ALL changes and exits non-zero

Safety:

Reverse-offset replacement (processes matches from end to start)
Never modifies code blocks, inline code, JSX comments, frontmatter
Skips exempt files (MermaidColours.jsx, style.css)
Skips non-layout properties for spacing (fontSize, borderRadius, width, height, etc.)
Standard mermaid signature check prevents re-processing compliant inits
Component migration finds matching closing tags via depth-aware parser
Dynamic replacement extracts icon names and text content from regex captures

Self-documenting: Run node tools/scripts/generators/styles/generate-styles-docs.js --check to verify documentation matches source code.

Data Pipelines

CoinGecko Exchanges

Script: operations/scripts/integrators/maintenance/data-feeds/fetch-exchanges-data.js Workflow: .github/workflows/update-exchanges-data.yml Output: snippets/data/exchanges/exchangesData.jsx Schedule: Weekly Monday 03:00 UTC API: CoinGecko /coins/livepeer/tickers (no API key required for free tier)

go-livepeer Configuration Flags

Script: operations/scripts/integrators/maintenance/data-feeds/fetch-config-flags.js Workflow: .github/workflows/update-config-flags.yml Output: snippets/data/gateways/configFlagsData.jsx Schedule: Weekly Monday 04:00 UTC Source: Parses cmd/livepeer/starter/flags.go from GitHub raw content Both scripts support --dry-run mode.

Component Authoring Checklist (Styles)

When creating or modifying components, verify:

Uses var(--lp-color-*) tokens, not legacy aliases or hardcoded hex
Accepts style={} and className="" props with merge pattern ({...defaultStyle, ...style})
Uses var(--lp-spacing-*) tokens for standard spacing (0.25rem–2rem)
No outline: none — use :focus-visible in a scoped <style> block if custom focus needed
Dark mode works via CSS variables (no JS theme detection)
data-docs-* attribute if style.css needs to target the component
Responsive: uses Tailwind responsive classes or <style> media queries
Tested at 375px, 768px, and 1024px viewports

Mintlify CLI Tools

Command	Purpose	When to use
`mint a11y`	Colour contrast + alt text	After any colour or image changes
`mint broken-links`	Link validation	After file moves or new links
`mint validate`	Full build validation	Before creating PRs
`mint dev`	Local preview	During development

Baseline Metrics

Metric	Initial (2026-04-07)	Final (2026-04-08)	Reduction
Total violations	3,986	74	98.1%
Inline styles in MDX	2,115	5	99.8%
Legacy CSS tokens	262	0	100%
Hardcoded hex in MDX	1,045	0	100%
Outline removal (WCAG)	4	0	100%
Literal spacing	474	0	100%
Mermaid hardcoded	86	69	19.8% (deferred)

Remaining 74: 5 irreducible inline styles (single-prop CSS vars in composable files without import scope) + 69 mermaid variant colour schemes (non-standard palettes, deferred for individual review).

Technical References

Compendium

Knowledge Hub

Changelogs

Documentation Guide

Styles Engineering Guide

Pipeline Architecture

Scripts Reference

Audit Validator

Remediator

Data Pipelines

CoinGecko Exchanges

go-livepeer Configuration Flags

Component Authoring Checklist (Styles)

Mintlify CLI Tools

Baseline Metrics

​Pipeline Architecture

​Scripts Reference

​Audit Validator

​Remediator

​Data Pipelines

​CoinGecko Exchanges

​go-livepeer Configuration Flags

​Component Authoring Checklist (Styles)

​Mintlify CLI Tools

​Baseline Metrics

Pipeline Architecture

Scripts Reference

Audit Validator

Remediator

Data Pipelines

CoinGecko Exchanges

go-livepeer Configuration Flags

Component Authoring Checklist (Styles)

Mintlify CLI Tools

Baseline Metrics