Token Bundle Size

January 15, 2026 • 4 min read

Token Bundle Size

Token bundle size refers to the file size of token outputs that applications load. As token systems grow, bundle sizes can impact load times, particularly on slower networks. Managing bundle size ensures tokens enhance rather than hinder application performance.

What Is Token Bundle Size

Token bundle size is the total bytes of token-related files delivered to clients. This typically includes CSS custom property declarations, JavaScript token modules, and any supplementary token data. Size affects download time, parse time, and caching behavior.

Bundle size management balances token completeness with delivery efficiency.

How Token Bundle Size Works

Size measurement:

# Measure CSS token file
$ ls -la dist/tokens.css
-rw-r--r--  1 user  group  45234 Jan 15 12:00 tokens.css

# Measure gzipped size
$ gzip -c dist/tokens.css | wc -c
12456

# Token size breakdown
CSS tokens: 45KB (12KB gzipped)
JS tokens: 23KB (8KB gzipped)
Total: 68KB (20KB gzipped)

Size contributors:

Token file composition:
- Property names: 35%
- Property values: 25%
- Syntax overhead: 20%
- Comments/whitespace: 20%

By category:
- Colors: 18KB (40%)
- Spacing: 4KB (9%)
- Typography: 12KB (27%)
- Shadows: 6KB (13%)
- Other: 5KB (11%)

Size tracking:

// Track bundle size in CI
const maxSize = 50 * 1024; // 50KB limit

const stats = fs.statSync('dist/tokens.css');
if (stats.size > maxSize) {
  console.error(`Token bundle exceeds limit: ${stats.size} > ${maxSize}`);
  process.exit(1);
}

Key Considerations

Gzipped size matters more than raw size
Compare size against value provided
Consider caching behavior
Mobile networks amplify size impact
Token loading strategy affects perceived performance
Size budgets prevent creep
Measure real-world impact, not just bytes
Optimization has diminishing returns

Common Questions

What size is acceptable?

Acceptable size depends on context and delivery strategy.

Size guidelines:

Small token system (< 100 tokens):
- CSS: 5-15KB (2-5KB gzipped)
- Acceptable for most applications

Medium token system (100-300 tokens):
- CSS: 15-40KB (5-12KB gzipped)
- Consider optimization for mobile

Large token system (300+ tokens):
- CSS: 40KB+ (12KB+ gzipped)
- Optimization recommended
- Consider splitting strategies

Context factors:

Performance-critical (e-commerce, mobile-first):
- Stricter budgets
- Aggressive optimization
- Consider critical CSS

Internal tools (admin dashboards):
- Relaxed budgets acceptable
- Developer convenience prioritized

Public websites:
- Balanced approach
- Consider mobile users

How can bundle size be reduced?

Reduction techniques target different size contributors.

Remove unused tokens:

// Tree shake unused tokens
function filterUsedTokens(tokens, usedNames) {
  return tokens.filter(t => usedNames.has(t.name));
}

Minimize output:

// Minify CSS
const CleanCSS = require('clean-css');
const minified = new CleanCSS({
  level: 2
}).minify(tokenCSS);

// Remove comments
const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');

Shorten names:

// Generate shorter custom property names
function shortenName(fullName) {
  const hash = createHash(fullName);
  return `--t${hash.slice(0, 6)}`;
}

// color.action.primary → --t3b82f6

Caution: Shortened names reduce debuggability.

Split bundles:

// Separate core and extended tokens
buildTokens({
  'tokens-core.css': coreTokens,     // Critical
  'tokens-extended.css': allTokens   // Lazy loaded
});

How should tokens be delivered?

Delivery strategy affects perceived performance.

Inline critical tokens:

<head>
  <style>
    /* Critical tokens inlined */
    :root {
      --color-primary: #3B82F6;
      --color-background: #fff;
      --spacing-md: 16px;
    }
  </style>
  <link rel="stylesheet" href="tokens.css" media="print" onload="this.media='all'">
</head>

Preload token file:

<link rel="preload" href="tokens.css" as="style">

CDN delivery:

Benefits:
- Geographic distribution
- HTTP/2 multiplexing
- Aggressive caching

Configuration:
Cache-Control: public, max-age=31536000, immutable

Summary

Token bundle size affects application performance, particularly on constrained networks. Size measurement should consider gzipped size, which better reflects actual transfer. Reduction techniques include removing unused tokens, minifying output, and splitting bundles. Delivery optimization through critical CSS inlining, preloading, and CDN caching minimizes performance impact. Size budgets in CI prevent gradual growth that accumulates unnoticed.

Buoy scans your codebase for design system inconsistencies before they ship

Detect Design Drift Free