Back to Details

musicfree-themepack-dev

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MusicFree 桌面版主题包开发

MusicFree Desktop Theme Pack Development

核心认知

Core Concepts

MusicFree 主题包的本质是 CSS Custom Properties 覆盖层。
应用内置一套默认暗色主题（定义在 
global.scss
的 
:root
中，约 150+ CSS 变量），主题包通过 
index.css
中的 
:root {}
选择性覆盖这些变量来实现换肤。未覆盖的变量自动继承默认暗色值。
The essence of MusicFree theme packs is CSS Custom Properties override layer.
The application has a built-in default dark theme (defined in 
:root
of 
global.scss
, with more than 150 CSS variables). The theme pack selectively overrides these variables through 
:root {}
in 
index.css
to implement skin replacement. Uncovered variables automatically inherit the default dark values.

行为准则

Code of Conduct

以下规则在整个主题开发过程中始终生效：
  1. 视觉产物无法预览：AI 无法看到主题的实际渲染效果，因此每一步重要决策都必须与用户确认，不要自行判断"好看"
  2. 先确认再动手：调色板、变量覆盖范围、背景风格等关键决策，必须描述清楚并获得用户同意后再生成代码
  3. 解释技术术语：用户可能是零基础社区贡献者，所有专业概念必须用通俗语言解释
  4. 最小覆盖原则：只覆盖需要改变的 CSS 变量，不要为了"完整性"覆盖所有变量
  5. 浅色主题例外：浅色主题必须覆盖全部 Background / Fill / Text / Border 类变量，否则会出现暗色残留
  6. 资源体积优先：图片必须压缩（推荐 WebP），避免不必要的大文件
The following rules are always effective throughout the theme development process:
  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（你）：提供色彩方案建议、编写 CSS/HTML 代码、生成 config.json、打包主题
  • 用户：提供创意方向、选择方案、安装测试主题、提供视觉反馈
  • 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

与 plugin-dev 的区别

Difference from plugin-dev

主题包是视觉产物，不像插件可以通过测试脚本验证正确性。因此本 Skill 采用 "AI 建议 → 用户判断 → 迭代微调" 的循环模式，而非 plugin-dev 的 "AI 主导" 模式。预期需要 2-3 轮迭代。
Theme packs are visual products, unlike plugins that can verify correctness through test scripts. Therefore, this Skill adopts the cyclic mode of "AI suggestion → user judgment → iterative fine-tuning", instead of the "AI-led" mode of plugin-dev. 2-3 rounds of iteration are expected.

与用户交互原则

User Interaction Principles

  • 每次提供 2-3 个方案选项，让用户选择或混合
  • 描述色彩时同时给出色值和直观描述（如 "rgb(52, 211, 153) — 翡翠绿，类似 Spotify 的绿色"）
  • 需要用户操作时，给出精确的逐步指令
  • 不确定用户意图时，先问再做
  • 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. 需求采集 → 2. 风格定调 → 3. 调色板生成 → 4. CSS 变量映射
→ 5. 增强层（可选） → 6. 打包与测试 → 7. 迭代优化
→ 8.（可选）提交到主题市场
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

阶段 1：需求采集

Phase 1: Demand Collection

收集以下信息（一次问全，不要分多轮零碎地问）：
必须收集：
  • 主题名称
  • 基本方向：暗色 / 浅色 / AMOLED 纯黑 / 其他
  • 用户的创意意图（以下任一形式均可）：
    • 情绪/氛围关键词（如"温暖的""赛博朋克""清新自然"）
    • 参考色值（如"我想要粉色系"）
    • 参考应用/网站（如"类似 Spotify 的深绿"）
    • 参考图片（用户直接贴图）
    • 完全自定义的详细描述
可选收集：
  • 作者名
  • 描述
  • 是否需要动态 iframe 背景
  • 是否有自定义图片素材（如背景图、预览图）
Collect the following information (ask all at once, do not ask in multiple fragmented rounds):
Must collect:
  • 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
Optional collection:
  • Author name
  • Description
  • Whether dynamic iframe background is required
  • Whether there are custom image materials (e.g. background image, preview image)

阶段 2：风格定调

Phase 2: Style Determination

基于用户输入，提供 2-3 个风格方向的文字描述（此阶段不写代码）。
每个方向包含：
  • 品牌色色值 + 直观描述
  • 明暗基调
  • 氛围关键词
  • 背景风格（纯色 / 渐变 / 图片 / 动态）
用户选择一个方向，或从多个方向中混合元素。
如果用户已经非常明确 — 比如直接给了色值、给了完整描述，可以跳过此阶段直接进入阶段 3。
Based on user input, provide 2-3 style directions in text description (no code writing at this stage).
Each direction includes:
  • Brand color value + intuitive description
  • Light and dark tone
  • Atmosphere keywords
  • Background style (solid color / gradient / image / dynamic)
The user chooses one direction, or mixes elements from multiple directions.
If the user is already very clear — for example, directly gave the color value, gave a complete description, you can skip this phase and go directly to Phase 3.

阶段 3：调色板生成

Phase 3: Palette Generation

根据选定方向，推导完整调色板。参考 references/color-paradigms.md 中的色彩范式。
向用户展示推导结果，按类别分组：
  1. 品牌色（brand）
  2. 背景色层级（base → sidebar → player → surface → ...）
  3. 文本色层级（primary → secondary → muted → ...）
  4. 边框色层级
  5. 状态色（如果需要自定义）
等待用户确认后进入下一阶段。
Derive the complete palette according to the selected direction. Refer to the color paradigm in references/color-paradigms.md.
Show the derivation results to the user, grouped by category:
  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)
Wait for user confirmation before entering the next phase.

阶段 4：CSS 变量映射

Phase 4: CSS Variable Mapping

将确认的调色板映射到 MusicFree 的语义 CSS 变量。
参考 references/css-variable-reference.md 获取完整变量清单和覆盖规则。
变量覆盖的三级分类：
分类说明
必须覆盖定义主题核心视觉身份的变量，不覆盖等于没换肤
建议覆盖覆盖后主题才完整；浅色主题如果不覆盖会出现暗色残留
禁止覆盖结构性 token（z-index / typography / spacing / layout / control sizes / icon sizes / motion），改了会破坏布局或功能
特殊分类：
  • Shadow / Blur：风格性 token。扁平化/AMOLED 主题可设为 
    none
    ；玻璃态主题可增大 blur 值
  • Radius：默认不覆盖。仅当用户明确要求极端风格时（如纯棱角赛博朋克）才可调整，需告知用户可能导致部分组件视觉异常
  • Background Image (
    --bg-image
    )    ：属于增强层，根据主题风格决定是否覆盖
生成 
index.css
文件，格式参照内置主题：
css
/*
 * 主题名称
 */
:root {
    /* ── Background ── */
    --color-bg-base: ...;
    /* ... */

    /* ── Fill ── */
    --color-fill-brand: ...;
    /* ... */
}
Map the confirmed palette to MusicFree's semantic CSS variables.
Refer to references/css-variable-reference.md for the complete variable list and override rules.
Three-level classification of variable coverage:
CategoryDescription
Must CoverVariables that define the core visual identity of the theme, no coverage means no skin replacement
Recommended to CoverThe theme is complete after coverage; light themes will have dark residues if not covered
Prohibited to CoverStructural tokens (z-index / typography / spacing / layout / control sizes / icon sizes / motion), modification will damage the layout or function
Special Categories:
  • 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
Generate 
index.css
file, the format refers to the built-in theme:
css
/*
 * Theme Name
 */
:root {
    /* ── Background ── */
    --color-bg-base: ...;
    /* ... */

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

阶段 5：增强层（可选）

Phase 5: Enhancement Layer (Optional)

根据主题风格，可选择性地添加增强效果：
5a. 背景渐变（
--bg-image
）
使用 CSS 
radial-gradient
/ 
linear-gradient
组合。推荐使用 
color-mix(in srgb, var(--color-fill-brand) X%, transparent)
引用品牌色，避免硬编码。
5b. 阴影风格调整
  • 柔阴影（默认）：保持默认值
  • 硬阴影：减小 blur-radius，增大 spread
  • 无阴影（AMOLED/扁平化）：全部设为 
    none
5c. 自定义图片资源
如果用户提供了背景图/预览图等素材：
  • 引导压缩图片（推荐 WebP 格式）
  • 单张图片 ≤ 500 KB
  • 在 CSS 中通过 
    @/
    路径引用（如 
    url(@/imgs/bg.webp)
    ）
  • @/
    是路径别名，运行时会被替换为主题包目录的绝对路径
5d. iframe 动态背景
详见 references/iframe-guide.md。
适合场景：粒子效果、动态渐变动画等。
需要额外准备：
  • iframes/app.html
    ：动态背景入口文件
  • config.json 中添加 
    "iframe": { "app": "@/iframes/app.html" }
  • 建议提供 
    blurHash
    字段作为加载占位符（可选但推荐）
According to the theme style, you can selectively add enhancement effects:
5a. Background Gradient (
--bg-image
)
Use CSS 
radial-gradient
/ 
linear-gradient
combination. It is recommended to use 
color-mix(in srgb, var(--color-fill-brand) X%, transparent)
to reference the brand color to avoid hard coding.
5b. Shadow Style Adjustment
  • Soft shadow (default): Keep the default value
  • Hard shadow: Reduce blur-radius, increase spread
  • No shadow (AMOLED/flat): All set to 
    none
5c. Custom Image Resources
If the user provides materials such as background images/preview images:
  • 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
5d. iframe Dynamic Background
See references/iframe-guide.md for details.
Suitable scenarios: particle effects, dynamic gradient animation, etc.
Additional preparation required:
  • 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)

阶段 6：打包与测试

Phase 6: Packaging and Testing

详见 references/packaging-checklist.md。
步骤概览：
  1. 确认文件结构完整
  2. 生成 
    config.json
  3. 检查资源体积
  4. 打包为 
    .mftheme
    （ZIP 格式，改扩展名）
  5. 指导用户安装测试
安装测试指引（告诉用户）：
  1. 打开 MusicFree 桌面版
  2. 进入「主题」页面
  3. 点击「安装主题包」按钮
  4. 选择生成的 
    .mftheme
    文件
  5. 点击主题卡片应用
  6. 检查各页面是否正常显示
See references/packaging-checklist.md for details.
Step Overview:
  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
Installation Test Guide (tell the user):
  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

阶段 7：迭代优化

Phase 7: Iterative Optimization

根据用户测试反馈进行微调。常见反馈和对应处理：
用户反馈可能原因调整方向
"某个区域看不清文字"文本色与背景色对比度不足增大文本色与背景色的亮度差
"按钮看不清"品牌填充色与 on-brand 文本色对比不足调整 
--color-text-on-brand
"侧边栏太暗/太亮"
--color-bg-sidebar
不合适		调整该变量的亮度或透明度
"整体太刺眼"浅色主题背景过白或品牌色过饱和降低背景亮度或品牌色饱和度
"弹窗不明显"overlay/modal 背景色与主背景区分度不够调整 
--color-bg-overlay
透明度
"选中状态看不出来"brand-muted 与 surface 太接近增大 
--color-fill-brand-muted
的透明度
每次修改后重新打包，让用户重新安装测试。
Fine-tune according to user test feedback. Common feedback and corresponding processing:
User FeedbackPossible CauseAdjustment Direction
"The text in a certain area is unclear"Insufficient contrast between text color and background colorIncrease the brightness difference between text color and background color
"The button is unclear"Insufficient contrast between brand fill color and on-brand text colorAdjust 
--color-text-on-brand
"The sidebar is too dark/too bright"
--color-bg-sidebar
is inappropriate		Adjust the brightness or transparency of this variable
"The whole is too dazzling"The light theme background is too white or the brand color is too saturatedReduce the background brightness or brand color saturation
"The pop-up window is not obvious"The distinction between overlay/modal background color and main background is not enoughAdjust the transparency of 
--color-bg-overlay
"The selected state cannot be seen"brand-muted is too close to surfaceIncrease the transparency of 
--color-fill-brand-muted
Repackage after each modification, let the user reinstall and test.

阶段 8（可选）：提交到主题市场

Phase 8 (Optional): Submit to Theme Market

如果用户希望将主题发布到 MusicFree 主题市场：
  1. Fork 仓库：引导用户 Fork MusicFreeThemePacks
  2. 切换分支：基于 
    v1/source
    分支创建开发分支
  3. 创建文件夹：在 
    themes/
    下创建主题文件夹
    • 命名规则：仅允许字母、数字、连字符（
      -
      ）、下划线（
      _
      ）
  4. 补充 tags：在 config.json 中添加 
    tags
    字段（1-5 个标签，从预定义列表选取）
    • 不要在 config.json 中添加 
      id
      字段（ID 由系统自动管理）
    • 动态主题必须包含 
      "动态"
      标签
  5. 本地校验：
    bash
    npm install
npm run validate:theme your-theme-name
  6. 提交 PR：向 
    v1/source
    分支提交 Pull Request
预定义标签列表：
keylabel说明
dark
暗色深色/暗黑系
light
亮色浅色/明亮系
gradient
渐变渐变色背景
minimalist
简约简洁风格
anime
动漫动漫/二次元风格
landscape
风景自然风景背景
illustration
插画插画风格背景
cyberpunk
赛博赛博朋克/科技感
pixel
像素像素风格
abstract
抽象抽象艺术风格
dynamic
动态包含动画效果（有 iframe 必加）
cute
可爱可爱/萌系风格
game
游戏游戏相关
movie
影视电影/动画电影相关
season
季节与季节相关
nature
自然花、樱花、星空等自然元素
If the user wants to publish the theme to the MusicFree 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
Predefined Tag List:
keylabelDescription
dark
暗色Dark color / dark style
light
亮色Light color / bright style
gradient
渐变Gradient background
minimalist
简约Simple style
anime
动漫Anime / two-dimensional style
landscape
风景Natural landscape background
illustration
插画Illustration style background
cyberpunk
赛博Cyberpunk / sense of technology
pixel
像素Pixel style
abstract
抽象Abstract art style
dynamic
动态Contains animation effects (must be added if there is an iframe)
cute
可爱Cute / moe style
game
游戏Game related
movie
影视Movie / animated movie related
season
季节Season related
nature
自然Natural elements such as flowers, cherry blossoms, starry sky, etc.

主题包文件结构

Theme Pack File Structure

my-theme/
├── config.json          # 必须 — 主题元信息
├── index.css            # 必须 — CSS 变量覆盖
├── imgs/                # 可选 — 图片资源
│   ├── preview.webp     # 预览图（推荐 WebP）
│   └── ...
└── iframes/             # 仅动态主题需要
    ├── app.html         # 动态背景入口
    └── ...
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 字段说明

config.json Field Description

jsonc
{
    "name": "主题名称",               // 必须
    "preview": "@/imgs/preview.webp", // 推荐 — 图片路径或 "#hex" 色值
    "description": "主题描述",         // 推荐
    "author": "作者",                 // 推荐
    "authorUrl": "https://...",       // 可选
    "version": "0.0.1",              // 推荐 — 更新时必须递增
    "tags": ["暗色"],                 // 提交到主题市场时需要，1-5 个
    "blurHash": "...",               // 有 iframe 时推荐（加载占位）
    "iframe": {                      // 仅动态主题
        "app": "@/iframes/app.html"
    }
}
注意：
  • preview
    可以是图片路径（如 
    @/imgs/preview.webp
    ）或 CSS 颜色值（如 
    "#1a1a2e"
    ）
  • tags
    在本地开发阶段可省略，提交到主题市场时再补充
  • id
    字段不要手动添加，由主题市场系统自动管理
jsonc
{
    "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"
    }
}
Note:
  • 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

CSS 和 config.json 中的 
@/
是路径别名，指向主题包根目录。运行时会被替换为 
file://
绝对路径。
例如：
  • @/imgs/bg.webp
    → 
    file:///C:/Users/.../themes/my-theme/imgs/bg.webp
  • url(@/imgs/texture.png)
    可在 CSS 中引用本地图片
@/
in CSS and config.json is a path alias pointing to the root directory of the theme pack. It will be replaced with the 
file://
absolute path at runtime.
For example:
  • @/imgs/bg.webp
    → 
    file:///C:/Users/.../themes/my-theme/imgs/bg.webp
  • url(@/imgs/texture.png)
    can reference local images in CSS

资源限制

Resource Limits

约束项限制
单张图片≤ 500 KB
单个视频≤ 5 MB
整个主题包≤ 10 MB
优化建议：
  • 优先使用 WebP 格式（比 PNG/JPG 体积小 25-35%）
  • 用 TinyPNG 等工具压缩图片
  • 优先使用 CSS 渐变替代图片纹理
  • 视频尽量使用较低分辨率或帧率
Constraint ItemLimit
Single image≤ 500 KB
Single video≤ 5 MB
Entire theme pack≤ 10 MB
Optimization Suggestions:
  • 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