Example: Radius + Shape Tokens

This example demonstrates deriving button border-radius tokens from font sizes using a proportional ratio.

The Definitions

math.module.scssdef

---
module: math
title: Math Utilities
summary: General-purpose snapping and rounding functions for token derivation.
category: foundations
since: 0.1.0
tags: [math, rounding, tokens]
---

/// @name snap
/// @summary Snap a value to a step.
/// @param $value <number|dimension|ref> The value to snap.
/// @param $step <number|dimension|ref> The snap interval.
/// @param $mode <nearest|floor|ceil> The rounding mode.
/// @returns <number|dimension>
/// @example snap(15.6px, 1px, nearest) → 16px
/// @example snap(16.86px, 1px, ceil) → 17px
@function snap($value, $step: 1px, $mode: nearest) {
  @return round($value, $step, $mode);
}

radius.module.scssdef

---
module: radius
title: Radius Utilities
summary: Proportional radius derivation functions for component shape tokens.
category: foundations
since: 0.1.0
tags: [radius, shape, tokens]
see: [math]
---

/// @name radius
/// @summary Compute a proportional radius from a size and ratio.
/// @param $size <dimension|ref> Base size (typically a font-size typescale reference).
/// @param $ratio <number|ref> Unitless ratio in the range (0, 1].
/// @param $step <dimension|ref> Snap interval.
/// @param $mode <nearest|floor|ceil> Rounding mode.
/// @returns <dimension>
/// @constraints $ratio > 0
/// @constraints $ratio <= 1
/// @example radius(16px, 0.6, 1px) → 10px
@function radius($size, $ratio, $step: 1px, $mode: nearest) {
  @return snap($size * $ratio, $step, $mode);
}

How It Works

1. radius() takes a font size and multiplies by a ratio (e.g., 0.6)
2. The result is snapped to a 1px grid via snap()
3. snap() delegates to the built-in round() function

Token Output

With shape.ratio.button = 0.6 and typescale base 16px / ratio 1.067:

Size	Font px	Shape (radius)	Slot-min-size
xs	14.05	8px	17px
sm	16.00	10px	20px
md	19.44	12px	24px
lg	23.61	14px	29px
xl	28.68	17px	35px
2xl	32.65	20px	40px
3xl	39.67	24px	48px

DTCG Extension

{
  "shape": {
    "button": {
      "md": {
        "$value": "12px",
        "$type": "dimension",
        "$extensions": {
          "org.dtcg-formulas": {
            "formula": "radius({typography.scale.15}, {shape.ratio.button})",
            "definition": "tokens/functions/radius.module.scssdef#radius"
          }
        }
      }
    }
  }
}