v0.2.3

Release Notes: v0.2.3

Release Date: December 26, 2025
Type: Minor Release - Badge Variants & Themes

Overview

This release introduces badge variants - a powerful new system for changing the visual design of your badges. Also added 4 new color themes and refactored the template architecture for better extensibility.

What's New

🎨 Badge Variants System

Badges now support multiple visual design approaches via the --badge-variant flag:

• default - Modern card-based design with gradients and shadows
• text-based - Clean typography-focused design (detailed style only)

# Generate a text-based detailed badge
gh-oss-stats --user mabd-dev \
  --badge \
  --badge-style detailed \
  --badge-variant text-based \
  --badge-output badge.svg

Visual Comparison:

Default Variant	Text-Based Variant

🌈 New Themes

4 new color themes added (total: 6 themes):

• Nord - Nordic-inspired blue and frost tones
• Dracula - Popular purple dark theme
• Gruvbox Dark - Warm retro dark theme
• Gruvbox Light - Warm retro light theme

All themes work with all styles. See the Badge Themes Gallery for visual examples.

# Use Nord theme
gh-oss-stats --user mabd-dev --badge --badge-theme nord

🏗️ Template Architecture Improvements

• Templates moved to badgeTemplates/ subpackage for better organization
• Separated default and text-based templates into distinct files
• Enhanced theme color system with semantic naming (BackgroundAlt, Positive, Negative, Star)
• All templates now fully theme-aware

🔧 CLI Enhancements

• New flag: --badge-variant (default, text-based)
• Improved error messages with available options
• Better verbose output showing variant selection

Breaking Changes

Badge File Naming

Badge files in docs/badges/ have been renamed to include variant prefix:

Before:

• summary-dark.svg
• detailed-light.svg

After:

• default-summary-dark.svg
• default-detailed-light.svg
• text-based-detailed-dark.svg

If you reference these files directly, update your paths accordingly.

Documentation Updates

• New Badge Themes Gallery showing all variant × theme × style combinations
• Updated Badge README with variant examples
• Updated Technical Documentation with variant CLI flags
• Enhanced architecture documentation in TECHNICAL.md

Upgrade Instructions

For End Users (GitHub Actions)

Update your workflow file to use the new variant flag (optional):

- name: Generate badge
  run: |
    gh-oss-stats \
      --user ${{ github.repository_owner }} \
      --badge \
      --badge-style detailed \
      --badge-variant default \  # New: optional, defaults to "default"
      --badge-theme dark \
      --badge-output images/oss-badge.svg

For Library Users

No breaking changes to the public API. If you use badge.RenderSVG(), the function signature is unchanged. The BadgeOptions struct now includes a Variant field:

opts := badge.BadgeOptions{
    Style:   badge.StyleDetailed,
    Variant: badge.VariantTextBased,  // New field
    Theme:   badge.ThemeDark,
    SortBy:  badge.SortByPRs,
    Limit:   5,
}