Building Data Applications

Step 0: Framework Selection

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

Shared Design Standards

resources/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

   resources/streamlit_framework.md

   for detailed CSS and component patterns.
2. Follow the "Checklist for New Dashboards" in that file.

If using React + Vite:

1. Read

   resources/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!".

> [!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

   resources/chat_integration.md

   for the technical requirements.
2. 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.
3. Verify Prerequisites: Ensure the user has the Gemini Data Analytics API enabled and data exists in BigQuery.
4. 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?