🛠️ Queensland Government Design System - Design tokens

📖 On this page:

• 🎨 What are 'design tokens'
• 🚀 Getting started
  • 📦 Install & build
  • ✅ Running tests
  • ⚙️ Continuous integration
• 🧩 Extending design tokens
  • ✏️ Create your own theme
  • 📁 Files to update
  • 🛠️ After creating a custom theme
• 🔄 Tokens Studio integration
• 📚 Additional resources
• 📦 Publishing

🎨 What are 'design tokens'?

“A Style Dictionary uses design tokens to define styles once and use those styles on any platform or language. It provides a single place to create and edit your styles, and exports these tokens to all the places you need.”
— Amazon

Design tokens are the single source of truth for your product’s visual style, they capture design decisions such as:

• 🎨 Colours (primary, secondary, background, border)
• 🔠 Typography (font families, weights, sizes, line heights)
• 📐 Spacing (margins, paddings, gaps)
• 🧱 Components (border radius, shadows, z-index)

These tokens are used to ensure consistency across multiple platforms and UI libraries (web, iOS, Android, emails, PDFs, etc.) without duplicating style logic in each codebase.

This repository implements design tokens using Amazon’s Style Dictionary, which compiles token definitions (stored in platform-agnostic JSON files) into platform-specific formats such as:

• ✅ SCSS variables
• ✅ CSS custom properties (--tokens)
• ✅ JavaScript constants
• ✅ JSON files for use in Figma, Storybook, or frontend frameworks

🧠 Why use Design Tokens?

• 🔁 Consistency: One change updates all platforms
• 🧩 Scalability: Add themes without rewriting UI
• 🤝 Collaboration: Designers and developers share a common language
• 🛡️ Governance: Enforce brand guidelines automatically

This package serves as the Queensland Government’s baseline design token system, and is intended to be:

• ✅ Extended per department/project
• ✅ Versioned and built into pipelines
• ✅ Source-controlled for audit and collaboration

🚀 Getting started

📦 Install & build

npm install
npm run build

✅ Running tests

npm run test

⚙️ Continuous integration

npm run ci

🧩 Extending Design Tokens

✏️ Create your own theme

You can fork this repository and create your own theme by extending the design tokens.

1. Fork this repo
2. Switch to the example branch for guidance:

git checkout custom-tokens-and-themes-example

Your forked files will remain untouched when pulling updates from the upstream repo.

📁 Files to update

To register a custom theme, update the following:

• ./$metadata.json
• ./$themes.json

📌 See the custom-tokens-and-themes-example branch for examples.

🛠️ After creating a custom theme

Run the following to validate:

npm run build
npm run test
npm run build:package

✅ You should see no errors.

🔄 Tokens Studio integration

Using Tokens Studio to update tokens directly from Figma is supported.

⚠️ Sometimes Tokens Studio may overwrite or add $metadata or $theme tokens.
To avoid issues, we preserve .original copies of expected formats for easy reversion.

📚 Additional resources

• 📘 Token Studio Official Documentation
• 📘 Style Dictionary Documentation
• 🔧 Style Dictionary Transforms for Tokens Studio

📦 Publishing

There are two publish subsystems:

1. To npmjs.com
2. To the GitHub repository package registry

Ensure you are authenticated correctly before publishing.