Update Theme contribution guidance

docs/getting_started/viewer.md

@@ -714,7 +714,11 @@ viewer.theme = 'dark'
 
 You can also change the theme using the "Toggle theme" keyboard shortcut, by default {kbd}`Command/Control+Shift+T`. Note that changing the theme using this shortcut will only change the *current* viewer theme. If you wish to make the change permanent for all viewers, make sure to also change your settings in the **Appearance** tab of the [**Preferences** dialog](napari-preferences).
 
-Adding your own custom theme isn't too hard but it requires creating your own color `palette` and rebuilding the icons. It's also possible for [plugins to contribute a theme](contributions-themes). If people want more themes, we're happy to add them or you can look at our [contributing guidelines](napari-contributing) for more information about building the icons and add one yourself!
+Custom themes can be prototyped directly in Python or distributed declaratively
+from a plugin.
+[Plugins can contribute a theme](contributions-themes) by declaring a light or
+dark base theme and overriding only the colors they need. See
+[Creating and testing themes](napari-themes) for both workflows.
 
 +++
 

docs/howtos/themes.md

@@ -2,43 +2,42 @@
 
 # Creating and testing themes
 
-A theme is a set of colors used throughout napari. See, for example, the
-builtin themes in `napari/utils/theme.py`. To make a new theme, create a new
-`dict` with the same keys as one of the existing themes, and
-replace the values with your new colors. For example
+A napari theme is a named collection of colors and style values used across the
+viewer canvas, widgets, icons, and console. If you want to programmatically
+prototype a theme, check out the {ref}`shpx_glr_gallery_new_theme.py` example.
+However, the `npe2` theme contribution allows declaratively 
+defining themes and enables easy distribution to others.
 
-```python
-from napari.utils.theme import get_theme, register_theme
+If you want other people to install and reuse your theme, prefer the plugin
+workflow. The programmatic workflow is still useful for local experiments and
+rapid iteration.
 
+(preview-themes)=
+## Preview themes in a full napari UI
 
-blue_theme = get_theme('dark')
-blue_theme.update(
-    background='rgb(28, 31, 48)',
-    foreground='rgb(45, 52, 71)',
-    primary='rgb(80, 88, 108)',
-    current='rgb(184, 112, 0)',
-)
+The most complete theme preview tool lives in the example gallery as
+{ref}`sphx_glr_gallery_theme_sample.py`. It opens napari with a dock widget
+that shows the theme color roles, common widget states, and a theme selector
+that includes plugin-contributed themes after plugins are initialized. 
 
-register_theme('blue', blue_theme)
-```
+You can download the python script from the example page and drag'n'drop it onto napari to run it.
 
-To test out the theme, use the
-`qt_theme_sample.py` file from the command line as follows:
+If you are working from a local checkout of `napari/napari`, you can run it
+directly:
 
 ```sh
-python -m napari._qt.widgets.qt_theme_sample
+python examples/theme_sample.py
 ```
 
-*note*: you may specify a theme with one additional argument on the command line:
-
-```sh
-python -m napari._qt.widgets.qt_theme_sample dark
-```
+## Ship a theme in a plugin
 
-(providing no arguments will show all themes in `theme.py`)
+The supported way to distribute a theme is via a [plugin](plugins-index)
+[theme contribution](contributions-themes). A theme contribution uses the plugin manifest
+(`napari.yaml`) to declaratively define properties of a theme.
 
-## Sharing your theme via a plugin
+After the plugin is installed, the contributed theme becomes available in
+napari's appearance settings and can also be selected with `viewer.theme`.
+For richer visual testing, use the [theme preview sample](preview-themes).
 
-You can also share your theme with the community via a [plugin](plugins-index)
-by adding a [theme contribution](contributions-themes). See the
-[plugin](plugins-index) documentation for details on creating a plugin.
+If you are contributing a builtin theme to napari itself rather than shipping a
+plugin, see the core theme definitions in `napari/utils/theme.py`.

docs/plugins/advanced_topics/npe2_migration_guide.md

@@ -413,7 +413,9 @@ def get_new_theme() -> Dict[str, Dict[str, Union[str, Tuple, List]]:
     return themes
 ```
 
-becomes this theme contribution in the plugin manifest:
+becomes this theme contribution in the plugin manifest. Note that `type`
+selects the base light/dark theme, omitted color keys inherit from that base,
+and `syntax_style` stays at the top level rather than under `colors`:
 
 ```yaml
 name: my-plugin
@@ -422,6 +424,7 @@ contributions:
     - label: Super dark
       id: super_dark
       type: dark
+      syntax_style: "native"
       colors:
         background: "rgb(12, 12, 12)"
         foreground: "rgb(65, 72, 81)"
@@ -432,7 +435,6 @@ contributions:
         icon: "rgb(209, 210, 212)"
         warning: "rgb(153, 18, 31)"
         current: "rgb(0, 122, 204)"
-        syntax_style: "native"
         console: "rgb(0, 0, 0)"
         canvas: "black"
 ```