# Theme System

The LinkedIn MCP Design System provides **10 pre-built themes** for different LinkedIn personas and content strategies. Themes define your voice, tone, and posting patterns.

## Overview

A **theme** is a complete content strategy that defines:
- Voice & tone
- Content mix (educational/personal/promotional)
- Formatting preferences
- Engagement style
- Posting frequency
- Preferred post formats

Think of themes as **LinkedIn personas** - each optimized for a specific goal.

---

## The 10 Pre-Built Themes

### 1. Thought Leader 🎯

**Description:** Establish expertise and industry authority

**Profile:**
- **Tone:** Professional
- **Formality:** Conversational
- **Emotion:** Analytical
- **Primary Goal:** Authority

**Content Mix:**
- Educational: 60%
- Personal: 20%
- Promotional: 20%

**Formatting:**
- Emoji Level: Minimal
- Line Breaks: Scannable
- Paragraph Length: Standard

**Strategy:**
- Preferred Structures: Framework, Listicle, Comparison
- Hook Style: Stat (0.9 power)
- CTA Style: Curiosity
- Hashtag Strategy: Minimal (1-2 targeted)
- Post Frequency: **4x per week**

**Best Formats:**
- Text posts with frameworks
- Document posts (deep dives)
- Carousel posts (data)

**Use When:**
- Building industry credibility
- Positioning as expert
- Attracting consulting clients
- Speaking opportunities

**Example Hook:**
> "80% of executives say thought leadership influences buying decisions."

---

### 2. Personal Brand 🌟

**Description:** Build authentic personal connection and following

**Profile:**
- **Tone:** Inspirational
- **Formality:** Friendly
- **Emotion:** Warm
- **Primary Goal:** Engagement

**Content Mix:**
- Personal: 50%
- Educational: 30%
- Promotional: 20%

**Formatting:**
- Emoji Level: Moderate
- Line Breaks: Dramatic
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Story Arc, Linear, Question-Based
- Hook Style: Story (0.85 power)
- CTA Style: Share
- Hashtag Strategy: Mixed
- Post Frequency: **5x per week**

**Best Formats:**
- Text posts (personal stories)
- Image posts (moments)
- Video posts (authenticity)

**Use When:**
- Building personal following
- Sharing journey/lessons
- Creating relatability
- Inspiring others

**Example Hook:**
> "I almost quit my job in 2023. Here's what happened next..."

---

### 3. Technical Expert 🔧

**Description:** Deep technical knowledge and precision

**Profile:**
- **Tone:** Technical
- **Formality:** Formal
- **Emotion:** Analytical
- **Primary Goal:** Authority

**Content Mix:**
- Educational: 70%
- Personal: 10%
- Promotional: 20%

**Formatting:**
- Emoji Level: None
- Line Breaks: Readable
- Paragraph Length: Standard

**Strategy:**
- Preferred Structures: Listicle, Framework, Linear
- Hook Style: Question
- CTA Style: Direct
- Hashtag Strategy: Niche (industry-specific)
- Post Frequency: **3x per week**

**Best Formats:**
- Text posts (technical)
- Document posts (guides)
- Carousel posts (tutorials)

**Use When:**
- Demonstrating technical depth
- Teaching technical concepts
- Attracting technical audience
- Establishing niche expertise

**Example Hook:**
> "How can microservices architecture scale to 10M requests per second?"

---

### 4. Community Builder 🤝

**Description:** Foster connection and conversation

**Profile:**
- **Tone:** Casual
- **Formality:** Friendly
- **Emotion:** Playful
- **Primary Goal:** Community

**Content Mix:**
- Personal: 40%
- Educational: 40%
- Promotional: 20%

**Formatting:**
- Emoji Level: Expressive
- Line Breaks: Scannable
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Question-Based, Story Arc, Listicle
- Hook Style: Question (0.8 power)
- CTA Style: Curiosity
- Hashtag Strategy: Trending
- Hashtag Placement: First Comment
- Post Frequency: **5x per week**

**Best Formats:**
- Poll posts (engagement!)
- Text posts (questions)
- Video posts (behind-scenes)

**Use When:**
- Building engaged community
- Fostering discussions
- Creating loyal following
- Networking authentically

**Example Hook:**
> "What's your biggest LinkedIn challenge in 2025?"

---

### 5. Corporate Professional 🏢

**Description:** Polished corporate communication

**Profile:**
- **Tone:** Professional
- **Formality:** Formal
- **Emotion:** Neutral
- **Primary Goal:** Awareness

**Content Mix:**
- Educational: 50%
- Promotional: 30%
- Personal: 20%

**Formatting:**
- Emoji Level: Minimal
- Line Breaks: Readable
- Paragraph Length: Standard

**Strategy:**
- Preferred Structures: Linear, Listicle, Comparison
- Hook Style: Stat
- CTA Style: Direct
- Hashtag Strategy: Branded
- Post Frequency: **3x per week**

**Best Formats:**
- Document posts (reports)
- Image posts (announcements)
- Article posts (resources)

**Use When:**
- Representing company
- Professional announcements
- Maintaining corporate image
- B2B marketing

**Example Hook:**
> "Our Q4 results show 25% YoY growth across all segments."

---

### 6. Contrarian Voice 🔥

**Description:** Challenge status quo, spark debate

**Profile:**
- **Tone:** Professional
- **Formality:** Conversational
- **Emotion:** Passionate
- **Primary Goal:** Engagement

**Content Mix:**
- Educational: 50%
- Personal: 30%
- Promotional: 20%

**Formatting:**
- Emoji Level: Minimal
- Line Breaks: Dramatic
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Linear, Comparison, Question-Based
- Hook Style: **Controversy (0.95 power)** 🔥
- CTA Style: Curiosity
- Hashtag Strategy: Minimal
- Hashtag Placement: Mid-post
- Post Frequency: **4x per week**

**Best Formats:**
- Text posts (hot takes)
- Carousel posts (comparisons)
- Video posts (rants)

**Use When:**
- Standing out from crowd
- Challenging industry norms
- Sparking debates
- Building thought leadership

**Example Hook:**
> "Unpopular opinion: Most LinkedIn advice is terrible."

---

### 7. Storyteller 📖

**Description:** Narrative-driven, emotional connection

**Profile:**
- **Tone:** Inspirational
- **Formality:** Conversational
- **Emotion:** Warm
- **Primary Goal:** Engagement

**Content Mix:**
- Personal: 60%
- Educational: 30%
- Promotional: 10%

**Formatting:**
- Emoji Level: Moderate
- Line Breaks: Dramatic
- Paragraph Length: Loose

**Strategy:**
- Preferred Structures: **Story Arc**, Linear
- Hook Style: Story (0.85 power)
- CTA Style: Soft
- Hashtag Strategy: Minimal
- Post Frequency: **4x per week**

**Best Formats:**
- Text posts (long-form stories)
- Video posts (personal)
- Image posts (moments)

**Use When:**
- Sharing personal journey
- Building emotional connection
- Teaching through stories
- Creating memorable content

**Example Hook:**
> "The email that changed my career arrived at 2 AM on a Tuesday."

---

### 8. Data-Driven Analyst 📊

**Description:** Let the numbers tell the story

**Profile:**
- **Tone:** Professional
- **Formality:** Conversational
- **Emotion:** Analytical
- **Primary Goal:** Authority

**Content Mix:**
- Educational: 70%
- Personal: 10%
- Promotional: 20%

**Formatting:**
- Emoji Level: Minimal
- Line Breaks: Scannable
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Listicle, Comparison, Framework
- Hook Style: **Stat (0.9 power)**
- CTA Style: Direct
- Hashtag Strategy: Niche
- Post Frequency: **3x per week**

**Best Formats:**
- **Document posts** (data reports) 📈
- Carousel posts (stats)
- Image posts (data viz)

**Use When:**
- Sharing research findings
- Data-driven insights
- Establishing analytical authority
- B2B credibility

**Example Hook:**
> "Our analysis of 1M+ posts reveals: Document posts get 45.85% engagement."

---

### 9. Coach/Mentor 🎓

**Description:** Guide and support your audience

**Profile:**
- **Tone:** Inspirational
- **Formality:** Friendly
- **Emotion:** Warm
- **Primary Goal:** Community

**Content Mix:**
- Educational: 50%
- Personal: 40%
- Promotional: 10%

**Formatting:**
- Emoji Level: Moderate
- Line Breaks: Scannable
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Framework, Question-Based, Listicle
- Hook Style: Question
- CTA Style: **Action** (0.75 power)
- Hashtag Strategy: Optimal (3-5)
- Post Frequency: **5x per week**

**Best Formats:**
- Text posts (advice)
- Carousel posts (tips)
- Video posts (teaching)

**Use When:**
- Coaching/mentoring
- Sharing actionable advice
- Building supportive community
- Teaching frameworks

**Example Hook:**
> "5 LinkedIn mistakes I see every day (and how to fix them):"

---

### 10. The Entertainer 🎭

**Description:** Make LinkedIn fun and memorable

**Profile:**
- **Tone:** Humorous
- **Formality:** Casual
- **Emotion:** Playful
- **Primary Goal:** Engagement

**Content Mix:**
- Personal: 50%
- Educational: 30%
- Promotional: 20%

**Formatting:**
- Emoji Level: Expressive
- Line Breaks: Dramatic
- Paragraph Length: Tight

**Strategy:**
- Preferred Structures: Story Arc, Linear, Question-Based
- Hook Style: **Curiosity (0.75 power)**
- CTA Style: Share (0.9 power)
- Hashtag Strategy: Trending
- Hashtag Placement: First Comment
- Post Frequency: **5x per week**

**Best Formats:**
- Text posts (humor)
- Video posts (comedy)
- Image posts (memes)

**Use When:**
- Standing out with personality
- Building memorable brand
- Making LinkedIn enjoyable
- Viral potential

**Example Hook:**
> "LinkedIn in 2025: Where professionals pretend to work while actually scrolling."

---

## Theme Comparison Matrix

| Theme | Goal | Frequency | Emoji | Controversy | Best Format |
|-------|------|-----------|-------|-------------|-------------|
| Thought Leader | Authority | 4/week | Minimal | Moderate | Document |
| Personal Brand | Engagement | 5/week | Moderate | Safe | Text/Video |
| Technical Expert | Authority | 3/week | None | Safe | Document |
| Community Builder | Community | 5/week | Expressive | Safe | Poll |
| Corporate Professional | Awareness | 3/week | Minimal | Safe | Document |
| Contrarian Voice | Engagement | 4/week | Minimal | **Bold** | Text |
| Storyteller | Engagement | 4/week | Moderate | Safe | Text |
| Data-Driven | Authority | 3/week | Minimal | Moderate | Document |
| Coach/Mentor | Community | 5/week | Moderate | Safe | Text/Carousel |
| Entertainer | Engagement | 5/week | Expressive | Moderate | Text/Video |

---

## Using Themes in Code

### Getting a Theme

```python
from chuk_mcp_linkedin import ThemeManager

theme_mgr = ThemeManager()

# Get a pre-built theme
theme = theme_mgr.get_theme("thought_leader")

# List all available themes
themes = theme_mgr.list_themes()
print(themes)
# ['thought_leader', 'personal_brand', 'technical_expert', ...]

# Get theme summary
summary = theme_mgr.get_theme_summary("thought_leader")
print(summary)
# {
#   'name': 'Thought Leader',
#   'description': 'Establish expertise and industry authority',
#   'tone': 'professional',
#   'goal': 'authority',
#   'post_frequency': '4x per week',
#   'best_formats': ['text', 'document', 'carousel'],
#   'emoji_level': 'minimal',
#   'controversy_level': 'moderate'
# }
```

### Using Theme with Post

```python
from chuk_mcp_linkedin import ComposablePost, ThemeManager

# Get theme
theme = ThemeManager().get_theme("thought_leader")

# Create post with theme
post = ComposablePost("text", theme=theme)

# Theme automatically applies:
# - emoji_level: "minimal"
# - line_break_style: "scannable"
# - hook_style: "stat"
# - cta_style: "curiosity"
# - hashtag_strategy: "minimal"

post.add_hook("stat", "80% of decision makers prefer thought leadership")
post.add_body("Here's what works...", structure="framework")
post.add_cta("curiosity", "What's your strategy?")

final_text = post.compose()
```

### Creating Custom Theme

```python
from chuk_mcp_linkedin import ThemeManager

theme_mgr = ThemeManager()

# Create custom theme
custom_theme = theme_mgr.create_custom_theme(
    name="Tech Founder",
    description="Blend of technical depth and startup hustle",
    tone="technical",
    formality="conversational",
    emotion="passionate",
    primary_goal="authority",
    content_mix={"educational": 0.5, "personal": 0.3, "promotional": 0.2},
    emoji_level="minimal",
    line_break_style="scannable",
    paragraph_length="tight",
    preferred_structures=["framework", "listicle", "story_arc"],
    hook_style="stat",
    cta_style="curiosity",
    hashtag_strategy="niche",
    hashtag_placement="end",
    comment_style="thoughtful",
    controversy_level="bold",
    vulnerability_level="selective",
    humor_level="subtle",
    preferred_formats=["text", "document", "video"],
    media_frequency=0.4,
    post_frequency=5,
    best_posting_times=["morning", "evening"]
)

# Use custom theme
post = ComposablePost("text", theme=custom_theme)
```

---

## Theme Recommendations by Goal

Use the Component Registry to get theme recommendations:

```python
from chuk_mcp_linkedin import ComponentRegistry

registry = ComponentRegistry()

# Get recommendations for "engagement" goal
recs = registry.get_recommendations("engagement")

print(f"Recommended theme: {recs['theme']}")
# Output: community_builder

print(f"Top formats: {recs['top_formats']}")
# Output: ['poll_post', 'video_post', 'text_post', 'image_post']

print(f"Best practices:")
for practice in recs['best_practices']:
    print(f"  - {practice}")
```

### Goal → Theme Mapping

| Goal | Recommended Theme | Why |
|------|------------------|-----|
| **Engagement** | Community Builder | Poll-focused, question-driven, high frequency |
| **Authority** | Thought Leader | Framework-focused, data-driven, minimal emoji |
| **Leads** | Corporate Professional | Document-heavy, professional, clear CTAs |
| **Community** | Coach/Mentor | Supportive, educational, action-oriented |
| **Awareness** | Personal Brand | Story-driven, authentic, mixed formats |

---

## Theme Best Practices

### 1. Choose ONE Primary Theme

Don't try to be everything. Pick a theme that matches:
- Your natural voice
- Your audience
- Your business goals

### 2. Stay Consistent

Use your theme for at least 30 days before switching. The algorithm rewards consistency.

### 3. Mix Content Types

Even within a theme, vary your post types:
- 60% primary format
- 30% secondary formats
- 10% experimental

### 4. Adjust for Audience Response

Monitor what works:
- Which hooks get most clicks?
- Which CTAs drive comments?
- Which formats get shares?

Adjust your theme parameters based on data.

### 5. Combine Themes Strategically

You can blend themes:
- 70% Thought Leader + 30% Storyteller
- 60% Data-Driven + 40% Contrarian Voice
- 80% Coach/Mentor + 20% Entertainer

---

## Theme Integration with System

Themes work with all system components:

### With Variants

```python
from chuk_mcp_linkedin import PostVariants, VariantResolver, ThemeManager

# Theme influences variant resolution
theme = ThemeManager().get_theme("thought_leader")
variants = PostVariants.text_post_variants()
selected = {"style": "insight", "tone": "professional", "length": "medium"}

# Theme overrides applied during resolution
config = VariantResolver.resolve(variants, selected, theme=theme)
# Theme's emoji_level, line_break_style, etc. are applied
```

### With Composition

```python
from chuk_mcp_linkedin import PostBuilder, ThemeManager

theme = ThemeManager().get_theme("storyteller")

# Theme determines story formatting
post = PostBuilder.story_post(
    hook="Last year changed everything...",
    problem="...",
    journey="...",
    solution="...",
    lesson="...",
    theme=theme  # Applies dramatic line breaks, moderate emoji
)
```

### With Draft Management

```python
from chuk_mcp_linkedin import LinkedInManager

manager = LinkedInManager()

# Create draft with theme
draft = manager.create_draft(
    name="Q4 Update",
    post_type="text",
    theme="data_driven"  # Theme name as string
)
```

---

## Advanced: Multi-Theme Strategy

For variety, rotate themes by day:

```python
WEEKLY_ROTATION = {
    "monday": "thought_leader",      # Start week with authority
    "tuesday": "data_driven",        # Mid-week insights
    "wednesday": "community_builder", # Engagement day
    "thursday": "storyteller",       # Personal connection
    "friday": "entertainer"          # End week fun
}

import datetime
today = datetime.datetime.now().strftime("%A").lower()
theme_name = WEEKLY_ROTATION.get(today, "thought_leader")
theme = ThemeManager().get_theme(theme_name)
```

---

## Measuring Theme Effectiveness

Track these metrics per theme:

1. **Engagement Rate** - Comments + Likes + Shares / Impressions
2. **First Hour Engagement** - Critical algorithm signal
3. **Comment Quality** - Deep discussions vs. emoji reactions
4. **Profile Clicks** - Are people interested in learning more?
5. **Follower Growth** - Net new followers per week

Optimal themes show:
- 3-5% engagement rate
- 50+ first hour engagements
- 30%+ comment quality
- 5%+ profile click rate
- Steady follower growth

---

## Next Steps

- Read [TOKENS.md](./TOKENS.md) to understand design tokens
- See [examples/complete_example.py](../examples/complete_example.py) for theme usage
- Try different themes and track your results!

---

## Quick Reference

```python
# Import
from chuk_mcp_linkedin import ThemeManager, ComposablePost

# Get theme
theme = ThemeManager().get_theme("thought_leader")

# Use with post
post = ComposablePost("text", theme=theme)

# List all themes
ThemeManager().list_themes()
# Returns: ['thought_leader', 'personal_brand', ...]

# Get recommendations
from chuk_mcp_linkedin import ComponentRegistry
ComponentRegistry().get_recommendations("engagement")
```
