GridKit – Grid Dynamics Design System

GridKit is the official design system and component library from Grid Dynamics.
It provides a set of reusable, accessible, and themeable React UI components designed to accelerate the development of consistent, scalable applications – with a focus on e-commerce and enterprise platforms.

✨ Features

• 🧩 35+ modular components (core, layout, domain-specific)
• 🎨 Theming support with dynamic runtime switching
• 🔗 Design tokens synced with Figma
• 📦 Optimized build using Vite
• 📚 Fully documented via Storybook
• ♿ WCAG 2.1 AA-compliant components
• ⚙️ Type-safe and fully tested with Vitest + RTL

📦 Installation

Start by ensuring that you already have @emotion/react and @emotion/styled installed. Then, run one of the following commands to install the dependencies:

npm install gd-design-library @emotion/styled @emotion/react
# or
yarn add gd-design-library @emotion/styled @emotion/react

Make sure you're using Node.js version ≥22.17.0.

Note: Since this package is private, you need to configure your .npmrc with a valid auth token:

//registry.npmjs.org/:_authToken=<npm_token>

🧑‍💻 Getting Started

Prerequisites

• Node.js (22.17.0 or higher)
• Yarn or npm

Clone & Install

git clone https://github.com/griddynamics/cto-rnd-system-design.git
cd gd-design-system
yarn install

🚀 Development

Start the local dev server with Vite:

yarn dev

Open http://localhost:5173 in your browser.

Run Storybook

yarn storybook

🏗️ Project Structure

gd-design-system/
├── src/
│   ├── components/
│   │   ├── core/               # Core UI components (Button, Input, etc.)
│   │   ├── domainSpecific/     # Business-specific components
│   ├── tokens/                 # Design tokens from Figma
│   ├── hooks/                 # Shared React hooks
│   └── utils/                 # Utility functions
├── .storybook/                # Storybook config
├── vite.config.ts             # Vite config
├── tsconfig.json              # TypeScript config
├── README.md

🧪 Testing & Linting

Run Tests

yarn test

Lint Code

yarn lint

Format Code

yarn format

Check Formatting

yarn format:check

🧰 Component Generator

Use our CLI script to quickly scaffold new components:

Add Execution Permission (first time)

chmod +x ./bin/create-component.js

Create a Component

yarn crc ButtonGroup

You’ll be prompted to select:

• core
• domainSpecific

The script will generate boilerplate files and update exports automatically.

🧩 Usage

Wrap your app in the ThemeProvider with isDefault to apply default GD global styles and tokens:

import { ThemeProvider } from 'gd-design-library';
// OPTIONAL: default GD global styles, reset, font.
import 'gd-design-library/styles.css';

function App() {
  return (
    <ThemeProvider isDefault>
      <YourAppRoutes />
    </ThemeProvider>
  );
}

or initialTheme to install custom one as default initially

{
  "name": "myCustomTheme",
  "componentAStyles": {
    "style": "value"
  }
}

import { ThemeProvider, defaultTheme } from 'gd-design-library';
import myCustomTheme from 'PROJECT_PATH/myCustomTheme'; // JSON or any js/ts and similliar with object return

const App = () => {
  // In case you want extend default theme, by overwriting only particular components
  const initialTheme = Object.assign({}, defaultTheme, myCustomTheme);
  return (
    <ThemeProvider initialTheme={initialTheme}>
      <YourAppRoutes />
    </ThemeProvider>
  );
};

You can now use components like this:

import { Button } from 'gd-design-library';

<Button variant="primary">Click me</Button>;

Adding new theme

Here’s a minimal React app example showing how to create and apply custom theme based on default, exactly like in your snippet. Example structure:

• main.tsx: wraps the app with ThemeProvider

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

import { ThemeProvider } from 'gd-design-library';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider isDefault>
      <App />
    </ThemeProvider>
  </React.StrictMode>
);

• useCustomTheme.tsx: theme hook

** Can be used on top level instead isDefault, use initialTheme, based on updateThemeTokens & defaultTheme from hook snippet

import { useEffect } from 'react';
import { updateThemeTokens, defaultTheme, useTheme } from 'gd-design-library';

export default function useCustomTheme() {
  const { addTheme, setTheme } = useTheme();
  const customTheme = {
    ...defaultTheme,
    name: 'CustomTheme',
  };
  useEffect(() => {
    // Customise tokens
    updateThemeTokens(customTheme, {
      'select.dropdown': {
        backgroundColor: 'red',
        borderRadius: '10px',
        boxShadow: '0 0 10px rgba(0, 0, 0, 0.1)',
        padding: '10px',
        width: '200px',
        height: '200px',
        zIndex: 1000,
        position: 'absolute',
        top: '50%',
        left: '50%',
      },
      // any other theme overwrites here
      'button.default': {
        borderRadius: '32px',
      },
      'chatbubble.question': {
        background: '#F1F5FA',
      },
    });
    // Add customTheme in a theme scope
    addTheme(customTheme.name, customTheme);
    //Set customTheme as an active, optional on demand to apply as an active
    setTheme(customTheme.name);
  }, []);
}

• App.tsx: renders a Select to demonstrate the change

import React from 'react';

import { FlexContainer, Typography, Row, Select, type Option } from 'gd-design-library';

import useCustomTheme from './useCustomTheme';

const items: Option[] = [
  { name: 'Option 1', value: 'option1' },
  { name: 'Option 2', value: 'option2' },
  { name: 'Option 3', value: 'option3' },
];

export default function App() {
  useCustomTheme();

  return (
    <FlexContainer>
      <Typography>Custom Themed Select</Typography>
      <Row>
        <Select items={items} />
      </Row>
    </FlexContainer>
  );
}

📘 Documentation

Explore our hosted Storybook:

👉 https://storybook.cto-rnd-system-design.griddynamics.net

📄 License

© Grid Dynamics. All rights reserved.
This package is for internal and authorized client use only.