diff --git a/ci/release/template/man/d2.1 b/ci/release/template/man/d2.1
index e78ea6c80..ed1b37017 100644
--- a/ci/release/template/man/d2.1
+++ b/ci/release/template/man/d2.1
@@ -67,9 +67,12 @@ Port listening address when used with
 Set the diagram theme ID
 .Ns .
 .It Fl -dark-theme Ar -1
-Set the diagram dark theme ID. If unset, the
-.Ar theme
-is used for both light and dark modes
+The theme to use when the viewer's browser is in dark mode. When left unset
+.Fl -theme
+is used for both light and dark mode. Be aware that explicit styles set in D2 code will
+still be applied and this may produce unexpected results. We plan on resolving this by
+making style maps in D2 light/dark mode specific. See
+.Lk https://github.com/terrastruct/d2/issues/831
 .Ns .
 .It Fl s , -sketch Ar false
 Renders the diagram to look like it was sketched by hand
diff --git a/main.go b/main.go
index 750bbcdf7..b23ed4d43 100644
--- a/main.go
+++ b/main.go
@@ -69,7 +69,7 @@ func run(ctx context.Context, ms *xmain.State) (err error) {
 	if err != nil {
 		return err
 	}
-	darkThemeFlag, err := ms.Opts.Int64("D2_DARK_THEME", "dark-theme", "", -1, "the diagram dark theme ID. When left unset only the theme will be applied")
+	darkThemeFlag, err := ms.Opts.Int64("D2_DARK_THEME", "dark-theme", "", -1, "The theme to use when the viewer's browser is in dark mode. When left unset -theme is used for both light and dark mode. Be aware that explicit styles set in D2 code will still be applied and this may produce unexpected results. We plan on resolving this by making style maps in D2 light/dark mode specific. See https://github.com/terrastruct/d2/issues/831.")
 	if err != nil {
 		return err
 	}