Setup Leafygreen

LeafyGreen UI Setup

Configure a Vite + React + TypeScript project to use MongoDB's LeafyGreen design system. Run all steps in order. See references/gotchas.md before troubleshooting any issues.

Prerequisites Check

Before starting, verify the project is a Vite + React + TypeScript project:

# Must exist
ls package.json src/main.tsx src/App.tsx vite.config.ts

If these files are missing, scaffold the project first:

echo "y" | npm create vite@latest . -- --template react-ts

Step 1 — Install Packages

npm install \
  @leafygreen-ui/leafygreen-provider \
  @leafygreen-ui/button \
  @leafygreen-ui/typography \
  @leafygreen-ui/tokens \
  @leafygreen-ui/icon \
  @leafygreen-ui/icon-button \
  @leafygreen-ui/logo

npm install --save-dev vite-plugin-node-polyfills

The polyfills package is required because some LeafyGreen packages reference Node.js built-ins (e.g. Buffer) that don't exist in the browser. Without it, the app renders a blank page with no visible error.

Step 2 — Update vite.config.ts

Replace the full contents of vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'
import path from 'path'

export default defineConfig({
  plugins: [react(), nodePolyfills()],
  resolve: {
    dedupe: ['react', 'react-dom'],
    alias: {
      react: path.resolve('./node_modules/react'),
      'react-dom': path.resolve('./node_modules/react-dom'),
    },
  },
})

The dedupe + alias block is critical — LeafyGreen packages bundle their own React copy, which causes an "Invalid hook call" crash in the browser. This forces every package to use the single React instance in the project.

Step 3 — Update src/main.tsx

Wrap the app in LeafyGreenProvider. Important: LeafyGreenProvider is a default export, not a named export.

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import LeafyGreenProvider from '@leafygreen-ui/leafygreen-provider'
import './index.css'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <LeafyGreenProvider darkMode={true}>
      <App />
    </LeafyGreenProvider>
  </StrictMode>,
)

Keep the provider in main.tsx only — not in App.tsx.

Step 4 — Replace src/index.css

Replace the entire contents of src/index.css with only this. The Vite template's default CSS overrides LeafyGreen colors and must be completely removed:

@font-face {
  font-family: 'Euclid Circular A';
  src:
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/euclid-circular/EuclidCircularA-Regular-WebXL.woff2') format('woff2'),
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/euclid-circular/EuclidCircularA-Regular-WebXL.woff') format('woff'),
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/euclid-circular/EuclidCircularA-Regular.ttf') format('truetype');
  font-weight: 400;
  font-style: normal;
}

@font-face {
  font-family: 'MongoDB Value Serif';
  src:
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/value-serif/MongoDBValueSerif-Regular.woff2') format('woff2'),
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/value-serif/MongoDBValueSerif-Regular.woff') format('woff'),
    url('https://d2va9gm4j17fy9.cloudfront.net/fonts/value-serif/MongoDBValueSerif-Regular.ttf') format('truetype');
  font-weight: 400;
  font-style: normal;
}

*, *::before, *::after { box-sizing: border-box; }

body {
  margin: 0;
  background-color: #001E2B;
  font-family: 'Euclid Circular A', 'Helvetica Neue', Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
}

Do not add anything to index.html for fonts. Do not add other styles.

Step 5 — Smoke Test src/App.tsx

Replace src/App.tsx with a smoke test to confirm components render:

import { H1 } from '@leafygreen-ui/typography'
import { Button } from '@leafygreen-ui/button'

function App() {
  return (
    <div style={{ padding: 24 }}>
      <H1>LeafyGreen is working</H1>
      <Button>Click me</Button>
    </div>
  )
}

export default App

Use named imports only — { H1 } and { Button }. Do not use default imports for these components.

Also clear src/App.css (keep the file but empty it) since the Vite template styles interfere.

Step 6 — Create src/components/

mkdir -p src/components

Step 7 — Verify

npm run dev

Open the browser. Confirm H1 text and Button render with MongoDB styling (Euclid Circular A font, dark background). If the page is blank, see references/gotchas.md.

npm run build

Build must pass with zero errors. A chunk-size warning about LeafyGreen's bundle size is expected and harmless.

Additional Resources

• [references/gotchas.md](references/gotchas.md) — React 19 type errors, multiple-React crash, darkMode quirks, and other known issues with fixes
• leafygreen-authoring skill — component mapping, import conventions, design tokens, Figma MCP workflow (auto-loaded when editing .tsx/.ts files)

LeafyGreen Gotchas & Fixes

Known issues encountered when working with LeafyGreen UI in Vite + React + TypeScript projects.

---

1. Blank page with "Invalid hook call" in console

Symptom: Browser shows a blank page. Console shows:

Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.
Uncaught TypeError: Cannot read properties of null (reading 'useContext')

Cause: Multiple copies of React in the bundle. Some LeafyGreen packages bundle their own React, causing a version conflict with the project's React.

Fix: Add dedupe and alias to vite.config.ts:

import path from 'path'

export default defineConfig({
  plugins: [react(), nodePolyfills()],
  resolve: {
    dedupe: ['react', 'react-dom'],
    alias: {
      react: path.resolve('./node_modules/react'),
      'react-dom': path.resolve('./node_modules/react-dom'),
    },
  },
})

---

2. LeafyGreenProvider import error

Symptom: TypeScript error:

'"@leafygreen-ui/leafygreen-provider"' has no exported member named 'LeafyGreenProvider'.
Did you mean 'LeafyGreenProviderProps'?

Cause: LeafyGreenProvider is a default export, not a named export.

Fix:

// ❌ Wrong
import { LeafyGreenProvider } from '@leafygreen-ui/leafygreen-provider'

// ✅ Correct
import LeafyGreenProvider from '@leafygreen-ui/leafygreen-provider'

---

3. Button (and other polymorphic components) TypeScript error with React 19

Symptom: TypeScript build error:

error TS2786: 'Button' cannot be used as a JSX component.
  Its type 'InferredPolymorphicComponentType<BaseButtonProps, "button">' is not a valid JSX element type.

Cause: LeafyGreen's polymorphic component type (InferredPolymorphicComponentType) is incompatible with React 19's updated JSX type definitions.

Fix: Add {/* @ts-ignore - React 19 polymorphic type mismatch */} on the line immediately before the component in JSX:

{/* @ts-ignore - React 19 polymorphic type mismatch */}
<Button variant="primary" size="large">Submit</Button>

This affects: Button, IconButton, and any other components that use InferredPolymorphicComponentType. The components render correctly at runtime — this is a type-checking-only issue.

---

4. MongoDBLogoMark has no darkMode prop

Symptom: TypeScript error:

Property 'darkMode' does not exist on type 'IntrinsicAttributes & BaseLogoProps & RefAttributes<SVGSVGElement>'

Cause: MongoDBLogoMark uses BaseLogoProps which does not include darkMode. Control the color with the color prop instead.

Fix:

// ❌ Wrong
<MongoDBLogoMark height={32} darkMode={false} />

// ✅ Correct
<MongoDBLogoMark height={32} color="green-dark-2" />

Available color values: "white", "black", "green-dark-2", "green-base".

---

5. darkMode={true} in provider but design uses light colors

Situation: LeafyGreenProvider darkMode={true} is set in main.tsx, but the Figma design uses light-mode colors (white cards, dark text).

Explanation: Setting darkMode={true} on the provider makes LeafyGreen CSS variables resolve to dark-mode values. However, when building a light-mode design, always use explicit hex color values from the Figma design rather than relying on CSS variable resolution. The dark-mode provider setting affects the shell/chrome (nav, etc.) but the page content should use explicit colors.

Pattern: Pass darkMode={false} to individual LG components (e.g. <Button darkMode={false}>) that appear inside light-mode cards.

---

6. Vite template CSS overriding LeafyGreen styles

Symptom: LeafyGreen components render but colors are wrong. Fonts are incorrect. Background is white instead of the expected dark MongoDB background.

Cause: The Vite template's src/index.css sets its own :root CSS variables, body styles, and heading styles that conflict with LeafyGreen's design tokens.

Fix: Replace the entire contents of src/index.css with only the MongoDB font declarations and base reset (see SKILL.md Step 4). Do not keep any of the template's default CSS.

Also clear src/App.css — the Vite template puts styles there too.

---

7. vite-plugin-node-polyfills deprecation warning

Symptom: Vite prints a warning on startup:

warning: `esbuild` option was specified by "vite-plugin-node-polyfills" plugin. This option is deprecated, please use `oxc` instead.

Cause: vite-plugin-node-polyfills uses the esbuild configuration option which is deprecated in newer versions of Vite (v7+). The polyfills still work correctly despite the warning.

Status: Harmless. Ignore until vite-plugin-node-polyfills ships an update for the oxc option.

---

8. Chunk size warning on build

Symptom:

(!) Some chunks are larger than 500 kB after minification.

Cause: LeafyGreen's full component library is large. This is expected and does not affect functionality.

Fix (optional): Use dynamic imports to split the bundle if performance becomes a concern in production. For prototypes, ignore this warning.

---

9. Icon glyph names

LeafyGreen icon glyph names match the Figma component names exactly. Common ones:

Usage: import Icon from '@leafygreen-ui/icon' then <Icon glyph="Lock" size={16} fill="#5c6c75" />