Platform Integration

Human’s design tokens compile from JSON source files to five platform outputs, ensuring visual consistency across web, iOS, Android, CLI, and documentation.

Build Pipeline

design-tokens/*.tokens.json
        │
        ▼
  design-tokens/build.ts
        │
        ├── ui/src/styles/_tokens.css          (Web UI)
        ├── website/src/styles/_tokens.css     (Docs site)
        ├── .../DesignTokens.swift              (iOS/macOS)
        ├── .../DesignTokens.kt                 (Android)
        ├── include/human/design_tokens.h     (CLI)
        └── docs/design-tokens-reference.json   (Docs reference)

CSS (Web)

Tokens are emitted as CSS custom properties on :root:

:root {
  --hu-accent: #7ab648;
  --hu-bg: #060b12;
  --hu-text: #d8e4f0;
  --hu-space-md: 1rem;
  --hu-radius-lg: 12px;
  --hu-duration-normal: 250ms;
  --hu-ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
  --hu-glass-standard-blur: 16px;
}

Usage:

.my-component {
  background: var(--hu-bg-surface);
  padding: var(--hu-space-lg);
  border-radius: var(--hu-radius-md);
  transition: transform var(--hu-duration-fast) var(--hu-ease-spring);
}

Swift (iOS/macOS)

Tokens are emitted as static properties on HUTokens:

struct HUTokens {
    static let accent = Color(hex: 0x7AB648)
    static let bgSurface = Color(hex: 0x0F2236)
    static let spaceMd: CGFloat = 16
    static let radiusLg: CGFloat = 12
    static let textBase: CGFloat = 16
    static let weightSemibold: Font.Weight = .semibold
}

Usage:

struct MyView: View {
    var body: some View {
        Text("Hello")
            .foregroundColor(HUTokens.accent)
            .padding(HUTokens.spaceLg)
            .cornerRadius(HUTokens.radiusMd)
    }
}

Kotlin (Android)

Tokens are emitted as properties on the HUTokens object:

object HUTokens {
    val accent = Color(0xFF7AB648.toInt())
    val bgSurface = Color(0xFF0F2236.toInt())
    val spaceMd = 16.dp
    val radiusLg = 12.dp
    val textBase = 16.sp
}

Usage:

@Composable
fun MyComponent() {
    Text(
        text = "Hello",
        color = HUTokens.accent,
        fontSize = HUTokens.textBase,
        modifier = Modifier
            .background(HUTokens.bgSurface, RoundedCornerShape(HUTokens.radiusMd))
            .padding(HUTokens.spaceLg)
    )
}

C (CLI/Terminal)

Tokens are emitted as preprocessor macros with four variants per color:

/* 256-color foreground (widest compat) */
#define HU_COLOR_ACCENT       "\033[38;5;43m"

/* Truecolor foreground (24-bit, best quality) */
#define HU_COLOR_ACCENT_TC    "\033[38;2;20;184;166m"

/* 256-color background */
#define HU_COLOR_BG_ACCENT    "\033[48;5;43m"

/* Truecolor background */
#define HU_COLOR_BG_ACCENT_TC "\033[48;2;20;184;166m"

Runtime capability detection chooses the right variant:

#include <human/terminal.h>

void print_status(const char *msg) {
    hu_color_level_t level = hu_terminal_color_level();
    if (level >= HU_COLOR_LEVEL_TRUECOLOR) {
        printf(HU_COLOR_SUCCESS_TC "%s" HU_COLOR_RESET "\n", msg);
    } else {
        printf(HU_COLOR_SUCCESS "%s" HU_COLOR_RESET "\n", msg);
    }
}

Terminal Theme Detection

hu_theme_t theme = hu_terminal_theme();
if (theme == HU_THEME_LIGHT) {
    printf(HU_COLOR_LIGHT_ACCENT "light mode" HU_COLOR_RESET);
} else {
    printf(HU_COLOR_ACCENT "dark mode" HU_COLOR_RESET);
}

Token Naming Convention

JSON Source	CSS	Swift	Kotlin	C
dark.accent	--hu-accent	HUTokens.accent	HUTokens.accent	HU_COLOR_ACCENT
space.lg	--hu-space-lg	HUTokens.spaceLg	HUTokens.spaceLg	N/A
text.xl	--hu-text-xl	HUTokens.textXl	HUTokens.textXl	N/A
glass.standard.blur	--hu-glass-standard-blur	HUTokens.glassStandardBlur	HUTokens.glassStandardBlur	N/A

Adding New Tokens

1. Add the token to the appropriate .tokens.json file
2. Run npx tsx design-tokens/build.ts
3. All platform outputs regenerate automatically
4. Run design-tokens/check-drift.sh to verify consistency
5. Commit all generated files together

Drift Detection

The pre-commit hook runs check-drift.sh which verifies:

• UI _tokens.css matches generated output
• Website _tokens.css matches generated output
• C header matches generated output
• clang-format consistency for the C header