1 files changed, 19 insertions, 0 deletions
diff --git a/docs/design/adt.md b/docs/design/adt.md
new file mode 100644
index 0000000..2011337
--- /dev/null
+++ b/docs/design/adt.md
@@ -0,0 +1,19 @@
+# tagged enums
+
+tagged enums let one pointer refer to a value with one of several payload shapes. a member with fields is declared using a block of field declarations; a member without fields has no block:
+
+```zc
+enum shape { circle { int r; }, rect { int w; int h; }, dot };
+int area(shape* s) {
+    switch (s) {
+    case circle(r): return r * r * 3;
+    case rect(w, h): return w * h;
+    case dot: return 0;
+    }
+    return -1;
+}
+```
+
+each constructor allocates an owned enum object and returns a pointer. word zero stores the tag; payload fields follow it. the object is sized for the largest member, and unused payload words are zeroed. a `case member(names)` arm tests the tag and binds that member's fields as locals scoped to the arm. a member omitted from a switch without `default` produces a warning, in typed and untyped code.
+
+see [the tagged enum example](../../examples/learn/16-tagged-enums.zc). the syntax and behavior described here are implemented by the parser, typechecker, code generator and language server.