diff --git a/README.md b/README.md
index 63ddf670..437f8f26 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,13 @@ void main() {
 }
 ```
 
+## Migrating to package:web
+
+`package:web` is replacing `dart:html` and other web libraries as Dart's 
+long-term web interop solution. To learn how to migrate from `dart:html`
+APIs to `package:web`, see our
+[migration guide](http://dart.dev/go/package-web).
+
 ## Generation conventions
 
 The generator scripts use a number of conventions to consistently handle Web IDL