The document

Behind every surface of Milda there is one value: the Milda document, a complete, platform-neutral description of a design system. The Studio edits it, the text spells it, every generator reads it, and nothing else is ever the source of anything.

#What it is

Think of it as the abstract syntax tree of a design system. It holds the foundations with their layers and context groups, every component with its contract and anatomy, the library around them, the usage rules, and the documentation. It has a canonical shape as plain data, so machines exchange it losslessly, and a text form, the .milda file, so people and agents read and write it.

the Milda document
├── foundations     context groups · layers of typed tokens · global props · rules · icons
├── components      contract (props, events, constraints) · anatomy (parts) · archetype · composition
├── library         groups · examples · assets · docs
└── (outside it)    the project's targets, release history, connections, credentials

The last line matters: what a project does with the system is not part of the system. Targets, publishing destinations and history are kept beside the document, which is what lets one document feed any generator and move between workspaces unchanged.

#Why it is neutral

The document contains no CSS, no HTML element name, no framework event, no Figma node type. A part says what it is (a container, an input, an icon) and what it does (raises this event, holds this value, is named by that part), and a generator decides what that becomes on its target when it realizes the document. Divergence between platforms is handled by two mechanisms, split by what diverges:

• Values diverge through tokens. A colour, a spacing, an elevation that differs per platform or per scheme is a token that aliases by a context group. No per-platform style code exists anywhere; see Tokens & context.
• Structure and behaviour diverge through realization. A select that is a popover listbox on the web and a wheel on iOS is the same component with the same contract, realized twice. The archetype declares it; see Behaviours.

#What one source of truth buys

• No drift. The canvas, the generated code, the Figma file and the docs site derive from the same value, and the preview and the React generator are tested against each other over every archetype.
• Computable versions. A release diffs the contract against the previous one and derives the version. A breaking change is a fact about the document, not a judgement.
• Interchange. The text form resolves every reference by name, so a reader that is not ours can read it, and an agent can write it.

#Three readings of the same thing

The pages in this section distinguish three layers, and name which one they are talking about:

• The spec says what the language means: the prelude of archetypes and behaviours, and the grammar. It is public, versioned, and in packages/milda/spec of the open-source language package.
• The surface is what a .milda file can say today. Every snippet on these pages is held to the parser by a test.
• A realization is what one target makes of it. Where the React target does something notable, or cannot yet do something the surface says, the page says so.

See it built in the tour14. One system, many surfaces