Creating a custom theme for Xiaomi MIUI 12: from idea to installation

Xiaomi’s MIUI 12 shell is famous for its flexibility and customization capabilities, but even hundreds of themes in the Theme Store don’t always meet the needs of users. Want a unique design with its own icons, fonts and animations? Creating your theme is a difficult task, but it is doable even without deep knowledge of programming. In this guide, we will analyze the entire process from preparing the necessary tools to final installation through the.mtz file.

It is important to understand that MIUI 12 has strict restrictions on modifying system files, for example, changing some elements (such as boot animations or system sounds) requires unlocking the bootloader and superuser rights. However, the basic elements — icons, wallpaper, interface styles — can be replaced without the risk of bricking the device. → Theme shop → My topics so that I can roll back in case of mistakes.

This guide will work for most Xiaomi, Redmi and POCO MIUI 12 devices (including MIUI 12.5 and MIUI 12 Enhanced Edition).If your device is running a newer version (e.g. MIUI 13/14), some steps may differ – check compatibility in advance.

1.Preparation: What will be needed to create a topic

Before you start designing, you can collect all the tools and files you need, and without them, the process of creating a theme becomes a agonizing search for a solution on the go.

• 📱 Xiaomi smartphone on the MIUI 12 (preferably with an unlocked bootloader for advanced features).
• 💻 Windows computer 10/11 macOS (for working with graphic editors).
• 🎨 Design software: Adobe Photoshop (or free analogues) GIMP, Krita) for creating icons and wallpaper, Figma for prototyping.
• 📂 Theme templates for MIUI (You can download it in official communities or forums like XDA Developers).
• 🔧 Utilities: MIUI Theme Editor (for packaging themes), MTZ Manager (for installation), ADB (debug).

Icons for MIUI 12 should be in PNG format with a transparent background and a resolution of 192×192 pixels (for the main ones) and 144×144 pixels (for folders), wallpaper is better prepared in a resolution of 1080×2340 pixels (for most modern smartphones) or 1440×3200 pixels (for flagships with 2K displays).

⚠️ Note: Do not use copyrighted images (e.g. logos of brands or characters from games/movies). Xiaomi can block such a theme from uploading to the Theme Store, and in some cases even suspend your account.

If you plan to distribute your theme, register as a developer on MIUI Themes Platform at https://zhuti.xiaomi.com. This will open access to official tools and documentation. Registration is not required for personal use.

2. Theme Structure: Which Files and Folders Should Be Modified

The theme for MIUI 12 is an archive with a rigid folder structure, and if you break the hierarchy, the system simply doesn't recognize the.mtz file.

To make things easier, download an empty theme template from Xiaomi’s official repository or forums. For example, 4PDA often posts current workpieces, unpacks the archive and explores the contents, which will help avoid errors when adding your files.

Pay special attention to the file description.xml. It indicates:

• 📌 <name> — title of the topic (maximum) 20 symbolism).
• 🖌️ <author> — your name.
• 🔢 <version> — version of the topic, for example, 1.0.0).
• 📅 <compatVersion> — version-compatibility MIUI (point out 12 or 12.5).

⚠️ Note: If the compatVersion specifies an incorrect version (e.g. 14 for the MIUI 12), the theme will either fail or cause a crash in the interface!

To edit description.xml, use any text editor (such as Notepad++ or VS Code). Avoid editors like Word or Windows Notepad, which can ruin the encoding of the file.

💡

Save backups of the theme files after every significant change, for example, after editing icons or wallpaper, create a folder. backup_The name of the item with the current version, which will save you hours of operation for random errors.

3. Design of icons: requirements and recommendations

Icons are the most visible element of the theme, so there are strict requirements for their design.

• 🎨 Style: All icons should be made in the same style (flat, voluminous, with shadows, etc.
• 🔍 Readability: The icon must be recognizable even when sized 48×48 pixels (as it is displayed in the notification panel).
• 🖼️ Format: Only PNG transparently (RGBA). JPG or WEBP unsupported.
• 📏 Sizes: 192×192 px – the main icons of applications; 144×144 px - folder icons; 96×96 px – icons in the notification panel.

To speed up, use script-based icon generation. For example, you can write Action in Photoshop, which will automatically trim the icon to the right size and save it in the right format. GitHub has ready-made batch processing scripts (see MIUI icon batch processor if you ask).

If you are not an artist, use free CC0-licensed icon sets (such as Flaticon or Iconfinder), and adapt them to MIUI requirements: trim them to the right sizes and make sure they look good on dark and light backgrounds (MIUI themes support both modes).

Icons have the same style and color gamut | All icons are saved in PNG format with transparency | Dimensions meet requirements (192x192, 144x144, 96x96) | Icons were tested on dark and light background | There are backups of the original files-->

4. Wallpaper and screensavers: how to avoid sprains and artifacts

Wallpaper MIUI 12 should take into account the features of Xiaomi displays: aspect ratio, cutout for the front camera (if any) and support for Always-on Display (for example, for the camera). AMOLED-Here are the key recommendations:

• 📱 Permit: Minimum — 1080×2340 px (for px) FHD+ displays), optimal — 1440×3200 px (for px) 2K).
• 🖼️ Format: JPG or PNG (transparently). PNG preferable to gradient-based wallpapers.
• 🎨 Security Zones: Important wallpaper elements (faces, logos) should not fall under: Camera Notch (if any); Notification Area (top edge); Sign Area (bottom edge, ~100 px).
• 🌓 Dark and light topics: Wallpaper should look good in both modes. Avoid images that are too dark or too light.

To create wallpapers with a camera cutout, use templates from Xiaomi. You can find them in the official documentation for theme developers or forums. For example, for the Redmi Note 10 Pro (with a central notch) and Xiaomi 11T Pro (with a left notch), the templates will be different.

If you want to add animated wallpaper, you will have to use the GIF or APNG format, but note:

• 🐢 The animation should not be too fast (optimally — 10-15 frame-of-second).
• 📴 File size – no more than 5 MB (otherwise the topic will not be installed).
• 🔋 Animated wallpaper increases battery consumption on 5-15%.

⚠️ Warning: Wallpaper with text or small details may look blurry on displays with the resolution below FHD+ (Like Redmi. 9A s 720p). Always test the wallpaper on the target device!

To check wallpaper, use the Wallpaper Preview app (available on Google Play), which lets you see how the wallpaper will look with the cutouts and MIUI interface.

5. Packing theme in MTZ: step-by-step instruction

When all the theme elements are ready, they need to be packaged into a.mtz file, the only format that MIUI recognizes.

1. Download MIUI Theme Editor. The official version can be found on the Xiaomi forum or in the Telegram channels of the developers of the theme. Avoid pirated builds - they may contain viruses.
2. Import files. Open the program, select File → Import Theme Folder, and specify the path to the folder with your theme.
3. Check the structure. The utility will show warnings if any files are missing or incorrect format.
4. Fill in metadata. Enter the title of the topic, version, description, etc. This data will be displayed in the Theme Store.
5. Gather it. MTZ. Press Build. → Create MTZ and save the file to a convenient location (for example, on the desktop).

The.mtz file can be installed in two ways:

• 📱 Through Theme Store: Copy the file to your smartphone (e.g., Download folder). Open a Theme Store → My subjects. → Import. Select your.mtz and confirm installation.
• 💻 Through ADB (For advanced users: adb push theme.mtz /sdcard/MIUI/theme/ adb shell am broadcast -a miui.intent.action.CHANGE_THEME --es theme_pkg_name com.android.theme.default This method requires enabled debugging USB and superuser rights.
• Here are the most common errors and ways to fix them: Error Reason Decision Topic not installed ("File corrupted") Wrong folder structure or error in description.xml Check the structure by template, repackage the theme of icons do not change the mismatch of the names of the icon files with the system MIUI Icon Naming Tool for name check Wallpaper stretched or cropped Wrong resolution or aspect ratio Resave wallpaper in the correct resolution (for example, 1080×2340 px) Theme applies but fails with style.css error or version incompatibility MIUI Remove custom styles or check compatVersion in description.xml No animations working Incorrect format or size GIF/APNG Optimize the animation (maximum) 5 MB, 15 FPS) If none of the solutions worked, try: Delete all custom themes through Settings → Theme shop → Reset to Wait for moderation. The process takes 3 before 7 If the topic is rejected, you'll get a reason for it: 🌍 XDA Developers (part of Xiaomi Themes). 📱 4PDA (Xiaomi). 💬 Telegram channels (e.g, @MIUIThemes). ⚠️ Note: When you publish in a Theme Store, Xiaomi becomes a co-owner of your theme, which means that the company can modify or distribute it without your consent (but with attribution of authorship). To increase the popularity of the topic: 📢 Add it to social networks (for example, to Xiaomi groups on Facebook or Facebook). VK). 🎥 Take short video reviews (you can use Screen Recorder). 🔄 Update theme regularly (fix bugs, add new items). 8. Frequent Errors and Their Solutions Even experienced theme developers face challenges. Clear the Theme Store cache (Settings) → Annexes → Application management → Theme shop → Clear cache. Reboot the device. Reset the theme. If the problem persists, contact forums (e.g., forums) for help, XDA or 4PDA). Attach to the message: Version MIUI The device model is an adb logcat, screenshots of the problem,.mtz file (if possible). 💡Most of the themes are made with version incompatible versions or file structure disruptions. Always check the theme on clean firmware before publishing. FAQ: Answers to frequent questions: Can you create a theme without a computer, only on your phone? Technically, but it's extremely inconvenient. You'll need: an image editing app (like PicsArt or Photoshop Express). A file manager with support ZIP (For example, Solid Explorer). Theme packaging app (e.g. MTZ Builder from Google Play). However, without a computer it is difficult to control the accuracy of the sizes of icons and wallpapers, so the result can be poor quality. Why does my theme work on one device but not installed on another? This is due to: Different versions of MIUI. For example, the the theme for MIUI 12.0 may not be supported on MIUI 12.5. Different screen resolutions. Wallpaper or icons may not be suitable for displays with non-standard aspect ratios (e.g. 21:9 on Xiaomi Mix 4).