Installation

Prerequisites

Ensure the following prerequisites are installed before proceeding:

Create a new project

WFP Design System integrates seamlessly with any React project that meets the prerequisites above. This guide uses Vite, the recommended tooling for building modern single-page applications.

pnpm create vite@latest

Select one of the following TypeScript configurations when prompted:

│  ○ TypeScript
│  ○ TypeScript + SWC
│  ○ TypeScript + React Compiler

Install Tailwind 4

For styling, Tailwind CSS v4 or higher is required, as the theme uses CSS variables for configuration.

pnpm add tailwindcss @tailwindcss/vite

Replace the contents of src/index.css with the following:

@import "tailwindcss";

Configure TypeScript

By default, Vite generates three TypeScript configuration files:

• tsconfig.json
• tsconfig.app.json
• tsconfig.node.json

Update the following two files to configure path aliases.

Update tsconfig.json

Add the baseUrl and paths options to the compilerOptions section:

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".", 
    "paths": {
      "@/*": ["./src/*"] 
    } 
  } 
}

Update tsconfig.app.json

Add the same path configuration to tsconfig.app.json:

{
  "compilerOptions": {
    // …existing options
    "baseUrl": ".", 
    "paths": {
      "@/*": ["./src/*"] 
    } 
    // …existing options
  }
}

Configure Vite

Update the Vite configuration to support path aliases and enable Tailwind CSS.

First, install the Node.js type definitions:

pnpm add -D @types/node

Then update vite.config.ts:

import path from "path"; 
import tailwindcss from "@tailwindcss/vite"; 
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), tailwindcss()], 
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"), 
    }, 
  }, 
});

Install fonts

See Install fonts

Install WFP Design System

Install WFP Design System theme package:

pnpm dlx shadcn@latest add https://designsystem.wfp.org/r/theme.json

This command will:

• Update index.css with WFP Design System styles
• Create src/lib/utils.ts containing the cn utility function
• Generate component.json in your project root for the shadcn configuration

Add components

Install components one by one

Install individual components as needed. Recommended to minimize bundle size.

For example, to add the Button component:

pnpm dlx shadcn@latest add https://designsystem.wfp.org/r/button.json

Install all components at once

Alternatively, you can install all components at once using the following command:

pnpm dlx shadcn@latest add https://designsystem.wfp.org/r/components.json

Use components

Import and use the component with the configured path alias:

import { Button } from "@/components/ui/button";

function App() {
  return <Button>Hello World</Button>;
}

export default App;