MusicFree Desktop Theme Pack Development

Core Concepts

:root

global.scss

:root {}

index.css

Code of Conduct

1. Visual products cannot be previewed: AI cannot see the actual rendering effect of the theme, so every important decision must be confirmed with the user, do not judge whether it is "good-looking" by yourself
2. Confirm before implementation: Key decisions such as color palette, variable coverage range, and background style must be clearly described and approved by the user before generating code
3. Explain technical terms: Users may be zero-based community contributors, all professional concepts must be explained in plain language
4. Minimum coverage principle: Only cover CSS variables that need to be changed, do not cover all variables for the sake of "completeness"
5. Light theme exception: Light themes must cover all Background / Fill / Text / Border variables, otherwise dark color residues will appear
6. Resource volume priority: Images must be compressed (WebP is recommended), avoid unnecessary large files

Roles and Collaboration Mode

• AI (you): Provide color scheme suggestions, write CSS/HTML code, generate config.json, package the theme
• User: Provide creative direction, select solutions, install and test the theme, provide visual feedback

Difference from plugin-dev

User Interaction Principles

• Provide 2-3 solution options each time for users to choose or mix
• Describe colors with both color values and intuitive descriptions (e.g. "rgb(52, 211, 153) — emerald green, similar to Spotify's green")
• Provide precise step-by-step instructions when user operation is required
• Ask first before acting when you are unsure of the user's intention

Workflow

1. Demand Collection → 2. Style Determination → 3. Palette Generation → 4. CSS Variable Mapping
→ 5. Enhancement Layer (Optional) → 6. Packaging and Testing → 7. Iterative Optimization
→ 8. (Optional) Submit to Theme Market

Phase 1: Demand Collection

• Theme name
• Basic direction: Dark / Light / AMOLED pure black / Other
• User's creative intention (any of the following forms is acceptable):
  • Emotion/atmosphere keywords (e.g. "warm", "cyberpunk", "fresh and natural")
  • Reference color values (e.g. "I want pink series")
  • Reference application/website (e.g. "Similar to Spotify's dark green")
  • Reference image (users post images directly)
  • Fully customized detailed description

• Author name
• Description
• Whether dynamic iframe background is required
• Whether there are custom image materials (e.g. background image, preview image)

Phase 2: Style Determination

• Brand color value + intuitive description
• Light and dark tone
• Atmosphere keywords
• Background style (solid color / gradient / image / dynamic)

Phase 3: Palette Generation

1. Brand color (brand)
2. Background color hierarchy (base → sidebar → player → surface → ...)
3. Text color hierarchy (primary → secondary → muted → ...)
4. Border color hierarchy
5. Status color (if customization is required)

Phase 4: CSS Variable Mapping

• Shadow / Blur: Stylish tokens. Flat/AMOLED themes can be set to

  none

  ; glass morphism themes can increase the blur value
• Radius: Not covered by default. It can be adjusted only when the user explicitly requires extreme styles (e.g. pure angular cyberpunk), and the user should be informed that it may cause visual abnormalities of some components
• Background Image (

  --bg-image

  ): Belongs to the enhancement layer, decide whether to cover according to the theme style

index.css

/*
 * Theme Name
 */
:root {
    /* ── Background ── */
    --color-bg-base: ...;
    /* ... */

    /* ── Fill ── */
    --color-fill-brand: ...;
    /* ... */
}

Phase 5: Enhancement Layer (Optional)

--bg-image

radial-gradient

linear-gradient

color-mix(in srgb, var(--color-fill-brand) X%, transparent)

• Soft shadow (default): Keep the default value
• Hard shadow: Reduce blur-radius, increase spread
• No shadow (AMOLED/flat): All set to

  none

• Guide to compress images (WebP format is recommended)
• Single image ≤ 500 KB
• Reference through

  @/

  path in CSS (e.g.

  url(@/imgs/bg.webp)

  )

• @/

  is a path alias, which will be replaced with the absolute path of the theme pack directory at runtime

• iframes/app.html

  : Dynamic background entry file
• Add

  "iframe": { "app": "@/iframes/app.html" }

  in config.json
• It is recommended to provide

  blurHash

  field as a loading placeholder (optional but recommended)

Phase 6: Packaging and Testing

1. Confirm the file structure is complete
2. Generate

   config.json

3. Check resource volume
4. Package as

   .mftheme

   (ZIP format, change the extension)
5. Guide users to install and test

1. Open MusicFree desktop version
2. Enter the「Themes」page
3. Click the「Install Theme Pack」button
4. Select the generated

   .mftheme

   file
5. Click the theme card to apply
6. Check whether each page is displayed normally

Phase 7: Iterative Optimization

--color-text-on-brand

--color-bg-sidebar

--color-bg-overlay

--color-fill-brand-muted

Phase 8 (Optional): Submit to Theme Market

1. Fork the repository: Guide the user to Fork MusicFreeThemePacks
2. Switch branches: Create a development branch based on the

   v1/source

   branch
3. Create a folder: Create a theme folder under

   themes/

   • Naming rules: Only letters, numbers, hyphens (

     -

     ), and underscores (

     _

     ) are allowed
4. Add tags: Add

   tags

   field in config.json (1-5 tags, selected from the predefined list)
   • Do not add the

     id

     field in config.json (ID is automatically managed by the system)
   • Dynamic themes must include the

     "动态"

     tag
5. Local verification:
   bash

   npm install
   npm run validate:theme your-theme-name

6. Submit PR: Submit a Pull Request to the

   v1/source

   branch

dark

light

gradient

minimalist

anime

landscape

illustration

cyberpunk

pixel

abstract

dynamic

cute

game

movie

season

nature

Theme Pack File Structure

my-theme/
├── config.json          # Required — Theme meta information
├── index.css            # Required — CSS variable override
├── imgs/                # Optional — Image resources
│   ├── preview.webp     # Preview image (WebP recommended)
│   └── ...
└── iframes/             # Only required for dynamic themes
    ├── app.html         # Dynamic background entry
    └── ...

config.json Field Description

{
    "name": "Theme Name",               // Required
    "preview": "@/imgs/preview.webp", // Recommended — Image path or "#hex" color value
    "description": "Theme Description",         // Recommended
    "author": "Author",                 // Recommended
    "authorUrl": "https://...",       // Optional
    "version": "0.0.1",              // Recommended — Must be incremented when updating
    "tags": ["暗色"],                 // Required when submitting to the theme market, 1-5
    "blurHash": "...",               // Recommended when there is an iframe (loading placeholder)
    "iframe": {                      // Only for dynamic themes
        "app": "@/iframes/app.html"
    }
}

• preview

  can be an image path (e.g.

  @/imgs/preview.webp

  ) or a CSS color value (e.g.

  "#1a1a2e"

  )

• tags

  can be omitted in the local development phase, and supplemented when submitting to the theme market
• Do not add the

  id

  field manually, it is automatically managed by the theme market system

@/

Path Alias

@/

file://

• @/imgs/bg.webp

  →

  file:///C:/Users/.../themes/my-theme/imgs/bg.webp

• url(@/imgs/texture.png)

  can reference local images in CSS

Resource Limits

• Prioritize using WebP format (25-35% smaller than PNG/JPG)
• Compress images with tools such as TinyPNG
• Prioritize using CSS gradients instead of image textures
• Try to use lower resolution or frame rate for videos