Design System

​

Design Philosophy

1. Digital Paper - Elements are physical sheets of paper layered on a surface
2. Hard Edges - Clear boundaries, minimal rounded corners (max 2px)
3. High Contrast - Strict polarity between Ink (dark) and Paper (light)

​

Applying to Documentation

• Clear Structure: Explicit section boundaries and hierarchy
• Visible Construction: Technical details visible, not hidden
• High Contrast: Clear visual hierarchy through typography and spacing
• Hard Edges: Clear separation between sections and concepts

​

Color System

​

Paper UI Colors

​

Mintlify Color Mapping

{
  "colors": {
    "primary": "#10b981",    // Paper UI Accent (Emerald 500)
    "light": "#07C983",      // Lighter accent for dark mode
    "dark": "#15803D"        // Darker accent for buttons
  }
}

• primary → Paper UI Accent (Emerald 500) - Used for highlights, links, active states
• light → Lighter green for dark mode accents
• dark → Darker green for primary buttons

​

Dark Mode

• Ink (dark text) becomes light (#f4f4f5)
• Paper (light background) becomes dark (#18181b)
• Accent remains consistent (green)

​

Typography

​

1. The Voice of Authority (Serif)

• Font: Playfair Display
• Usage in Docs: H1 titles (via frontmatter), major section headings conceptually
• Style: Bold, tight tracking, classic editorial feel
• Mintlify Equivalent: H1 headings (styled by Mintlify theme)

​

2. The Voice of Utility (Sans-Serif)

• Font: Inter
• Usage in Docs: Body text, descriptions, most content
• Style: Standard weights, generous line-height, highly legible
• Mintlify Equivalent: Default body text (Mintlify uses system sans-serif)

​

3. The Voice of the Machine (Monospace)

• Font: JetBrains Mono
• Usage in Docs: Code blocks, inline code, technical terms, file paths
• Style: Uppercase often, smaller size, wide tracking
• Mintlify Equivalent: Code blocks (Mintlify uses monospace font for code)

​

Typography Guidelines

• Use H2 for main sections
• Use H3 for subsections
• Keep headings descriptive and keyword-rich
• Maintain consistent heading patterns across similar pages

• Keep paragraphs concise (3-5 sentences)
• Use lists for multiple items
• Use inline code (backticks) for technical terms, filenames, commands
• Use bold sparingly for emphasis

• Use inline code for short snippets, variable names, commands
• Use code blocks for multi-line examples
• Always specify language tags
• Include comments in code examples when helpful

​

Component Mapping

​

Paper UI → Mintlify Components

​

Card Usage

<CardGroup cols={2}>
  <Card title="Feature 1" icon="key">
    Description
  </Card>
  <Card title="Feature 2" icon="shield">
    Description
  </Card>
</CardGroup>

<Card title="Important" icon="alert">
  Key information here
</Card>

​

Callout Boxes

• <Note>: Helpful supplementary information (visible technical details)
• <Warning>: Important cautions, breaking changes (high contrast alerts)
• <Info>: Neutral contextual information
• <Tip>: Best practices, expert advice

• Use callouts for information that should stand out
• Keep callout content concise
• Use appropriate callout type for content urgency

​

Spacing & Layout

​

Section Spacing

• Between Major Sections (H2): Generous spacing (equivalent to p-8 conceptually)
• Between Subsections (H3): Moderate spacing
• Within Sections: Standard paragraph spacing
• Around Code Blocks: Extra spacing for readability

​

Content Organization

1. Narrative Sections: Overview, introduction, concepts
2. Technical Sections: Code examples, API details, implementation
3. Clear Separation: Visual separation between narrative and technical content

​

Lists

• Bulleted Lists: For unordered items, features, characteristics
• Numbered Lists: For sequential steps, procedures
• Nested Lists: Use sparingly, maintain clear hierarchy

​

Iconography

​

Icon Selection

• Source: Use Lucide icon names (Mintlify supports these)
• Style: Sharp, clean lines matching Paper UI aesthetic
• Usage: Icons in cards should be relevant to content
• Pairing: Icons paired with descriptive text (not standalone)

​

Common Icons

• key - Authentication, security
• shield - Security, protection
• route - Routing, navigation
• network - Architecture, connections
• file-text - Documents, content
• code - Code, development
• database - Data, storage
• settings - Configuration
• rocket - Getting started, launch
• search - Search, discovery

​

Mermaid Diagrams

​

Styling Guidelines

• Node Names: No spaces, use camelCase or PascalCase
• Labels: Clear, descriptive (use quotes for special characters)
• Colors: Avoid explicit colors (let theme handle it)
• Complexity: Keep diagrams focused and understandable
• Purpose: Use diagrams to clarify concepts that text cannot

​

Common Patterns

​

Tables

​

Formatting Guidelines

• Headers: Clear, descriptive column headers
• Alignment: Left for text, right for numbers
• Consistency: Similar tables use similar formatting
• Width: Keep tables readable (avoid overly wide tables)

​

When to Use Tables

• Comparisons: Feature comparisons, API endpoint lists
• Configuration: Settings, options, parameters
• Reference Data: Status codes, error codes, mappings

​

Code Examples

​

Formatting

• Language Tags: Always specify language
• Completeness: Include complete, runnable examples
• Context: Include necessary imports, setup
• Comments: Add comments for clarity
• Real Data: Use realistic data, not placeholders

​

CodeGroup Usage

<CodeGroup>
```typescript
// TypeScript example
```

```javascript
// JavaScript example
```
</CodeGroup>

​

Visible Construction

• File Paths: Show actual file paths in examples
• Configuration: Show actual configuration values
• IDs/Keys: Show example IDs, not just “ID: xxx”
• Status Values: Show actual status strings, error codes
• Metadata: Make technical metadata visible in examples

​

Best Practices

​

Do’s

• ✅ Use CardGroup for feature lists (2-column typical)
• ✅ Use appropriate callout types for important information
• ✅ Include code examples with language tags
• ✅ Use descriptive headings and link text
• ✅ Include “Related Documentation” sections
• ✅ Use Mermaid diagrams for complex concepts
• ✅ Make technical details visible and explicit

​

Don’ts

• ❌ Don’t use cards for every piece of information
• ❌ Don’t overuse callouts (they lose impact)
• ❌ Don’t use placeholder data in examples
• ❌ Don’t hide technical details (visible construction)
• ❌ Don’t create overly complex diagrams
• ❌ Don’t use “click here” for link text

​

Related Documentation

• Design Guide - Practical Mintlify guidelines
• Review Checklist - Quality checklist
• Page Templates - Standard page structures
• Component Guide - Detailed component usage