Building Kawaiintu OS: Exhaustive MIME-type Icon Mapping on Native GTK4/libadwaita

In the development of Kawaiintu OS (based on Ubuntu 26.04), achieving ultimate visual consistency across the entire desktop was a top priority. To do this within the strict theming boundaries of modern GTK4/libadwaita, I implemented an exhaustive custom MIME-type icon mapping system.

Here is a breakdown of the implementation process, from the core design philosophy to strict system integration.

1. Custom Icon Design: Achieving "Visual Grep"

To ensure every file on the system aligns with Kawaiintu’s unique "Emo & Cool" aesthetic, I created a massive library of custom icons from scratch, completely bypassing standard themes.

• Dynamic Colors & Animal Motifs
  Using a custom Python script to dynamically adjust Hue, Saturation, and Multiply parameters, I generated 9 distinct color themes. Each theme color is paired with a specific animal motif placed in the top-left corner of the icons, balancing a playful vibe with visual consistency.

• High Visibility for Dev Files ("Visual Grep")
  For the overwhelmingly large number of TEXT-based files (source code for various programming languages, config files, etc.), I applied distinct color coding and subtle design accents based on the theme. This allows users to intuitively identify file types at a glance when browsing the file manager. I call this "Visual Grep"—an overwhelming level of searchability and visibility directly within the GUI.

• Universal Formats in SVG
  Beyond standard images, audio, and video, I designed dedicated icons for various archive formats (ZIP, TAR.GZ, etc.). Everything is designed meticulously in SVG to ensure flawless scaling on modern HiDPI displays.

2. Strict Mapping Based on Freedesktop.org Specs

To ensure file managers like GNOME Files and Thunar recognize these custom icons perfectly, I mapped them strictly according to the Freedesktop.org Icon Theme Specification.

• MIME-type Naming Conventions
  Every icon is named to match the system's MIME-type database exactly (e.g., text-plain.svg for generic text, text-x-python.svg for Python scripts, application-pdf.svg for PDFs).

• Symlinking for Complete Coverage
  For similar MIME types (e.g., audio/mpeg and audio/mp3), I heavily utilized symbolic links. This prevents any icons from falling through the cracks while keeping the overall storage footprint minimal.

Defining index.theme

To prevent the system from throwing fetching errors, you must accurately define the context and sizes of the directories holding your MIME types in the root index.theme file.

[Icon Theme]
Name=Kawaiintu-MIME
Comment=Exhaustive MIME-type icon mapping for Kawaiintu OS
Directories=mimes/scalable

[mimes/scalable]
Size=64
Context=MimeTypes
Type=Scalable
MinSize=16
MaxSize=256

3. GTK4 Integration and Cache Control

The final step is securely applying the built icon theme to the OS UI system. Even under the strict theming limits of GTK4, this method guarantees reliable overrides.

① Directory Deployment

Deploy your completed icon theme directory to either the user environment at ~/.local/share/icons/ or globally at /usr/share/icons/.

② Forcing the Cache Update

To prevent delayed icon loading or the system clinging to old cached themes, execute the following command to make the OS recognize the new mapping data instantly:

gtk-update-icon-cache -f -t ~/.local/share/icons/Kawaiintu-MIME

Through exhaustive custom icon development and strict adherence to mapping specifications, I successfully permeated Kawaiintu OS's "Emo & Cool" aesthetic into every corner of the system.