@narrows/tokens

Narrows design tokens — CSS, SCSS, JSON, and JS/TS. Zero runtime dependencies. Works in any JS/TS project, SCSS build, Python script, or plain HTML page.

This package was extracted from the Narrows monorepo, which contains the companion @narrows/react component library.

Install

npm install @narrows/tokens
# or
pnpm add @narrows/tokens

Usage

JavaScript / TypeScript

import { tokens } from '@narrows/tokens'

const primary = tokens.arup.brand.arupRed    // '#AE132A'
const blue    = tokens.colors.base.blue[600] // '#2563EB'
const gap     = tokens.spacing[4]            // '1rem'
const radius  = tokens.radii.md              // '0.375rem'

CSS custom properties

/* Import once at the root of your app */
@import '@narrows/tokens/tokens.css';

.button {
  background: var(--narrows-arup-brand-arupRed);
  border-radius: var(--narrows-radii-md);
  padding: var(--narrows-spacing-2) var(--narrows-spacing-4);
}

SCSS variables

@use '@narrows/tokens/tokens.scss' as t;

.button {
  background: t.$narrows-arup-brand-arupRed;
  border-radius: t.$narrows-radii-md;
}

JSON (Python, Ruby, etc.)

import json, pathlib

tokens = json.loads(
    pathlib.Path("node_modules/@narrows/tokens/dist/tokens.json").read_text()
)

primary = tokens["arup"]["brand"]["arupRed"]      # '#AE132A'
blue    = tokens["colors"]["base"]["blue"]["600"] # '#2563EB'

Design tokens

All tokens are defined once in src/ and emitted in multiple formats on every build:

| File | Use case | |---|---| | dist/tokens.css | Any HTML/CSS project — var(--narrows-arup-brand-arupRed) | | dist/tokens.scss | SCSS projects — $narrows-arup-brand-arupRed | | dist/tokens.json | Python, Ruby, Style Dictionary, generic JSON consumers | | dist/tokens.figma.json | Tokens Studio ↔ Figma sync (W3C DTCG format, committed to git) | | dist/tokens.js / .cjs | JS/TS projects |

CSS variables follow the --narrows-* prefix to avoid collisions with other libraries.

Typography — composite text styles

Typography is organized around named roles (body, heading, caption, label, code) with four size steps each (small, medium, large, xlarge). Each role-size token is a composite that sets font family, size, weight, and line height together.

import { tokens } from '@narrows/tokens'

tokens.textStyles['body-medium']
// { fontFamily: '...', fontSize: '1rem', fontWeight: '500', lineHeight: '1.5' }

Lower-level primitives (fontSizes, fontWeights, lineHeights, fonts) are still exported for one-off sizing needs (e.g. icon dimensions), but textStyles should be preferred for actual typographic content.

Figma integration

This repo syncs design tokens to Figma via the Tokens Studio plugin (free tier).

dist/tokens.figma.json is the sync file — it is committed to the repo and read directly from GitHub by the plugin. Composite textStyles tokens (e.g. body-medium) are exported using the W3C DTCG typography composite type, so Tokens Studio/Figma variables surface them as a single typography style rather than separate size/weight/line-height variables.

When you update a token value:

# 1. Edit src/*.ts (e.g. typography.ts)
pnpm build

# 2. Commit and push tokens.figma.json
git add dist/tokens.figma.json
git commit -m "chore: update tokens"
git push

# 3. In Figma → Tokens Studio plugin → Pull

Local development

Requirements

• Node.js 20+
• pnpm

Setup

pnpm install

Build

pnpm build

Typecheck

pnpm typecheck

Watch mode

pnpm dev

Repository structure

narrows-tokens/
├── src/
│   ├── arup/           # ARUP corporate identity colors: brand, neutral,
│   │                   # accent, secondary, status (tokens.arup.*)
│   ├── colors/         # Non-ARUP default palette: base (tokens.colors.base)
│   ├── typography.ts   # fonts, fontSizes, fontWeights, lineHeights,
│   │                   # letterSpacings, and composite textStyles
│   │                   # (e.g. `body-medium`)
│   └── index.ts        # Aggregates all token categories
├── build/
│   └── generate.ts     # Emits CSS, SCSS, JSON, and tokens.figma.json
└── dist/
    ├── tokens.js / .cjs / .d.ts
    ├── tokens.css
    ├── tokens.scss
    ├── tokens.json
    └── tokens.figma.json  # Committed — used by Tokens Studio ↔ Figma sync

Releasing

Versions are managed manually by bumping the version field in package.json and publishing with pnpm.

pnpm typecheck
pnpm build
pnpm publish --access public

| Change type | Example | Version bump | |---|---|---| | Bug fix, internal refactor | Fix a token value | patch — 0.0.1 → 0.0.2 | | New token category | Add a new spacing scale | minor — 0.0.1 → 0.1.0 | | Breaking API change | Rename a token key | major — 0.0.1 → 1.0.0 |

Contributing

1. Fork the repo and create a branch from main
2. Make your changes
3. Run pnpm typecheck && pnpm build to verify nothing is broken
4. Open a pull request

License

MIT