CLI-Anything Design Token Architecture: Organization Guide for Colors, Radius, Spacing, Shadows, and Typography

HKUDS/CLI-Anything stores all design tokens in a single JSON file with five top-level groups, resolved at build time through a builder utility that substitutes placeholder strings like "$primary" with concrete values.

The CLI-Anything project from HKUDS implements a flat, single-file design token system that keeps visual styling consistent across its agent harness. This article examines how colors, radius, spacing, shadows, and typography are organized, accessed, and applied in the codebase.

---

Where Design Tokens Live in HKUDS/CLI-Anything

All visual design tokens reside in one canonical location:

sketch/agent-harness/tokens/default.json

This flat JSON structure contains five top-level groups. The organization prioritizes simplicity and direct lookup over nested hierarchies.

Token Group	Purpose	Example Keys
colors	Named color palette for UI elements	primary, secondary, success, warning, danger
radius	Standard border-radius values	small, medium, large, full
spacing	Base spacing scale for margins and paddings	xs, sm, md, lg, xl
shadows	CSS-compatible shadow definitions	elevation1, elevation2, elevation3
typography	Font families, weights, and sizes	fontFamily, fontWeight, fontSize, lineHeight

Each group uses a flat key-value layout. Numeric values are typically expressed in pixels. Shadow values store complete CSS box-shadow strings.

---

How the Builder Resolves Design Tokens

The builder utility at sketch/agent-harness/src/builder.js provides the runtime access pattern for all tokens.

Token references use a dollar-prefixed placeholder convention. The builder strips the $ prefix and looks up the key in the appropriate token group:

// Excerpt from sketch/agent-harness/src/builder.js
if (tokens.colors && tokens.colors[key]) return tokens.colors[key];

This resolution happens during template processing. A single placeholder like "$primary" becomes "#0052CC" (or whatever value is defined in tokens.colors.primary).

---

Design Token Usage Examples

The builder supports cross-category placeholders. The category is inferred from naming conventions rather than explicit prefixes.

Template Before Processing

{
  "color": "$primary",
  "borderRadius": "$large",
  "margin": "$md"
}

After Builder Resolution

{
  "color": "#0052CC",
  "borderRadius": 8,
  "margin": 16
}

• $primary → tokens.colors.primary
• $large → tokens.radius.large
• $md → tokens.spacing.md

The builder handles this resolution automatically without requiring category prefixes in the placeholder syntax.

---

Key Files in the Design Token System

File	Responsibility
sketch/agent-harness/tokens/default.json	Master token definitions—the single source of truth for all visual values
sketch/agent-harness/src/builder.js	Runtime token resolution engine; substitutes placeholders with concrete values
sketch/agent-harness/README.md	Documentation explaining the "$token" → tokens.group.key mapping convention

These three artifacts form the complete design token architecture. No additional configuration files or build-time transforms are required.

---

Design Decisions in CLI-Anything's Token System

The HKUDS team made specific architectural choices that distinguish this system:

• Single file over distributed tokens: All five categories live in one JSON document, reducing import complexity
• Flat structure over nested hierarchies: Direct key access avoids deep property chains
• Runtime resolution over static replacement: The builder evaluates tokens dynamically, enabling potential theme switching
• Implicit categorization: The builder infers categories from key names ($md → spacing) rather than explicit syntax like $spacing.md

These decisions prioritize the needs of a CLI tool generator over a traditional web component library.

---

Summary

• HKUDS/CLI-Anything stores all design tokens in sketch/agent-harness/tokens/default.json with five top-level groups: colors, radius, spacing, shadows, and typography
• The builder utility at sketch/agent-harness/src/builder.js provides runtime token resolution using $placeholder syntax
• Flat key-value structures enable direct lookup without nested property access
• Implicit categorization allows concise placeholders like $primary without verbose prefixes
• The system targets template generation workflows rather than CSS-in-JS or design-system distribution

---

Frequently Asked Questions

What file contains all design tokens in CLI-Anything?

The master token file is sketch/agent-harness/tokens/default.json. This single JSON document defines colors, radius, spacing, shadows, and typography in five top-level object keys. No other token files exist in the repository structure.

How does the builder resolve token placeholders?

The builder strips the $ prefix from placeholders like $primary, then searches token groups for a matching key. According to the source code in sketch/agent-harness/src/builder.js, it checks tokens.colors[key] and other groups until finding a match. The first match wins—colors are typically checked before other categories.

Can design tokens be customized or themed?

The flat JSON structure and runtime resolution pattern make theming technically possible. You could replace default.json with an alternative file, or modify token values before the builder initializes. However, the repository ships with only one token file; multi-theme support would require extending the builder's token loading logic.

Why doesn't CLI-Anything use CSS variables or a design system like Tailwind?

CLI-Anything generates CLI tools and agent harnesses, not web applications. The token system targets JSON-to-JSON template transformation rather than browser rendering. CSS variables would be useless for generated configuration files, whereas the current builder produces concrete values consumable by any target environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}