Developing Sliprail Themes

A Sliprail theme is a registered theme manifest plus a CSS file and optional image assets. Themes do not export JavaScript.

manifest.json

A theme manifest requires id, displayName, description, main, and type.

{
  "id": "your-registered-theme-id",
  "displayName": {
    "en": "My Theme",
    "zh-hans": "我的主题"
  },
  "description": {
    "en": "A custom Sliprail launcher theme",
    "zh-hans": "一个自定义 Sliprail 启动器主题"
  },
  "main": "main.css",
  "type": "Theme",
  "preview": "preview.png",
  "icon": "icon.svg",
  "theme": {
    "appearance": "Dark",
    "extend": {
      "top": 24,
      "right": 24,
      "bottom": 24,
      "left": 24
    }
  }
}

• id - The theme ID registered in the Developer Portal
• displayName - A string or language map shown in Sliprail
• description - A string or language map used in theme details
• main - The CSS file loaded by Sliprail. Keep theme styles in this file and avoid @import
• type - Must be Theme
• preview - Optional local preview image filename
• icon - Optional local file, HTTP URL, data URI, or icon options object
• theme.appearance - Optional base appearance. Supported values are Light, Dark, and FollowSystem
• theme.extend - Optional extra space around the launcher for decorative elements. Each side accepts a value from 0 to 500

Relative url(...) references inside main.css are resolved from the theme directory.

Theme Selectors

Use these stable class names to style the desktop launcher:

• .window - The outer theme canvas. Use it for background images and decorative content around the launcher
• .window-foreground - A pointer-transparent foreground layer for overlays and illustrations
• .main - The launcher content container. Apply the main background and frame styles here
• .search-input-box - The search input container
• .results - The search result area
• .result-item - A result row
• .result-item-selected - The active result row
• .result-item-title - The result title
• .result-item-subtitle - The result subtitle
• .app-icon - App and window icons in result rows

The default outer padding is 10 pixels before any theme.extend value is added. Avoid changing result row height or adding expensive transitions because the list updates continuously while the user types.

Test a Theme

1. Register a public or private theme and copy its ID
2. Open Sliprail Settings > All Themes
3. Open the file menu and choose Load Unpacked Theme
4. Select the directory containing manifest.json
5. Choose the loaded theme from the theme list

After editing CSS, load the unpacked theme again or restart Sliprail to refresh it.

Run GenerateThemePreview while the launcher is focused to capture the current window and save a lossless WebP preview in the Downloads folder.

Publish a Public Theme

1. Create a public GitHub repository
2. Register a public Sliprail theme and attach the repository URL
3. Set the registered ID in manifest.json
4. Include the manifest, CSS, preview, icon, and all referenced assets in the repository
5. Push the completed theme and publish it from the Developer Portal

Published themes can appear in the Sliprail theme store. Eligible GitHub themes are checked for new commits by Sliprail's update system.

Use a Private Theme

Register the theme as private, use its ID in the manifest, and load the unpacked directory or ZIP file from All Themes. Local unpacked themes remain on the current device and are not automatically synchronized.