added-colorby-instruction-to-system-prompts

packages/ai/src/agents/analyst-agent/analyst-agent-prompt.txt

@@ -420,6 +420,28 @@ You operate in a loop to complete tasks:
     - Number cards should always have a metricHeader and metricSubheader.
   - Always use your best judgment when selecting visualization types, and be confident in your decision
   - When building horizontal bar charts, put your desired x-axis as the y and the desired y-axis as the x in chartConfig (e.g. if i want my y-axis to be the product name and my x-axis to be the revenue, in my chartConfig i would do barAndLineAxis: x: [product_name] y: [revenue] and allow the front end to handle the horizontal orientation)
+- **Using "category" vs. "colorBy" Guidelines**
+  - When adding dimensions to a bar or line chart, carefully decide whether to use `category` or `colorBy`.
+  - **Use `category` when you want to create separate series or groups of values.**
+    - Each category value generates its own line, bar group, or stacked section.
+    - Examples:
+      - Line chart with revenue by month split by region → `category: [region]`
+      - Grouped bar chart of sales by product split by channel → `category: [channel]`
+    - Rule of thumb: use `category` when the visualization should **separate and compare multiple data series**.
+  - **Use `colorBy` when you want to keep a single series (no grouping, stacking, etc) but visually differentiate elements by color.**
+    - Bars or lines remain part of one series, but the colors vary by the field.
+    - Examples:
+      - Bar chart of sales by sales rep, with bars colored by region → `colorBy: [region]`
+      - Line chart of monthly revenue, with points/segments colored by product line → `colorBy: [product_line]`
+    - Rule of thumb: use `colorBy` when the visualization should **highlight categories inside a single series** rather than split into multiple groups.
+  - **Guidance by chart type**:
+    - Bar/Line:
+      - `category` → multiple series (grouped/stacked bars, multiple lines).
+      - `colorBy` → single series, colored by attribute.
+  - **Quick heuristic**:
+    - Ask: “Does the user want multiple grouped/stacked series, or just one series with colored differentiation?”
+      - Multiple → `category`
+      - One series, just colored → `colorBy`
   ...
 - Visualization Design Guidelines
   - Always display names instead of IDs when available (e.g., "Product Name" instead of "Product ID")

packages/ai/src/agents/think-and-prep-agent/think-and-prep-agent-investigation-prompt.txt

@@ -765,6 +765,28 @@ If all true → proceed to submit prep for Asset Creation with `submitThoughts`.
         - if you are building a table of customers, the first column should be their name. 
         - If you are building a table comparing regions, have the first column be region.
         - If you are building a column comparing regions but each row is a customer, have the first column be customer name and the second be the region but have it ordered by region so customers of the same region are next to each other.
+- **Using "category" vs. "colorBy" Guidelines**
+  - When adding dimensions to a bar or line chart, carefully decide whether to use `category` or `colorBy`.
+  - **Use `category` when you want to create separate series or groups of values.**
+    - Each category value generates its own line, bar group, or stacked section.
+    - Examples:
+      - Line chart with revenue by month split by region → `category: [region]`
+      - Grouped bar chart of sales by product split by channel → `category: [channel]`
+    - Rule of thumb: use `category` when the visualization should **separate and compare multiple data series**.
+  - **Use `colorBy` when you want to keep a single series (no grouping, stacking, etc) but visually differentiate elements by color.**
+    - Bars or lines remain part of one series, but the colors vary by the field.
+    - Examples:
+      - Bar chart of sales by sales rep, with bars colored by region → `colorBy: [region]`
+      - Line chart of monthly revenue, with points/segments colored by product line → `colorBy: [product_line]`
+    - Rule of thumb: use `colorBy` when the visualization should **highlight categories inside a single series** rather than split into multiple groups.
+  - **Guidance by chart type**:
+    - Bar/Line:
+      - `category` → multiple series (grouped/stacked bars, multiple lines).
+      - `colorBy` → single series, colored by attribute.
+  - **Quick heuristic**:
+    - Ask: “Does the user want multiple grouped/stacked series, or just one series with colored differentiation?”
+      - Multiple → `category`
+      - One series, just colored → `colorBy`
 - Planning and Description Guidelines
     - For grouped/stacked bar charts, specify the grouping/stacking field (e.g., "grouped by `[field_name]`").
     - For bar charts with time units (e.g., days of the week, months, quarters, years) on the x-axis, sort the bars in chronological order rather than in ascending or descending order based on the y-axis measure.

packages/ai/src/agents/think-and-prep-agent/think-and-prep-agent-standard-prompt.txt

@@ -619,6 +619,28 @@ When in doubt, be more thorough rather than less. Reports are the default becaus
         - if you are building a table of customers, the first column should be their name. 
         - If you are building a table comparing regions, have the first column be region.
         - If you are building a column comparing regions but each row is a customer, have the first column be customer name and the second be the region but have it ordered by region so customers of the same region are next to each other.
+- **Using "category" vs. "colorBy" Guidelines**
+  - When adding dimensions to a bar or line chart, carefully decide whether to use `category` or `colorBy`.
+  - **Use `category` when you want to create separate series or groups of values.**
+    - Each category value generates its own line, bar group, or stacked section.
+    - Examples:
+      - Line chart with revenue by month split by region → `category: [region]`
+      - Grouped bar chart of sales by product split by channel → `category: [channel]`
+    - Rule of thumb: use `category` when the visualization should **separate and compare multiple data series**.
+  - **Use `colorBy` when you want to keep a single series (no grouping, stacking, etc) but visually differentiate elements by color.**
+    - Bars or lines remain part of one series, but the colors vary by the field.
+    - Examples:
+      - Bar chart of sales by sales rep, with bars colored by region → `colorBy: [region]`
+      - Line chart of monthly revenue, with points/segments colored by product line → `colorBy: [product_line]`
+    - Rule of thumb: use `colorBy` when the visualization should **highlight categories inside a single series** rather than split into multiple groups.
+  - **Guidance by chart type**:
+    - Bar/Line:
+      - `category` → multiple series (grouped/stacked bars, multiple lines).
+      - `colorBy` → single series, colored by attribute.
+  - **Quick heuristic**:
+    - Ask: “Does the user want multiple grouped/stacked series, or just one series with colored differentiation?”
+      - Multiple → `category`
+      - One series, just colored → `colorBy`
 - Planning and Description Guidelines
     - For grouped/stacked bar charts, specify the grouping/stacking field (e.g., "grouped by `[field_name]`").
     - For bar charts with time units (e.g., days of the week, months, quarters, years) on the x-axis, sort the bars in chronological order rather than in ascending or descending order based on the y-axis measure.