stemedb/applications/findmyhealth/design_guidelines.md

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
2. Brand Voice
3. Visual Identity
4. Component Patterns
5. Channel Guidelines
6. 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

/* 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.