npm package: @graphprotocol/gds-css
Description: Tailwind preset and design tokens for The Graph Design System
Author: Edge & Node and contributors
Latest version: 0.3.3

# @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`](https://github.com/graphprotocol/gds/tree/main/packages/react), which includes this package as a dependency.

## Installation

```bash
pnpm add @graphprotocol/gds-css
```

## Setup

1. Ensure [Tailwind CSS is installed and configured](https://tailwindcss.com/docs/installation) 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:

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

3. [Register source paths](https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources) relative to your CSS file:

   ```diff
     @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](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss).
     - 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:

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

   - Set up your formatter to sort Tailwind classes:

     **[Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html)** (recommended) — add to `.oxfmtrc.json`:

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

     **[Prettier](https://prettier.io/)** — install [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) and add to your config (e.g. `.prettierrc`):

     ```json
     {
       "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**](https://github.com/graphprotocol/gds/blob/main/packages/css/styles/typography.css): Font families, weights, sizes, line heights, etc.
- [**See all**](https://github.com/graphprotocol/gds/blob/main/packages/css/styles/theme.css)

### Color Schemes

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

```html
<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