# Adding a New Brand

Steps to add a new brand to `@mindvalley/css`.

## 1. Add token source file

Create the color token JSON file at:

```
packages/css/tokens/brands/{brand-name}/color.json
```

This file should be in the Supernova export format with color tokens nested by subcategory, group, token name, and theme:

```json
{
  "subcategory": {
    "group": {
      "token-name": {
        "base": {
          "value": "#hex",
          "type": "color"
        },
        "dark": {
          "value": "#hex",
          "type": "color"
        }
      }
    }
  }
}
```

## 2. Add a brand filter

In `packages/css/src/style-dictionary/filters.ts`:

Add the brand config to `BRAND_CONFIGS`:

```typescript
const BRAND_CONFIGS: Record<string, ColorBrandConfig> = {
  // ...existing brands
  'new-brand': {
    allowedSubcategories: ['accent', 'primary'],
    themeSubcategories: ['backgrounds', 'content'],
    numberedScaleSubcategories: ['primary'],
    greyGroupException: false,
    excludedColorGroups: [],
    excludedOutputTokens: [],
  },
}
```

- `allowedSubcategories` — base-layer subcategories (raw color scales)
- `themeSubcategories` — theme-layer subcategories (semantic tokens, no scale filtering)
- `numberedScaleSubcategories` — which base-layer subcategories require numbered scale names

Export the filter:

```typescript
export const newBrandColorsFilter = {
  name: 'new-brand-colors',
  filter: createBrandColorFilter(BRAND_CONFIGS['new-brand']),
}
```

Add the export to `src/style-dictionary/index.ts`.

## 3. Register in the generate script

In `packages/css/scripts/generate.ts`:

Add the brand to the `brands` array:

```typescript
const brands = [
  { name: 'mindvalley', filter: 'mindvalley-colors' },
  { name: 'b2b', filter: 'b2b-colors' },
  { name: 'new-brand', filter: 'new-brand-colors' },
]
```

Register the new filter:

```typescript
sd.registerFilter(newBrandColorsFilter)
```

## 4. Update package.json exports

In `packages/css/package.json`, add the new CSS file to exports:

```json
{
  "exports": {
    "./mindvalley.css": "./dist/mindvalley.css",
    "./b2b.css": "./dist/b2b.css",
    "./new-brand.css": "./dist/new-brand.css"
  }
}
```

## 5. Generate and verify

```bash
nx run @mindvalley/css:generate
```

Check `packages/css/dist/new-brand.css` contains the expected tokens.

## 6. Configure Supernova

If the new brand's tokens are managed in Figma/Supernova, configure the Supernova bot to push updates to `packages/css/tokens/brands/{brand-name}/color.json`.

## Optional: shadcn support

Only do this if a project consuming the brand uses shadcn/ui.

Create `packages/css/src/themes/{brand-name}-shadcn.css` with the shadcn variable mappings. See [shadcn Mapping](shadcn-mapping.md) for the full variable list and how to map tokens.

The generate script writes this to `dist/{brand-name}-shadcn.css` as a separate, opt-in file. Add the export to `package.json`:

```json
{
  "exports": {
    "./new-brand-shadcn.css": "./dist/new-brand-shadcn.css"
  }
}
```

Consumers can then import it alongside the main brand CSS:

```css
@import "@mindvalley/css/new-brand.css";
@import "@mindvalley/css/new-brand-shadcn.css";
```

Note: this file is hand-maintained and does not auto-sync with Figma token updates.