# FindMyHealth Design Guidelines

> "Not what people are saying. What the evidence actually shows."

This document defines how FindMyHealth looks, sounds, and feels across every touchpoint. The goal: help people cut through health misinformation without overwhelming them or talking down to them.

---

## Table of Contents

1. [Brand Essence](#brand-essence)
2. [Brand Voice](#brand-voice)
3. [Visual Identity](#visual-identity)
4. [Component Patterns](#component-patterns)
5. [Channel Guidelines](#channel-guidelines)
6. [Anti-Patterns](#anti-patterns)

---

## Brand Essence

### Who We Protect

Regular people who get duped by health misinformation. Your aunt on Facebook. Your neighbor who shares miracle cure posts. People who spend money on supplements that don't work because an influencer said so.

They are not stupid. They are targeted.

### Our Role

The pharmacist, not the professor. We look out for people without lecturing them. We give them power over the con artists trying to take their money and health.

### Core Tension

**Insurgent + Authoritative.** We fight against pharma BS and influencer grifts, but we do it with methodology, not conspiracy theories. Rebellion with receipts.

### The Promise

Your health. Your proof. Your decision.

---

## Brand Voice

### Personality Traits

| Trait | What It Means | Example |
|-------|---------------|---------|
| **Protective** | Looking out for you, not selling to you | "Here's what the studies actually show." |
| **Plain-spoken** | No jargon, no academic language | "The evidence is weak" not "inconclusive meta-analytic findings" |
| **Honest** | Admit uncertainty, show our work | "We found 3 studies. Two support it, one doesn't." |
| **Warm** | Human, not robotic | "Good question. Let's dig in." |
| **Empowering** | You decide, we inform | "Now you have the data. Your call." |

### Tone by Context

| Context | Tone | Example |
|---------|------|---------|
| Neutral finding | Calm, informative | "The FDA approved this in 2019. Here's what their data showed." |
| Conflict detected | Alert but not alarming | "Heads up: the clinical trials and user reports don't match." |
| Debunking a scam | Direct, protective | "This claim traces back to one paid study. The independent research doesn't support it." |
| Uncertainty | Honest, humble | "The evidence is mixed. Here's both sides." |
| User question | Warm, helpful | "Great question. Here's what we found." |

### Writing Principles

**1. Lead with the answer, then show the work.**
Not: "After analyzing 47 studies across 12 databases, we found..."
But: "The evidence is strong. Here's why: 47 studies, mostly positive."

**2. Use "you" and "your" liberally.**
This is personal. "Your health" not "consumer health outcomes."

**3. Quantify when possible.**
Not: "Some studies suggest..."
But: "3 of 5 studies found..."

**4. Name the sources.**
Not: "Research shows..."
But: "A 2023 Stanford study found..."

**5. Admit what we don't know.**
"We couldn't find strong evidence either way. Here's what exists."

### Words We Use

- "Evidence" (not "data" or "research")
- "Studies" (not "the literature")
- "Found" (not "suggests" or "indicates")
- "Conflict" (not "discrepancy")
- "Heads up" (not "warning" or "alert")
- "Here's the breakdown" (not "analysis")

### Words We Avoid

- "Revolutionary" / "breakthrough" / "game-changing"
- "Studies show" (too vague - which studies?)
- "Experts say" (which experts?)
- "You should" (we inform, you decide)
- "Obviously" / "clearly" (nothing is obvious)
- "Just" (minimizing - "just subscribe")
- Any urgency language ("Act now", "Don't miss", "Limited time")

---

## Visual Identity

### Color Palette

#### Primary Colors

| Name | Hex | RGB | Usage |
|------|-----|-----|-------|
| **Trust Blue** | `#1E40AF` | 30, 64, 175 | Primary brand, links, interactive elements |
| **Deep Navy** | `#0F172A` | 15, 23, 42 | Text, headers, high contrast |
| **Clean White** | `#FFFFFF` | 255, 255, 255 | Backgrounds, cards |
| **Soft Gray** | `#F8FAFC` | 248, 250, 252 | Page backgrounds, subtle sections |

#### Semantic Colors

| Name | Hex | RGB | Usage |
|------|-----|-----|-------|
| **Verified Green** | `#059669` | 5, 150, 105 | Strong evidence, verified claims, positive signals |
| **Caution Amber** | `#D97706` | 217, 119, 6 | Conflicts, mixed evidence, needs attention |
| **Alert Red** | `#DC2626` | 220, 38, 38 | Weak evidence, debunked claims, scam warnings |
| **Neutral Slate** | `#64748B` | 100, 116, 139 | Secondary text, metadata, timestamps |

#### Color Usage Rules

1. **Blue is for trust and action.** Links, buttons, interactive elements.
2. **Semantic colors are for evidence quality only.** Never use green/amber/red decoratively.
3. **Backgrounds stay neutral.** White and soft gray only. No colored backgrounds except for alerts.
4. **Text is high contrast.** Deep navy on white. Never gray text on gray backgrounds.

### Typography

#### Font Stack

```css
/* Primary - UI and body text */
--font-primary: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

/* Monospace - Data, sources, citations */
--font-mono: 'JetBrains Mono', 'SF Mono', 'Monaco', 'Consolas', monospace;
```

#### Type Scale

| Name | Size | Weight | Line Height | Usage |
|------|------|--------|-------------|-------|
| **Display** | 36px / 2.25rem | 700 | 1.2 | Hero headlines only |
| **H1** | 28px / 1.75rem | 700 | 1.3 | Page titles |
| **H2** | 22px / 1.375rem | 600 | 1.35 | Section headers |
| **H3** | 18px / 1.125rem | 600 | 1.4 | Card titles, subsections |
| **Body** | 16px / 1rem | 400 | 1.6 | Paragraphs, descriptions |
| **Body Small** | 14px / 0.875rem | 400 | 1.5 | Captions, metadata |
| **Mono** | 13px / 0.8125rem | 400 | 1.4 | Source citations, data |

#### Typography Rules

1. **Inter for everything human.** Headlines, body, UI.
2. **Monospace for everything data.** Source names, percentages, citations, evidence tiers.
3. **Never more than 3 weights on a page.** Regular (400), Semibold (600), Bold (700).
4. **Max line length: 680px.** Optimal reading comfort.

### Spacing System

Base unit: 4px

| Token | Value | Usage |
|-------|-------|-------|
| `--space-1` | 4px | Tight gaps, icon padding |
| `--space-2` | 8px | Inline spacing, small gaps |
| `--space-3` | 12px | Form element padding |
| `--space-4` | 16px | Card padding, list gaps |
| `--space-6` | 24px | Section gaps, card margins |
| `--space-8` | 32px | Major section breaks |
| `--space-12` | 48px | Page section divisions |
| `--space-16` | 64px | Hero spacing, major landmarks |

#### Spacing Rules

1. **Generous whitespace.** When in doubt, add more space.
2. **Consistent rhythm.** Use the scale, don't invent values.
3. **Group related items.** Less space within groups, more space between.

### Icons and Emoji

#### Emoji as Visual Anchors

Emoji make content feel alive without being clinical. Use them sparingly and consistently.

| Emoji | Meaning | When to Use |
|-------|---------|-------------|
| `+` | Strong evidence, verified | High-confidence findings |
| `!` | Caution, conflict detected | Mixed evidence, needs attention |
| `-` | Weak evidence, debunked | Low-confidence or disproven claims |
| `?` | More research needed | Insufficient evidence |
| `>` | Source/citation | Attributing information |
| `#` | Topic/category | Tagging content |
| `@` | Update/new info | Time-sensitive changes |
| `*` | Key insight | Important takeaways |

#### Icon Style

- **Line icons only.** No filled icons, no gradients.
- **Consistent stroke width.** 1.5px or 2px, never mixed.
- **Icon library:** Lucide (MIT licensed, consistent style)
- **Size:** 16px inline, 20px in buttons, 24px standalone

### Layout Principles

#### Grid System

- **Max content width:** 1200px
- **Reading content max:** 680px
- **Sidebar width:** 280px (when used)
- **Gutter:** 24px
- **Columns:** 12-column grid for complex layouts

#### Information Density

We show a lot of data. The goal is density without overwhelm.

1. **Hierarchy through typography, not decoration.** Size and weight, not boxes and lines.
2. **Scannable structure.** Headers, bullets, tables. No walls of text.
3. **Progressive disclosure.** Summary first, details on demand.
4. **Consistent patterns.** Same structure for same content types.

---

## Component Patterns

### Evidence Cards

The primary unit of content. Shows a claim with its evidence quality.

```
+----------------------------------------------------------+
|  [Emoji] Claim Title                           [Tier Badge]
|
|  One-sentence summary of the finding.
|
|  Sources: `FDA (2023)` `NEJM Study` `+2 more`
|
|  [See Evidence ->]
+----------------------------------------------------------+
```

**Rules:**
- Always show evidence tier badge (color-coded)
- Always show source count
- Summary is one sentence max
- Link to full breakdown

### Evidence Tiers

How we communicate source authority.

| Tier | Label | Color | Examples |
|------|-------|-------|----------|
| Tier 0 | Official | Trust Blue | FDA, WHO, CDC |
| Tier 1 | Clinical | Verified Green | Peer-reviewed studies, trials |
| Tier 2 | Professional | Trust Blue | Medical associations, doctors |
| Tier 3 | Journalistic | Neutral Slate | Major publications, investigative |
| Tier 4 | Community | Caution Amber | Forums, patient reports |
| Tier 5 | Social | Neutral Slate | Social media, influencers |

**Display format:**
```
Tier 0: Official  [solid blue badge]
```

### Conflict Alerts

When sources disagree, we highlight it.

```
+----------------------------------------------------------+
|  ! Conflict Detected                                      |
|                                                           |
|  FDA approval data shows X.                               |
|  Reddit user reports suggest Y.                           |
|                                                           |
|  [View Full Comparison]                                   |
+----------------------------------------------------------+
```

**Rules:**
- Amber left border
- State both positions clearly
- Never take sides in the alert itself
- Link to detailed comparison

### Source Citations

How we attribute information.

**Inline citation:**
```
The FDA approved this in 2019 `[FDA, 2019]`.
```

**Expanded citation:**
```
> FDA Drug Approval Database
  fda.gov/drugs/... | Tier 0: Official | Retrieved Jan 2024
```

**Rules:**
- Always link to original source when available
- Show tier for context
- Show retrieval date for time-sensitive info

### Call-to-Action Buttons

**Primary button:**
- Trust Blue background, white text
- Used for main actions (Subscribe, Search, View Evidence)
- One per section max

**Secondary button:**
- White background, Trust Blue text, subtle border
- Used for alternative actions

**Button labels:**
- Verb + Object: "View Evidence", "Search Topics", "Read More"
- Never: "Click Here", "Submit", "Go"

### Forms

**Email signup (newsletter):**
```
+----------------------------------------------------------+
|  Get weekly evidence reviews.                             |
|  No spam. Unsubscribe anytime.                           |
|                                                           |
|  [        Your email        ] [Subscribe]                 |
|                                                           |
|  Join 1,234 readers                                       |
+----------------------------------------------------------+
```

**Rules:**
- Minimal fields (email only for newsletter)
- Clear value proposition
- Explicit anti-spam promise
- Social proof if available (subscriber count)
- No fake urgency

### Tables

For comparing evidence across sources.

```
| Source          | Finding      | Quality | Year |
|-----------------|--------------|---------|------|
| FDA             | Approved     | +       | 2019 |
| Stanford Study  | Effective    | +       | 2022 |
| Reddit Reports  | Side effects | !       | 2024 |
```

**Rules:**
- Left-align text, right-align numbers
- Use emoji for quick quality scanning
- Link source names when possible
- Sort by tier (highest first) or date (newest first)

---

## Channel Guidelines

### Website

#### Homepage

**Purpose:** Explain what we do, show recent topics, convert to newsletter.

**Structure:**
1. **Hero** (above fold)
   - Headline: Value proposition
   - Subhead: One-sentence explanation
   - Search bar: Primary action
   - No hero image. Text is the hero.

2. **How It Works** (3 steps, icons + short text)

3. **Recent Topics** (3-4 evidence cards)

4. **Newsletter CTA** (simple form, no popup)

5. **Footer** (minimal: About, Contact, Privacy)

**Rules:**
- No popups
- No animations
- No stock photos
- Load time under 2 seconds
- Mobile-first

#### Topic Pages

**Purpose:** Deep dive on a health topic with full evidence hierarchy.

**Structure:**
1. **Topic header**
   - Topic name
   - Last updated date
   - Overall evidence quality badge

2. **Summary section**
   - 2-3 sentence plain-language summary
   - Key conflicts highlighted

3. **Evidence hierarchy**
   - Grouped by tier
   - Expandable source details

4. **Timeline** (if relevant)
   - How understanding evolved
   - Key dates and findings

5. **Related topics**

**Rules:**
- Scannable at a glance
- Details on demand
- Always show source tiers
- Always show conflicts

#### Blog / Articles

**Purpose:** Longer-form analysis, weekly newsletter archive.

**Structure:**
- Title
- Date + reading time
- Author (optional - can be "FindMyHealth Team")
- Body (max 680px width)
- Sources section at bottom

**Rules:**
- No sidebar ads
- No popups
- Related articles at bottom only
- Share buttons subtle, not sticky

### Newsletter

#### Format

**Subject line:**
- Direct, not clickbait
- Include topic name
- Example: "FindMyHealth: What the evidence says about creatine"

**Structure:**
```
[FindMyHealth logo - small, text-based]

This Week's Evidence Reviews
---

# Main Topic
[Evidence card format]

## Quick Takes
- Topic 2: One-line summary [link]
- Topic 3: One-line summary [link]
- Topic 4: One-line summary [link]

---

That's it for this week.

Questions? Reply to this email.
Unsubscribe: [link]
```

**Rules:**
- Plain text friendly (works without images)
- One main topic, 3-4 quick takes
- Under 500 words total
- No ads, no sponsored content
- Reply-to goes to real inbox

#### Tone

- Casual but informed
- "This week we looked at..."
- "Heads up on..."
- "You asked about X. Here's what we found."

### Bot (Conversational Interface)

#### Personality

The bot is a helpful research assistant, not an AI personality. It's warm but focused.

**Greeting:**
```
Hey! I can help you find evidence on health topics.

What would you like to look up?
```

**Not:**
```
Hello! I'm FindMyHealth Bot, your AI-powered health research assistant!
I'm here to help you navigate the complex world of health information!
What can I help you with today? :)
```

#### Response Format

**For quick questions:**
```
Creatine for muscle building:

+ Strong evidence it works (Tier 1: 47 studies)
* Most effective: 3-5g daily
! Some reports of water retention

Want the full breakdown?
```

**For complex topics:**
```
Ozempic - here's what I found:

FDA Status: Approved for Type 2 diabetes, weight management
Evidence quality: + Strong (Tier 0-1 sources)

Conflicts detected:
! Clinical trials vs. user reports differ on side effects

I can go deeper on:
1. Effectiveness data
2. Side effect reports
3. How it compares to alternatives

Which interests you?
```

#### Conversation Principles

1. **Answer first, offer depth second.**
2. **Use emoji for quick scanning.**
3. **Offer clear next steps.**
4. **Admit uncertainty.** "I couldn't find strong evidence on that."
5. **Never diagnose or prescribe.** "Here's what the evidence shows. Talk to your doctor about your situation."

#### Safety Guardrails

**Always include when relevant:**
- "This isn't medical advice."
- "Talk to your doctor before making changes."
- Links to emergency resources for crisis topics.

**Refuse to engage with:**
- Requests for diagnosis
- Specific dosage recommendations
- Emergency medical situations (redirect to 911 / emergency services)

### Community (Future)

#### Principles

When we add community features:

1. **Reputation = evidence contribution quality, not popularity.**
2. **No follower counts.** Not a social network.
3. **Highlight corrections.** People who update their views get credit.
4. **Source requirements.** Claims must include sources to be posted.

#### Comment Format (Future)

```
[Username] [Reputation badge]
Comment text with required source citation.
> Source: [linked]

[Helpful: 12] [Needs Source] [Reply]
```

#### Profile Elements (Future)

- Topics contributed to
- Corrections made (positive signal)
- Source quality average
- No follower/following counts
- No profile photos (optional avatar only)

---

## Anti-Patterns

Things we NEVER do. If you see these, fix them.

### Visual Anti-Patterns

| Never Do This | Why | Do This Instead |
|---------------|-----|-----------------|
| Gradient backgrounds | Feels like marketing spam | Solid colors only |
| Hero stock photos | Generic, untrustworthy | Let content be the hero |
| Animations on load | Distracting, slow | Static, fast-loading |
| Decorative icons | Visual noise | Icons only for function |
| Drop shadows on everything | Dated, cluttered | Flat design, borders if needed |
| Colored text for emphasis | Confusing, accessibility issues | Bold or size for emphasis |
| Multiple CTAs competing | Overwhelming | One primary action per section |

### Copy Anti-Patterns

| Never Write This | Why | Write This Instead |
|------------------|-----|-------------------|
| "Studies show..." | Vague, unverifiable | "A 2023 Stanford study found..." |
| "Experts agree..." | Weasel words | Name the experts |
| "You should..." | Prescriptive | "The evidence suggests..." |
| "Don't miss out!" | Fake urgency | No urgency language at all |
| "Subscribe now!" | Pushy | "Get weekly reviews" |
| "Revolutionary breakthrough" | Hype language | Just state what it does |
| "AI-powered" | Meaningless buzzword | Don't mention AI unless relevant |

### UX Anti-Patterns

| Never Do This | Why | Do This Instead |
|---------------|-----|-----------------|
| Email popup on landing | Hostile, spammy | Inline form, earn the signup |
| Exit intent popups | Desperate, annoying | No popups ever |
| Scroll-jacking | Frustrating | Native scroll behavior |
| Auto-playing video | Disruptive | User-initiated only |
| Infinite scroll without purpose | Addictive pattern | Pagination or clear endpoints |
| Dark patterns in unsubscribe | Unethical, illegal in some places | One-click unsubscribe |
| Hiding sources behind signup | Against our mission | Sources always visible |

### Content Anti-Patterns

| Never Do This | Why | Do This Instead |
|---------------|-----|-----------------|
| Hide conflicts | Dishonest | Surface conflicts prominently |
| Cherry-pick evidence | Misleading | Show the full picture |
| Use tier without showing it | Opaque | Always show source tier |
| Present opinion as evidence | Undermines trust | Clearly separate analysis from data |
| Update without noting it | Erodes trust | Show update dates, changelog for major changes |

---

## Implementation Checklist

When building any FindMyHealth interface:

### Before Launch

- [ ] No popups of any kind
- [ ] No fake urgency language
- [ ] All sources attributed with tiers
- [ ] Conflicts highlighted, not hidden
- [ ] Mobile-responsive
- [ ] Load time under 3 seconds
- [ ] One primary CTA per section max
- [ ] Unsubscribe is one click
- [ ] Reply-to email works

### Accessibility

- [ ] Color contrast meets WCAG AA (4.5:1 for text)
- [ ] Semantic HTML structure
- [ ] Alt text for any images
- [ ] Keyboard navigable
- [ ] Screen reader tested

### Voice Check

- [ ] No jargon without explanation
- [ ] Sources named, not vague
- [ ] Uncertainty admitted when present
- [ ] Warm but not fake
- [ ] Empowering, not prescriptive

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2024-02 | Initial guidelines |

---

*These guidelines are living documentation. Update them as we learn what works.*