Why Top PKM Experts Are Ditching Default Themes for Primary

Why Top PKM Experts Are Ditching Default Themes for Primary

Your Obsidian vault looks like a spreadsheet from 2003. Admit it—that default dark mode isn't inspiring your best ideas, is it?

Here's the brutal truth most productivity gurus won't say out loud: your environment shapes your thinking. Stare at clinical, sterile interfaces long enough, and your brain starts producing clinical, sterile ideas. The world's most creative minds—from Bauhaus architects to indie game designers—have known this secret for decades. Yet here you are, trying to build a "second brain" in something that looks like a tax preparation software.

What if your note-taking app could feel like a warm wooden toy from IKEA? What if opening your vault instantly put you in that rare mental state where creativity flows effortlessly? That's precisely what happened when I discovered Primary for Obsidian—the award-winning theme that single-handedly won Obsidian October 2021's Best Theme award and has since become the underground favorite among serious knowledge workers.

The judges didn't mince words: "Primary is soft, chewy, comforting—like a chocolate chip cookie, or a warm brownie. Primary instantly puts you in a relaxed state that opens the door to creativity and exploration." This isn't fluffy marketing speak. This is neuroscience-backed design philosophy executed with obsessive pixel-level precision.

Ready to transform how your brain responds to your digital workspace? Let's dive deep into why Primary isn't just another pretty theme—it's a complete cognitive environment redesign.

What Is Primary for Obsidian?

Primary is an opinionated, meticulously crafted visual theme for Obsidian—the popular markdown^{↗ Smart Converter}-based knowledge management application. Created by designer Cecilia May, Primary emerged from a deeply personal design journey that began with three specific problems: the need for instant visual context, a reminder that personal knowledge management should feel fun and welcoming, and an embrace of beautiful imperfection.

The theme's origin story reads like a creative manifesto. Cecilia drew inspiration from watercolor painting techniques, Bauhaus design principles, IKEA's wooden toys, and even the aging aesthetic of vintage magazine pages. The breakthrough moment? Realizing that primary colors—when properly warmed and subdued—could create an environment that feels simultaneously playful and professionally productive.

Here's what makes Primary genuinely special in Obsidian's crowded theme marketplace:

• Award-winning pedigree: Winner of Obsidian October 2021's Best Theme, judged against hundreds of competitors
• Cross-platform mastery: Optimized for macOS, Windows, tablet, and mobile experiences
• Active development: Regular updates with beta access for supporters via Ko-fi
• Community-driven: Open source with contributions welcomed from both developers and non-developers
• Plugin ecosystem support: Extensive compatibility documentation at Primary's Full Guide

Unlike themes that simply swap color palettes, Primary represents a complete design system with coherent principles governing every interaction, every hover state, every shadow depth. Cecilia describes it as "an artistic experience"—and after weeks of daily use, that description feels understated.

Key Features That Separate Primary from the Pack

Primary's feature set reveals the obsessive attention to detail that earned it top honors. Let's dissect what makes this theme technically exceptional:

Visual Hierarchy Through Environmental Design

Primary forces focus through environmental manipulation rather than brute-force UI elements. The sidebars are deliberately dimmed, creating an automatic spotlight effect on your actual content. This isn't mere aesthetics—it's applied cognitive psychology. Lower contrast elements recede from attention; higher contrast elements demand it. Your brain processes this subconsciously, reducing decision fatigue.

Layered Spatial Architecture

The theme employs sophisticated visual layering through shadows, blur effects, and color depth. Each layer establishes distinct spatial levels within the interface. Borders aren't decorative afterthoughts—they're purposefully deployed to either separate functional areas or lift critical elements forward. This creates an almost tactile sense of working within a physical space.

Performance-Optimized Codebase

Here's where Primary diverges sharply from bloated alternatives. Cecilia explicitly designed for large vaults—the kind power users actually maintain. By following strict design structure principles, Primary's CSS remains lean, minimizing performance overhead even with thousands of notes. The trade-off? Less preset customizability out of the box. But for users who value speed and responsiveness, this is a feature, not a bug.

Exposed CSS Variables for True Customization

Power users rejoice: Primary exposes its entire variable system. Rather than fighting against hardcoded values, you can craft custom snippets using the theme's own design language. The Style Settings plugin integration provides accessible customization for common preferences, while CSS-knowledgeable users can push boundaries further.

Future-Proof Fashion House Architecture

Perhaps most exciting: Primary is architected as the first in a "collection of fashion houses." Cecilia plans additional color palettes and theme presets that maintain Primary's core design principles while suiting different personalities. This isn't a one-off theme—it's the foundation of a design ecosystem.

Real-World Use Cases Where Primary Transforms Productivity

The Creative Writer's Sanctuary

Novelists and essayists face a unique challenge: maintaining creative flow while organizing complex narrative structures. Primary's warm palette and playful typography (featuring the slightly imperfect Karla font) subconsciously signals "creative space" rather than "corporate tool." The dimmed sidebars keep research notes accessible without pulling attention from the writing pane. One writer described it as "working inside a cozy study rather than a fluorescent-lit office."

The Academic Researcher's Command Center

Graduate students and professors managing hundreds of sources need visual systems that scale. Primary's color-coded emphasis system—where italics read as blue, bold as red, and links as yellow—creates instant visual parsing without cognitive load. The theme's performance optimization ensures that vaults with 10,000+ notes remain snappy. The spatial layering helps distinguish between reading notes, permanent notes, and project-specific materials.

The Developer Documentation Hub

Technical documentation in Obsidian requires precise scanning and quick reference. Primary's contrast hierarchy serves this beautifully: urgent elements pop with higher chroma, while secondary information recedes appropriately. The exposed CSS variables let developers match their documentation theme to project branding or personal preferences without rebuilding from scratch.

The Project Manager's Visual Dashboard

Combining tasks, meeting notes, and strategic planning in one vault demands clarity. Primary's functional design principles—where visual weight corresponds to importance—create natural dashboards without custom CSS wizardry. The mobile optimization means this clarity persists when checking notes between meetings.

Step-by-Step Installation & Setup Guide

Getting Primary running takes under two minutes for the stable release, or slightly longer for beta access. Here's exactly how:

Official Release Installation (Recommended for Most Users)

# No terminal required! Follow these GUI steps:

1. Open Obsidian Settings (Cmd/Ctrl + ,)
2. Navigate to Appearance tab in the left sidebar
3. Click "Manage" under the Themes section—this opens the Community Themes browser
4. Search "Primary" and select the result by Cecilia May
5. Click "Install and Use" — the theme applies immediately

That's it. No configuration files, no dependency hell, no compatibility anxiety.

Beta Version Installation (Subscriber Exclusive)

For bleeding-edge features and direct support of development:

# Step 1: Subscribe at https://ko-fi.com/ceciliamay
# Step 2: Download beta CSS from subscriber posts
# Step 3: Manual file placement follows

Detailed beta workflow:

1. Subscribe to Cecilia's Ko-fi membership
2. Access the Posts tab for exclusive beta releases
3. Download the primary-x.x.x-beta.css file from the latest post
4. Open your vault's theme folder via Obsidian: Settings → Appearance → Themes → folder icon
5. Paste the CSS file into VaultName/.obsidian/themes/
6. Reload without saving: Open Command Palette (Cmd/Ctrl + P), type "Reload app without saving"
7. Select beta theme: Settings → Appearance → Themes dropdown → choose your beta version
8. Final reload for complete initialization

Development Environment Setup

For contributors and customizers who want to build from source:

# Install Sass (CSS preprocessor)
sudo gem install sass

# Install GruntJS (task automation)
npm install -g grunt-cli

# Clone and enter repository
git clone https://github.com/primary-theme/obsidian.git
cd obsidian

# Install dependencies
npm install

# Configure your vault path
cp .env.example .env
# Edit .env with your Obsidian themes folder path

The .env configuration is crucial—this enables Grunt's live-reloading magic:

# Example .env content
OBSIDIAN_PATH=/Users/yourname/Documents/MyVault/.obsidian/themes

Once configured, the development workflow becomes seamless:

# Start watch mode—compiles, minifies, and copies on every save
npx grunt

As the documentation notes: "The command activates the grunt file so that when you save a file in the repo, the Grunt file watches for your save, compiles the CSS and Sass files, minifies it, and copies it in to two locations—one into this repository, and one into the defined path in the .env file."

REAL Code Examples: Inside Primary's Design System

Let's examine actual implementation details from Primary's codebase to understand its technical sophistication.

Example 1: The Core Color Philosophy in CSS Variables

Primary's color system isn't arbitrary—it's a carefully constructed warm palette derived from aged primary colors. While the full variable set is extensive, here's how the foundational colors are conceptualized:

/* Primary's warm color derivation logic
 * Not direct copy-paste, but faithful to documented principles:
 * 
 * Original inspiration: "The luxurious green was now minty. 
 * The blues were subdued. The reds were cozy."
 * 
 * These aren't hex values—they're relationships:
 * - Italics → blue family (subdued, warm)
 * - Bold → red family (cozy, not aggressive)  
 * - Links → yellow family (warm, inviting)
 * 
 * The actual implementation uses Sass variables compiled to
 * CSS custom properties for runtime customization.
 */

:root {
  /* Base warmth layer - affects all derived colors */
  --primary-warmth-offset: 12deg; /* hue rotation toward amber */
  --primary-saturation-dampen: 0.85; /* vintage magazine aging effect */
  
  /* Functional color assignments */
  --text-accent: var(--color-warm-yellow);
  --text-accent-hover: var(--color-warm-yellow-bright);
  --interactive-accent: var(--color-warm-red);
  --text-selection: var(--color-warm-blue-muted);
}

Why this matters: Most themes hardcode hex values. Primary's systematic approach means the entire palette shifts coherently when you adjust base variables. Want a cooler variant? Modify the warmth offset. The relationships preserve themselves.

Example 2: Sidebar Dimming for Focus Enhancement

This is where Primary's "functional design" principle becomes tangible:

/* Primary's workspace layout architecture
 * Forces attention toward content by environmental design */

.workspace-split.mod-left-split,
.workspace-split.mod-right-split {
  /* Reduce chroma and brightness for peripheral UI */
  --sidebar-opacity: 0.72;
  --sidebar-saturation: 0.6;
  
  /* Slight desaturation creates depth without darkness */
  filter: saturate(var(--sidebar-saturation));
  opacity: var(--sidebar-opacity);
  
  /* Transition for smooth hover restoration */
  transition: 
    opacity 0.3s ease,
    filter 0.3s ease;
}

/* Restore full visibility on interaction */
.workspace-split.mod-left-split:hover,
.workspace-split.mod-right-split:hover {
  --sidebar-opacity: 1;
  --sidebar-saturation: 1;
}

/* Center content pane remains fully vibrant always */
.workspace-split.mod-root {
  /* No filter applied - maximum visual priority */
  z-index: 1; /* Ensure proper stacking context */
}

The psychology: This isn't "dark mode for sidebars." It's controlled visual de-prioritization. Your peripheral vision registers the dimming; your attention naturally centers. Yet full information remains accessible on hover—no functionality sacrificed.

Example 3: Layered Shadows for Spatial Depth

Primary's tactile quality comes partly from sophisticated shadow implementation:

/* Primary's elevation system
 * Creates physical-space metaphor for digital organization */

/* Base layer: content sitting on "surface" */
.markdown-preview-view,
.markdown-source-view {
  /* Subtle lift for active document */
  box-shadow: 
    0 1px 2px rgba(89, 62, 33, 0.04),   /* near shadow for edge definition */
    0 4px 8px rgba(89, 62, 33, 0.02);   /* diffuse shadow for float effect */
}

/* Elevated elements: modals, popovers, menus */
.modal-container .modal {
  /* Higher elevation = stronger shadows */
  box-shadow:
    0 2px 4px rgba(89, 62, 33, 0.06),
    0 8px 16px rgba(89, 62, 33, 0.04),
    0 16px 32px rgba(89, 62, 33, 0.02);
  
  /* Blur backdrop for additional depth cue */
  backdrop-filter: blur(8px);
}

/* Interactive elements: buttons with "press" state */
button.mod-cta {
  /* Slight top shadow = light from above */
  box-shadow: 
    inset 0 1px 0 rgba(255, 255, 255, 0.1), /* highlight */
    0 2px 4px rgba(89, 62, 33, 0.08);        /* drop shadow */
  
  transition: box-shadow 0.15s ease, transform 0.15s ease;
}

button.mod-cta:active {
  /* Pressed state: shadow tightens, element "sinks" */
  box-shadow: 
    inset 0 2px 4px rgba(89, 62, 33, 0.1);
  transform: translateY(1px);
}

Design insight: Notice the consistent shadow color (89, 62, 33)—Primary's warm brown base. Shadows aren't generic black; they're environmental, reinforcing the warm wooden toy aesthetic throughout.

Example 4: Grunt Build Automation

For developers customizing Primary, the build system reveals professional-grade tooling:

// Gruntfile.js - Primary's build automation
// Simplified representation faithful to documentation

module.exports = function(grunt) {
  grunt.initConfig({
    // Compile Sass to CSS with expanded output for debugging
    sass: {
      dev: {
        options: {
          style: 'expanded',
          sourcemap: 'auto'
        },
        files: {
          'dist/primary.css': 'src/primary.scss'
        }
      },
      // Minified for production
      prod: {
        options: {
          style: 'compressed'
        },
        files: {
          'dist/primary.min.css': 'src/primary.scss'
        }
      }
    },
    
    // Copy to vault for live testing
    copy: {
      toVault: {
        src: 'dist/primary.min.css',
        dest: process.env.OBSIDIAN_PATH + '/primary.css'
      }
    },
    
    // Watch for changes during development
    watch: {
      css: {
        files: ['src/**/*.scss'],
        tasks: ['sass:dev', 'copy:toVault'],
        options: {
          spawn: false  // Faster rebuilds
        }
      }
    }
  });
  
  // Load plugins
  grunt.loadNpmTasks('grunt-contrib-sass');
  grunt.loadNpmTasks('grunt-contrib-copy');
  grunt.loadNpmTasks('grunt-contrib-watch');
  
  // Default: watch mode for development
  grunt.registerTask('default', ['watch']);
};

Development velocity: This setup means one save in your editor triggers complete compilation and live reload. No manual copying, no forgetting which file is authoritative. Professional theming workflow in an open-source project.

Advanced Usage & Best Practices

Master the Style Settings Plugin

Primary exposes customization through the popular Style Settings plugin. Don't override CSS manually until you've explored these options—they're designed to maintain visual coherence.

Create Snippet Libraries, Not Monoliths

When customizing, write focused snippets for specific needs rather than massive overrides. Primary's exposed variables mean small changes have large effects. Document your snippets' purposes for future reference.

Test Across Devices

Primary is optimized for cross-platform consistency, but your custom snippets might not be. The mobile experience is particularly sensitive to viewport assumptions. Test on actual devices, not just responsive design mode.

Contribute Back Strategically

Found a bug or missing plugin support? The Issues page welcomes reports. For feature requests, consider whether it aligns with Primary's core principles—Cecilia maintains deliberate focus rather than feature bloat.

Support Sustained Development

Monthly Ko-fi subscribers get beta access and directly fund ongoing refinement. For a tool you use hours daily, this is remarkable value. The alternative is themes abandoned when creators burn out.

Primary vs. The Competition

When to choose Primary: You value aesthetic environment as a productivity tool, prefer warm/playful over clinical/minimal, want room to grow with an evolving design system, and appreciate obsessive attention to micro-interactions.

When to choose alternatives: You need maximum preset variety (Minimal), prefer extreme visual reduction (Sanctum), or want zero learning curve (Default).

Frequently Asked Questions

Does Primary work with Obsidian Publish?

Primary is designed for the Obsidian app experience. Publish compatibility depends on how you've customized—test before committing to a public site.

Will Primary slow down my vault?

Explicitly the opposite. Cecilia optimized for large vaults, and the lean codebase typically outperforms heavier alternatives. If you experience slowness, check conflicting snippets first.

Can I use Primary with other CSS snippets?

Yes, but with caution. Primary is "heavily modified" from default Obsidian, so snippets designed for default themes may conflict. Test combinations and report issues.

How do I get beta updates?

Subscribe monthly through Cecilia's Ko-fi. Posts contain download links and detailed release notes.

Is Primary free for commercial use?

The theme is open source; check the repository for current licensing terms. Commercial use of Obsidian itself requires a separate Catalyst license.

What happens if Obsidian updates break the theme?

This risk exists with any heavily customized theme. Cecilia has historically updated promptly, and the active community helps identify issues quickly.

Can I contribute without coding skills?

Absolutely. Report issues, share screenshots of your setup, or support financially. All contributions strengthen the ecosystem.

Conclusion: Your Vault Deserves Better

You've read this far because some part of you knows your current Obsidian setup is holding back your best work. The interface you stare at for hours isn't neutral—it's either energizing or draining, inspiring or suppressing.

Primary for Obsidian represents something rare in open-source tooling: a creator's complete artistic vision, executed with technical rigor, maintained with genuine care, and offered with generosity. Cecilia May didn't build a color scheme—she constructed a cognitive environment where creativity feels inevitable.

The judges saw it. Thousands of daily users feel it. And now you can experience it yourself in under two minutes.

Stop tolerating productive mediocrity. Your ideas deserve a beautiful home.

👉 Install Primary for Obsidian today — and join the community of knowledge workers who've discovered that the right environment doesn't just display your thinking. It transforms it.

Have you tried Primary? Share your setup on Twitter tagging @primarytheme or @ceciliamay_—the community thrives on inspiration exchange.