embersparks_obsidian-github-stars-manager/THEMES_EN.md

Theme System Technical Documentation

Overview

The Obsidian GitHub Stars Manager plugin provides two themes: Default theme and iOS Glass theme. This document details the technical implementation of the theme system, particularly the design philosophy and latest optimizations of the iOS Glass theme.

Theme Architecture

Theme Switching Mechanism

The plugin uses CSS class switching to implement theme functionality:

// Theme switching logic
toggleTheme(theme: 'default' | 'ios-glass') {
    const container = this.containerEl;
    container.removeClass('github-stars-theme-default', 'github-stars-theme-ios-glass');
    container.addClass(`github-stars-theme-${theme}`);
}

CSS Variables System

The iOS Glass theme uses CSS custom properties to manage colors and effects:

.github-stars-theme-ios-glass {
  --ios-glass-bg: rgba(255, 255, 255, 0.25);
  --ios-glass-bg-secondary: rgba(255, 255, 255, 0.15);
  --ios-glass-border: rgba(255, 255, 255, 0.3);
  --ios-glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
  --ios-glass-blur: blur(20px);
  --ios-glass-accent: rgba(0, 122, 255, 0.8);
}

iOS Glass Theme Deep Dive

Design Philosophy

The iOS Glass theme is inspired by iOS's frosted glass design language, aiming to create a modern, elegant visual experience. Key characteristics:

1. Transparency Hierarchy: Multiple transparency layers create depth perception
2. Blur Effects: backdrop-filter achieves realistic frosted glass effects
3. Dynamic Backgrounds: Gradient colors and animations enhance visual appeal
4. Interactive Feedback: Subtle animations on hover and click

Core Technical Implementation

1. Multi-layer Gradient Backgrounds

.github-stars-theme-ios-glass .github-stars-container {
  background: 
    /* Colorful gradient layer */
    linear-gradient(135deg, 
      rgba(74, 144, 226, 0.12) 0%,
      rgba(80, 200, 120, 0.08) 25%,
      rgba(255, 107, 107, 0.06) 50%,
      rgba(196, 181, 253, 0.08) 75%,
      rgba(251, 191, 36, 0.1) 100%),
    /* Base white gradient layer */
    linear-gradient(135deg, 
      rgba(255, 255, 255, 0.15) 0%, 
      rgba(255, 255, 255, 0.08) 100%);
}

2. Dynamic Floating Animation

.github-stars-theme-ios-glass .github-stars-container::before {
  content: '';
  position: absolute;
  top: -50%;
  left: -50%;
  width: 200%;
  height: 200%;
  background: radial-gradient(circle, 
    rgba(74, 144, 226, 0.03) 0%,
    transparent 50%);
  animation: float 20s ease-in-out infinite;
}

@keyframes float {
  0%, 100% { transform: translate(0, 0) rotate(0deg); }
  33% { transform: translate(30px, -30px) rotate(120deg); }
  66% { transform: translate(-20px, 20px) rotate(240deg); }
}

3. Frosted Glass Blur Effect

.github-stars-theme-ios-glass .github-stars-repo {
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.4);
  box-shadow: 
    inset 0 1px 0 rgba(255, 255, 255, 0.4),
    0 8px 32px rgba(0, 0, 0, 0.12);
}

4. Shimmer Sweep Animation

.github-stars-theme-ios-glass .github-stars-repo::before {
  content: '';
  position: absolute;
  top: 0;
  left: -100%;
  width: 100%;
  height: 100%;
  background: linear-gradient(90deg, 
    transparent 0%, 
    rgba(255, 255, 255, 0.15) 50%, 
    transparent 100%);
  transition: left 0.6s ease;
}

.github-stars-theme-ios-glass .github-stars-repo:hover::before {
  left: 100%;
}

Latest Optimization Records

August 8, 2024 - Major iOS Glass Theme Optimization

Bug Fixes

1. Font Blur Issue

   • Problem: Text becomes blurry on card hover
   • Cause: transform: scale(1.02) causing sub-pixel rendering issues
   • Solution:

     .github-stars-theme-ios-glass .github-stars-repo:hover {
       transform: translateY(-3px); /* Remove scale to avoid font blur */
       -webkit-font-smoothing: antialiased;
       -moz-osx-font-smoothing: grayscale;
     }
     

2. Insufficient Background Contrast

   • Problem: Insufficient contrast between cards and background, failing to showcase liquid glass style
   • Solution:
     • Added colorful gradient backgrounds to improve contrast
     • Enhanced card background opacity (from 0.15 to 0.25)
     • Increased border opacity (from 0.3 to 0.4)

Visual Effect Enhancements

1. Colorful Gradient Backgrounds

   • Using gradient combinations of blue, green, red, purple, and yellow
   • Creating richer visual hierarchy

2. Dynamic Background Animation

   • 20-second loop floating animation
   • Dynamic radial gradient effects

3. Shimmer Animation Optimization

   • 0.6-second smooth transition
   • More natural shimmer sweep effect

4. Shadow System Upgrade

   • Inner shadows enhance glass texture
   • Outer shadows provide depth perception

Technical Metrics

• Performance Impact: Minimized, using CSS hardware acceleration
• Compatibility: Supports modern browsers with backdrop-filter
• Responsive: Fully adaptive to different screen sizes
• Accessibility: Maintains good contrast and readability

Waterfall Layout

Implementation Principle

Using CSS Column layout to achieve Xiaohongshu-style waterfall effect:

.github-stars-theme-ios-glass .github-stars-repos {
  column-count: auto;
  column-width: 280px;
  column-gap: 20px;
  padding: 0 20px 20px 20px;
}

.github-stars-theme-ios-glass .github-stars-repo {
  break-inside: avoid;
  margin-bottom: 20px;
  display: inline-block;
  width: 100%;
}

Advantages

1. Adaptive: Automatically adjusts column count based on container width
2. Excellent Performance: Pure CSS implementation, no JavaScript calculations
3. Responsive: Perfect adaptation to various screen sizes
4. Smooth Experience: Avoids card overlap and layout jumping

Browser Compatibility

Feature	Chrome	Firefox	Safari	Edge
backdrop-filter	✅ 76+	✅ 103+	✅ 9+	✅ 79+
CSS Grid	✅ 57+	✅ 52+	✅ 10+	✅ 16+
CSS Columns	✅ 50+	✅ 52+	✅ 9+	✅ 12+
CSS Animations	✅ 43+	✅ 16+	✅ 9+	✅ 12+

Performance Optimization

1. Hardware Acceleration: Using transform and opacity to trigger GPU acceleration
2. Avoid Reflow: Using transform instead of top/left for animations
3. Reasonable Blur Usage: Controlling blur radius to avoid performance issues
4. Animation Optimization: Using will-change property to hint browser optimization

Future Plans

1. Theme Extensions: Planning to add more theme options
2. Custom Configuration: Allow users to customize colors and effect intensity
3. Dark Mode: Adapt to Obsidian's dark theme
4. Animation Controls: Provide animation toggle options for users

---

Last Updated: August 8, 2024