@wazir-dev/cli 1.0.0

package/expertise/design/patterns/gamification.md

@@ -0,0 +1,801 @@
+# Gamification Patterns
+
+> Design expertise module for gamification mechanics, ethical implementation,
+> and evidence-based engagement design across digital products.
+
+---
+
+## 1. Pattern Anatomy
+
+Gamification applies game mechanics to non-game contexts to drive engagement
+and behavior change. Each mechanic targets distinct psychological drivers
+mapped to Yu-Kai Chou's Octalysis Core Drives.
+
+### 1.1 Points / XP
+
+**Purpose:** Quantify user effort and provide continuous progress feedback.
+**Core Drive:** Development and Accomplishment (CD2).
+
+- Display XP gain immediately after action (+25 XP) with cumulative total.
+- Use an XP bar to visualize proximity to the next milestone.
+- Calibrate inflation: 5-7 actions per early level, scaling logarithmically.
+- Fixed XP for predictable tasks; variable XP for discovery-based actions.
+- Variants: skill-specific XP, decay XP (decreases over time to encourage
+  sustained engagement), bonus multipliers for streaks or difficulty.
+
+### 1.2 Badges / Achievements
+
+**Purpose:** Recognize accomplishments and signal expertise to self and others.
+**Core Drive:** CD2 + Social Influence and Relatedness (CD5).
+
+- Every badge must correspond to a meaningful behavior. "You opened the app!"
+  erodes trust and devalues all other badges.
+- Mix visible badges (goal-setting) with hidden ones (surprise, CD7).
+- Tiered badges (bronze/silver/gold) mark escalating mastery. Stack Overflow
+  maintains ~90 badges across three tiers, each tied to valuable community
+  behavior.
+- Badge art must be visually distinct and scannable at small sizes (24x24px
+  minimum for mobile).
+- Variants: collection badges, seasonal/event badges (CD6 Scarcity),
+  collaborative badges earned by teams.
+
+### 1.3 Levels / Tiers
+
+**Purpose:** Structure the journey into progressive stages unlocking
+capabilities and signaling status.
+**Core Drive:** CD2 + Ownership and Possession (CD4).
+
+- Early levels come quickly (1-3 sessions) to establish momentum.
+- Mid-game feels challenging but achievable (the "flow" zone).
+- Late-game rewards dedication without being unattainable.
+- Stack Overflow's privilege system is the gold standard: 15 rep = upvote,
+  50 = comment, 2000 = edit, 10000 = moderator tools. Each unlock is a trust
+  signal that gives the user real capabilities.
+- Always show what the next level unlocks to create forward momentum.
+- Avoid 100+ levels with no meaningful differentiation between them.
+- Variants: prestige systems (reset with marker), parallel leveling (separate
+  tracks per skill), named tiers (Duolingo leagues: Bronze through Diamond).
+
+### 1.4 Streaks
+
+**Purpose:** Encourage consistent daily engagement via unbroken chains.
+**Core Drive:** Loss and Avoidance (CD8) + CD4.
+
+- The most powerful and most dangerous mechanic. Users with 7+ day streaks
+  are 2.3x more likely to engage daily, but streak anxiety causes real
+  psychological harm.
+- Always provide recovery mechanics. Duolingo's streak freeze reduced churn
+  by 21% among at-risk users.
+- Consider "streak shields" for weekends/holidays. Offer weekly streaks as a
+  less intense alternative.
+- Frame around upcoming milestones ("3 more days to your 30-day badge!")
+  rather than around loss ("You're losing your streak!").
+- Variants: activity streaks (any qualifying action), goal streaks (specific
+  threshold), weekly streaks (more forgiving cadence), team streaks.
+
+### 1.5 Leaderboards
+
+**Purpose:** Leverage social comparison and competition.
+**Core Drive:** CD5.
+
+- Global leaderboards discourage 99% of users. Only the top 1% benefits;
+  the rest see an insurmountable gap.
+- Duolingo solves this with cohort-based leagues (~30 users, similar activity
+  levels). Weekly resets and promotion/demotion keep competition relevant.
+- Show the user's position and the 2-3 users above/below (relative positioning
+  is more motivating than absolute rank).
+- Allow filtering by friends, region, and time period.
+- Consider anonymizing or removing leaderboards for users who opt out.
+- Variants: sprint leaderboards (24-hour or weekly), category leaderboards,
+  team leaderboards, percentile displays ("You're in the top 15%").
+
+### 1.6 Progress Bars
+
+**Purpose:** Visualize completion and leverage the endowed progress effect.
+**Core Drive:** CD2 + Zeigarnik Effect.
+
+- LinkedIn's profile completion bar boosted completion by 55%.
+- Start the bar slightly filled (10-15%) to trigger the endowed progress
+  effect (increases completion by up to 78%).
+- Use clear labels showing both percentage and remaining steps.
+- For long journeys, break into segment milestones. Avoid bars that stall
+  or move backwards.
+- Variants: segmented progress, circular/radial progress, step indicators,
+  skill trees (branching visualization).
+
+### 1.7 Challenges / Quests
+
+**Purpose:** Structured, time-bound goals creating narrative engagement.
+**Core Drive:** Epic Meaning and Calling (CD1) + Empowerment of Creativity
+and Feedback (CD3).
+
+- Offer a mix of difficulty levels so users can self-select appropriate
+  challenges.
+- Daily challenges drive habitual engagement; weekly challenges sustain
+  deeper engagement.
+- Nike Run Club's guided runs function as narrative quests: coached audio
+  creates a story arc around each run.
+- Allow abandonment without penalty to preserve autonomy.
+- Variants: daily quests (refreshed every 24 hours), seasonal events,
+  chain quests (sequential), community challenges (collective goals).
+
+### 1.8 Rewards
+
+**Purpose:** Provide tangible or intangible value for desired behaviors.
+**Core Drive:** CD4 + Unpredictability and Curiosity (CD7).
+
+- Variable reward schedules (CD7) are more engaging than fixed. Mix
+  predictable and surprise rewards.
+- Intrinsic rewards (mastery, autonomy, purpose) sustain engagement longer
+  than extrinsic. Use extrinsic to bootstrap, then transition to intrinsic.
+- Rewards must feel proportional to effort. Disproportionate rewards break
+  the economy and user trust.
+- Never monetize achievement signals. Monetize cosmetics and convenience
+  instead.
+
+### 1.9 Unlockables
+
+**Purpose:** Gate content behind milestones to create aspirational goals.
+**Core Drive:** Scarcity and Impatience (CD6) + CD2.
+
+- Show locked items with clear unlock criteria ("Reach Level 10 to unlock").
+  Use silhouettes, blurred previews, or lock icons.
+- Space unlockables across the journey to sustain mid-game motivation.
+- Never gate essential functionality behind gamification walls.
+- Variants: cosmetic unlockables (avatar items, themes), functional
+  unlockables (tools, permissions), content unlockables (lessons, levels),
+  social unlockables (moderation, group creation).
+
+### 1.10 Onboarding Gamification
+
+**Purpose:** Make first-use setup rewarding rather than tedious.
+**Core Drive:** CD2 + CD3.
+
+- Engineer the first achievement within 60 seconds of first use.
+- Duolingo places the first lesson before account creation -- users experience
+  the reward loop before committing.
+- Use checklists of 5-7 items (not 15+). Calibrate XP so the first level-up
+  happens during onboarding, creating an immediate emotional payoff.
+- LinkedIn's setup flow pairs each step with motivational copy ("Users with
+  complete profiles are 40x more likely to receive opportunities").
+
+---
+
+## 2. Best-in-Class Examples
+
+### 2.1 Duolingo
+
+34M daily / 128M+ monthly users (Q2 2025). Streaks make users 3x more likely
+to return daily. Streak freezes reduced churn 21%. XP leaderboards drive 40%
+more engagement. Badges boost completion 30%. Researchers identified 22
+distinct gamification elements. Lesson-before-signup lets users experience
+the reward loop before committing. The owl mascot (Duo) provides emotional
+connection via both encouragement and playful guilt in push notifications.
+
+**Lesson:** Layer multiple reinforcing mechanics; no single mechanic carries
+the full weight.
+
+### 2.2 GitHub Contributions
+
+Contribution heatmap is streak visualization without punitive mechanics --
+green squares show activity intensity over 365 days without penalizing
+inactivity. Badges (Pull Shark, Galaxy Brain, Pair Extraordinaire) reward
+collaboration behaviors, tiered from default to gold. No leaderboards --
+developer culture values craftsmanship over competition. Reputation built
+through inherent contribution value (stars, forks, community adoption).
+
+**Lesson:** Gamification does not require competition. Visibility and
+recognition drive engagement without aggressive mechanics.
+
+**Caveat:** Research (2023) found badges "poorly correlated with developers'
+qualities such as timeliness and collaboration."
+
+### 2.3 Nike Run Club
+
+Guided runs as narrative quests with professional audio coaching that creates
+story arcs around runs. Milestone badges (first 5K, first 10K, 100 miles)
+tied to real physical achievement. Friend-filterable leaderboards keep
+competition personal. Post-run shareable celebration cards drive viral growth.
+Instant split-time feedback provides continuous reinforcement during activity.
+
+**Lesson:** Tie gamification to real-world accomplishment. Badges mean
+something because they represent genuine physical achievement.
+
+### 2.4 Fitbit
+
+10,000-step daily goal creates a universally understood target. Hourly
+micro-goals ("250 steps to go this hour!") break large goals into achievable
+chunks. Friend challenges (Weekend Warrior, Workweek Hustle) add social
+competition without requiring simultaneous activity. Lifetime distance badges
+(Penguin March at 70 miles, Serengeti at 500) provide long-term aspiration.
+Celebratory wrist haptics deliver instant tactile feedback.
+
+**Lesson:** Break macro-goals into micro-goals with immediate feedback.
+
+### 2.5 Khan Academy
+
+Mastery system with skill-tree visualization showing learning dependencies.
+Five badge tiers (meteorite through black hole) with increasing rarity.
+Energy points normalize both video consumption and exercise practice. Mastery
+percentage per topic provides granular progress beyond simple completion.
+Avatar customization with earned currency creates ownership and identity
+investment.
+
+**Lesson:** Gamification should reinforce mastery, not just completion.
+
+### 2.6 Stack Overflow
+
+Reputation unlocks real capabilities: 15 rep = upvote, 50 = comment,
+125 = downvote, 2000 = edit others' posts, 10000 = moderator tools,
+20000 = trusted user. Over 66M badges awarded to 8.6M+ users. Bounty system
+lets users spend reputation to incentivize answers, creating a functional
+economy. Inspired by Xbox achievements (per co-founder Jeff Atwood). Tag
+scores show expertise depth in specific technologies.
+
+**Lesson:** The most sustainable gamification ties rewards to real capability
+and trust. Gamification is the governance model itself.
+
+### 2.7 LinkedIn
+
+Profile completion bar increased setup by 55%. Social proof copy ("Users with
+complete profiles are 40x more likely to receive opportunities") drives action
+alongside the progress bar. One-click endorsements gamify peer validation.
+Profile view statistics ("47 views this week") leverage curiosity (CD7) to
+drive return visits. "All-Star" profile badge serves as completion reward and
+status signal.
+
+**Lesson:** Gamification works best when it directly serves the user's
+real-world goals. The game serves the goal, not the other way around.
+
+---
+
+## 3. User Flow Mapping
+
+### 3.1 Primary Progression: First Achievement to Mastery
+
+**Day 1 -- First Session:**
+- Guided tour with interactive elements
+- First win engineered within 60 seconds
+- Profile setup with progress bar
+- Onboarding checklist (5-7 items)
+- Session ends with unfinished streak (Day 1 of N)
+
+**Days 2-14 -- Habit Building:**
+- Daily streaks begin on Day 2
+- First badge earned around Day 3
+- XP multipliers for consistency
+- Push notification cadence: daily reminders
+
+**Weeks 2-8 -- Level Progression:**
+- Level-ups with meaningful unlocks
+- Harder challenges introduced gradually
+- League/leaderboard placement activated
+- Skill branching begins
+
+**Weeks 8-24 -- Social Competition:**
+- Leaderboard climbing and weekly sprints
+- Friend challenges and seasonal events
+- Cohort promotions and demotions
+
+**Months 3-6 -- Social Contribution:**
+- Mentoring new users, content creation
+- Team challenges and collaborative achievements
+- Transition from extrinsic to intrinsic motivation
+
+**Months 6+ -- Mastery:**
+- Rare badges and prestige tiers
+- Community leadership roles
+- Legacy rewards and expertise signaling
+
+**Critical transitions:**
+- Day 1 to Day 2 is the biggest drop-off. End first session with an
+  unfinished streak to create return motivation.
+- Day 7 streak = 2.3x retention. Celebrate with a meaningful badge.
+- Activate social features at Week 2, not during onboarding.
+- Month 1-3: transition from extrinsic rewards to intrinsic motivation.
+
+### 3.2 Lapsed User Re-engagement
+
+**Lapse detected** (inactive 3+ days):
+- Day 3: Gentle push notification
+- Day 7: "We miss you" email
+- Day 10: Time-boxed XP multiplier offer (2x for 3 days)
+- Day 14: Social proof ("Your friends passed you")
+
+**Re-onboarding flow:**
+- Reduced initial goals (lower the bar)
+- "Welcome back" celebration (never shame)
+- Streak repair offer or partial credit
+- Graduated re-entry at lower difficulty
+- Quick win within first 30 seconds
+
+Re-engaged users are more valuable than newly acquired ones. Never use guilt
+language ("You've been gone for 23 days"). Frame return as positive.
+
+### 3.3 Streak Recovery Flow
+
+1. **Grace period** (0-24 hours): User has time to complete action and
+   maintain streak without penalty.
+2. **If action completed:** Streak saved, continue as normal.
+3. **If grace expires:** Check for streak freeze item.
+   - Available: Auto-apply freeze, notify user with encouraging message.
+   - Unavailable: Streak breaks.
+4. **Recovery options on break:**
+   - Repair streak for virtual currency (gems/coins)
+   - Start fresh with "comeback bonus" (XP multiplier)
+   - Accept reset with dignity
+5. **Compassionate reset messaging:**
+   - "Streaks reset, but your progress stays."
+   - Show total XP earned and badges kept.
+   - Offer easy win to start new streak immediately.
+   - Maintain "longest streak" record permanently.
+
+---
+
+## 4. Micro-Interactions
+
+Micro-interactions are the sensory feedback that makes gamification feel
+responsive. They are the difference between tracking progress and celebrating
+it.
+
+### 4.1 XP Counter Animation
+
+**Sequence:** XP increment appears near action point (+25 XP) with upward
+float and fade (200ms ease-out). Number flies toward header XP counter (300ms
+arc path). Counter performs bump animation (scale 1.0 to 1.15 to 1.0, 200ms).
+XP bar fills with smooth ease-in-out (400ms). Optional particle burst for
+significant actions.
+
+**Sound:** Soft ascending chime, 100-200ms. Pitch increases slightly with
+consecutive rapid completions to create a "combo" feel.
+
+**Accessibility:** Announce via `aria-live` region. Replace animations with
+instant state changes when `prefers-reduced-motion` is active.
+
+### 4.2 Badge Unlock
+
+**Sequence:** Current view dims slightly (20% overlay). Badge appears center-
+screen with scale-up (0 to 1.1 to 1.0, 400ms spring easing). Radial glow
+pulses outward (600ms). Name and description fade in (200ms delay, 300ms
+fade). Share and Dismiss CTAs appear. Confetti for rare/significant badges
+only -- avoid overuse.
+
+**Sound:** Two-note ascending tone (similar to Xbox achievement). Higher-tier
+badges get richer, longer sounds.
+
+**Accessibility:** Announce badge name and description via
+`aria-live="assertive"`. Ensure dismiss button receives auto-focus and is
+keyboard-accessible. Provide badge gallery for review at user's own pace.
+
+### 4.3 Level-Up Celebration
+
+**Sequence:** XP bar fills completely, then bursts (300ms). Full-screen or
+modal celebration with rolling counter from old level to new (500ms). Unlocked
+features cascade in one at a time (200ms intervals). Radial burst or confetti
+(800ms). CTA to explore new features or continue.
+
+**Sound:** Triumphant fanfare, 1-2 seconds. Distinct from badge unlocks.
+
+**Accessibility:** Dismissible via Escape key or tap-outside. Announce level
+change and new unlocks. Provide text summary alongside visuals. Replace
+confetti with static "Level Up!" card when `prefers-reduced-motion` is active.
+
+### 4.4 Streak Freeze
+
+**Sequence:** Streak icon transitions from fire to frost (orange to blue,
+400ms). Shield icon overlays the counter (200ms fade-in). Toast notification:
+"Streak Freeze activated! Your 15-day streak is safe." (3-second auto-
+dismiss). Optional frost particle effect (600ms).
+
+**Sound:** Crystalline/ice effect, brief and non-alarming.
+
+**Accessibility:** Announce freeze activation and current streak count. Also
+log in streak history (not just the transient toast notification).
+
+### 4.5 Leaderboard Position Change
+
+**Promotion:** User's row slides upward past displaced competitor (300ms
+ease-out). Rank number flashes highlight (200ms). Small upward green arrow
+appears (1-second fade). Optional motivational micro-copy.
+
+**Demotion:** Subtle downward slide (300ms, less dramatic). No celebratory
+effects. Neutral indicator -- avoid red. Motivational copy: "Just 12 XP to
+reclaim #7." No demotion sound (avoid punishing the user sensorially).
+
+**Accessibility:** Announce rank changes via `aria-live="polite"` (not
+assertive -- informational, not critical). Ensure leaderboard table is
+navigable via keyboard with clear row/column headers.
+
+---
+
+## 5. Anti-Patterns
+
+### 5.1 Forced Gamification
+Mandatory game mechanics with no opt-out in contexts users did not expect.
+Banking apps requiring badges to access features. **Fix:** Make all
+gamification optional. Provide a "classic" or "simple" mode.
+
+### 5.2 Meaningless Badges
+Awards for trivial actions ("You Changed Your Settings!"). Erodes the entire
+badge system. NNG: "Steer away from tired ideas like badges unless you have a
+new spin." **Fix:** Every badge must reinforce a behavior the product
+genuinely values.
+
+### 5.3 Pay-to-Win / Monetized Progress
+Allowing purchase of XP, badges, or leaderboard advantages. Destroys system
+credibility. No accomplishment in a purchase (CD2 violation). **Fix:**
+Monetize cosmetics and convenience, never achievement signals.
+
+### 5.4 Streak Anxiety / Guilt
+Streak mechanics creating psychological pressure and compulsive behavior.
+Snapchat's Snap Streaks cited as a source of significant anxiety among teens.
+"When the reward becomes the reason, the system shifts from motivation to
+behavioral dependence." **Fix:** Generous recovery mechanics, encouraging
+language, weekly streak alternatives, option to hide streaks entirely.
+
+### 5.5 Leaderboards That Discourage
+Global boards where the top user has 10,000 workouts and the average has 12.
+Demotivating for 99% of users. **Fix:** Cohort-based leaderboards,
+friend-only boards, percentile displays ("Top 25% this week"), opt-out.
+
+### 5.6 Fake Urgency / Artificial Scarcity
+"This badge expires in 2 hours!" when it recurs daily. Users discover
+deception and distrust all time-based mechanics thereafter. **Fix:** If
+scarcity is real (seasonal, one-time), it works. If fabricated, do not use it.
+Never create false countdown timers.
+
+### 5.7 Gamification of Serious Tasks
+Achievement badges in medical diagnosis apps. Leaderboards for workplace
+safety reporting. Trivializes critical contexts. **Fix:** Use progress
+visualization without game framing. Progress bars for treatment plans; skip
+the confetti and celebrations.
+
+### 5.8 Overwhelming Notifications
+Every gamification event triggers a push notification. Trains users to disable
+all notifications or uninstall. **Fix:** Batch low-priority events into daily
+digest. Max 1 gamification push per day. Granular per-type controls.
+
+### 5.9 Progress Resets Without Recovery
+Resetting a 200-day streak to zero with no freeze option and no record of
+prior achievement. Users who experience harsh resets often quit permanently.
+**Fix:** Maintain "longest streak" record. Offer recovery options. Frame
+reset as fresh start showing total lifetime progress (XP, badges kept).
+
+### 5.10 Competitive Mechanics in Collaborative Contexts
+Individual leaderboards in team tools incentivize claiming easy tasks over
+tackling important collaborative work. **Fix:** Team-based gamification.
+Reward collaborative behaviors explicitly (edits, reviews, mentoring).
+
+### 5.11 Overjustification Effect
+Adding point rewards to activities users already find intrinsically enjoyable.
+When points are removed, engagement drops below pre-gamification baseline.
+**Fix:** Use extrinsic rewards for onboarding and habit formation, then
+transition to intrinsic drivers. Never gamify activities users already
+perform willingly and consistently.
+
+### 5.12 Hidden Downgrade Mechanics
+Silently reducing rewards or increasing difficulty to force monetization.
+Users eventually notice and feel betrayed. Violates ETHIC framework
+Transparency principle. **Fix:** Communicate all economy changes before
+they take effect. Never silently degrade the experience to drive revenue.
+
+---
+
+## 6. Accessibility
+
+### 6.1 Visual Accessibility
+
+- Never rely on color alone for gamification state. Pair color with icons,
+  text labels, or patterns.
+- Badge icons must meet WCAG 2.1 AA contrast ratios (4.5:1 for text, 3:1
+  for UI components).
+- All badges need descriptive alt text: "Gold Pull Shark badge: merged 128
+  pull requests" -- not "badge icon."
+- Progress bars must use `role="progressbar"` with `aria-valuenow`,
+  `aria-valuemin`, `aria-valuemax`.
+- XP gains, level-ups, and streak changes announced via `aria-live` regions.
+- Leaderboard tables must use proper `<table>` semantics with `<th>` headers.
+- Badge unlock modals must trap focus and announce content immediately.
+
+### 6.2 Motion and Animation
+
+- All gamification animations must respect `prefers-reduced-motion`. Replace
+  animations with instant state changes when active.
+- WCAG 2.1 SC 2.3.3 (Animation from Interactions, Level AAA): motion
+  animation triggered by interaction can be disabled unless essential.
+- Provide explicit pause/stop/hide controls even for users without OS-level
+  motion preferences.
+- Never auto-play video celebrations without user control.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .xp-animation, .badge-unlock, .confetti, .level-up-celebration {
+    animation: none;
+    transition: none;
+  }
+}
+```
+
+### 6.3 Auditory Accessibility
+
+- All sound effects must be optional and independently controllable (separate
+  from system volume).
+- Provide visual equivalents for all audio feedback (vibration on mobile,
+  visual flash indicators).
+- Never rely on audio alone to communicate gamification events.
+- Provide captions for narrative audio content (guided runs, coached sessions).
+
+### 6.4 Motor Accessibility
+
+- All gamification interactions must be keyboard-operable.
+- Badge unlock modals dismissible via Escape key.
+- Leaderboards navigable with arrow keys and Tab.
+- Swipe-based interactions (scratch cards, spin wheels) must have tap/click
+  alternatives.
+- Time-limited actions must have extended time options or alternatives.
+
+### 6.5 Cognitive Accessibility
+
+- Plain language: "Complete 3 lessons" -- not "Embark on a triple-quest
+  learning odyssey."
+- Sequence simultaneous gamification events (badge + level-up + leaderboard
+  change) with adequate processing time between them.
+- Provide a gamification settings panel to simplify or disable individual
+  mechanics.
+- Gamification must not interfere with the primary task flow. All game
+  elements should be dismissible without losing progress on the underlying
+  task.
+- Consistent visual language: if a flame icon means streak, never repurpose
+  it for "hot deals."
+
+---
+
+## 7. Cross-Platform Adaptation
+
+### 7.1 Mobile Widgets
+
+- Streak widgets (iOS WidgetKit / Android App Widgets): display current
+  streak count, daily goal progress, and next milestone.
+- Widget tap deep-links to most relevant in-app action (e.g., start today's
+  lesson).
+- Support small (2x2) and medium (4x2) widget sizes.
+- Dark/light mode variants mandatory. Test at all Dynamic Type / font scale
+  sizes.
+- Apple Live Activities: real-time streak progress on lock screen and Dynamic
+  Island during active sessions.
+
+### 7.2 Push Notifications
+
+| Event                 | Push? | Timing                  | Tone                          |
+|-----------------------|-------|-------------------------|-------------------------------|
+| Streak at risk        | Yes   | 2hr before deadline     | Encouraging, not guilt-based  |
+| Streak broken         | Yes   | Morning after            | Compassionate, offer recovery |
+| Badge earned          | No    | In-app only             | Celebratory                   |
+| Level up              | No    | In-app only             | Celebratory                   |
+| Friend challenge      | Yes   | Immediate               | Social, casual                |
+| Leaderboard overtaken | Maybe | Batched, 1x daily max   | Motivational                  |
+| Weekly digest         | Yes   | Sunday evening           | Summary, forward-looking      |
+| Re-engagement         | Yes   | Day 3, 7, 14 of lapse   | Warm, value-focused           |
+
+**Best practices:** Max 1 gamification push per day. Include direct action
+("Tap to save your streak"). Use rich notifications with badge artwork where
+supported. A/B test copy (Duolingo's optimization drove 25% engagement
+boost). Provide granular in-app preferences per event type. Honor Do Not
+Disturb and Focus modes.
+
+### 7.3 Wearables
+
+- Streak counts and goal progress on watch complications (Apple Watch) and
+  tiles (Wear OS).
+- Haptic feedback for goal completion (Fitbit's celebratory vibration).
+- One-tap max interactions on wearables.
+- Real-time cross-device sync to prevent confusion.
+
+### 7.4 Desktop / Web
+
+- Gamification elements present but less intrusive. Professional contexts
+  (LinkedIn, GitHub) use subtle indicators over modal celebrations.
+- Browser notifications opt-in and used sparingly.
+- Keyboard shortcuts for dismissing gamification overlays (Escape key).
+
+### 7.5 Cross-Device Synchronization
+
+- Gamification state must sync in real-time across all platforms.
+- Offline actions must sync retroactively without penalizing the user.
+- Device-agnostic messaging: "Complete your daily goal" -- not "Open the app."
+
+---
+
+## 8. Decision Tree
+
+### 8.1 When Gamification Helps
+
+- Core activity is boring or repetitive --> Gamification adds engagement.
+- Users need to build a habit over time --> Streaks, daily challenges,
+  progress tracking.
+- Clear learning curve or skill progression --> Levels, skill trees, mastery
+  indicators.
+- Users benefit from social comparison --> Cohort leaderboards, team
+  challenges.
+- Context is appropriate for playfulness --> Full toolkit available.
+
+### 8.2 When Gamification Hurts
+
+- Emergency or safety contexts (gamifying incident reports trivializes them).
+- Grief, health crisis, or sensitive personal contexts.
+- Mandatory participation with no user choice (breeds resentment).
+- Core product is fundamentally broken (fix the product first).
+- Metrics easily gamed (rewards wrong behaviors).
+- High-stakes professional contexts (legal, medical, financial).
+
+### 8.3 Mechanic Selection by Goal
+
+| Goal                     | Primary Mechanics                        | Secondary                     |
+|--------------------------|------------------------------------------|-------------------------------|
+| Daily habit formation    | Streaks, daily challenges, push reminders| XP, progress bars             |
+| Skill development        | Levels, skill trees, mastery indicators  | Badges, challenges            |
+| Content completion       | Progress bars, checklists, unlockables   | Badges, XP                    |
+| Community building       | Team challenges, collaborative badges    | Leaderboards, social rewards  |
+| Onboarding               | Checklists, first-win flow               | Progress bars, XP             |
+| Retention                | Streaks, daily quests, limited events    | Push notifications, XP decay  |
+| Social sharing           | Shareable achievements, friend challenges| Leaderboards, referral badges |
+| Knowledge contribution   | Reputation, privilege unlocks, tag scores| Badges, bounties              |
+| Profile completion       | Progress bars, completion rewards        | Badges, social proof copy     |
+| Re-engagement            | XP multipliers, streak recovery          | Reduced difficulty, quick wins|
+
+### 8.4 Octalysis Core Drive Mapping
+
+| Core Drive                              | Type       | Key Mechanics                         |
+|-----------------------------------------|------------|---------------------------------------|
+| 1. Epic Meaning and Calling             | White Hat  | Narrative quests, community missions  |
+| 2. Development and Accomplishment       | White Hat  | XP, levels, badges, progress bars     |
+| 3. Empowerment of Creativity & Feedback | White Hat  | Custom challenges, creative tools     |
+| 4. Ownership and Possession             | White Hat  | Virtual currency, collections         |
+| 5. Social Influence and Relatedness     | White Hat  | Leaderboards, team challenges         |
+| 6. Scarcity and Impatience              | Black Hat  | Limited-time events, unlockables      |
+| 7. Unpredictability and Curiosity       | Black Hat  | Random rewards, hidden badges         |
+| 8. Loss and Avoidance                   | Black Hat  | Streaks, countdowns, expiring items   |
+
+**White Hat drives (1-5)** make users feel powerful, fulfilled, and in
+control. They sustain long-term engagement and positive sentiment.
+
+**Black Hat drives (6-8)** create urgency, curiosity, and fear of loss. They
+drive short-term action but risk anxiety and burnout if overused.
+
+**Best practice:** Aim for 70%+ White Hat mechanics. Use Black Hat sparingly
+and ethically for specific tactical goals. Always pair Black Hat mechanics
+with recovery options and user control.
+
+---
+
+## 9. Ethical Gamification Principles
+
+### 9.1 The ETHIC Framework
+
+- **Empowerment:** Users feel more capable, not more dependent. If removing
+  gamification collapses engagement, the system creates dependency, not
+  empowerment.
+- **Transparency:** Display XP calculations, badge criteria, and leaderboard
+  algorithms openly. Hidden mechanics erode trust.
+- **Humanity:** Design for wellbeing, not just engagement metrics. Monitor
+  for compulsive behavior. Build safeguards (break reminders, session caps).
+- **Intentional Alignment:** Gamification goals must align with user goals.
+  "Learn Spanish" vs. "maximize daily app opens" is a misalignment that
+  will eventually frustrate users.
+- **Customization/Control:** Users adjust, disable, or opt out of gamification
+  without losing access to core functionality.
+
+### 9.2 Core Ethical Principles
+
+**Autonomy preservation:** Users should feel motivated, not compelled. NNG
+emphasizes that gamification should offer "varying degrees of freedom in
+choosing their path through the experience." If users engage to relieve
+anxiety rather than pursue genuine goals, a dark pattern has been created.
+
+**Proportional reinforcement:** Reward magnitude matches effort magnitude.
+Over-rewarding trivial actions devalues the system; under-rewarding
+significant effort creates frustration. Avoid slot-machine mechanics
+(variable-ratio reinforcement) in non-entertainment contexts.
+
+**Wellbeing monitoring:** Track session length distribution, streak anxiety
+signals (users completing actions at 11:59 PM consistently), and negative
+sentiment in feedback. Build break reminders and engagement caps where
+overuse is harmful.
+
+**Honest representation:** Badges and levels must represent genuine
+achievement. Leaderboard positions reflect real standing, not algorithmically
+manipulated rankings designed to keep users "almost" at the next level.
+
+**Inclusive design:** Gamification must not create two tiers of users. Core
+functionality must be equally accessible regardless of gamification
+participation. Competitive mechanics must not systematically disadvantage
+users with disabilities or limited time.
+
+### 9.3 Self-Determination Theory Alignment (NNG)
+
+- **Autonomy:** Users choose to engage. Gamification invites, never coerces.
+- **Competence:** Progress tracks real skill development, not just time spent.
+- **Relatedness:** Social mechanics build community, not just competition.
+
+When all three needs are met, intrinsic motivation develops alongside
+extrinsic gamification, creating sustainable engagement that persists even
+when game mechanics are reduced.
+
+---
+
+## 10. Quick Reference Checklist
+
+### Pre-Design
+- [ ] Business goals and user goals identified and aligned
+- [ ] Context validated as appropriate for gamification
+- [ ] Target behaviors mapped to Octalysis Core Drives
+- [ ] White Hat / Black Hat ratio planned (aim 70/30+)
+
+### Mechanic Design
+- [ ] Every badge corresponds to a meaningful behavior
+- [ ] XP economy calibrated (quick early wins, challenging mid-game)
+- [ ] Levels unlock meaningful capabilities or content
+- [ ] Streaks include recovery mechanics (freezes, grace periods)
+- [ ] Leaderboards are cohort/friend-based, not global-only
+- [ ] Progress bars use endowed progress (start 10-15% filled)
+- [ ] Onboarding delivers first win within 60 seconds
+- [ ] Reward schedules mix fixed and variable elements
+
+### User Control
+- [ ] All gamification elements can be hidden/disabled
+- [ ] Granular push notification preferences per event type
+- [ ] Users can opt out of leaderboards and social comparison
+- [ ] Core functionality accessible without gamification participation
+- [ ] Break reminders or session limits implemented where appropriate
+
+### Accessibility
+- [ ] All animations respect `prefers-reduced-motion`
+- [ ] Badges have descriptive alt text for screen readers
+- [ ] Progress bars use proper ARIA roles (progressbar + valuenow/min/max)
+- [ ] Leaderboard tables use semantic HTML with proper headers
+- [ ] Color never sole indicator of gamification state
+- [ ] All modals keyboard-dismissible (Escape key)
+- [ ] Sound effects optional and independently controllable
+
+### Ethical Review
+- [ ] No guilt-inducing language for missed activities or broken streaks
+- [ ] No fake urgency or artificial scarcity for recurring events
+- [ ] No monetization of achievement signals (badges, levels, rank)
+- [ ] No hidden mechanics or undisclosed economy changes
+- [ ] Gamification does not trivialize serious user contexts
+- [ ] Competitive mechanics appropriate for social context
+- [ ] Wellbeing indicators monitored alongside engagement metrics
+
+### Cross-Platform
+- [ ] Gamification state syncs real-time across all platforms
+- [ ] Max 1 gamification push notification per day
+- [ ] Offline actions sync retroactively without penalty
+- [ ] Wearable integrations use haptic feedback for goal completion
+- [ ] Widgets display correctly across sizes and accessibility settings
+
+### Post-Launch Monitoring
+- [ ] Badge earn rates tracked (<5% too hard, >95% too easy)
+- [ ] Streak length distribution and anxiety indicators monitored
+- [ ] A/B testing gamified vs. non-gamified controls
+- [ ] Quarterly user sentiment surveys on gamification
+- [ ] Stale or low-engagement mechanics reviewed and retired
+
+---
+
+## References
+
+- [Yu-Kai Chou, Octalysis Framework](https://yukaichou.com/gamification-examples/octalysis-gamification-framework/)
+- [Yu-Kai Chou, Streak Design](https://yukaichou.com/gamification-study/master-the-art-of-streak-design-for-short-term-engagement-and-long-term-success/)
+- [NNG, Autonomy/Relatedness/Competence](https://www.nngroup.com/articles/autonomy-relatedness-competence/)
+- [NNG, Social Media and Gamification](https://www.nngroup.com/videos/social-media-gamification/)
+- [Sam Liberty, The ETHIC Framework](https://sa-liberty.medium.com/the-ethic-framework-designing-ethical-gamification-that-actually-works-50fa57c75610)
+- [Stack Overflow Badges Explained](https://stackoverflow.blog/2021/04/12/stack-overflow-badges-explained/)
+- [Duolingo Gamification Case Study](https://trophy.so/blog/duolingo-gamification-case-study)
+- [GitHub Gamification Case Study](https://trophy.so/blog/github-gamification-case-study)
+- [Nike Run Club Gamification](https://trophy.so/blog/nike-run-club-gamification-case-study)
+- [Ethical Gamification and User Wellbeing](https://blog.prototypr.io/ethical-gamification-designing-for-user-well-being-in-the-age-of-addictive-tech-85fe9d16f130)
+- [Streak Design for Long-Term Growth](https://trophy.so/blog/designing-streaks-for-long-term-user-growth)
+- [WCAG 2.1 Animation from Interactions](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html)
+- [LinkedIn Gamification Analysis](https://thomas-lindemann.com/gamification-en/how-linkedin-uses-gamification-to-boost-engagement/)
+- [Re-engagement Gamification Patterns](https://strivecloud.io/blog/gamification-examples-reengagement/)
+- [Dark Patterns in Gamification](https://medium.com/@neil_62402/gamification-dark-patterns-light-patterns-and-psychology-9442d49f8b56)