# Design Brief: [App Name]

## 1. App Analysis

### What This App Does
[One paragraph explaining the app's purpose]

### Who Uses This
[Describe the typical user]

### The ONE Thing Users Care About Most
[What do they want to see immediately when opening the app?]

### Primary Actions (IMPORTANT!)
[What do users DO most often? The #1 action becomes the Primary Action Button.
This dashboard is NOT read-only - users must be able to interact!
List actions in priority order, e.g.:
1. Log a workout → Primary Action Button
2. Add a meal
3. Record weight]

---

## 2. What Makes This Design Distinctive

[This section is CRITICAL. Describe what makes this design feel custom-designed for THIS app, NOT a generic template.]

### Visual Identity
[One paragraph explaining what makes this design special and memorable.
NOT generic descriptions like "clean and modern" - be specific!
Example: "The warm cream background with terracotta accents creates a grounded, earthy feel that suits a fitness app focused on sustainable habits."]

### Layout Strategy
[Describe your layout approach:
- How is the hero element emphasized? (size, position, whitespace)
- Is the layout symmetric or asymmetric? Why does this suit the app?
- What creates visual interest? (size variation, typography, spacing)
- How do secondary elements support without competing?]

### Unique Element
[Describe ONE specific design element that sets this apart:
- A distinctive card style
- An unusual color accent placement
- A unique way of displaying data
- A layout break that creates interest
Example: "The progress ring around the hero KPI uses a thick 8px stroke with rounded caps and a subtle glow effect, making the weekly goal feel almost game-like."]

---

## 3. Theme & Colors

### Font
- **Family:** [Font name from Google Fonts]
- **URL:** `https://fonts.googleapis.com/css2?family=...`
- **Why this font:** [Explain why it fits this app]

### Color Palette
All colors as complete hsl() functions:

| Purpose | Color | CSS Variable |
|---------|-------|--------------|
| Page background | `hsl(X X% X%)` | `--background` |
| Main text | `hsl(X X% X%)` | `--foreground` |
| Card background | `hsl(X X% X%)` | `--card` |
| Card text | `hsl(X X% X%)` | `--card-foreground` |
| Borders | `hsl(X X% X%)` | `--border` |
| Primary action | `hsl(X X% X%)` | `--primary` |
| Text on primary | `hsl(X X% X%)` | `--primary-foreground` |
| Accent highlight | `hsl(X X% X%)` | `--accent` |
| Muted background | `hsl(X X% X%)` | `--muted` |
| Muted text | `hsl(X X% X%)` | `--muted-foreground` |
| Success/positive | `hsl(X X% X%)` | (component use) |
| Error/negative | `hsl(X X% X%)` | `--destructive` |

### Why These Colors
[Explain the color choices - what mood/feeling do they create?]

### Background Treatment
[Is the background plain white? A subtle gradient? A light texture?
Describe exactly what makes it interesting, or explain why plain is intentional.]

---

## 4. Mobile Layout (Phone)

Design mobile as a COMPLETELY SEPARATE experience, not squeezed desktop.

### Layout Approach
[Describe how you're creating visual hierarchy on mobile:
- Does the hero dominate the first viewport?
- What creates visual interest? (size variation, typography, etc.)]

### What Users See (Top to Bottom)

**Header:**
[Describe exactly what's in the header - title, actions, etc.]

**Hero Section (The FIRST thing users see):**
[Describe the most important element in detail:
- What is it? (number, chart, status?)
- How big is it? (give relative sizes - e.g., "takes 60% of viewport height")
- Styling that makes it dominant (large font, color, whitespace)
- Why is this the hero? (explain the user need it answers)]

**Section 2: [Name]**
[Describe this section - what it contains, why it's here, how it contrasts with hero]

**Section 3: [Name]**
[Continue for each section]

**Bottom Navigation / Action:**
[What's at the bottom? Fixed action button? Nav tabs? Nothing?]

### Mobile-Specific Adaptations
[Describe how content is reorganized for mobile - stacking, scrolling, etc.
Only hide elements if they're truly impossible to use on a phone.]

### Touch Targets
[Any specific notes about button sizes, tap areas?]

### Interactive Elements (if applicable)
[If any elements should be tappable to reveal more details, note them here.
Only add drill-down where there's actually more information to show.]

---

## 5. Desktop Layout

### Overall Structure
[Describe the layout:
- How many columns? What proportions?
- Where does the eye go first, second, third?
- What creates visual interest in this layout?]

### Section Layout
[Describe what goes where:
- Top area: [what content]
- Main content area: [what content]
- Supporting areas: [what content]
Include proportions if using multi-column layout.]

### What Appears on Hover
[What extra information is revealed when hovering over elements?]

### Clickable/Interactive Areas (if applicable)
[If any elements should open detail views when clicked, note them here.
Only add where it provides additional useful information.]

---

## 6. Components

### Hero KPI
The MOST important metric that users see first.

- **Title:** [Name]
- **Data source:** [Which app to query]
- **Calculation:** [How to calculate: sum, count, latest, etc.]
- **Display:** [How it looks - large number? With icon? Progress ring?]
- **Context shown:** [What comparison? Goal progress? Trend?]
- **Why this is the hero:** [Explain why this matters most to users]

### Secondary KPIs
[For each secondary KPI:]

**[KPI Name]**
- Source: [App]
- Calculation: [How]
- Format: [number/currency/percent]
- Display: [Card? Inline? Size?]

### Chart (if applicable)
- **Type:** [line/bar/area - and WHY this type]
- **Title:** [Chart title]
- **What question it answers:** [Why does the user need this chart?]
- **Data source:** [App]
- **X-axis:** [Field, label]
- **Y-axis:** [Field, label]
- **Mobile simplification:** [How is it simplified for small screens?]

### Lists/Tables (if applicable)
[For each list:]

**[Section Name]**
- Purpose: [Why users need this]
- Source: [App]
- Fields shown: [Which fields]
- Mobile style: [cards/simple list]
- Desktop style: [table/cards]
- Sort: [By what field]
- Limit: [How many items]

### Primary Action Button (REQUIRED!)

**⚠️ Every dashboard MUST have a primary action.** This is NOT a read-only view!

Users need to DO things from the dashboard, not just look at data. The most common action should be one tap/click away.

Think about what action users perform most often:
- Adding a new record (workout, meal, expense, etc.)
- Logging something (weight, progress, status)
- Starting a process (timer, session, etc.)

**This section is REQUIRED - do not skip it or write "None"!**

- **Label:** [Action-oriented text, e.g. "Workout starten", "Mahlzeit hinzufügen"]
- **Action:** [add_record | navigate - specify which]
- **Target app:** [Which Living Apps app receives the data]
- **What data:** [What fields will the form contain]
- **Mobile position:** [bottom_fixed (recommended) | header | fab]
- **Desktop position:** [header | sidebar | inline]
- **Why this action:** [Why is this the most important thing users do?]

The implementation skill knows how to create forms that send data to Living Apps API.

---

## 7. Visual Details

### Border Radius
[sharp (4px) / rounded (8px) / pill (16px+)]

### Shadows
[none / subtle / elevated - describe the shadow style]

### Spacing
[compact / normal / spacious - how much breathing room?]

### Animations
- **Page load:** [none / fade / stagger]
- **Hover effects:** [What happens on hover?]
- **Tap feedback:** [What happens on tap?]

---

## 8. CSS Variables (Copy Exactly!)

The implementer MUST copy these values exactly into `src/index.css`:

```css
:root {
  --background: hsl(...);
  --foreground: hsl(...);
  --card: hsl(...);
  --card-foreground: hsl(...);
  --popover: hsl(...);
  --popover-foreground: hsl(...);
  --primary: hsl(...);
  --primary-foreground: hsl(...);
  --secondary: hsl(...);
  --secondary-foreground: hsl(...);
  --muted: hsl(...);
  --muted-foreground: hsl(...);
  --accent: hsl(...);
  --accent-foreground: hsl(...);
  --destructive: hsl(...);
  --border: hsl(...);
  --input: hsl(...);
  --ring: hsl(...);
}

---

## ⚠️ How Colors Are Applied (Critical!)

Your colors are mapped to CSS variables. The implementation agent uses them directly.

**Color Mapping:**

| Your design_brief color | CSS Variable |
|-------------------------|--------------|
| `background` | `--background` |
| `foreground` | `--foreground` |
| `card` | `--card` |
| `card_foreground` | `--card-foreground` |
| `primary` | `--primary` |
| `primary_foreground` | `--primary-foreground` |
| `accent` | `--accent` |
| `muted` | `--muted` |
| `muted_foreground` | `--muted-foreground` |
| `border` | `--border` |
| `negative` | `--destructive` |

**Light Theme Contrast Rules:**
- `foreground` must be dark (readable on light backgrounds)
- `card` can be white or slightly off-white
- `card_foreground` must be dark
- `primary` needs sufficient contrast for buttons

**All colors MUST be complete hsl() functions:**

---

## Quality Checklist

Before finalizing design_brief.md:

### Distinctiveness
- [ ] Would a designer recognize this as intentionally designed (not default)?
- [ ] Is there at least ONE memorable visual detail?
- [ ] Is the font choice appropriate and NOT from forbidden list?
- [ ] Does the color accent feel considered, not generic?

### Layout & UX (CRITICAL FOR AVOIDING AI SLOP!)
- [ ] Is there ONE clear hero element that stands out?
- [ ] Is there visual interest? (size variation, typography hierarchy, spacing variation)
- [ ] NOT everything the same size - some variation exists
- [ ] Is mobile designed FOR mobile (not just smaller)?
- [ ] Does desktop use horizontal space meaningfully?
- [ ] Would this get featured in the App Store?

### Interactivity
- [ ] Is the primary action clearly defined?
- [ ] Are clickable elements marked where drill-down adds value?

### Information
- [ ] Is the visual hierarchy clear?
- [ ] Are all relevant KPIs included?

### Clarity
- [ ] Is every section detailed enough that someone else could implement it?
- [ ] Are there WHY explanations for major decisions?
- [ ] Are the CSS variables complete and ready to copy?
- [ ] Is the Layout Strategy section filled out with specific proportions?

### Technical
- [ ] Are all colors complete hsl() functions?
- [ ] Is contrast sufficient for readability?
- [ ] Are all required colors defined?

---

## Remember

1. **Write for the implementer** - They will follow your words exactly
2. **Explain WHY** - Context helps them understand intent
3. **Be specific** - "Large number" is vague, "48px bold" is specific
4. **Minimal ≠ Generic** - Minimal can be distinctive
5. **Layout is everything** - 80% of design time on layout
6. **Visual interest is required** - Vary sizes, not everything identical
7. **Mobile ≠ Small Desktop** - Separate experiences
8. **One memorable detail** - What makes this special?
9. **App Store quality** - Would Apple feature this?