From b108a7f0e9c9ed5bc16992328bd260ea274752c8 Mon Sep 17 00:00:00 2001
From: Jess Kuras <jesskuras@google.com>
Date: Mon, 12 Oct 2026 16:29:09 +0000
Subject: [PATCH 1/2] Remove unsupported directory syntax from pubspec shaders
 section

---
 sites/docs/src/content/tools/pubspec.md | 41 +++++++------------------
 1 file changed, 11 insertions(+), 30 deletions(-)

diff --git a/sites/docs/src/content/tools/pubspec.md b/sites/docs/src/content/tools/pubspec.md
index be8489349a..dad7e674e3 100644
--- a/sites/docs/src/content/tools/pubspec.md
+++ b/sites/docs/src/content/tools/pubspec.md
@@ -621,33 +621,25 @@ To learn more about plugins, see
 
 ### shaders field {: #shaders }
 
-GLSL Shaders with the `.frag` extension must be declared in
-the shaders section of your project's `pubspec.yaml` file.
+GLSL shaders with the `.frag` extension must be declared in
+the `shaders` section of your project's `pubspec.yaml` file.
 The Flutter command-line tool compiles the shader to its
 appropriate backend format and generates its necessary
 runtime metadata. The compiled shader is then included in
 the application just like an asset.
 
+Each shader file must be listed individually
+(directory paths aren't supported).
 The `shaders` field has the following structure:
 
 ```yaml title="pubspec.yaml"
 flutter:
   shaders:
-    -  { path_to_file | path_to_directory }
+    - [path_to_file]
     [...]
 ```
 
-```yaml
-# path_to_file structure
-- assets/shaders/file
-```
-
-```yaml
-# path_to_directory structure
-- assets/shaders/
-```
-
-Add specific shaders:
+For example, to add specific shaders to your project:
 
 ```yaml title="pubspec.yaml"
 flutter:
@@ -656,24 +648,13 @@ flutter:
     - assets/shaders/shader_b.frag
 ```
 
-Add a directory of shaders:
+Like other assets, shaders also support `flavors`, `platforms`,
+and `transformers`.
 
-```yaml title="pubspec.yaml"
-flutter:
-  shaders:
-    - assets/shaders/
-```
-
-Alternatively, you can add your shader directory to the
-`assets` field:
-
-```yaml title="pubspec.yaml"
-flutter:
-  assets:
-    - assets/shaders/my_shader.frag
-```
+To learn more about using shaders in Flutter, check out
+[Writing and using fragment shaders][].
 
-Like other assets, shaders also support `flavors` and `transformers`.
+[Writing and using fragment shaders]: /ui/design/graphics/fragment-shaders
 
 ### uses-material-design field {: #uses-material-design }
 

From ece52d3b295765ce59be71e8bb1f90468651fb8c Mon Sep 17 00:00:00 2001
From: Jess Kuras <jesskuras@google.com>
Date: Mon, 12 Oct 2026 18:07:11 +0000
Subject: [PATCH 2/2] Tighten shaders wording and note assets conflict error

---
 sites/docs/src/content/tools/pubspec.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/sites/docs/src/content/tools/pubspec.md b/sites/docs/src/content/tools/pubspec.md
index dad7e674e3..121b35397a 100644
--- a/sites/docs/src/content/tools/pubspec.md
+++ b/sites/docs/src/content/tools/pubspec.md
@@ -628,9 +628,9 @@ appropriate backend format and generates its necessary
 runtime metadata. The compiled shader is then included in
 the application just like an asset.
 
-Each shader file must be listed individually
-(directory paths aren't supported).
-The `shaders` field has the following structure:
+The `shaders` field accepts a list of individual file paths;
+directory paths aren't supported.
+The field has the following structure:
 
 ```yaml title="pubspec.yaml"
 flutter:
@@ -648,6 +648,11 @@ flutter:
     - assets/shaders/shader_b.frag
 ```
 
+Don't list shader files under the `assets` field,
+either directly or through a directory that contains them.
+The Flutter tool reports an error if a shader is declared
+in both places.
+
 Like other assets, shaders also support `flavors`, `platforms`,
 and `transformers`.