Xiaomi custom theme builder: a complete guide with nuances for MIUI 14/15

Creating your own Xiaomi theme is a way to stand out from the millions of MIUI users who are content with standard designs. Custom themes allow you to change not only wallpaper and icons, but also animations, fonts, system notification sounds, and the interface of embedded applications. However, the process of building a theme often scares beginners: you need to understand the structure of MIUI files, find compatible resources and avoid errors that can lead to system failures.

In this article, we will look at the whole process from A to Z, from tool preparation to uploading a finished theme to the Xiaomi Theme Store. Particular attention will be paid to the new requirements of MIUI 15 for theme packages (the mandatory APK signature and file size restrictions), as well as the typical problems that developers face when testing on Redmi Note 12, POCO F5 and Xiaomi 13 devices. If you have never done an interface modification, but want to try – this guide will help avoid common errors and save hours of finding solutions.

1. What you need to build a theme: tools and requirements

Before you start creating a theme, make sure you have everything you need.

• 📱 Xiaomi smartphone on the MIUI 12 or later (for testing) on devices with MIUI 11 and below may have problems with compatibility of new formats of theme.
• 💻 Windows computer 10/11 or macOS (for assembly) APK). Linux is partially supported, but additional libraries may be required.
• 📂 MIUI Theme Editor is the official software from Xiaomi for editing themes (you can download on the official website — MT Manager for manual file editing.
• 🔧 Java JDK 8 or 11 – required for compilation APK. New versions JDK (17+) They can cause errors in assembly.
• 🎨 Graphic editors: Adobe Photoshop (for icons), Figma or GIMP (wallpaper).

You will also need a developer account at Xiaomi Theme Store, which can be created for free, but you will need verification to publish themes (can take up to 3 days). Note: since 2023, Xiaomi has tightened the rules – now all topics must be moderated to comply with the rules of content, including a ban on the use of brand logos without permission.

2. MIUI Theme Structure: Which Files and Folders Are Required

The MIUI theme is an archive with an extension of.mtz (older versions) or.apk (newer versions), and it has to have a clear folder structure inside it, otherwise the system won't recognize the topic.

miui/


├── description.xml # Metadata topics (title, version, author)




├── preview/ # Store Preview (5-7 screenshots)




│   ├── preview1.jpg




│   └── preview2.jpg




├── wallpaper/ # Wallpaper (resolution at least 1080×1920)




├── icon/ # Icons (format PNG, size 192×192




├── lockscreen/ # Lock screen elements




├── font/ # Fonts (TTF or OTF)




└── animation/ # Animations (format GIF or Lottie JSON)

Critical files without which the topic will not load:

• 📄 description.xml — contains the name of the topic, version MIUI, the author's identifier for which it is intended, and the author's identifier:

<theme>


<name>MyCustomTheme</name>




<author>YourName</author>




<version>1.0</version>




<targetMiuiVersion>15</targetMiuiVersion>




<packageName>com.example.mycustomtheme</packageName>




</theme>

If you miss the targetMiuiVersion field or provide the wrong version, the theme will either not install or will malfunction. For example, the themes for MIUI 14 may not display correctly on MIUI 15 due to changes in the structure of system applications.

💡

Use the APKTool tool to decompile ready-made themes from the store – this will help you understand how popular solutions work.

3. Step-by-step instruction: create a theme from scratch

Consider the process of creating a simple theme with modified icons and wallpapers, and complex themes (with animations or custom fonts) require additional steps.

Step 1: Resource preparation

Collect all the necessary files:

• 🖼️ Wallpaper (permission not less than 1080×2340 modern-day smartphones).
• 📱 Icons (size) 192×192 px, format PNG For convenience, use the templates from Flaticon.
• 🎬 Animations (if needed) in format GIF or Lottie JSON.

Step 2: Editing in MIUI Theme Editor

1. Open MIUI Theme Editor and create a new project.

2. Import the prepared resources to the appropriate folders (wallpaper, icon, etc.).

3. Edit description.xml – specify the title of the topic, version and target MIUI.

4. Save the project in.mtz (for testing) or.apk (for publishing).

The icons are 192×192 px| in size.

Wallpaper optimized for screen resolution |

File. description.xml well-filled|

Theme tested on the target version MIUI-->

Step 3: Testing on the device

Transfer the.mtz file to your smartphone and install it through the Themes app (Settings → Display → Themes → Local).

• 🔍 Correctness of the display of icons (whether there are croppings or distortions).
• 🎨 Color schemes in the system menu (settings, notifications).
• 🔄 The work of animations (if any).

4.Typical mistakes and how to avoid them

Even experienced developers have problems with building themes, and here are the most common mistakes and solutions:

Pay special attention to the signature APK. From 2026, Xiaomi requires all themes in the store to be digitally signed:

1. Generate the key with the keytool:
2. Sign up for APK with jarsigner:

💡

Without an APK signature, the theme will not be moderated in the Xiaomi Theme Store, even if it works locally.

5.Publishing the theme in the Theme Store

Once the theme is ready and tested, it can be uploaded to the official store.

1. Sign in to themes.xiaomi.com under your developer account.
2. Go to the section Download the topic and fill out the form: 📌 Title (maximum) 20 symbolism). 📝 Description (up to) 200 symbols, can be in several languages). 🖼️ Preview (5-7 Screenshots showing key elements of the topic). 🔖 Tags (select the appropriate ones: Minimalism, Dark Theme, Anime, etc.).

.apk

Send it to moderation. The test period is 1 to 3 days.

Once approved, the theme will be available to all MIUI users, and for each jump you will receive points that can be exchanged for prizes in Mi Credit.

⚠️ Note: Xiaomi is blocking themes that contain:

• 🚫 Brand logos (Apple, Samsung, etc.) without permission.
• 🚫 Content 18+ or provocative images.
• 🚫 Elements that disrupt the system (e.g., changing system fonts without checking compatibility).

6. Optimizing theme for different Xiaomi models

The same theme may appear differently on the Xiaomi 13 Ultra and Redmi 10A due to differences in screen resolution and MIUI version.

• 📏 Adaptive wallpaper: Use images with at least a resolution 1440×3200 For flagships and optimize them for 720×1600 budgetary.
• 🎨 Icons: Check the display on high-pixel density screens (400)+ PPI). Nana POCO F4 GT Icons can look small, if you do not consider the scale.
• 🔄 Animations: On 60Hz devices (like the Redmi Note 11), complex animations can slow down.

For devices with AMOLED-screens (e.g. Xiaomi) 12T Pro) it is recommended to add dark versions of wallpaper and icons to reduce battery consumption. description.xml You can also indicate support for the dark mode:

<theme>


...




<supportDarkMode>true</supportDarkMode>




<darkWallpaper>wallpaper/dark.jpg</darkWallpaper>




</theme>

💡

To test on different devices, use emulators in Android Studio with Xiaomi profiles (available in AVD Manager).

7. Alternative means of disseminating topics

If your theme has not been moderated in the official store or you want to share it in a narrow circle, there are alternative options:

• 🌐 Telegram channels: many communities are dedicated to custom topics for MIUI (for example, @MIUIThemes).
• 💾 Forums: XDA Developers, 4PDA or Mi Community (Section "Themes and Design").
• 📦 Own site: You can upload a theme to GitHub or cloud storage with installation instructions.

When distributing via third-party sources, consider:

⚠️ Note: Users must manually allow installation of topics from unknown sources (Settings) → Annexes → Installation of unknown applications → Without it, the system will block the installation of.mtz or.apk.

FAQ: Frequent questions about assembling themes