Lesson 1 of 14

A file and a token

The smallest complete system: a header, a name, and three typed values.

#The idea

A design system in Milda is one text file, and the smallest complete one is a few lines: a header that says which language the file speaks, a name, and some values. Everything the tour builds grows from this file, and at every step the file stays complete and valid.

#What this lesson adds

foundations {
  token violet/600 : color = hex(7c3aed)
  token space/sm : spacing = 8px
  token radius/sm : radius = 6px
}

#What to notice

• The header is two versions. milda is the surface version: which statements a reader may meet in this file. prelude is the vocabulary version: the built-in archetypes and behaviours the file was written against. They answer different questions, which is why there are two.
• A token has a name, a type and a value. token violet/600 : color = hex(7c3aed) reads “the token named violet/600 is a colour, and its value is this hex”. The type is a closed word from a short list (color, spacing, radius, font-size, duration…), and it decides what the value means.
• Values know what they are. hex(7c3aed) is a colour function, not a string, because # starts a comment. 8px is a length with a unit; px in Milda is a density-independent unit, not a CSS pixel, and every target converts it. A colour in a spacing slot is an error before anything is generated.
• Names declare with a slash and reference with a dot. You write token space/sm and, later, gap space.sm. The slash groups tokens into a tree the editor shows; the dot is how anything in the file points at anything else.

#What the generator makes of it

The React generator turns foundations into a stylesheet of custom properties, one per token, named by type and path: --ds-color-violet-600, --ds-spacing-space-sm. Nothing references them yet; lesson 3 will.

#Try it

Open the file in the Playground. Change 8px to hex(ffffff) and read the diagnostic: the language knows a colour landed in a spacing slot. Then try #7c3aed as a value and see why colours are functions.

#The file at the end of this lesson

milda 0.10
prelude 0.0.2

meta { name "Acme" }

foundations {
  token violet/600 : color = hex(7c3aed)
  token space/sm : spacing = 8px
  token radius/sm : radius = 6px
}