The library around the components

A design system is more than components. It has an organisation, demo scenes, an asset library, an icon library and documentation, and all of it travels in the .milda file by name. A system exported and imported elsewhere is the same system, docs and all.

#Groups

A top-level group Forms "Collecting input." declares a category; groups nest by path (group Forms/Selection), ancestors implied. A component joins one with group Forms in its body. The prose is what the docs show at the head of the section, and the Studio's component list and the generated DESIGN.md follow the same tree.

#Examples: demo scenes

An example is a composition with no contract of its own. It places components the way a page would, for names the component it demonstrates, and its parts are written exactly like a component's. A scene can carry demo variables of its own and change them with actions, so a scene can open its own dialog without any consumer code.

component Dialog {
  archetype Dialog
  props {
    open : boolean = false
    title : string = "Delete project?"
  }
  part Dialog: container {
    bind state open open
  }
  part trigger: control {
    content "Delete"
  }
  part surface: container {
    content bind title
  }
}

example "Open dialog" for Dialog "A scene that opens its own dialog." {
  demo {
    open : boolean = false
  }
  part stage: container {
    layout { stack column; gap space.md }
  }
  part stage.open: control {
    content "Open the dialog"
    action activate toggle open
  }
  part stage.dialog: instance {
    instance Dialog {
      open = bind open
    }
  }
}

#Assets

Fonts, images, SVGs, videos and animations, in folders. An asset carries its identity and metadata plus where its bytes are, and that is the one choice the format offers: url means beside the file, as a bundle whose text stays diffable; data means inside the file, self-contained. Both are the same grammar, so a reader implements one path.

#Icons

The icon library says which sets a bare glyph name resolves against, in order, and which glyphs the system curated. A part names a glyph by name (content "check"); the name resolves to a curated glyph first, then to the first set. A curated glyph carries its SVG body, so the generated code vendors it and nothing loads from a CDN at runtime; a custom glyph is drawn by an asset of the library.

assets {
  folder brand
  svg "logo" in brand {
    mime "image/svg+xml"
    view-box "0 0 24 24"
    url "assets/logo.svg"
  }
  image "hero" {
    mime "image/png"
    width 1200
    height 600
    data "data:image/png;base64,iVBORw0KGgo="
  }
}

icons {
  set lucide "Lucide" { provider lucide; license ISC; samples [check, x, search, menu] }
  set phosphor "Phosphor" { provider phosphor; license MIT }
  glyph lucide check { label "Done"; svg "<path d='M20 6 9 17l-5-5'/>" }
  custom "logo-mark" { asset logo; label "Acme" }
}

#Docs

The documentation site is part of the system: its header, footer and pages. A page sits in a sidebar section (in "Components") and may nest under another page by title. Its blocks are prose (heading, paragraph, list, quote, callout, code) or transclusions, each naming what it shows:

• component Button - a live preview; component-props, component-events, component-composition - its tables; component-prop Button variant - one prop.
• component-group Actions - every component of a group; example "Open dialog" - a scene.
• tokens color - a table of one type; swatch color - swatches; image asset logo.

Because a transclusion names its target, the docs stay current as the system changes, and a page can be read by an agent as structure rather than as prose. The site is published per organisation at its milda.page address, and the same model is what DESIGN.md and the MCP server's get_docs render.

group Actions "Things a person presses."

component Button {
  archetype Button
  group Actions
  props { label : string = "Save" }
  part Button: container {
  }
  part label: text {
    content bind label
  }
}

docs {
  site { name "Acme"; tagline "One system, every surface"; version "2.1" }
  footer { copyright "Acme, 2026"; link "GitHub" "https://github.com/acme" }
  page "Getting started" in "Guides" {
    heading "Getting started" anchor top
    paragraph "Install the package and import the theme once."
    code "npm install @acme/design-system"
    callout "The theme is where the tokens live. Without it every component renders unstyled."
  }
  page "Actions" in "Components" {
    heading "Actions"
    component-group Actions
  }
  page "Button" in "Components" under "Actions" {
    heading "Button" anchor top
    component Button
    component-props Button
    component-events Button
    tokens color
    swatch color
  }
}

Every statement on this page is in the reference under “The library around the components”.

See it built in the tour12. Docs, examples, assets and icons