diff --git a/widget/doc.go b/widget/doc.go
index 4367ddb9..52d486b0 100644
--- a/widget/doc.go
+++ b/widget/doc.go
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
-// Package widget implements common user interface controls. Widgets
-// contain peristent state and process user events. Theme packages
-// such as `widget/material` implements drawing of widgets.
+// Package widget implements state tracking and event handling of
+// common user interface controls. To draw widgets, use a theme
+// packages such as package gioui.org/widget/material.
 package widget
diff --git a/widget/material/doc.go b/widget/material/doc.go
new file mode 100644
index 00000000..eafca5b7
--- /dev/null
+++ b/widget/material/doc.go
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+// Package material implements the Material design.
+//
+// To maximize reusability and visual flexibility, user interface controls are
+// split into two parts: the stateful widget and the stateless drawing of it.
+//
+// For example, widget.Button encapsulates the state and event
+// handling of all buttons, while the Theme can draw a single Button
+// in various styles.
+//
+// This snippet defines a button that prints a message when clicked:
+//
+// 	  var gtx *layout.Context
+//    button := new(widget.Button)
+//
+//    for button.Clicked(gtx) {
+//        fmt.Println("Clicked!")
+// 	  }
+//
+// Use a Theme to draw the button:
+//
+//     theme := material.NewTheme(...)
+//
+//     th.Button("Click me!").Layout(gtx, button)
+//
+// Quite often, a program needs to customize the theme provided defaults. Several
+// options are available, depending on the nature of the change:
+//
+// - Mandatory parameters. Some parameters are not part of the widget state but
+// have no obvious default. In the program above, the button text is a
+// parameter to the Theme.Button method.
+//
+// - Theme-global parameters. For changing the look of all widgets drawn with a
+// particular theme, adjust the `Theme` fields:
+//
+//     theme.Color.Primary = color.RGBA{...}
+//
+// - Widget-local parameters. For changing the look of a particular widget,
+// adjust the widget specific theme object:
+//
+//     btn := th.Button("Click me!")
+//     btn.Font.Style = text.Italic
+//     btn.Layout(gtx)
+//
+// - Widget variants. A widget can have several distinct representations even
+// though the underlying state is the same. A widget.Button can be drawn as a
+// round icon button:
+//
+//     icon := material.NewIcon(...)
+//
+//     th.IconButton(icon).Layout(gtx, button)
+//
+// - Specialized widgets. Theme both define a generic Label method
+// that takes a text size, and specialized methods for standard text
+// sizes such as Theme.H1 and Theme.Body2.
+package material
diff --git a/widget/material/material.go b/widget/material/material.go
index d5b70dba..2a4d00e7 100644
--- a/widget/material/material.go
+++ b/widget/material/material.go
@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
-// Package material implements the Material design.
 package material
 
 import (