# Design principles

> The rules a Masque document can rely on, and why the language keeps them.

These are the rules the language keeps for anyone writing a document. Each one is something you can count on without reading the runtime.

## 1. Host state flows in, events flow out

A document reads your app's state but cannot write it. When something should change, the document sends an `event`, and your app changes in response, in Rust. The result shows up on the next render rather than as a return value, so there is one place where your data changes, and it is yours.

## 2. The UI is described, never instructed

Every render runs the document from the top and produces a fresh description of the whole UI. There is no handle to a widget and no way to show, hide, move or restyle one after the fact. To change what is on screen, you change state, and the next description differs.

Events are not an exception. An event is a message to your app about its data, not an instruction to the screen. An event handler can change a `state` cell or send an event, and that is all it can do. What the screen does next follows from the next description.

## 3. Motion follows from change

You never start or stop an animation. A widget declares which properties `transition`, what it looks like when it arrives (`initial`) and when it leaves (`exit`). When a value changes, the widget springs toward the new one from wherever it is, keeping its velocity, even partway through an earlier change. Appearing and disappearing from the description become entry and exit.

## 4. Identity comes from where something sits in the source

A `state` cell belongs to the place that declares it, so calling a component from three places gives three independent cells, and a `state` inside an `if` is fine. A widget keeps its identity by `key`, or by position among its siblings when it has none. This is what lets the UI be described afresh every render while hover, focus, scroll and springs in flight carry on.

## 5. Structure is built from the language's own constructs

A component is a function that returns a widget. A widget is a value. A condition is an `if`, a `match` or a spread, and a list is a `for`. There is no template syntax beside the language, so anything you can compute, you can render.