Design Token Caching

Design token caching stores token files for reuse, avoiding repeated downloads and improving application performance. Effective caching strategies ensure users receive token updates when they change while maximizing cache hits for unchanged tokens. Caching is particularly valuable for token files that change infrequently.

What Is Design Token Caching

Design token caching leverages browser and CDN caching mechanisms to store token CSS or JavaScript files locally. Once cached, subsequent page loads retrieve tokens from cache rather than making network requests. This dramatically improves performance for returning visitors.

Caching strategy must balance cache duration (longer = better performance) with freshness (users need updates).

How Design Token Caching Works

Browser caching with Cache-Control:

# Server response headers
Cache-Control: public, max-age=31536000, immutable
ETag: "v2.3.0-abc123"

This tells browsers to cache for one year. The immutable hint indicates the file will not change at this URL.

Versioned filenames:

<!-- Old version -->
<link rel="stylesheet" href="tokens.v2.2.0.css">

<!-- New version (different filename) -->
<link rel="stylesheet" href="tokens.v2.3.0.css">

Version in filename means new versions have new URLs, bypassing cached old versions.

Content-based hashing:

<!-- Hash changes when content changes -->
<link rel="stylesheet" href="tokens.abc123.css">

Build process generates hash from file content. Changed content produces new hash, new URL.

CDN caching:

Origin → CDN Edge → User

First request: CDN fetches from origin, caches, serves
Subsequent requests: CDN serves from cache

TTL: 1 year at edge
Purge: On deploy of new version

Key Considerations

• Cache duration should match token update frequency
• Cache invalidation must be reliable
• Development should bypass caching
• Monitor cache hit rates
• Consider mobile and offline scenarios
• Service workers enable advanced caching
• Cross-domain caching has limitations
• Cache warming improves first-request performance

Common Questions

How should cache invalidation work?

Cache invalidation ensures users receive updated tokens.

Filename-based invalidation:

// Build process includes version/hash in filename
const hash = crypto
  .createHash('md5')
  .update(tokenCSS)
  .digest('hex')
  .slice(0, 8);

const filename = `tokens.${hash}.css`;
// Old files naturally become unused
// New files have new URLs, not cached

CDN purge on deploy:

# CI deployment
deploy:
  steps:
    - run: npm run build-tokens
    - run: aws s3 sync dist/ s3://assets/
    - run: aws cloudfront create-invalidation --paths "/tokens/*"

Versioned imports:

// Token version in import
import tokens from '@company/tokens/v2.3.0';

// Upgrade means changing import
import tokens from '@company/tokens/v2.4.0';

What cache duration is appropriate?

Duration depends on update frequency and tolerance for stale content.

Long cache (1 year):

Cache-Control: max-age=31536000, immutable

When to use:
- Hashed/versioned filenames
- Any change creates new URL
- Maximizes cache efficiency

Medium cache (1 week to 1 month):

Cache-Control: max-age=604800

When to use:
- Stable token system
- Acceptable if users see week-old tokens briefly
- Simpler deployment (no filename changes)

Short cache (1 hour to 1 day):

Cache-Control: max-age=3600

When to use:
- Frequent token changes
- Critical that users see updates quickly
- Accepts more network requests

Recommended approach:

Use long cache (1 year) with content-hashed filenames.
Best of both: maximum caching, instant updates.

How should development caching differ?

Development needs fresh files; caching interferes with iteration.

Disable caching in development:

Cache-Control: no-cache, no-store, must-revalidate

Cache busting in development:

<!-- Add timestamp to bypass cache -->
<link rel="stylesheet" href="tokens.css?t=${Date.now()}">

Webpack dev server configuration:

devServer: {
  headers: {
    'Cache-Control': 'no-store'
  }
}

Local development vs. production:

const cacheControl = process.env.NODE_ENV === 'production'
  ? 'public, max-age=31536000, immutable'
  : 'no-store';

Summary

Design token caching stores token files for reuse, dramatically improving performance for returning visitors. Effective caching uses long cache durations (1 year) combined with content-hashed filenames that change when content changes. Cache invalidation through filename changes or CDN purges ensures users receive updates. Development environments should disable caching to enable rapid iteration. Monitoring cache hit rates validates caching effectiveness.