` | `style={{ display: "grid" }}` |
| Spacing between sections | `` | `style={{ border: "1px solid var(--accent)" }}` |
| Brand colour text | `` | `style={{ color: "var(--lp-color-accent)" }}` |
| Show/hide for dark mode | `
` / `
` | JavaScript theme detection |
**Rule:** Single-property CSS variable usage inline is acceptable (e.g. `style={{ color: "var(--lp-color-accent)" }}`). Multi-property layout styles must use a component or Tailwind classes.
## Icon Usage
### How icons render
| Source | Renders as | Colour styleable? | Example |
| ----------------------- | --------------- | ------------------------------ | ------------------------------------------------------ |
| Lucide/FontAwesome name | Inline SVG | Yes – `color` prop works | `![]()
` element | No – CSS `color` has no effect | `` is a Mintlify global component – no import needed.
| Colour | Meaning |
| --------- | ------------------------------------------------------------------------- |
| `green` | Workload: Dual/Realtime AI. Ownership: Livepeer Product. State: confirmed |
| `blue` | Workload: Video. Ownership: public |
| `purple` | Workload: AI. Ownership: commercial product |
| `yellow` | Status: draft/conditional. Funding: SPE-funded |
| `gray` | Configuration values, neutral reference metadata |
| `surface` | Neutral states, compound icon badges, metadata |
| `orange` | Warnings, caution states |
| `red` | Critical/destructive actions |
Green is context-dependent: in solutions it means "Livepeer Product", in Gateways it means "Dual workload", in pricing it means "ETH(wei)". Context determines meaning.
### On-chain / off-chain markers
```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
Video
AI
Dual
```
The full badge reference lives at `docs-guide/tooling/reference-maps/badge-map.mdx`.
## Responsive Design
Use **Tailwind responsive prefixes** for breakpoint-based layouts. These work in both MDX and JSX.
| Prefix | Breakpoint | Viewport |
| ------ | ----------- | -------------------- |
| (none) | `< 640px` | Mobile-first default |
| `sm:` | `>= 640px` | Small tablets |
| `md:` | `>= 768px` | Tablets |
| `lg:` | `>= 1024px` | Desktop |
| `xl:` | `>= 1280px` | Large desktop |
Test at three viewports minimum: **375px** (iPhone SE), **768px** (iPad), **1024px+** (Desktop).
## Accessibility Checklist
### Required for every page
* **Single H1** – set via frontmatter `title:` property, not in content
* **Sequential heading hierarchy** – H2 under H1, H3 under H2, no gaps
* **Descriptive alt text** on all images
* **Meaningful link text** – no "click here" or bare URLs
* **Language declared** on code blocks
### Required for components
* **Never remove focus indicators** – do not use `outline: "none"` or `outline: 0`
* **Keyboard accessible** – all interactive elements reachable via Tab
* **ARIA labels** on icon-only buttons and inputs
* **Colour contrast** – body text minimum 4.5:1, large text minimum 3:1
### Tooling
```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
mint a11y # Full check
mint a11y --skip-contrast # Alt text only
mint a11y --skip-alt-text # Contrast only
```
## Typography
### Headings
Use standard Markdown headings (`#`, `##`, `###`, etc.) for most content. Mintlify automatically styles these.
For **frame mode pages**, use custom heading components:
```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { H1, H2, PageHeader } from "/snippets/components/scaffolding/frame-mode/FrameMode.jsx";
Main Title
` - General information and tips
* `` - Helpful suggestions
* `` - Important cautions
* `` - Critical warnings
* `` - Additional context
### Prefer Custom Components for Links and Navigation
**Preference**: Use custom components for links, cards, quotes, and other visually appealing elements instead of plain Mintlify links.
**Why**: Custom components provide better visual design, consistent theming, enhanced user experience, and better integration with the Livepeer documentation design system.
**Custom Components to Use:**
* **Links**: Use `` and `` instead of plain markdown links or Mintlify `` with `href`
* **Quotes**: Use `
Section Title
Subsection Title
``` **Note:** Frame mode components use CSS Custom Properties internally - no ThemeData import needed. ### Text Styling * Use **bold** (`**text**`) for emphasis * Use *italic* (`*text*`) sparingly * Use `code` (backticks) for inline code * Use code blocks for multi-line code ### Punctuation * Do not use em dashes in English docs prose. Replace `—` with spaced en dash `–` or rewrite the sentence if a comma or colon reads more. ### Mathematical Expressions Mintlify supports LaTeX for rendering mathematical expressions. Use proper syntax to ensure equations render correctly. #### Inline Math Use single dollar signs `$...$` for inline mathematical expressions within text: ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} The voting power is calculated as $V_i = \frac{B_i}{B_T}$ where $B_i$ is bonded stake. ``` **Result:** The voting power is calculated as $V_i = \frac{B_i}{B_T}$ where $B_i$ is bonded stake. #### Block Equations Use double dollar signs `$$...$$` for standalone equations on their own line: ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} $$ R_t = S_t \cdot r_t $$ ``` **Result:** $$ R_t = S_t \cdot r_t $$ #### Common LaTeX Syntax | Expression | Syntax | Result | | -------------------------- | ------------------------- | ----------------------- | | Fractions | `$\frac{a}{b}$` | $\frac{a}{b}$ | | Subscripts | `$B_i$` | $B_i$ | | Superscripts | `$x^2$` | $x^2$ | | Greek letters | `$\alpha, \beta, \theta$` | $\alpha, \beta, \theta$ | | Summation | `$\sum_{i=1}^{n} x_i$` | $\sum_{i=1}^{n} x_i$ | | Square root | `$\sqrt{x}$` | $\sqrt{x}$ | | Proportional | `$\propto$` | $\propto$ | | Greater/less than or equal | `$\geq, \leq$` | $\geq, \leq$ | #### Critical: Do NOT Use Backslash Delimiters **WRONG - These will cause MDX errors:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ WRONG - backslash delimiters break MDX */} \(B_i\) for inline math \[R_t = S_t \cdot r_t\] for block math ``` **CORRECT - Use dollar sign delimiters:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ✅ CORRECT - dollar sign delimiters */} $B_i$ for inline math $$R_t = S_t \cdot r_t$$ for block math ``` #### LaTeX Configuration You can configure LaTeX rendering in `docs.json` under `styles.latex` to override automated detection if needed. See [Mintlify LaTeX docs](https://mintlify.com/docs/text) for details. ## Spacing & Layout ### Consistent Spacing * Use consistent spacing between sections * Group related content together * Use dividers (`` and `` instead of plain blockquotes * **Cards**: Use ` ` for navigation cards with better styling * **Callouts**: Use ` ` and ` ` for enhanced visual callouts * **External Links**: Use ` ` for external links (GitHub, etc.) **Examples:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ Plain markdown link */} [Getting Started](/get-started) {/* ✅ Custom component with better styling */} import { GotoLink } from '/snippets/components/elements/links/Links.jsx'; ``` ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ Plain blockquote */} > This is a quote {/* ✅ Custom quote component with attribution */} import { FrameQuote } from '/snippets/components/displays/quotes/Quote.jsx'; This is a quote with better visual design. ``` ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ Basic Mintlify Card with href */}API documentation {/* ✅ Custom GotoCard with enhanced styling */} import { GotoCard } from '/snippets/components/elements/links/Links.jsx';``` **When to Use Plain Links:** * Inline links within paragraphs (markdown links are fine) * Links in code examples or technical references * Links that don't need visual emphasis **See the [Component Library](./component-library) for all available custom components.** ## Mintlify Overrides & Best Practices Our styling framework intentionally overrides some Mintlify default recommendations to work better within Mintlify's constraints and maintain consistency. ### Override: "Use Tailwind classes" **Mintlify suggests**: Use Tailwind utility classes\ **Our approach**: ❌ Don't use Tailwind - use component primitives\ **Reason**: Tailwind classes in MDX create maintenance burden and reduce semantic meaning. Component primitives are more maintainable and self-documenting. **Example:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ Don't use Tailwind */} {/* ✅ Use component primitives */}Content ``` ### Override: "Inline styles are fine for quick fixes" **Mintlify suggests**: Inline styles acceptable in MDX\ **Our approach**: ❌ No inline styles in MDX, only in JSX components\ **Reason**: Consistency and maintainability. Inline styles in MDX make it harder to maintain theme consistency and create visual inconsistencies. **Example:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ Don't use inline styles in MDX */} Content {/* ✅ Use component primitives */}Content ``` ### Override: "Use global CSS for everything" **Mintlify suggests**: Put all styles in `style.css`\ **Our approach**: ✅ Only theme variables and framework overrides in `style.css`\ **Reason**: Mintlify only allows one global CSS file. Putting everything there makes it unmaintainable. Component-specific styles belong in JSX components. **What goes in `style.css`:** * ✅ Theme variables (CSS Custom Properties) * ✅ Mintlify component overrides (nav, footer) * ✅ Frame mode container classes * ✅ Utility classes used 5+ times globally **What does NOT go in `style.css`:** * ❌ Component-specific styles (put in JSX) * ❌ Page-specific styles (create component primitives) * ❌ One-off styling needs (create component primitives) ### Override: "Component styles can be external" **Mintlify suggests**: External CSS files for components\ **Our approach**: ❌ Styles must be within JSX component files\ **Reason**: Mintlify doesn't support CSS imports in components reliably. Inline styles and ` ); }; ``` ## Mintlify Gotchas & Limitations ### Critical Limitations #### 1. Import Paths Must Be Absolute ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ Correct - absolute path from repo root import { MyComponent } from '/snippets/components/MyComponent.jsx'; // ⚠️ Avoid - relative paths resolve but are harder to validate and grep import { MyComponent } from '../components/MyComponent.jsx'; ``` #### 2. File Extensions Required ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ Include extension import { Component } from '/snippets/Component.jsx'; // ❌ May not resolve import { Component } from '/snippets/Component'; ``` #### 3. Cannot Import into Component Files **You CANNOT import data or other components into a JSX component file:** ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ❌ WRONG - This will fail // snippets/components/MyComponent.jsx import { themeColor } from '/snippets/styles/themeStyles.jsx'; export const MyComponent = () => { return Content Hello; }; ``` **Solution: Import in the MDX file that uses the component:** ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ CORRECT // MyPage.mdx import { MyComponent } from '/snippets/components/MyComponent.jsx'; import { ThemeData } from '/snippets/styles/themeStyles.jsx';// MyComponent can access ThemeData from parent scope ``` #### 4. JSX Files Cannot Import Other JSX Files Mintlify does not allow JSX files to import other JSX files. This is why we use MDX-in-MDX patterns instead. #### 5. MDX Scope Inheritance When importing MDX files into other MDX files: * ✅ **Child MDX inherits parent scope for props** - Parent's imports work when used as component props * ❌ **Child MDX may NOT inherit parent scope for direct JSX interpolation** - Variables used as `{variable}` may need re-import * ✅ **Child can import its own variables** - If the child needs something the parent doesn't import **Example:** ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // Parent.mdx import { DOCKER_CODE } from '/snippets/data/gateways/code.jsx' import ChildView from '/snippets/pages/ChildView.mdx' ``` ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ChildView.mdx {/* Can use DOCKER_CODE as props */} {/* ✅ Works */} {/* But direct interpolation may need re-import */} {latestVersion} {/* ❌ May need import */} ``` #### 6. React Hooks Are Global Mintlify provides React hooks globally - no imports needed: ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ Works - hooks available without import export function MyComponent() { const [count, setCount] = useState(0); useEffect(() => { /* ... */ }, []); return{count}; } // ❌ Not needed - will cause errors import React, { useState, useEffect } from 'react'; ``` #### 7. Icon Component Behaviour **CRITICAL:** Mintlify's `` component renders custom icons as ` ` elements, NOT inline SVG. ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ❌ This will NOT work - color styling has no effect
``` **Solution:** Use theme-aware SVG files with internal CSS, or use different files for each theme. #### 8. Mintlify Global Components These components are available globally - **do not import them**: * `React`, `Frame`, `Card`, `Icon`, `Steps`, `Step`, `Tabs`, `Tab` * `Note`, `Warning`, `Info`, `Tip`, `Danger` * `Accordion`, `Columns`, `CardGroup`, `CodeBlock`, `Expandable`, `Badge`, `Tooltip` ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ Correct - use directly Content // ❌ Wrong - don't import import { Card, Tabs } from "@mintlify/components"; ``` **CRITICAL:** Mintlify global components **cannot be stored in variables** - they must be used directly as JSX: ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ❌ WRONG - Will cause "ReferenceError: Expandable is not defined" const componentMap = { expandable: Expandable, accordion: Accordion }; const Component = componentMap[component]; // ✅ CORRECT - Use conditional rendering with direct JSX if (component === "expandable") { return Content {content} ; } return{content} ; ``` #### 9. JSX Comments Don't Prevent MDX Parsing **CRITICAL:** JSX comments (`{/* */}`) in MDX files do **NOT** prevent MDX from parsing the content inside them. MDX will still try to evaluate JSX components and expressions within comments. ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} {/* ❌ WRONG - MDX will still try to parse CustomCodeBlock */} {/**/} {/* ✅ CORRECT - Remove the entire section, don't comment it */} {/* Code components temporarily unavailable - see component-bugs.md */} ``` **If you need to temporarily disable a component section:** 1. **Remove the entire section** from the MDX file 2. **Add a comment explaining why** it was removed 3. **Document in `docs/PLAN/errors/component-bugs.md`** if it's a component bug 4. **Do NOT use JSX comments** to "comment out" component usage #### 9. Frame Mode Limitations Frame mode (`mode: frame` in frontmatter) removes all default Mintlify styling. When using frame mode: * Default markdown headings may not render correctly * Use custom heading components from `frameMode.jsx` * All styling must be custom * Mintlify components still work but lose default styles * Keep responsive layout primitives in `style.css` (`.frame-mode-container`, `.frame-mode-hero-full`, frame pagination) * Keep portal/page-specific structure in shared JSX components (for example `/snippets/components/scaffolding/portals/Portals.jsx`) * Do not use fixed breakout constants directly in component styles (for example hardcoded `96px`, `20px`, or fixed `%` widths) * Prefer CSS variables + breakpoints for frame mode layout, and CSS custom properties (`var(--...)`) for theming ### Import Patterns #### Correct Pattern: Import in MDX, Use in Component ```mdx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ MyPage.mdx import { MyComponent } from '/snippets/components/MyComponent.jsx'; import { DOCKER_CODE } from '/snippets/data/gateways/code.jsx'; ``` ```jsx icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} // ✅ MyComponent.jsx - uses CSS Custom Properties (production-grade) export const MyComponent = () => { return ( ); }; ``` ## Git Workflow ### Branch Management **ALWAYS create a new branch from `docs-v2`:** ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} git checkout docs-v2 git pull git checkout -b docs-plan/XX-task-name ``` **Never work directly on:** * `docs-v2` (active docs branch) * `main` or `master` * Any branch another agent is using **Branch naming:** Use pattern `docs-plan/XX-task-name` where XX is the task number. ## Best Practices ### Code Organisation 1. **Keep components in `/snippets/components/`** organised by purpose: * `primitives/` - Basic UI elements * `layout/` - Layout components * `display/` - Media and embeds * `content/` - Content display * `integrations/` - External services * `domain/` - Domain-specific components 2. **Keep data in `/snippets/data/`** for reusable code strings and variables 3. **Use `/snippets/pages/`** for modular MDX content that's imported into main pages ### Writing Style 1. **Be Clear and Concise** - Write for users with varying technical backgrounds 2. **Use Examples** - Include code examples and real-world scenarios 3. **Provide Context** - Explain why, beyond how 4. **Link Related Content** - Help users discover related information 5. **Test Both Themes** - Verify content looks good in both light and dark modes ### Component Guidelines 1. **Use CSS Custom Properties ONLY** - Never use ThemeData or hardcode colours 2. **Reference Variables from style.css** - All theme colours are in `style.css` as CSS variables 3. **Test Components** - Ensure components render correctly 4. **Handle Children Properly** - Always handle children as arrays when mapping 5. **Document Props** - Include JSDoc comments for component props 6. **Provide Examples** - Add examples in the `examples/` folder for each component ### Component Immutability **CRITICAL RULE: Components in `snippets/components/` are IMMUTABLE** **NEVER modify files in `snippets/components/`** - These components are used across many pages. Any changes could break existing functionality. **Allowed:** * Creating new components * Modifying MDX files that use components * Fixing MDX imports and usage **Forbidden:** * Modifying existing component files * Changing component function signatures * Adding/removing component exports * Changing component logic **Exception:** Only if explicitly requested by user AND after confirming impact assessment. **If a component appears to have a bug:** 1. **Comment out the component section** in the MDX file where it's used 2. **Verify the page renders** without that section 3. **If page renders correctly** → Component is the issue 4. **Document the error** in `docs/PLAN/errors/component-bugs.md` with: * Component name and file path * Error message from console * Page where error occurs * Verification that commenting out fixes the page * Recommendation for component fix (but do not implement) **DO NOT fix the component** - Components are immutable without explicit user permission. ### File Naming * Use kebab-case for file names: `my-component.mdx` * Use PascalCase for component names: `MyComponent` * Use descriptive names that indicate purpose ## Testing Checklist Before submitting documentation: * Content renders correctly in dark mode (default) * Content renders correctly in light mode * All links work and point to correct pages * Code examples are accurate and tested * Images load and have appropriate alt text * Components use theme-aware colours * No hardcoded colours that should adapt to theme * Components render correctly * No console errors in browser dev tools * MDX syntax errors checked and fixed * All pages verified in headless browser (see Verification Requirements below) ## Verification Requirements ### MDX Syntax Checking **Before declaring work complete, check MDX files:** 1. Use linting tools to check all modified MDX files 2. Check for: * Unclosed JSX tags * Invalid import syntax * Missing frontmatter * Syntax errors 3. Fix any MDX errors before considering work complete ### Headless Browser Verification **Before declaring work complete, verify each page in a headless browser:** 1. Use Puppeteer or similar tool to load each page 2. Wait for network idle 3. Check for console errors (filtering out test script artifacts) 4. Verify content length > 500 chars 5. Verify H1 element exists 6. Check for 404 errors **Filter out false positives:** * Ignore "require is not defined" from test scripts * Ignore "puppeteer" related errors * Ignore "fs has already been declared" errors * Focus on actual component errors **Report must show:** * Page URL * Content length * H1 text * List of actual console errors (if any) * Status: ✅ OK or ❌ ERRORS ### URL Structure Verification **Mintlify pages use full path structure:** * Page path in `docs.json`: `v2/resources/documentation-guide/component-library/primitives` * URL: `/v2/resources/documentation-guide/component-library/primitives` **Do not assume URL patterns - verify by testing actual URLs.** ## Mintlify Theme Configuration Mintlify also supports theme configuration in `docs.json`: ```json icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} { "theme": "palm", "colors": { "primary": "#3CB540", "light": "#2b9a66", "dark": "#3CB540" } } ``` This controls Mintlify's built-in components (buttons, links, etc.). For custom styling, always use CSS Custom Properties in `style.css`. ## Pre-Commit Hooks This repository uses Git pre-commit hooks to automatically enforce the style guide rules. **These hooks are mandatory and will block commits that violate the style guide.** ### What Gets Checked The pre-commit hooks automatically check for: * **Deprecated `ThemeData` Usage** - Blocks imports of `ThemeData` from `snippets/styles/themeStyles.jsx` * **Hardcoded Theme Colours** - Warns about direct hex colour codes that should use CSS Custom Properties * **Relative Snippets Imports** - Flags imports from `snippets/` that use relative paths instead of absolute paths * **Unnecessary Imports** - Warns about explicit imports for Mintlify's globally available components and React hooks * **Syntax Validation** - Checks MDX, JSON, Shell, and JavaScript syntax * **Browser Validation** - Tests that MDX pages actually render correctly in a headless browser (if `mint dev` is running) ### Installation **MANDATORY**: You must install the hooks before making any commits: ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} ./.githooks/install.sh ``` ### What Happens on Violation If you attempt to commit code that violates the style guide: 1. The commit is **blocked** 2. You receive a detailed error message listing all violations 3. You must fix the violations before committing again ### Protected `.allowlist` Edits (Human-Only) The `.allowlist` file is protected by pre-commit checks. If a human intentionally needs to edit `.allowlist`, use: ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} git commit -m "Update .allowlist" --trailer "allowlist-edit=true" ``` This override still runs all other pre-commit checks. If a human intentionally needs to allow file deletions, use: ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} git commit -m "Remove obsolete files" --trailer "allow-deletions=true" ``` This deletion override also runs all other pre-commit checks. ### Example Error Output ```icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} ╔═══════════════════════════════════════════════════════════════╗ ║ STYLE GUIDE VIOLATIONS DETECTED - COMMIT BLOCKED ║ ╚═══════════════════════════════════════════════════════════════╝ Found 2 violation(s): ❌ my-component.jsx: Uses deprecated ThemeData - use CSS Custom Properties instead ⚠️ my-page.mdx: Contains hardcoded theme colors - use CSS Custom Properties (var(--accent), etc.) 📖 MANDATORY: Read the Style Guide before committing: v2/resources/documentation-guide/style-guide.mdx ``` ### Browser Validation The hooks include headless browser validation that tests MDX files actually render in the browser. This catches: * Runtime errors in components * Failed imports * Console errors * Render failures **Note**: Browser validation requires `mint dev` to be running. If it's not running, the check is skipped (doesn't block commit). ### Comprehensive Test Suite The repository includes a comprehensive test suite that validates all style guide rules and more: #### Running Tests ```bash icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}} # Run all tests npm test # Run specific test suites npm run test:style # Style guide validation npm run test:mdx # MDX syntax validation npm run test:spell # UK English spelling npm run test:quality # Quality checks (alt text, links, frontmatter) npm run test:browser # Browser rendering tests ``` #### What Gets Tested **Style Guide Tests** (`test:style`): * CSS Custom Properties usage (no ThemeData, no hardcoded colours) * No inline styles in MDX files * No em dashes in English `v2` docs prose (use `–` or rewrite the sentence) * No Tailwind classes * Absolute import paths * File naming conventions * Component immutability warnings **MDX Validation** (`test:mdx`): * Frontmatter validation * Unclosed JSX tags * Invalid import syntax * MDX scope inheritance issues **Spelling Tests** (`test:spell`): * UK English spelling validation * Custom dictionary for technical terms (Livepeer, Arbitrum, etc.) * Excludes code blocks and frontmatter **Quality Checks** (`test:quality`): * Image alt text presence * Frontmatter completeness * Internal link validation * SEO metadata validation **Browser Tests** (`test:browser`): * Page rendering in headless browser * Console error detection * Theme testing (light/dark) * Content validation (H1, content length) The test suite runs automatically in pre-commit hooks (staged/fast mode) and in CI/CD. In pull request CI, static checks are changed-file scoped for blocking, while browser sweeps keep full-route coverage. For full details on the hooks, see the [Git Hooks Documentation](/docs-guide/contributing/git-hooks). ## Resources * [Component Library](./component-library) - Complete component reference * [Mintlify Documentation](https://mintlify.com/docs) - Official Mintlify docs * [Mintlify Repo Guide](/docs-guide/contributing/Mintlify) - Repo-safe Mintlify authoring and workflow rules * [Git Hooks Documentation](/docs-guide/contributing/git-hooks) - Complete pre-commit hook documentation * `style.css` - Global CSS Custom Properties for theming ## Next Steps * Review the [Component Library](./component-library) for available components * Check [Snippets Inventory](./snippets-inventory) for all available snippets * Read [Mintlify Repo Guide](/docs-guide/contributing/Mintlify) for repo-safe Mintlify gotchas * See [Contribute to the Docs](./contribute-to-the-docs) for contribution guidelines * Install Git hooks: `./.githooks/install.sh`