Hardcoded Values vs Tokens

The choice between hardcoded values vs tokens affects maintainability, consistency, and the ability to evolve design systems over time. Hardcoded values embed specific numbers and colors directly in code, while tokens abstract these values behind meaningful names. Understanding when each approach is appropriate and how to migrate from hardcoded values to tokens improves design system health.

What Are Hardcoded Values

Hardcoded values are literal values written directly in code without indirection through variables or tokens. A hardcoded color might appear as #3B82F6 directly in a CSS rule. A hardcoded spacing value might be padding: 16px without reference to any named variable.

Hardcoded values are quick to write and immediately understandable in isolation. However, they create maintenance challenges: changing a color used in fifty places requires fifty edits. They also resist systematic updates like theming, where values need to change based on context.

How Tokens Differ from Hardcoded Values

Tokens provide named references to values, creating a layer of indirection that offers several benefits.

Centralized updates allow changing a value once in its token definition to update all usages automatically. Renaming the brand color from blue to green requires changing only the token value, not every usage.

Semantic meaning communicates design intent. A token named color-background-primary explains its purpose, while #ffffff requires inference or additional documentation.

Theming support enables the same token name to resolve to different values in different contexts. Dark mode changes color-background-primary from white to near-black without component code changes.

Constraint enforcement limits available values to those defined in the token system. Developers choose from the token palette rather than inventing arbitrary values.

Tokens add indirection complexity and require infrastructure for transformation and distribution. This overhead justifies itself as systems scale but may not benefit very small projects.

Key Considerations

• Tokens provide most value when values are reused across multiple locations
• One-time-use values may not warrant tokenization
• Migration from hardcoded values to tokens should be incremental
• Detection tooling can identify hardcoded values for remediation
• Some contexts genuinely require literal values
• Documentation should clarify which values must use tokens
• Code review should flag inappropriate hardcoding
• Metrics can track hardcoded value prevalence over time

Common Questions

When are hardcoded values acceptable?

Hardcoded values remain appropriate in specific circumstances.

Truly one-off values that will never repeat and carry no semantic meaning may not warrant tokenization. A specific pixel offset to align a particular icon might be a hardcoded value if it addresses a unique rendering quirk.

External requirements might mandate specific values. Compliance standards, third-party integration requirements, or platform-specified values may need to be hardcoded to ensure exact matches regardless of token system changes.

Computed values derived from other sources might be hardcoded results of calculations. However, these often benefit from being computed from token values rather than hardcoded.

Mathematical relationships like 50% or 100vh express proportional values that typically should not be abstracted.

The key question is whether the value represents a design decision that might change or be reused. If yes, a token is appropriate. If the value is fixed by external constraints or mathematical necessity, hardcoding may be acceptable.

How can hardcoded values be detected?

Detection tools scan codebases for patterns that indicate hardcoded values that should use tokens.

Regular expression matching finds literal values in expected formats. Hex color patterns like #[0-9A-Fa-f]{3,8} identify potential hardcoded colors. Pixel values like \d+px find potential hardcoded dimensions.

Linting rules can flag hardcoded values in specific contexts. ESLint or Stylelint plugins can warn when raw values appear where token references are expected:

// stylelint rule pseudo-configuration
{
  "rules": {
    "scale-unlimited/declaration-strict-value": [
      ["/color/", "font-size", "padding", "margin"],
      { "ignoreKeywords": ["inherit", "transparent"] }
    ]
  }
}

Static analysis tools specifically designed for design systems can identify values that match token values but do not reference them, suggesting the developer may have intended to use a token.

IDE integration provides real-time feedback as developers write code, highlighting hardcoded values and suggesting token alternatives.

How should migration from hardcoded values proceed?

Migration requires systematic identification, prioritization, and replacement of hardcoded values.

Audit first to understand the scope. How many hardcoded values exist? Which categories (colors, spacing, typography)? Which areas of the codebase?

Prioritize by impact. Colors are often most visible and benefit most from tokenization. High-traffic components warrant earlier migration than rarely-used utilities.

Create missing tokens for values that should be tokenized but lack corresponding tokens. The audit may reveal values that are not yet in the token system.

Replace incrementally rather than attempting complete migration at once. A codemod can handle straightforward replacements:

// Codemod to replace hardcoded colors
module.exports = function(fileInfo, api) {
  const replacements = {
    '#3B82F6': 'var(--color-primary)',
    '#ffffff': 'var(--color-background-primary)'
  };

  let source = fileInfo.source;
  Object.entries(replacements).forEach(([value, token]) => {
    source = source.replace(new RegExp(value, 'gi'), token);
  });
  return source;
};

Verify that visual appearance remains unchanged after migration. Automated visual regression testing catches unintended changes.

Track progress through metrics showing hardcoded value counts over time. Decreasing counts indicate successful migration progress.

Summary

Hardcoded values and tokens represent different approaches to storing design values, with tokens providing maintainability, semantic meaning, and theming support at the cost of indirection. Most design values benefit from tokenization, though genuinely one-off values or external requirements may justify hardcoding. Detection tools identify hardcoded values for migration, which proceeds incrementally with validation at each step.