The language

The Milda language is what a .milda file can say: a formal, platform-neutral description of a design system, precise enough for a generator to turn into code and plain enough for a person to read in a pull request. This section explains it part by part; the reference lists it word by word.

#Two front-ends, one document

The Studio and the text are equals. Both edit the Milda document; neither is a view over the other. People author in the Studio. The text is what an AI agent reads and writes, what an import produces, what a release ships beside the code, what a pull request diffs, and what you type in the Playground to learn. Reading a file and writing it back gives the same document, and that round trip is a tested fixed point.

Built

One language server behind the VS Code and Open VSX extension, the JetBrains plugin, any LSP editor, and the Playground.

#The shape of a file

A file is a sequence of declarations, in any order, and a system reads top to bottom in the order the tour meets it:

milda

milda 0.10
prelude 0.0.2

meta { name "Acme" }                       # the system's own name and version

context-group ColorScheme { Light Dark }   # the dimensions tokens answer along
group Actions "Things a person presses."   # the library's categories

foundations { … }                          # typed tokens, in layers
global-prop size : enum(sm, md, lg) = md   # props the whole system shares
type Option = object { … }                 # shared types

component Button { … }                     # contract + anatomy, from an archetype
rule one-primary-action error { … }        # how the system is meant to be used

example "Primary" for Button { … }         # demo scenes
assets { … }  icons { … }  docs { … }      # the library around the components

Values & literals - what goes on the right of a token: colour functions, unit lengths, times, records, computed values.
Tokens & context - layers, context groups, aliasing, and props that are a dimension.
Components, parts & the contract - props, events, constraints; parts, kinds, slots, instances, foreign content.
Facets - the paint vocabulary, states and conditions.
Layout - propose/choose: stacks, sizing, position.
Behaviours - the atoms, the states they emit, and what the file can say about them.
Archetypes - every blueprint, one page each.
Usage rules & constraints - how the system is meant to be composed.
The library - groups, examples, assets, icons, docs.
The .milda file - what it carries, what it leaves out, how references resolve, how it is versioned.

#Three readings of one file

Every page in this section keeps three layers apart, because confusing them is the easiest way to be wrong about Milda:

The spec says what the language means: the prelude (archetypes, atoms, facets, states, capabilities) and the grammar. Public, versioned, in the open-source language package.
The surface is what a file can say today, at surface version 0.10. Every snippet on these pages is held to the parser by a test.
A realization is what one target does with it. Where the React target does something notable, or does not yet do something the surface says, the page says so with a status.

No platform in the model

The language contains no CSS, no HTML tags, no framework APIs. Value divergence between platforms collapses into token aliasing; structure and behaviour divergence is a declared realization of the same archetype. Both are explained on their pages, and the ten rules are the short version.

#Where it lives

The language package, @mildastudio/milda, is open source and carries the parser, the prelude and the spec; the language server and the editor extensions reuse the same parser, so completion and diagnostics cannot drift from the language. See Packages and Editor support.