Skip to main content
Version: Migration Guide (1.2.0)

Using Tailwind CSS

🚀 v1.1.0-dev

This is the NEXT version with enhanced semantic utilities and improved dark mode support.

Learn how to style your documentation using Tailwind CSS v4 with our custom design system.

Quick Overview​

This project is set up with:

  • ✅ Tailwind CSS v4 - Utility-first CSS framework
  • ✅ Custom Design Tokens - Consistent colors, spacing, shadows
  • ✅ Auto Dark Mode - Seamless theme switching
  • ✅ Responsive Design - Mobile-first approach

Basic Usage in MDX​

You can use Tailwind classes directly in your MDX files:

<div className="p-6 bg-white dark:bg-primary-gray-950 rounded-lg border border-primary-gray-200 dark:border-primary-gray-800">
  <h3 className="text-xl font-bold text-primary-gray-900 dark:text-white mb-2">
    Card Title
  </h3>
  <div className="text-primary-gray-600 dark:text-primary-gray-400">
    This is a card with proper dark mode support.
  </div>
</div>

Result:

Card Title

This is a card with proper dark mode support.

Using Semantic Utilities​

The easiest way to style with auto dark mode is using our semantic utilities with d- prefix:

<div className="d-bg-primary d-text-primary border d-border-primary p-6 rounded-lg">
  Content automatically adapts to light/dark mode!
</div>

Result:

Content automatically adapts to light/dark mode!

Why Semantic Utilities?​

  • ✅ No dark: prefix needed - Auto dark mode
  • ✅ Consistent - Based on design system
  • ✅ Maintainable - Change theme globally

Semantic Color Utilities​

This project includes comprehensive semantic utilities from utilities-v4.css. All utility classes use d- prefix to avoid conflicts.

Text Colors​

Semantic text utilities automatically adapt to light/dark mode:

<div className="space-y-2 my-4">
  <div className="d-text-primary">Primary text</div>
  <div className="d-text-secondary">Secondary text</div>
  <div className="d-text-brand-primary">Brand primary text</div>
  <div className="d-text-error-primary">Error text</div>
  <div className="d-text-warning-primary">Warning text</div>
  <div className="d-text-success-primary">Success text</div>
</div>

Result:

Primary text
Secondary text
Brand primary text
Error text
Warning text
Success text

Background Colors​

<div className="space-y-2 my-4">
  <div className="d-bg-primary d-text-primary p-3 rounded">Primary background</div>
  <div className="d-bg-secondary d-text-primary p-3 rounded">Secondary background</div>
  <div className="d-bg-brand-primary d-text-primary p-3 rounded">Brand background</div>
</div>
Primary background
Secondary background
Brand background

Responsive Grid Layouts​

Create responsive layouts that adapt to different screen sizes:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 my-6">
  <div className="p-6 d-bg-secondary d-border-primary border rounded-lg">
    <h4 className="font-semibold d-text-primary mb-2">Feature 1</h4>
    <div className="text-sm d-text-secondary">
      Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns
    </div>
  </div>
  <div className="p-6 d-bg-secondary d-border-primary border rounded-lg">
    <h4 className="font-semibold d-text-primary mb-2">Feature 2</h4>
    <div className="text-sm d-text-secondary">
      Using semantic utilities with auto dark mode!
    </div>
  </div>
  <div className="p-6 d-bg-secondary d-border-primary border rounded-lg">
    <h4 className="font-semibold d-text-primary mb-2">Feature 3</h4>
    <div className="text-sm d-text-secondary">Clean and maintainable</div>
  </div>
</div>

Feature 1

Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns

Feature 2

Using semantic utilities with auto dark mode!

Feature 3

Clean and maintainable

Alert Boxes​

Create styled alert boxes using semantic utilities:

Info Alert​

ℹī¸ Info

This is an informational alert with semantic colors.

Success Alert​

✅ Success

Operation completed successfully!

Warning Alert​

⚠ī¸ Warning

Please proceed with caution.

Error Alert​

❌ Error

An error has occurred.

Using Custom Components​

Import and use custom React components in your MDX:

import ExampleCard from "@site/src/components/global/ExampleCard";

<ExampleCard
  title="Custom Component"
  description="This is a reusable component with TypeScript and Tailwind"
  variant="primary"
/>

Custom Component

This is a reusable component with TypeScript and Tailwind

Component Variants​

Default Variant

Clean and minimal

Primary Variant

Brand colored

Success Variant

For positive feedback

Warning Variant

For cautionary messages

Best Practices​

✅ DO​

  1. Use semantic utilities (auto dark mode):

    <div className="d-bg-brand-primary d-text-primary p-6 rounded-lg">
      No need for dark: prefix!
    </div>

  2. Use responsive classes:

    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

  3. Use design tokens for custom values:

    <div className="p-[var(--spacing-4xl)] rounded-[var(--radius-lg)]">

❌ DON'T​

  1. Don't forget dark mode (if not using semantic utilities):

    <!-- ❌ BAD - Will break in dark mode -->
    <div className="bg-white text-gray-900">

  2. Don't use inline styles:

    <!-- ❌ BAD - Use Tailwind instead -->
    <div style={{background: 'white'}}>

Testing Your Styles​

Before publishing, always test:

  • ✅ Light mode looks good
  • ✅ Dark mode looks good (toggle theme in navbar)
  • ✅ Mobile (375px) - resize browser
  • ✅ Tablet (768px) - resize browser
  • ✅ Desktop (1024px+) - full width

What's Next?​

Now that you know how to use Tailwind CSS:

  • ✅ Create beautiful documentation pages
  • ✅ Build custom components
  • ✅ Ensure dark mode compatibility
  • ✅ Make responsive layouts

Happy styling! 🎨