Skip to content
Designer Decisions

Decisions as Data

Creating decision records

At a minimum, a decision record requires

  • model - defines both the decision type and which model should be used to produce it;
  • name - to identify the decision;
  • params - an object following the decision model schema.

The following example defines two decisions:

[
    {
        "model": "color-value/explicit",
        "name": "Primary Background",
        "params": {
            "value": "#090E0B"
        }
    },
    {
        "model": "color-set/explicit",
        "name": "Brand Colors",
        "params": {
            "values": ["#FF0000", "#00FF00", "#0000FF"]
        }
    }
]

You are also free to create sub-directories and name the files as you wish.

When declaring decisions in JSON files you are encouraged to organize them in small files. Grouping decisions by type or scope is a good starting point.

  • Directoryspace/
    • …
  • Directorytypography/
    • …
  • Directorycolors/
    • base.json
    • palettes.json
    • ratios.json
  • Directorycontexts/
    • …

Referencing decisions

You can reuse decision values and avoid repetition by referencing them in other decisions.

The following example defines an explicit Space Value decision called “Space Unit” and a Space Scale anchored on the value of the first one.

[
    {
        "type": "space-value/explicit",
        "name": "Space Unit",
        "params": {
            "value": "8"
        }
    },
    {
        "type": "space-scale/anchored",
        "name": "Sizing Scale",
        "params": {
            "anchor": { "$name": "Space Unit" },
            "after": {
                "steps": 5,
                "modifier": { "mode": "gemetric", "by": 1.5 }
            }
        }
    }
]

You can also reference items of a decision set set or scale by adding the index to the reference.

In the following example we are creating a Space Value decision based on the second element of the “Sizing Scale” declared before.

[
    {
        "type": "space-value/explicit",
        "name": "Default Size",
        "params": {
            "value": { "$name": "Sizing Scale", "index": 3 }
        }
    }
]

Next steps

Proceed to the next guide for step by step instructions on how to load all decision files at once, as well as how to validate the input data and inspect validation errors.

Loading and Validating

See also