LeafyGreen Authoring Conventions

Apply these conventions whenever writing or editing React components in a project that uses @leafygreen-ui/* packages.

Always prefer LeafyGreen components over plain HTML

When a user asks to add any UI element — in plain language, from a Figma design, or anywhere else — always check if a LeafyGreen component exists for it first. Never use a plain HTML element (<button>, <input>, <select>, etc.) when an @leafygreen-ui equivalent is available.

Common mappings:

If a package is not yet installed, install it before writing the component code:

npm install @leafygreen-ui/[package-name]

Component imports

Always use named imports for LG components:

import { H1, Body, Subtitle } from '@leafygreen-ui/typography'
import { Button } from '@leafygreen-ui/button'
import Icon from '@leafygreen-ui/icon'           // default import
import { MongoDBLogoMark } from '@leafygreen-ui/logo'

Styling approach

Always use design tokens from @leafygreen-ui/tokens for colors — never hard-coded hex values. Tokens are the single source of truth for color in the design system and automatically resolve to the correct value for dark or light mode.

import { palette } from '@leafygreen-ui/tokens'

// Correct: use a token
color: palette.gray.dark2

// Avoid: hard-coded hex
color: '#3D4F58'

Figma MCP → auto-install missing packages

When implementing a design from the Figma MCP, the component descriptions include the LeafyGreen package name, e.g.:

⚛️ React name: @leafygreen-ui/text-input
⚛️ React name: @leafygreen-ui/select

Before writing any component code:

1. Scan all ⚛️ React name: entries in the Figma design context
2. Cross-check each @leafygreen-ui/* package against package.json
3. Install any that are missing: npm install @leafygreen-ui/[package-name]
4. Never substitute plain HTML for a LeafyGreen component that is called out in the design spec

File structure

• New components go in src/components/[ComponentName].tsx
• One component per file
• Name files and components in PascalCase: ProjectCard.tsx, not project-card.tsx
• Ask before creating new folders outside of src/components/

TypeScript

• Always define prop types explicitly using TypeScript interfaces
• Do not use any as a type

General

• Keep components focused. If a component is doing more than one thing, split it.