@graphprotocol/gds-css

Tailwind preset for The Graph Design System that includes design tokens, custom utilities, and custom variants.

Note: You do not need to install this package or follow these instructions in a React project. Instead, use @graphprotocol/gds-react, which includes this package as a dependency.

Installation

pnpm add @graphprotocol/gds-css

Setup

1. Ensure Tailwind CSS is installed and configured in your project (preferably with Vite).

2. Replace the tailwind import in your main CSS file with @graphprotocol/gds-css and register the Tailwind plugin:

   - @import 'tailwindcss';
   + @import '@graphprotocol/gds-css';
   + @plugin '@graphprotocol/gds-css/tailwind-plugin';

3. Register source paths relative to your CSS file:

     @import '@graphprotocol/gds-css';
     @plugin '@graphprotocol/gds-css/tailwind-plugin';
   + @source '../src';

   @graphprotocol/gds-css disables Tailwind's default content scanning as an optimization measure, so you must explicitly register your source paths using @source directives. Make sure to include all paths where Tailwind classes are used.

4. Optional recommended steps:

   • If you use VS Code (or a fork like Cursor), install the Tailwind CSS IntelliSense extension.

     • If it doesn't automatically recognize GDS-specific classes like text-16, it is likely because it cannot find the CSS file that registers GDS's Tailwind theme and plugin (which can happen in monorepos or projects with unusual/complex directory structures). Add the following to .vscode/settings.json and customize the paths to match your project:

       {
         "tailwindCSS.experimental.configFile": {
           "packages/ui/globals.css": "packages/ui/**"
         }
       }

   • Set up your formatter to sort Tailwind classes:

     Oxfmt (recommended) — add to .oxfmtrc.json:

     {
       "sortTailwindcss": {
         "functions": ["cn"],
         "preserveWhitespace": true,
         "stylesheet": "packages/ui/globals.css"
       }
     }

     Prettier — install prettier-plugin-tailwindcss and add to your config (e.g. .prettierrc):

     {
       "plugins": ["prettier-plugin-tailwindcss"],
       "tailwindPreserveWhitespace": true,
       "tailwindFunctions": ["cn"],
       "overrides": [
         {
           "files": "packages/ui/**",
           "options": {
             "tailwindStylesheet": "packages/ui/globals.css"
           }
         }
       ]
     }

     Make sure to customize the paths to match your project (files should match any file that contains classes, and tailwindStylesheet should point to your main CSS file, from which you imported GDS).

That's it, you're ready to use GDS utilities in your markup!

What's Included

Design Tokens

• Colors: Primitive color scales like brand, space, starfield, solar, sonja, and galactic, as well as semantic color tokens like text-default, bg-muted, border-subtle, etc.
• Border Radii: Numbers instead of t-shirt sizes (e.g. rounded-4)
• Breakpoints: Two custom breakpoints in addition to Tailwind's core ones (xs and 2xs)
• Typography: Font families, weights, sizes, line heights, etc.
• See all

Color Schemes

Even though GDS is dark by default, all semantic color tokens support both dark and light modes using CSS light-dark():

<div class="bg-canvas">This text is light on a dark background.</div>

<div class="gds-light bg-canvas">
  This text is dark on a light background.
  <div class="gds-dark bg-canvas">This text is light on a dark background.</div>
</div>

<div class="gds-system bg-canvas">
  This text is light on a dark background when the system is dark, and dark on a light background
  when the system is light.
</div>

Tailwind Extensions

TODO: Document custom utilities and variants

License

MIT