version: "1.0.1" name: building-data-apps description: | Build modern data apps, dashboards, and interactive reports using either React + Vite or Streamlit. Includes optional Gemini Data Analytics chat integration for an AI powered "chat with your data" experience.

Relevant when any of the following conditions are true:

1. User explicitly requests to build a data dashboard, data application, or visualization UI, and the UI pulls data from a GCP database (defaulting to BigQuery unless otherwise specified).
2. You need to generate a frontend web application to interact with, query, and visualize data from GCP data sources.
3. User wants to build a "chat with your data" experience or integrate the Gemini Data Analytics chat API into a web interface.

Do NOT use when any of the following conditions are true:

1. The request is for building backend-only services.
2. The request is for simple CLI scripts or command-line applications.
3. The web application is not data-centric or does not involve visualizing/querying data from GCP sources.

license: Apache-2.0 metadata: version: v1 publisher: google

Building Data Applications

Architect high-quality data dashboards and interactive reports. You MUST select the appropriate framework before implementation.

Step 0: Framework Selection

You MUST select the framework based on the user's maintenance requirements and data ecosystem.

Choice: Streamlit

• User Profile: Data Scientists / Python users.
• Logic Complexity: High Python dependency (Pandas, NumPy, local data

processing).

• Deployment: Single-file Python script.
• Customization: Standard layout (fast boilerplate).

Choice: React + Vite

• User Profile: Web Developers / Full-stack teams.
• Logic Complexity: High UI and Interactivity requirements (e.g.,

drag-and-drop, interactive maps).

• Deployment: Standalone Frontend + Backend API.
• Customization: Infinite (Custom CSS, specialized JS libraries).

Guidance:

• Check for existing stack first: ALWAYS prefer the framework the user is

already using in their project (e.g., if you see a package.json with React dependencies, use React; if you see existing Streamlit files, use Streamlit).

• Default to React + Vite for production-grade applications that require

complex client-side state, custom branding, or integration into a larger web ecosystem.

• Default to Streamlit if the user specifically mentions "Python

dashboard", needs to iterate on complex local Python data processing, or requires a single-script deployment.

Step 1: Implementation Plan

You MUST propose a plan to the user that specifies the chosen framework and justifies the choice based on the criteria above.

Shared Design Standards

Regardless of framework, you MUST follow the principles in references/shared_design_system.md.

• Visual Style: Minimal chrome, zinc color palette, and card-based

layouts.

• Typography: DM Sans for content, JetBrains Mono for data.

Framework Implementation

If using Streamlit:

1. Read references/streamlit_framework.md for detailed CSS and component

patterns.

1. Follow the "Checklist for New Dashboards" in that file.

If using React + Vite:

1. Read references/react_framework.md for Tailwind and ECharts setup.
2. Follow the detailed component guidelines for KPI cards, Tables, and Panels.

AI Chat Interface (Optional Feature)

> [!IMPORTANT]
>
> If the user does not explicitly request a chat interface, you SHOULD
> proactively ask them: "Would you like to include a Gemini-powered chat
> interface to enable natural language queries against your data?" OR if
> there is an implementation plan: "Would you like to include a
> Gemini-powered chat interface to enable natural language queries against
> your data? Let me know and I'll update the plan!".

If the user requests or agrees to the chat interface:

> [!CAUTION]
>
> Adding the chat interface is a significant change. Implicit approval of
> the implementation plan for including the chat interface MUST never be
> assumed.

1. Gather Technical Details: You MUST read references/chat_integration.md

for the technical requirements.

1. Update the implementation plan: If and only if there is an

implementation plan, you MUST update the implementation plan. This is a significant change so the user must explicitly approve the updated plan.

1. Verify Prerequisites: Ensure the user has the Gemini Data Analytics API

enabled and data exists in BigQuery.

1. Reference Examples: Adapt the patterns in

examples/react_chat_panel.jsx and either examples/fastapi_chat.py or examples/express_chat.ts.

Acceptance Criteria

[!CAUTION]

If available, you MUST use browser testing capabilities (such as

browser_subagent, Puppeteer, Playwright, or an equivalent available tool) to

visually verify the frontend application is working correctly before

notifying the user that the task is complete.

[!IMPORTANT]

The following checklist represents the strict requirements for this task. You

must include these items in whatever format you use to track your work (e.g.,

your task list, implementation plan, or internal checklist).

• [ ] Are CSS hover transitions smooth?
• [ ] Are date fields formatted readably? (e.g., MMM dd, yyyy)
• [ ] Do z-indexes stack correctly so dropdowns appear above table headers?

(relative z-30)

• [ ] Do all interactive form/button inputs handle loading/disabled states?
• [ ] Is the application responsive and does the layout adapt well to

different screen sizes?

• [ ] Are API calls for data fetching successful, and is there appropriate

error handling?

• [ ] Does the dark mode toggle function correctly and apply styles

consistently?

• [ ] Do all visualizations render correctly and are they interactive where

expected?

• [ ] Is the dashboard visually appealing?