Configuration
Learn more about how to configure Specify to generate design tokens and assets fitting your company standards.
- Design tokens are returned in JSON
- Assets are returned as files
A configuration file helps you:
- 1.request design tokens and assets from a Specify
repository
- 2.transform them to fit your company standards thanks to rules, token types and parsers.
A configuration is composed of 3 main properties:
repository
personalAccessToken
rules
The name of the Specify
repository
you want to pull your design tokens and assets from.Let's say we have the following repository in Specify called "all-design-data" located in the "@acme-inc" organization.

An example Specify repository called "all-design-data" located in the "@acme-inc" organization.
We target it like this:
JavaScript (CommonJS)
JSON
.specifyrc.js
1
module.exports = {
2
repository: '@acme-inc/all-design-data',
3
personalAccessToken: '<your-personal-access-token>',
4
rules: [],
5
};
.specifyrc.json
1
{
2
"repository": "@acme-inc/all-design-data",
3
"personalAccessToken": "<your-personal-access-token>",
4
"rules": []
5
}
You can only target one repository per configuration file. Want to pull design tokens from several Specify repositories? Create a several configuration files and run them with the Specify CLI.
The Specify
personalAccessToken
used to authenticate your actions.JavaScript (CommonJS)
JSON
1
module.exports = {
2
repository: '@workspace/repository',
3
personalAccessToken: '<your-personal-access-token>',
4
rules: [],
5
};
1
{
2
"repository": "@workspace/repository",
3
"personalAccessToken": "<your-personal-access-token>",
4
"rules": []
5
}
Rules help you transform your design tokens and assets the way you want.
You can have as many
rules
as you want and you can have rules that transform several Token types at once.A rule is composed of the following properties:
interface Rule {
name: string;
path: string;
filter?: {
types: Array<TokenType>
};
parsers?: Array<Parser>;
};
Name | Type | Required | Description |
---|---|---|---|
name | string | true | The name of your rule. |
path | string | true | The path in your project where you want Specify to generate your design data. |
filter | Record<'types', Array<TokenType>> | false | |
parsers | Array<Parser> | false |
Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards.
Inside a configuration, a parser has the following properties:
interface Parser {
name: string;
options?: Record<string, any>;
}
Name | Type | Required | Description |
---|---|---|---|
name | string | true | |
options | Record<string, any> | false | The options relative to the parser you apply. Each parser has its own options you can find in their respective README file. |
Here's a rule named "Design Tokens" that:
- 1.targets
color
andmeasurement
design tokens - 2.sorts them alphabetically by their
name
- 3.transforms them as CSS Custom Properties
- 4.writes them in a
design-tokens.css
file inside astyles
folder
JavaScript (CommonJS)
JSON
.specifyrc.js
1
[
2
{
3
name: 'Design Tokens',
4
path: 'styles/design-tokens.css',
5
filter: {
6
types: ['color', 'measurement']
7
},
8
parsers: [
9
{
10
name: 'sort-by',
11
options: {
12
keys: ['name']
13
}
14
},
15
{
16
name: 'to-css-custom-properties'
17
}
18
]
19
},
20
]
.specifyrc.json
1
[
2
{
3
"name": "Design Tokens",
4
"path": "styles/design-tokens.css",
5
"filter": {
6
"types": ["color", "measurement"]
7
},
8
"parsers": [
9
{
10
"name": "sort-by",
11
"options": {
12
"keys": ["name"]
13
}
14
},
15
{
16
"name": "to-css-custom-properties"
17
}
18
]
19
}
20
]
The following examples are made to be used with the Specify CLI.
Requirements:
- a Specify repository containing design tokens
Run all examples by copying the code and running the
specify pull
command.Here's a basic configuration file that targets a Specify repository called
all-design-data
from the @acme-inc
organization:JSON
JavaScript (CommonJS)
.specifyrc.json
1
{
2
"repository": "@acme-inc/all-design-data",
3
"personalAccessToken": "<your-personal-access-token>",
4
"rules": [
5
{
6
"name": "All design tokens in JSON",
7
"path": "design-tokens.json",
8
"parsers": []
9
}
10
]
11
}
.specifyrc.js
1
module.exports = {
2
repository: '@acme-inc/all-design-data',
3
personalAccessToken: '<your-personal-access-token>',
4
rules: [
5
{
6
name: 'All design tokens in JSON',
7
path: 'design-tokens.json',
8
parsers: [],
9
},
10
],
11
};
This example config file will return a
design-tokens.json
file containing all design tokens and assets stored in the all-design-data
repository.Here's an example of a token value returned by Specify:
{
"id": String,
"createdAt": String,
"updatedAt": String,
"name": String,
"value": Object,
"meta": Object,
"type": String,
"originId": String,
"sourceId": String,
"description": String,
"repositoryId": String
}
Now let's update our previous configuration to only pull colors and transform them as CSS Custom Properties in HSL.
JavaScript (CommonJS)
JSON
.specifyrc.js
1
module.exports = {
2
repository: '@acme-inc/all-design-data',
3
personalAccessToken: '<your-personal-access-token>',
4
rules: [
5
{
6
name: 'All design tokens in JSON',
7
path: 'colors.css',
8
filter: {
9
types: ['color']
10
},
11
parsers: [
12
{
13
name: 'to-css-custom-properties',
14
options: {
15
formatTokens: {
16
color: 'hsl'
17
},
18
},
19
},
20
],
21
},
22
],
23
};
.specifyrc.json
1
{
2
"repository": "@acme-inc/all-design-data",
3
"personalAccessToken": "<your-personal-access-token>",
4
"rules": [
5
{
6
"name": "Colors as CSS Custom Properties",
7
"path": "colors.css",
8
"filter": {
9
"types": ["color"]
10
},
11
"parsers": [
12
{
13
"name": "to-css-custom-properties",
14
"options": {
15
"formatTokens": {
16
"color": "hsl"
17
}
18
}
19
}
20
]
21
}
22
]
23
}
Here is the input returned by Specify and the output generated by Specify after executing our configuration.
Input (Before)
Output (After)
1
[
2
{
3
"name": "Primary/100",
4
"value": {
5
"a": 1,
6
"b": 254,
7
"g": 233,
8
"r": 237
9
},
10
"type": "color",
11
"description": ""
12
},
13
{
14
"name": "Primary/200",
15
"value": {
16
"a": 1,
17
"b": 254,
18
"g": 214,
19
"r": 221
20
},
21
"type": "color",
22
"description": ""
23
},
24
{
25
"name": "Primary/300",
26
"value": {
27
"a": 1,
28
"b": 253,
29
"g": 181,
30
"r": 196
31
},
32
"type": "color",
33
"description": ""
34
}
35
]
colors.css
1
:root {
2
/* COLOR */
3
--primary-100: hsl(251, 91%, 95%);
4
--primary-200: hsl(251, 95%, 92%);
5
--primary-300: hsl(252, 95%, 85%);
6
}
Last modified 3mo ago