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

> Discover the CLI-Anything design token architecture. Learn how HKUDS organizes colors, radius, spacing, shadows, and typography in a single JSON file for efficient design system management.

- Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- Tags: architecture
- Published: 2026-08-16

---

**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`](https://github.com/HKUDS/CLI-Anything/blob/main/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:

```javascript
// 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

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

```

### After Builder Resolution

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

```

- `$primary` → `tokens.colors.primary`
- `$large` → `tokens.radius.large`
- `$md` → [`tokens.spacing.md`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/sketch/agent-harness/tokens/default.json) | Master token definitions—the single source of truth for all visual values |
| [`sketch/agent-harness/src/builder.js`](https://github.com/HKUDS/CLI-Anything/blob/main/sketch/agent-harness/src/builder.js) | Runtime token resolution engine; substitutes placeholders with concrete values |
| [`sketch/agent-harness/README.md`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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.