diff --git a/text/shaper.go b/text/shaper.go
index 531e49a1..ecd89878 100644
--- a/text/shaper.go
+++ b/text/shaper.go
@@ -199,7 +199,15 @@ func (f Flags) String() string {
 
 type GlyphID uint64
 
-// Shaper converts strings of text into glyphs that can be displayed.
+// Shaper converts strings of text into glyphs that can be displayed. The same
+// Shaper should not be used in different goroutines.
+//
+// The Shaper controls text layout and has a cache, implemented as a map, and
+// so laying out text in two different goroutines can easily result in
+// concurrent access to said map, resulting in a panic.
+//
+// Practically speaking, this means you should use different Shapers for
+// different top-level windows.
 type Shaper struct {
 	config struct {
 		disableSystemFonts bool
diff --git a/widget/material/theme.go b/widget/material/theme.go
index 8f6c070f..3da7f4e7 100644
--- a/widget/material/theme.go
+++ b/widget/material/theme.go
@@ -32,6 +32,9 @@ type Palette struct {
 	ContrastFg color.NRGBA
 }
 
+// Theme holds the general theme of an app or window. Different top-level
+// windows should have different instances of Theme (with different Shapers;
+// see the godoc for [text.Shaper]), though their other fields can be equal.
 type Theme struct {
 	Shaper *text.Shaper
 	Palette