# Milpa Design System · `@milpa/design`
> **La cara visual del framework [Milpa](https://milpa.lat).** Tokens dark-first, motion, y
> contratos de componente introspectables. *Siembra módulos, cosecha aplicaciones.*
Repo hermano del framework **Milpa** (core PHP + CLI `coa`). Este paquete se desarrolla y
**versiona por separado** y el framework lo **consume por versión** (`@milpa/design@x.y.z`) — así
ambos avanzan en paralelo sin pisarse. La costura entre los dos es un **contrato**: los tokens
(DTCG) + los `*.contract.json` de cada componente. *(Milpa aplicado a sí mismo.)*
- **Framework / plan maestro:** `VISION.md` (repo `teamx` / futuro `github.com/getmilpa`).
- **La constitución de este DS:** [`DESIGN.md`](./DESIGN.md) — léela primero. Describe el *alma* y
las reglas, no solo los valores.
## Estado
**v0.9 — el almácigo: primitivas didácticas.** Cuatro piezas nuevas en *el elote* para material
educativo de arquitectura, destiladas del battle-test de Milpa Academy: **`mui-plot`** (la
parcela: módulos con contrato visible, estados slot/germinating/sown/wilted), **`mui-pipeline`**
(el tubo de etapas con canica `--_pipeline-progress` y salidas tempranas denied/failed/skipped),
**`mui-gate`** (la compuerta tri-estado — aprobar/rechazar/exonerar — con audit `role="log"`
append-only y `self-denied` por construcción) y **`mui-replay`** (el log reproducible: eventos +
corte con `` nativo + proyección). Cero JS publicado: estados por atributos y el
comportamiento del consumidor documentado en `a11y.behavior` (lógica de referencia testeada en el
repo hermano `academy`). Paleta didáctica desde la semántica existente (olivo=germinando,
oro=sembrado, success=completado, danger=marchito, warning=exonerado). Contratos **68 → 72** ·
**193/193 AA** — audit de cierre: **0 pares nuevos**. Battle-test: `proof/almacigo.html`.
**v0.8 — el rocío: cierra los huecos de theming de marca (bordes, superficies, blur) + glass.**
Grupo `effect` nuevo: `--border-style` (default `solid` — los ~83 bordes del bundle lo usan,
dashed/double/none por token), `--surface-backdrop` (default `none`, expuesto en `.mui-card`/
`.mui-modal`/`.mui-drawer` — un skin glass activa `backdrop-filter` sin CSS propio) y
`--blur-sm/base/lg` (tokenizan los blurs frosted que ya existían en header/topbar/drawer).
Invariante nueva: **`--bg` debe ser opaco** (referencia de composición). `npm run verify:theme`
ahora parsea color con alpha (`#RRGGBBAA`/`rgba`) y compone superficies translúcidas sobre
`--bg` antes de medir contraste AA — el gate valida glassmorphism de verdad, no solo lo deja
pasar. Glass se suma como **3er flavor** del proof de theme-swap (junto a Nopal y Brutalist). Todo
aditivo — cero cambio visual por defecto (solid/none/mismos blurs). Paleta cerrada sin cambios:
`oro` (primario) + `olivo` (secundario / la milpa viva) + `tierra` (neutro); `cielo` = `info`; y
`--syntax-*` (highlighting AA-verificado) y `--viz-*` (charts, colorblind-safe) — semánticos de
las mismas rampas. **193/193 pares WCAG AA** (dark + light, `npm test`) — audit de cierre: **0
pares nuevos** (release sin color). **68 piezas** con contrato en cuatro capas (sin cambio de
conteo): primitivas (*el grano*), componentes admin + commerce (*el frijol*), artefactos de
contenido (*el elote*: code, terminal, chart, prose, api, search, kit de versionado…) y layouts
(*la parcela*: el shell de docs versionadas, hero, pricing, faq, footer, media-grid, lightbox,
`mui-header`…). **Tres headers, tres contextos:** `mui-topbar` (shell admin) / `mui-docs__topbar`
(shell docs) / `mui-header` (sitio público — marketing, con variante overlay); el off-canvas
móvil de `mui-header` y del shell docs es un **`