Using your own design tokens

FEWD Studio’s styling panel and CSS touch bar offer your project’s design tokens — the CSS custom properties in your connected globals file — instead of raw values. Out of the box, FEWD looks for tokens by the names GenCSS uses: --space-m, --radius-l, --primary-light-1 and so on.

If your project uses another framework, or your own naming — --spacing-4, --rounded-lg, --color-slate-500 — the token map tells FEWD which of your names belong to which control. You set it once as your own default, and, where a project differs, for that project.

Nothing changes until you set a map. A GenCSS project needs none.

---

Before you start

Connect your tokens file in the Globals pane. FEWD reads tokens from one globals stylesheet: the file you connect there. Every token the styling panel and touch bar offer comes from it. If your tokens are spread over several files, gather them into one globals sheet first.

---

Set up a token map

1. Connect your globals file in the Globals pane (if it isn’t already).
2. Open the token map. In the Globals pane bar, click the Token map button (beside the GenCSS button).
3. Choose where it applies:
   • My default: saved in FEWD’s preferences, used in every project that has no map of its own. Use this for the framework you work with most.
   • This project: saved in the project as .fewd/token-map.json. It goes with the project, so anyone else opening it in FEWD gets the same map. It only needs to fill in the rows where the project differs from your default.
4. Fill in the rows that need it. Each row is one kind of control: Padding, Margin, Radius, Font size, Colour palette and so on.
   • Type the start of the token names that belong to it, separated by commas: for example --spacing- for Padding. Any token whose name starts with that is a candidate.
   • The grey placeholder shows FEWD’s default names for that row. Leave a row empty to keep the default.
   • The line under each row shows, as you type, what your names match in the connected globals file, and which level the row’s names come from: This project, My default or FEWD default.
   • If none match (optional) is a second list, used only when the first finds nothing.
5. Click Save. The styling panel and the touch bar use the new names straight away.

Nothing changes until you click Save. Cancel or Escape leaves everything as it was.

---

Worked example

Take a small example framework, Northwind. It names its tokens the way many frameworks do:

:root {
  --spacing-4: 1rem;               /* spacing: one scale for padding, margin, gap */
  --rounded-lg: 0.5rem;            /* corners */
  --elevation-2: 0 4px 6px -1px rgb(0 0 0 / 0.1);   /* shadows */
  --layer-modal: 50;               /* stacking */
  --color-slate-500: oklch(0.554 0.046 257.417);    /* palette */
  --fg: var(--color-slate-900);    /* colour roles */
  --line: var(--color-slate-200);
  --text-lg: 1.125rem;             /* type: FEWD's default already finds these */
}

With FEWD’s defaults alone, Padding, Margin, Gap, Inset, Radius, Shadow, Stack order and the colour palette find nothing, and the colour picker’s Roles tab shows the raw --color-* palette rather than the roles. Font size, Font weight, Leading, Tracking, Max width and Transition already work: Northwind happens to use the same names as FEWD’s defaults there.

The map fills the rest:

Row	Token names
Padding, Margin, Gap, Inset	--spacing-
Radius	--rounded
Shadow	--elevation-
Stack order	--layer-
Colour roles	--fg, --bg, --line, --accent
Colour palette	--color-slate-, --color-indigo-, --color-rose-

To try it: save the map below as token-map.json, connect your own tokens file in the Globals pane, open the Token map, click Import…, choose the file, then Save. Click an element in the preview: Padding now offers your --spacing- tokens, and the colour picker shows the slate, indigo and rose ramps.

{
  "version": 1,
  "families": {
    "padding":      { "prefixes": ["--spacing-"] },
    "margin":       { "prefixes": ["--spacing-"] },
    "gap":          { "prefixes": ["--spacing-"] },
    "inset":        { "prefixes": ["--spacing-"] },
    "radius":       { "prefixes": ["--rounded"] },
    "shadow":       { "prefixes": ["--elevation-"] },
    "z":            { "prefixes": ["--layer-"] },
    "colour-roles": { "prefixes": ["--fg", "--bg", "--line", "--accent"] }
  },
  "palette": { "prefixes": ["--color-slate-", "--color-indigo-", "--color-rose-"] }
}

---

Colours

• Colour palette (the last row): each name you list becomes one ramp of swatches. For example, --color-slate- gives every --color-slate-… colour, in the order the file lists them. A mapped palette replaces GenCSS’s palettes in the touch bar and in the styling panel’s Palette tab.
• Colour roles fills the colour picker’s Roles tab: the tokens that say what a colour is for (--fg, --bg, --accent), rather than which shade it is.

Every colour control (text colour, border colour, background) chooses from the colour picker, so these two rows map all of them. The Transparency and Status tabs are GenCSS’s own and are not mapped.

---

Levels, sharing and reset

For each row, FEWD uses the first of these that fills it in:

1. This project: .fewd/token-map.json in the project.
2. My default: your FEWD preferences.
3. FEWD default: the GenCSS names.

So a project can override just Padding, and keep your usual names for everything else.

• Share with a team: save at This project and commit .fewd/token-map.json with the project.
• Move a map: Export… saves the level you’re looking at to a file; Import… loads a file into the level you’re looking at. Click Save afterwards to keep it.
• Start again: Reset to FEWD default clears the level you’re looking at. Click it twice: the first click asks. At This project, the project’s file is deleted; at My default, your saved default is cleared.

---

How FEWD decides a token fits

A name only makes a token a candidate. FEWD also checks the token’s value, following var() references to the final value, and only offers tokens whose value suits the control. So a Padding row can’t offer a colour, however it’s mapped, and a token that’s a var() of another token works as expected.

Row	FEWD’s default names	Offers tokens whose value is
Width	--width-, --measure-	a length (rem, px, %, clamp(), calc() …)
Max width	--container-, --measure-, --width-	a length
Height	--height-	a length
Radius	--radius-, --border-radius-	a length
Border width	--border-width-, --border-	a length
Shadow	--shadow-	a shadow (offsets and a colour)
Opacity	--opacity-	a plain number
Inset	--space-	a length
Stack order	--z-	a whole number
Gap	--gap- (if none: --space-)	a length
Padding	--padding- (if none: --space-)	a length
Margin	--margin-, --space-	a length
Font size	--text-, --font-size-	a length
Font weight	--weight-, --font-weight-	a font weight (400, 700, bold …)
Leading	--leading-, --line-height-	a ratio or a length
Tracking	--tracking-, --letter-spacing-	0 or a length
Transition	--transition-, --duration-	a duration (150ms, 0.2s …)
Colour roles	--color-	a colour
Colour palette	GenCSS palettes (--primary, --secondary …)	a colour

A colour is a value FEWD can read as one: oklch(), rgb(), hsl(), a hex code, light-dark() or color-mix(). Named colours such as white or rebeccapurple are not recognised: write oklch(1 0 0) or #fff instead.

---

If a row matches nothing

• No globals file connected: connect one in the Globals pane.
• The names don’t match: a row matches tokens whose names start with what you type, so --spacing- matches --spacing-4 but not --space-4. Check the spelling against your globals file.
• The values don’t suit the control: see the table above. A token mapped to Padding must be a length. A colour named with a keyword (white) isn’t read as a colour.
• A project prefix: if every token in your file starts with the same word, for example --acme-space-m, FEWD sees through it. Type either --space- or --acme-space-; both work.
• The project’s file was changed outside FEWD (by a pull, say): reopen the project, or open the Token map, and FEWD reads it again.

---

The file

.fewd/token-map.json (and an exported map) looks like this:

{
  "version": 1,
  "families": {
    "padding": { "prefixes": ["--spacing-"] },
    "gap":     { "prefixes": ["--gap-"], "fallback": ["--spacing-"] }
  },
  "palette": { "prefixes": ["--color-slate-", "--color-indigo-"] }
}

The names in families are, in the order of the table above: width, max-width, height, radius, border-width, shadow, opacity, inset, z (Stack order), gap, padding, margin, font-size, font-weight, line-height (Leading), letter-spacing (Tracking), transition, colour-roles. The colour palette is palette, outside families. Any other name in the file is ignored.

The file only lists token names. It can’t add a value, point at another file or run anything; FEWD ignores anything else in it. So it is safe to open a project that has one, whoever wrote it.