# to-css-custom-properties

## Interface

```typescript
interface parser {
  name: 'to-css-custom-properties';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    tokenNameTemplate?: string;
    selectorTemplate?: string;
    tokenNotInCollectionNameTemplate?: string;
    includeCoreTokensInScopes?: boolean;
    allowUnresolvable?: boolean;
    withSDTFView?: string;
  };
}
```

## Options

<table data-full-width="true"><thead><tr><th width="371">Parameter</th><th width="101">Required</th><th width="110">Type</th><th width="96">Default</th><th width="448">Description</th></tr></thead><tbody><tr><td><code>selectorTemplate</code></td><td><code>false</code></td><td><code>string</code></td><td></td><td>The pattern used to generate the CSS selector name(s). It must match <a href="https://github.com/janl/mustache.js#templates">mustache</a> template syntax.<br><br>You can use <code>collection</code>, <code>mode</code> and <code>groups</code> names.</td></tr><tr><td><code>tokenNameTemplate</code></td><td><code>false</code></td><td><code>string</code></td><td></td><td>The pattern used to generate token names. It must match <a href="https://github.com/janl/mustache.js#templates">mustache</a> template syntax.<br><br>You can use <code>collection</code>, <code>mode</code>,<code>groups</code> and <code>token</code> names.</td></tr><tr><td><code>tokenNotInCollectionNameTemplate</code></td><td><code>false</code></td><td><code>string</code></td><td></td><td>The pattern used to generate token names when they are <strong>located outside of collections</strong>. It must match <a href="https://github.com/janl/mustache.js#templates">mustache</a> template syntax.<br><br>You can use <code>mode</code>,<code>groups</code> and <code>token</code> names.</td></tr><tr><td><code>includeCoreTokensInScopes</code></td><td><code>false</code></td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, you will have both core tokens and alias tokens in each CSS scopes thus making alias tokens always resolvable.</td></tr><tr><td><code>allowUnresolvable</code></td><td><code>false</code></td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, you'll be able to generate alias CSS variables targeting tokens which are not generating in the same scope or file (e.g., if you want a <code>primitive.css</code> and <code>semantic.css</code> files).<br><br>When set to <code>true</code>, tokens will be named with the <code>tokenNotInCollectionNameTemplate</code> option.</td></tr><tr><td><code>withSDTFView</code></td><td><code>false</code></td><td><code>string</code></td><td></td><td>The name of a registered view. See <a href="register-view">register-view</a> for more details using the CLI or GitHub.</td></tr></tbody></table>

## Basic usage

A design token can have modes, be nested in groups and be part of a collection. The following use case will generate a single CSS file containing core tokens and semantic tokens.

{% tabs %}
{% tab title="Input" %}
{% code lineNumbers="true" %}

```json
{
  "colors": {
    "$collection": { "$modes": ["light", "dark"] },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          },
          "dark": {
            "red": 41,
            "blue": 67,
            "alpha": 1,
            "green": 52,
            "model": "rgb"
          }
        }
      },
      "blue-700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "red": 17,
            "blue": 249,
            "alpha": 1,
            "green": 125,
            "model": "rgb"
          },
          "dark": {
            "red": 96,
            "blue": 250,
            "alpha": 1,
            "green": 168,
            "model": "rgb"
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "dark": {
                  "$mode": "dark",
                  "$alias": "colors.core.blue-100"
                },
                "light": {
                  "$mode": "light",
                  "$alias": "colors.core.blue-700"
                }
              }
            }
          }
        }
      }
    }  
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Config" %}
{% code title=".specifyrc.json" lineNumbers="true" %}

```json5
{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          },
          "options": {
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}
{% code title="tokens.css" lineNumbers="true" %}

```css
[data-theme="dark"] {
  --core-blue-100: rgb(41, 52, 67);
  --core-blue-700: rgb(96, 168, 250);
  --semantic-background-button-primary-hover: var(--core-blue-100);
}
[data-theme="light"] {
  --core-blue-100: rgb(219, 236, 254);
  --core-blue-700: rgb(17, 125, 249);
  --semantic-background-button-primary-hover: var(--core-blue-700);
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Head towards our [templates section](https://docs.specifyapp.com/resources/parser-rules-templates/css-custom-properties) to see how you can use this parser with others to suit a common use case when working with CSS.
{% endhint %}