Mastodon DESIGN.md

Decentralized, open-source social network with privacy-first design. Mastodon Purple (#6364FF) accent, dark immersive theme, multi-column TweetDeck-style interface, federation-aware UI patterns.

1. Visual Theme & Atmosphere

Overall Aesthetic

Mastodon embraces a privacy-conscious, community-driven design philosophy. The interface feels like a thoughtfully crafted space that respects user autonomy—dark, focused, and intentionally free from dark patterns. Every element is designed to promote healthy social interaction while giving users control over their experience.

Mood & Feeling

• Open & Transparent: The open-source ethos extends to design—no hidden features, clear navigation
• Calm & Focused: Dark backgrounds reduce eye strain and create a distraction-free reading experience
• Community-First: Instance branding, federation indicators, and local/federated timelines emphasize decentralization
• Privacy-Respectful: Content warnings, granular visibility controls, and clear data handling

Design Density

Medium-high density with intentional information hierarchy. The multi-column layout allows power users to monitor multiple timelines simultaneously while maintaining readability. Single-column mode provides a cleaner experience for focused browsing.

Visual Character

• Clean, functional design without unnecessary decoration
• Subtle rounded corners for approachability
• Clear visual hierarchy through background layering
• Federation indicators (instance badges, remote user markers)
• Content warning system as first-class UI element
• Boost and favorite actions clearly distinguished
• Accessible, screen-reader friendly patterns

2. Color Palette & Roles

Primary Dark Theme

Brand Colors

Text Colors

Semantic Colors

Federation Indicators

Light Theme (Alternate)

3. Typography Rules

Font Stack

css/* Primary system font stack */
--font-primary: 'mastodon-font-sans-serif', system-ui, -apple-system, 
                BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, 
                Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 
                sans-serif;

/* Monospace for code and technical content */
--font-mono: 'mastodon-font-monospace', ui-monospace, 'Cascadia Mono', 
             'Segoe UI Mono', 'Liberation Mono', Menlo, Monaco, Consolas, 
             monospace;

/* Display font for marketing/landing pages */
--font-display: 'Poppins', var(--font-primary);

Type Scale

Font Weights

Post Content Typography

css/* Post text with proper wrapping and overflow */
.post-content {
  font-size: 15px;
  line-height: 22px;
  color: #9baec8;
  word-wrap: break-word;
  overflow-wrap: break-word;
}

/* Hashtags and mentions */
.hashtag,
.mention {
  color: #6364FF;
  text-decoration: none;
}

.hashtag:hover,
.mention:hover {
  text-decoration: underline;
}

/* Content warnings */
.content-warning {
  font-size: 15px;
  font-weight: 500;
  color: #ffffff;
}

4. Component Stylings

Buttons

Primary Button (Purple)

css.button-primary {
  background: #6364FF;
  color: #ffffff;
  font-size: 14px;
  font-weight: 600;
  padding: 10px 18px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
  transition: background-color 100ms ease-in-out;
}

.button-primary:hover {
  background: #7477FF;
}

.button-primary:active {
  background: #5253E0;
}

.button-primary:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

Secondary Button (Outlined)

css.button-secondary {
  background: transparent;
  color: #6364FF;
  font-size: 14px;
  font-weight: 600;
  padding: 9px 17px;
  border-radius: 4px;
  border: 1px solid #6364FF;
  cursor: pointer;
}

.button-secondary:hover {
  background: rgba(99, 100, 255, 0.1);
}

Danger Button

css.button-danger {
  background: #df405a;
  color: #ffffff;
}

.button-danger:hover {
  background: #e85e73;
}

Icon Button (Actions)

css.button-icon {
  background: transparent;
  color: #606984;
  padding: 8px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
  transition: all 100ms ease-in-out;
}

.button-icon:hover {
  color: #6364FF;
  background: rgba(99, 100, 255, 0.1);
}

/* Boost action */
.button-icon.boost:hover,
.button-icon.boost.active {
  color: #2b90d9;
}

/* Favorite action */
.button-icon.favorite:hover,
.button-icon.favorite.active {
  color: #ca8f04;
}

Inputs

Text Input

css.input {
  background: #1f232b;
  border: 1px solid #393f4f;
  border-radius: 4px;
  color: #ffffff;
  font-size: 15px;
  padding: 10px 12px;
  width: 100%;
  transition: border-color 100ms ease-in-out;
}

.input:focus {
  outline: none;
  border-color: #6364FF;
}

.input::placeholder {
  color: #606984;
}

Compose Text Area

css.compose-textarea {
  background: #282c37;
  border: none;
  border-radius: 4px;
  color: #ffffff;
  font-size: 15px;
  line-height: 22px;
  padding: 12px;
  resize: none;
  min-height: 100px;
}

.compose-textarea::placeholder {
  color: #606984;
}

.compose-textarea:focus {
  outline: none;
}

Search Input

css.search-input {
  background: #1f232b;
  border: 1px solid transparent;
  border-radius: 8px;
  color: #ffffff;
  font-size: 14px;
  padding: 10px 12px 10px 40px;
  width: 100%;
}

.search-input:focus {
  border-color: #6364FF;
  background: #282c37;
}

Cards

Toot/Post Card

css.toot-card {
  background: #282c37;
  border-bottom: 1px solid #393f4f;
  padding: 14px 16px;
}

.toot-card:hover {
  background: #2c313d;
}

.toot-avatar {
  width: 46px;
  height: 46px;
  border-radius: 4px;
  margin-right: 10px;
}

.toot-header {
  display: flex;
  align-items: baseline;
  gap: 4px;
}

.toot-author {
  color: #ffffff;
  font-weight: 700;
  font-size: 15px;
}

.toot-handle {
  color: #606984;
  font-size: 15px;
}

.toot-timestamp {
  color: #606984;
  font-size: 14px;
}

.toot-content {
  color: #9baec8;
  font-size: 15px;
  line-height: 22px;
  margin-top: 8px;
}

Content Warning Card

css.content-warning {
  background: #393f4f;
  border-radius: 4px;
  padding: 12px;
  margin-top: 8px;
}

.content-warning-label {
  color: #ffffff;
  font-size: 14px;
  font-weight: 500;
  margin-bottom: 8px;
}

.content-warning-toggle {
  background: #282c37;
  color: #9baec8;
  border: none;
  border-radius: 4px;
  padding: 6px 12px;
  font-size: 13px;
  cursor: pointer;
}

.content-warning-toggle:hover {
  background: #313543;
}

Account Card

css.account-card {
  background: #282c37;
  border-radius: 8px;
  padding: 16px;
}

.account-card-header {
  background: linear-gradient(135deg, #6364FF 0%, #8385FF 100%);
  height: 80px;
  border-radius: 8px 8px 0 0;
  margin: -16px -16px 16px -16px;
}

.account-card-avatar {
  width: 80px;
  height: 80px;
  border-radius: 4px;
  border: 4px solid #282c37;
  margin-top: -40px;
}

.account-card-name {
  color: #ffffff;
  font-size: 16px;
  font-weight: 700;
}

.account-card-handle {
  color: #606984;
  font-size: 14px;
}

Media Attachment

css.media-attachment {
  border-radius: 8px;
  overflow: hidden;
  margin-top: 10px;
}

.media-attachment img,
.media-attachment video {
  width: 100%;
  height: auto;
  display: block;
}

.media-sensitive-overlay {
  background: #191b22;
  display: flex;
  align-items: center;
  justify-content: center;
  color: #9baec8;
}

Action Bar

css.action-bar {
  display: flex;
  justify-content: space-between;
  margin-top: 12px;
  max-width: 400px;
}

.action-button {
  display: flex;
  align-items: center;
  gap: 6px;
  background: transparent;
  border: none;
  color: #606984;
  font-size: 14px;
  padding: 4px 8px;
  border-radius: 4px;
  cursor: pointer;
  transition: all 100ms ease-in-out;
}

.action-button:hover {
  background: rgba(99, 100, 255, 0.1);
}

.action-button.reply:hover { color: #6364FF; }
.action-button.boost:hover,
.action-button.boost.active { color: #2b90d9; }
.action-button.favorite:hover,
.action-button.favorite.active { color: #ca8f04; }
.action-button.bookmark:hover,
.action-button.bookmark.active { color: #6364FF; }
.action-button.share:hover { color: #6364FF; }

Navigation

Column Header

css.column-header {
  background: #282c37;
  border-bottom: 1px solid #393f4f;
  padding: 15px;
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.column-header-title {
  color: #ffffff;
  font-size: 16px;
  font-weight: 700;
}

.column-header-icon {
  color: #9baec8;
}

Tab Navigation

css.tabs {
  display: flex;
  border-bottom: 1px solid #393f4f;
}

.tab {
  flex: 1;
  padding: 14px;
  color: #606984;
  font-size: 14px;
  font-weight: 600;
  text-align: center;
  border-bottom: 2px solid transparent;
  cursor: pointer;
  transition: all 100ms ease-in-out;
}

.tab:hover {
  color: #9baec8;
  background: rgba(99, 100, 255, 0.05);
}

.tab.active {
  color: #6364FF;
  border-bottom-color: #6364FF;
}

Sidebar Navigation

css.nav-item {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 12px 16px;
  color: #9baec8;
  font-size: 15px;
  font-weight: 500;
  border-radius: 8px;
  cursor: pointer;
  transition: all 100ms ease-in-out;
}

.nav-item:hover {
  background: #282c37;
  color: #ffffff;
}

.nav-item.active {
  background: rgba(99, 100, 255, 0.15);
  color: #6364FF;
}

.nav-item-icon {
  width: 22px;
  height: 22px;
}

.nav-item-badge {
  background: #6364FF;
  color: #ffffff;
  font-size: 12px;
  font-weight: 600;
  padding: 2px 8px;
  border-radius: 10px;
  margin-left: auto;
}

Modals

css.modal-overlay {
  background: rgba(0, 0, 0, 0.7);
  position: fixed;
  inset: 0;
  display: flex;
  align-items: center;
  justify-content: center;
}

.modal {
  background: #282c37;
  border-radius: 8px;
  max-width: 480px;
  width: 100%;
  max-height: 90vh;
  overflow-y: auto;
}

.modal-header {
  padding: 16px;
  border-bottom: 1px solid #393f4f;
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.modal-title {
  color: #ffffff;
  font-size: 16px;
  font-weight: 700;
}

.modal-close {
  color: #606984;
  background: transparent;
  border: none;
  cursor: pointer;
}

.modal-body {
  padding: 16px;
}

.modal-footer {
  padding: 16px;
  border-top: 1px solid #393f4f;
  display: flex;
  justify-content: flex-end;
  gap: 8px;
}

Toasts/Notifications

css.toast {
  background: #282c37;
  border-radius: 8px;
  padding: 14px 16px;
  display: flex;
  align-items: center;
  gap: 12px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
}

.toast-success {
  border-left: 4px solid #79bd9a;
}

.toast-error {
  border-left: 4px solid #df405a;
}

.toast-message {
  color: #9baec8;
  font-size: 14px;
}

Instance Badge

css.instance-badge {
  background: #393f4f;
  color: #9baec8;
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 3px;
  display: inline-block;
}

.instance-badge.local {
  background: rgba(121, 189, 154, 0.2);
  color: #79bd9a;
}

5. Layout Principles

Spacing Scale

Multi-Column Layout (Advanced Web)

┌────────────────────────────────────────────────────────────────────────┐
│ ┌────────┬───────────┬───────────┬───────────┬───────────┬──────────┐ │
│ │        │           │           │           │           │          │ │
│ │  Nav   │   Home    │ Notifi-   │  Local    │ Federated │ Getting  │ │
│ │        │  Timeline │  cations  │  Timeline │  Timeline │  Started │ │
│ │        │           │           │           │           │          │ │
│ │  60px  │   350px   │   350px   │   350px   │   350px   │  285px   │ │
│ │        │           │           │           │           │          │ │
│ └────────┴───────────┴───────────┴───────────┴───────────┴──────────┘ │
└────────────────────────────────────────────────────────────────────────┘

Single-Column Layout (Simple Web/Mobile)

┌─────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────┐ │
│ │              Navigation                 │ │
│ ├─────────────────────────────────────────┤ │
│ │              Compose                    │ │
│ ├─────────────────────────────────────────┤ │
│ │                                         │ │
│ │              Timeline                   │ │
│ │                                         │ │
│ │           max-width: 600px              │ │
│ │                                         │ │
│ │                                         │ │
│ ├─────────────────────────────────────────┤ │
│ │    Search / Trends / Suggestions        │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Column Widths

Grid System

Mastodon uses a flex-based multi-column layout for the advanced web interface. Columns are fixed-width and horizontally scrollable. Single-column mode centers content with max-width constraints.

Whitespace Philosophy

• Breathing room in posts: Adequate padding between posts for readability
• Compact action bars: Action buttons are tightly spaced to save vertical space
• Clear column separation: Visual distinction through background color
• Consistent internal padding: 14-16px within cards and containers

6. Depth & Elevation

Shadow System

Surface Hierarchy

┌─────────────────────────────────────────────────────────┐
│ Modal/Floating                         #282c37 + shadow │
├─────────────────────────────────────────────────────────┤
│ Columns/Panels                         #282c37          │
├─────────────────────────────────────────────────────────┤
│ Hover/Interactive                      #313543          │
├─────────────────────────────────────────────────────────┤
│ Base/App Background                    #191b22          │
└─────────────────────────────────────────────────────────┘

Z-Index Scale

Border Treatments

css/* Standard border */
border: 1px solid #393f4f;

/* Subtle separator */
border-bottom: 1px solid #393f4f;

/* Focus ring */
outline: 2px solid #6364FF;
outline-offset: 2px;

/* Boost indicator */
border-left: 4px solid #2b90d9;

/* Content warning */
border-radius: 4px;
background: #393f4f;

7. Do's and Don'ts

Do's

Don'ts

Content & Tone Guidelines

8. Responsive Behavior

Breakpoints

Mobile Adaptations

Touch Targets

Responsive Typography

Image Handling

9. Agent Prompt Guide

Quick Reference

yaml# Backgrounds
Background Base: #191b22
Background Elevated: #282c37
Background Input: #1f232b
Background Hover: #313543
Background Active: #393f4f

# Brand
Mastodon Purple: #6364FF
Mastodon Purple Hover: #7477FF
Mastodon Purple Active: #5253E0

# Text
Text Primary: #ffffff
Text Secondary: #9baec8
Text Tertiary: #606984
Text Link: #6364FF

# Actions
Boost Color: #2b90d9
Favorite Color: #ca8f04
Bookmark Color: #6364FF

# Semantic
Success: #79bd9a
Warning: #ca8f04
Error: #df405a

# Borders & Radii
Border Default: #393f4f
Border Radius Small: 4px
Border Radius Medium: 8px
Border Radius Avatar: 4px (square-ish)

# Typography
Font Primary: system-ui, sans-serif
Font Size Base: 15px
Font Size Small: 14px
Font Size Large: 16px
Line Height: 22px

Example Prompts

Toot/Post Card

Create a Mastodon post (toot) card:
- Container: #282c37 background, 1px #393f4f border-bottom
- Padding: 14px 16px
- Avatar: 46px square with 4px radius, left aligned
- Display name: 15px bold #ffffff
- Handle: 15px regular #606984
- Timestamp: 14px #606984, separated by "·"
- Content: 15px #9baec8, line-height 22px
- Links/hashtags: #6364FF color
- Action bar: reply, boost (#2b90d9), favorite (#ca8f04), bookmark, share
- Hover: background lightens to #2c313d

Content Warning Component

Design a content warning wrapper:
- Outer container: 15px font post content as normal
- CW text: #ffffff bold, followed by warning text
- Toggle button: #282c37 background, #9baec8 text
- Button text: "Show more" / "Show less"
- Hidden content: collapsed by default
- When expanded: full content visible below button
- Border: none, but CW indicator visible

Boost Indicator

Create a boosted post indicator:
- Top bar: "🔁 [User] boosted" in #606984, 13px
- Icon: boost icon in #2b90d9 when boosted
- Border-left: 4px solid #2b90d9 (optional style)
- Original post nested below
- Maintain post author's avatar and info

Compose Modal

Design a compose post modal:
- Modal: #282c37 background, 8px radius
- Header: "New post" title, close button
- Avatar: current user, 46px
- Textarea: #282c37, no border, 15px, placeholder "What's on your mind?"
- Content warning toggle: shield icon, #606984
- Media buttons: image, poll, emoji picker
- Character count: "0/500" in #606984
- Visibility dropdown: public, unlisted, followers-only, mentioned only
- Post button: #6364FF, "Post!" text

Profile Header

Design a user profile header:
- Header image: 400px height or gradient fallback
- Avatar: 80px square, 4px radius, -40px overlap
- Display name: 20px bold #ffffff
- Handle: 15px #606984 with instance badge
- Bio: 15px #9baec8
- Stats: Following, Followers, Posts counts
- Follow button: #6364FF if not following, outlined if following
- Instance badge: #393f4f background, #9baec8 text

Federation Timeline

Create a federated timeline column:
- Column header: "Federated timeline" #ffffff, globe icon
- Settings cog icon in header
- Posts from multiple instances
- Instance badges visible on remote posts
- Load more button at bottom
- Streaming indicator when live updating

CSS Variables Template

css:root {
  /* Backgrounds */
  --background-base: #191b22;
  --background-elevated: #282c37;
  --background-input: #1f232b;
  --background-hover: #313543;
  --background-active: #393f4f;
  
  /* Brand */
  --mastodon-purple: #6364FF;
  --mastodon-purple-hover: #7477FF;
  --mastodon-purple-active: #5253E0;
  
  /* Text */
  --text-primary: #ffffff;
  --text-secondary: #9baec8;
  --text-tertiary: #606984;
  --text-link: #6364FF;
  
  /* Semantic */
  --color-success: #79bd9a;
  --color-warning: #ca8f04;
  --color-error: #df405a;
  --color-boost: #2b90d9;
  --color-favorite: #ca8f04;
  
  /* Borders */
  --border-color: #393f4f;
  
  /* Spacing */
  --spacing-4: 4px;
  --spacing-8: 8px;
  --spacing-10: 10px;
  --spacing-14: 14px;
  --spacing-16: 16px;
  --spacing-20: 20px;
  
  /* Radii */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  
  /* Typography */
  --font-primary: system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, monospace;
  --font-size-sm: 13px;
  --font-size-base: 15px;
  --font-size-lg: 16px;
  --line-height: 22px;
}

Summary

Mastodon's design system embodies the values of the decentralized, open-source social web:

1. Dark, immersive interface with layered backgrounds (#191b22 → #282c37 → #393f4f)
2. Mastodon Purple (#6364FF) as the distinctive brand accent
3. Multi-column TweetDeck-style layout for power users, with single-column alternative
4. Federation-aware UI patterns showing instance context and remote content indicators
5. Privacy-first components including content warnings, visibility controls, and sensitive media handling
6. Accessible, ethical design avoiding dark patterns and engagement manipulation
7. Clear action semantics with distinct boost (blue), favorite (gold), and bookmark (purple) colors

When implementing Mastodon-style interfaces, prioritize:

• User autonomy and control over their experience
• Transparency about content origin and federation
• Content warning system as a first-class feature
• Accessible design with proper contrast and keyboard navigation
• Chronological, algorithm-free timeline presentation
• Respect for decentralization and instance diversity