@mildastudio/milda 0.1.1 → 0.2.0

package/README.md

@@ -3,8 +3,8 @@
 The **Milda language** - a platform-neutral design language for describing design
 systems and their components, and the canonical AST that tools exchange.
 
-Milda separates *what a component is* (its contract, anatomy, behavior, and
-styling intent) from *how any one platform realizes it*. A description written
+Milda separates _what a component is_ (its contract, anatomy, behavior, and
+styling intent) from _how any one platform realizes it_. A description written
 once can be generated into React, CSS, Figma variables, and - by design - other
 targets, without the description itself leaking platform assumptions.
 
@@ -12,6 +12,9 @@ targets, without the description itself leaking platform assumptions.
 > package from the Milda monorepo, which stays the single source of truth. See
 > [milda.dev](https://milda.dev) for the product and the full DSL documentation.
 
+Try the language in the browser, with live preview of the tokens and components a file
+describes, at [play.milda.dev](https://play.milda.dev).
+
 ## Install
 
 ```bash
@@ -19,7 +22,7 @@ npm install @mildastudio/milda
 ```
 
 ```ts
-import { preludeV0, validate, resolveToken } from "@mildastudio/milda";
+import { preludeV0, validate, resolveToken } from '@mildastudio/milda'
 ```
 
 ## What's in here
@@ -37,10 +40,12 @@ import { preludeV0, validate, resolveToken } from "@mildastudio/milda";
 - **Facets, layout, states, capabilities** (`types/facets.ts`) - the
   platform-neutral styling and layout vocabulary.
 - **Prelude** (`prelude/preludeV0.ts`) - the standard library expressed as
-  data: behavior *atoms*, *archetypes*, facets, states, and capabilities.
-- **Engine** (`engine/*`) - pure, side-effect-free semantics over the AST:
-  `resolveToken`, `resolveFacets`/`resolveLayout`, `validate`, and `conformance`
-  (which reports where a description has holes for a given target).
+  data: behavior _atoms_, _archetypes_, facets, states, and capabilities.
+- **Parser and printer** (`dsl/*`) - the `.milda` reader (`parseMildaDocument`), the closed
+  vocabularies every tool imports (`dsl/vocabulary.ts`), and the surface version.
+- **Engine** (`engine/*`) - pure, side-effect-free semantics over the AST: `resolveToken`,
+  `validate`, and `conformance` (which reports where a description has holes for a given
+  target).
 
 ## Design invariants
 
@@ -62,8 +67,10 @@ repo (`@mildastudio/core`, `@mildastudio/contract`, `@mildastudio/generate`,
 
 ## Status
 
-`0.x` - the language and AST are still evolving; treat the shape as unstable
-until `1.0`.
+`0.x` - the language and AST are still evolving; treat the shape as unstable until `1.0`. The
+surface syntax is versioned separately (`milda 0.7` in a file's header) and every change to it is
+recorded in [`spec/FORMAT.md`](spec/FORMAT.md) §6. The documentation, including a tour and a
+keyword-by-keyword reference held to this parser by tests, is at [milda.dev](https://milda.dev).
 
 ## License