@worldresources/wri-design-systems

WRI UI Library

Requirements

Node: 22.14.0

React: 19.0.1

Installation

yarn add @worldresources/wri-design-systems

or

npm i @worldresources/wri-design-systems

Other dependecies

yarn add @chakra-ui/react @emotion/react

or

npm i @chakra-ui/react @emotion/react

Usage

Set up AI tooling

Run the DS CLI to set up AI tooling for this design system in your project root (the directory where you run the command).

ds setup-ai

This will:

• Install / update AI instruction files (these may be overwritten):
  • AGENTS.md content distributed as: CLAUDE.md, GEMINI.md, .geminirules
• Configure IDE integrations when detected:
  • Cursor: writes .cursor/rules and creates .cursor/mcp.json (skips if it already exists)
  • VS Code / GitHub Copilot: writes .github/copilot-instructions.md and creates .vscode/mcp.json (skips if it already exists)
  • Windsurf: writes .windsurfrules
  • Cline: writes .clinerules
• Ensure a .gitignore block is present (creates .gitignore if missing; appends once and never duplicates):
  • CLAUDE.md
  • .windsurfrules
  • .clinerules
  • .github/copilot-instructions.md
  • .cursor/rules
  • .cursor/mcp.json
  • .vscode/mcp.json
  • GEMINI.md
  • .geminirules

Optional: run it against a specific path:

ds setup-ai /path/to/your/project

Create the Project Theme

With this custom theme you can change the color scheme according to your Project Theme

import { createSystem, defaultConfig } from '@chakra-ui/react'
import { designSystemStyles } from '@worldresources/wri-design-systems'

export const system = createSystem(designSystemStyles._config, {
  theme: {
    tokens: {
      colors: {
        neutral: {
          100: { value: '#FFFFFF' },
          200: { value: '#F6F6F6' },
          300: { value: '#E7E6E6' },
          400: { value: '#C9C9C9' },
          500: { value: '#B0B0B0' },
          600: { value: '#A1A1A1' },
          700: { value: '#5C5959' },
          800: { value: '#3D3B3B' },
          900: { value: '#1A1919' },
        },
        primary: {
          100: { value: '#FFFBF2' },
          200: { value: '#FCEFD3' },
          300: { value: '#FADFA7' },
          400: { value: '#F5BF4F' },
          500: { value: '#F0AB00' },
          600: { value: '#DE9E00' },
          700: { value: '#855B00' },
          800: { value: '#5F4205' },
          900: { value: '#332300' },
        },
        secondary: {
          100: { value: '#F2F6FF' },
          200: { value: '#D7E0F7' },
          300: { value: '#B2C3F0' },
          400: { value: '#4F6CBA' },
          500: { value: '#3855A3' },
          600: { value: '#0A4298' },
          700: { value: '#123369' },
          800: { value: '#162241' },
          900: { value: '#0B1121' },
        },
        success: {
          100: { value: '#EBF5F2' },
          200: { value: '#D3EED1' },
          300: { value: '#C2E5DC' },
          500: { value: '#009E77' },
          900: { value: '#00664D' },
        },
        warning: {
          100: { value: '#FBF7EA' },
          200: { value: '#E3CC8F' },
          300: { value: '#EEDDA5' },
          500: { value: '#A88100' },
          900: { value: '#715804' },
        },
        error: {
          100: { value: '#FFEFED' },
          200: { value: '#EDA1A9' },
          300: { value: '#F6C5C1' },
          500: { value: '#C11101' },
          900: { value: '#8D0D01' },
        },
        accessible: {
          'text-on-primary-mids': { value: '#332300' }, // primary 900
          'text-on-secondary-mids': { value: '#F2F6FF' }, // secondary 100
          'controls-on-neutral-lights': { value: '#855B00' }, // primary 700
          'controls-on-neutral-darks': { value: '#F5BF4F' }, // primary 400
        },
      },
    },
  },
})

Wrap ChakraProvider at the root of your app

import React from 'react'
import { ChakraProvider } from '@chakra-ui/react'
import { designSystemStyles } from "@worldresources/wri-design-systems";
import { system } from './lib/theme'

function App() {
  return (
    {/* if you want to use the default WRI Theme colors */}
    {/* <ChakraProvider value={designSystemStyles}> */}

    {/* if you want to use your custom system Theme colors */}
    <ChakraProvider value={system}>
      <TheRestOfYourApplication />
    </ChakraProvider>
  )
}

Adding theme to your CSS variables

--color-neutral-100: var(--chakra-colors-neutral-100);
--color-neutral-200: var(--chakra-colors-neutral-200);
--color-neutral-300: var(--chakra-colors-neutral-300);
--color-neutral-400: var(--chakra-colors-neutral-400);
--color-neutral-500: var(--chakra-colors-neutral-500);
--color-neutral-600: var(--chakra-colors-neutral-600);
--color-neutral-700: var(--chakra-colors-neutral-700);
--color-neutral-800: var(--chakra-colors-neutral-800);
--color-neutral-900: var(--chakra-colors-neutral-900);

--color-primary-100: var(--chakra-colors-primary-100);
--color-primary-200: var(--chakra-colors-primary-200);
--color-primary-300: var(--chakra-colors-primary-300);
--color-primary-400: var(--chakra-colors-primary-400);
--color-primary-500: var(--chakra-colors-primary-500);
--color-primary-600: var(--chakra-colors-primary-600);
--color-primary-700: var(--chakra-colors-primary-700);
--color-primary-800: var(--chakra-colors-primary-800);
--color-primary-900: var(--chakra-colors-primary-900);

--color-secondary-100: var(--chakra-colors-secondary-100);
--color-secondary-200: var(--chakra-colors-secondary-200);
--color-secondary-300: var(--chakra-colors-secondary-300);
--color-secondary-400: var(--chakra-colors-secondary-400);
--color-secondary-500: var(--chakra-colors-secondary-500);
--color-secondary-600: var(--chakra-colors-secondary-600);
--color-secondary-700: var(--chakra-colors-secondary-700);
--color-secondary-800: var(--chakra-colors-secondary-800);
--color-secondary-900: var(--chakra-colors-secondary-900);

--color-success-100: var(--chakra-colors-success-100);
--color-success-200: var(--chakra-colors-success-200);
--color-success-300: var(--chakra-colors-success-300);
--color-success-500: var(--chakra-colors-success-500);
--color-success-900: var(--chakra-colors-success-900);

--color-warning-100: var(--chakra-colors-warning-100);
--color-warning-200: var(--chakra-colors-warning-200);
--color-warning-300: var(--chakra-colors-warning-300);
--color-warning-500: var(--chakra-colors-warning-500);
--color-warning-900: var(--chakra-colors-warning-900);

--color-error-100: var(--chakra-colors-error-100);
--color-error-200: var(--chakra-colors-error-200);
--color-error-300: var(--chakra-colors-error-300);
--color-error-500: var(--chakra-colors-error-500);
--color-error-900: var(--chakra-colors-error-900);

--color-accessible-text-on-primary-mids: var(
  --chakra-colors-accessible-text-on-primary-mids
);
--color-accessible-text-on-secondary-mids: var(
  --chakra-colors-accessible-text-on-secondary-mids
);
--color-accessible-controls-on-neutral-lights: var(
  --chakra-colors-accessible-controls-on-neutral-lights
);
--color-accessible-controls-on-neutral-darks: var(
  --chakra-colors-accessible-controls-on-neutral-darks
);

getThemedColor

Use getThemedColor to access your theme colors and variants.

import { getThemedColor } from '@worldresources/wri-design-systems'

border: 1px solid ${getThemedColor('neutral', 400)};

Components

Containers

• Modal
• Panel
• Sheet

Data Display

• Item Count
• List
• Table
• Extendable Card
• Analysis Widget

Forms

Actions

• Button
• Close Button
• Icon Button
• Toolbar
• Menu
• Multi Action Button
• Tooltip

Controls

• Checkbox
• Checkbox Option Card
• Option Card
• Radio Button
• Slider
• Switch

Inputs

• Checkbox List
• Input With Units
• Password
• Radio List
• Select
• Slider Input
• Text Area
• Text Input

Tags

• Tag

Geospatial

• Base Map
• Icon Marker
• Map Pop Up

Layers

• Layer Group
• Layer Item
• Layer Panel

Legends

• Layer Parameters
• Legend Item
• Legend Panel
• Qualitative Attribute
• Scale Bar

Navigation

• Breadcrumb
• Footer
• Mobile Tab Bar
• Navbar
• Navigation Rail
• Pagination
• Tab Bar

Status

• Avatar
• Badge
• Inline Message
• Progress Bar
• Step Progress Indicator
• Toast

Templates

• Next.js

Building the lib

yarn lint-fix

yarn build

Publish new version (manual)

npm login

npm publish

PR Label Rules

Use exactly one versioning label on every PR. The label drives the npm version bump when the PR is merged into main.

How it works

• Open a PR and add one of the labels below.
• The PR Label Guard workflow enforces that exactly one label is present.
• On merge, the Release & Publish workflow bumps package.json, tags, and publishes to npm for major, minor, or patch.
• no-bump skips all versioning and publishing.

Label guide

• patch: non-breaking fixes (styles, internal refactors, Storybook-only tweaks that do not change usage)
• minor: backwards-compatible feature or API additions (new component/prop), or behavior changes that may affect usage but are not breaking
• major: breaking changes (removed/renamed props, changed required behavior, incompatible defaults)
• no-bump: documentation-only or internal changes that should not publish

If you are unsure, choose minor and leave a note in the PR for review.