deveco_hmigbot 0.21.5

package/skills/migrate-core/references/topics/resources/dependency-analysis-rules.md

@@ -0,0 +1,328 @@
+# Android Resource Dependency Analysis Rules
+
+This document defines how to extract, track, and resolve inter-resource dependencies during Android-to-HarmonyOS resource conversion. Dependency analysis runs regardless of resource source — whether from a decompiled APK (complete resource set) or from the project's source `res/` directory (potentially missing library resources). When working from source `res/`, more references will be unresolvable, but the analysis is still essential to identify exactly what's missing and why.
+
+## Table of Contents
+1. [Resource Reference Patterns](#resource-reference-patterns)
+2. [Building the Resource Value Lookup Table](#building-the-resource-value-lookup-table)
+3. [Resolving References to True Values](#resolving-references-to-true-values)
+4. [Where to Scan for Dependencies](#where-to-scan-for-dependencies)
+5. [Dependency Verification](#dependency-verification)
+6. [Handling Missing Library Resources](#handling-missing-library-resources)
+
+---
+
+## Resource Reference Patterns
+
+Android resources reference each other using `@type/name` syntax. Extract these references from XML attribute values and text content.
+
+### Reference Regex Pattern
+
+Use the following pattern to extract resource references from any XML content:
+
+```
+@(color|drawable|mipmap|string|dimen|integer|bool|array|style|attr|id|layout|menu|anim|animator|raw|font|xml|plurals)/([a-zA-Z_][a-zA-Z0-9_]*)
+```
+
+This captures:
+- Group 1: resource type (`color`, `drawable`, etc.)
+- Group 2: resource name
+
+### System Resource References
+
+References prefixed with `@android:` (e.g., `@android:color/black`, `@android:drawable/ic_menu_close`) are Android framework resources provided by the OS. These do NOT need to be tracked as dependencies — they have no equivalent that needs to be migrated. Log them as "system resource reference" but do not flag them as unsatisfied.
+
+### Theme Attribute References
+
+References using `?attr/name` or `?android:attr/name` are theme attribute references resolved at runtime. These **cannot** be statically resolved — they depend on which theme is applied at runtime. Log them as "unresolvable theme attribute" and keep the reference as-is in the converted output.
+
+### Reference Locations in XML
+
+Resource references can appear in several places within Android XML files:
+
+**1. XML attribute values:**
+```xml
+<background android:drawable="@color/md_amber_700" />
+<TextView android:text="@string/hello" android:textColor="@color/primary" />
+<ImageView android:src="@drawable/icon" />
+```
+
+**2. Style/theme item values:**
+```xml
+<style name="AppTheme">
+    <item name="colorPrimary">@color/primary</item>
+    <item name="android:windowBackground">@drawable/bg_window</item>
+</style>
+```
+
+**3. Color state list references:**
+```xml
+<selector>
+    <item android:color="@color/pressed_color" android:state_pressed="true" />
+    <item android:color="@color/default_color" />
+</selector>
+```
+
+**4. Drawable XML references:**
+```xml
+<layer-list>
+    <item android:drawable="@drawable/bg_layer" />
+</layer-list>
+
+<adaptive-icon>
+    <background android:drawable="@color/ic_bg" />
+    <foreground android:drawable="@mipmap/ic_fg" />
+</adaptive-icon>
+```
+
+**5. Values XML cross-references (these are the primary targets for resolution):**
+```xml
+<!-- colors.xml -->
+<color name="primary_light">@color/primary</color>
+
+<!-- dimens.xml -->
+<color name="margin_double">@dimen/margin_base</color>
+```
+
+---
+
+## Building the Resource Value Lookup Table
+
+Before resolving references, build a complete lookup table from the resource source directory (either decompiled `res/` or source `res/`). When using the decompiled APK, this table will be comprehensive. When using source `res/`, it will only contain app-defined resources — library resources will be absent, and references to them will be flagged during verification.
+
+### Value Resources
+
+Parse all `values*/*.xml` files and build mappings:
+
+```
+colors:
+  "primary" → "#FF6200EE"
+  "primary_light" → "@color/primary"     # reference chain — will be resolved
+  "md_blue_500" → "#2196F3"
+
+dimens:
+  "margin_base" → "16dp"
+  "margin_double" → "@dimen/margin_base"  # reference chain
+
+strings:
+  "app_name" → "My App"
+  "greeting" → "Hello, %1$s!"
+
+integers:
+  "max_items" → "10"
+
+bools:
+  "is_tablet" → "false"
+```
+
+Include ALL qualifier variants (e.g., `values/colors.xml`, `values-night/colors.xml`, `values-ar/colors.xml`). Each qualifier variant gets its own entry in the lookup table.
+
+### File Resources
+
+Record all drawable and mipmap files:
+
+```
+drawables:
+  "icon" → "drawable/icon.png"
+  "bg_card" → "drawable/bg_card.xml" (shape)
+  "ic_arrow" → "drawable/ic_arrow.xml" (vector)
+
+mipmaps:
+  "ic_launcher" → "mipmap-anydpi-v26/ic_launcher.xml" (adaptive-icon)
+  "ic_launcher_foreground" → "mipmap-xxxhdpi/ic_launcher_foreground.png"
+```
+
+---
+
+## Resolving References to True Values
+
+The key step: walk through all resource values and replace references with actual concrete values.
+
+### Resolution Algorithm
+
+```
+function resolve(type, name, qualifier, depth=0):
+    if depth > 5: return UNRESOLVABLE  # prevent infinite loops
+    value = lookup_table[qualifier][type][name]
+    if value is a concrete value (hex color, number, string literal):
+        return value
+    if value matches @type/other_name:
+        return resolve(type, other_name, qualifier, depth+1)
+    if value matches ?attr/name:
+        return UNRESOLVABLE  # theme attribute, cannot resolve statically
+    return value
+```
+
+### What Gets Resolved
+
+**Value-to-value references** (primary targets):
+- `@color/name` → resolved hex color (e.g., `@color/primary` → `#FF6200EE`)
+- `@dimen/name` → resolved dimension value (e.g., `@dimen/margin_base` → `16dp`)
+- `@string/name` → resolved string value
+- `@integer/name` → resolved integer value
+- `@bool/name` → resolved boolean value
+
+**File references** (kept as HarmonyOS references, not resolved to values):
+- `@drawable/name` → `$media:name` (the file itself is converted separately)
+- `@mipmap/name` → `$media:name`
+
+**Unresolvable references** (logged but kept as-is):
+- `?attr/name` — theme attributes depend on runtime theme
+- `@android:type/name` — system resources, provided by the platform
+- `@style/name` — styles have no HarmonyOS equivalent
+
+### Resolution During Conversion
+
+Resolution happens at conversion time, not as a separate pass. When converting a value from Android XML to HarmonyOS JSON:
+
+1. Parse the XML value
+2. If it's a concrete value (hex color, number, string), convert directly using format rules
+3. If it's a resource reference (`@type/name`):
+   a. Look up in the lookup table
+   b. Follow the chain to the concrete value
+   c. Convert the concrete value using format rules
+   d. Use the resolved concrete value in the HarmonyOS JSON output
+4. If the reference can't be resolved, use HarmonyOS reference syntax (`$color:name`, `$float:name`, etc.) and log it
+
+### Example: Full Resolution Chain
+
+Android `values/colors.xml`:
+```xml
+<color name="app_background">@color/surface_color</color>
+<color name="surface_color">@color/md_grey_50</color>
+<color name="md_grey_50">#FAFAFA</color>
+```
+
+Resolution:
+- `app_background` → `@color/surface_color` → `@color/md_grey_50` → `#FAFAFA`
+
+HarmonyOS `color.json` output:
+```json
+{
+  "color": [
+    {"name": "app_background", "value": "#ffFAFAFA"},
+    {"name": "surface_color", "value": "#ffFAFAFA"},
+    {"name": "md_grey_50", "value": "#ffFAFAFA"}
+  ]
+}
+```
+
+All three resolve to the same concrete value. The `#ffFAFAFA` format is after applying the `#RRGGBB` → `#ffRRGGBB` color format conversion.
+
+---
+
+## Where to Scan for Dependencies
+
+Scan ALL resource files from the resource source directory for dependencies, organized by priority:
+
+### High Priority (converted resources — broken dependencies cause direct errors)
+
+| File Type | Typical Location | Why It Matters |
+|---|---|---|
+| Adaptive icon XML | `mipmap-anydpi-v26/*.xml` | References colors, drawables, mipmaps for icon layers |
+| Vector drawables | `drawable/*.xml` (root: `<vector>`) | May reference colors via theme attrs |
+| Shape drawables | `drawable/*.xml` (root: `<shape>`) | May reference colors, dimens |
+| Layer-list drawables | `drawable/*.xml` (root: `<layer-list>`) | References other drawables |
+| Selector drawables | `drawable/*.xml` (root: `<selector>`) | References other drawables for states |
+| Color state lists | `color/*.xml` | References other colors |
+| Values XML | `values*/*.xml` | Cross-references between value types |
+
+### Required — Layout and Menu (not converted, but dependencies must be verified)
+
+Layout and menu files are **not** converted to HarmonyOS (they use ArkUI instead), but the resources they reference — strings, colors, drawables, dimensions — **must** be present in the converted output so the developer has everything needed when rebuilding the UI.
+
+| File Type | Typical Location | Why It Matters |
+|---|---|---|
+| Layout XML | `layout*/*.xml` | References strings, colors, drawables, dimens used by every UI component |
+| Menu XML | `menu/*.xml` | References strings and drawables for action bar / navigation items |
+
+### Skip (no meaningful dependencies)
+
+- Raw files (`raw/`)
+- Font files (`font/`) — unless font XML family definitions reference other fonts
+- Image files (PNG, JPG, WEBP, etc.) — binary files, no references
+
+---
+
+## Dependency Verification
+
+After conversion with reference resolution, verify that the output is self-consistent:
+
+### Check by Resource Type
+
+| Dependency Type | Where to Check in HarmonyOS Output |
+|---|---|
+| `@color/name` | Should be resolved to hex in `*/element/color.json`. If not resolved, check `name` exists. |
+| `@drawable/name` | Look for `name.*` (any extension: .png, .svg, .jpg, etc.) in `*/media/` |
+| `@mipmap/name` | Same as drawable — mipmaps go to `media/` in HarmonyOS |
+| `@string/name` | Should be resolved to literal in `*/element/string.json`. If not resolved, check `name` exists. |
+| `@dimen/name` | Should be resolved to value in `*/element/float.json`. If not resolved, check `name` exists. |
+| `@integer/name` | Look for `name` in `*/element/integer.json` |
+| `@bool/name` | Look for `name` in `*/element/boolean.json` |
+| `@array/name` | Look for `name` in `*/element/strarray.json` or `*/element/intarray.json` |
+| `@plurals/name` | Look for `name` in `*/element/plural.json` |
+| `@style/name` | Mark as "unmappable type" (styles have no HarmonyOS equivalent) |
+| `@attr/name` | Mark as "unmappable type" |
+| `@layout/name` | Mark as "not applicable" (layouts aren't converted) |
+| `@id/name` | Mark as "not applicable" (IDs are code-level concerns) |
+
+### Qualifier Coverage Check
+
+When a dependency is satisfied, also verify qualifier coverage. If the dependent resource exists in multiple qualifier directories (e.g., `base`, `dark`, `ldpi`), the dependency should ideally exist in matching qualifier directories. Flag cases where a dependency exists in `base` but the dependent resource also has `dark` or density-qualified variants — the dependency may need those variants too.
+
+---
+
+## Handling Missing Library Resources
+
+When converting from source `res/` (because the APK build failed or no APK was available), library-provided resources will be absent from the lookup table. This section describes how to handle these gaps gracefully.
+
+### Identifying Library Resources
+
+Many common Android libraries define resources with recognizable naming patterns. Use these heuristics to correlate unsatisfied dependencies with likely library sources:
+
+| Library | Common Resource Prefixes |
+|---|---|
+| Material Components (`com.google.android.material`) | `material_*`, `design_*`, `mtrl_*`, `Widget.Material*`, `Theme.Material*` |
+| AndroidX AppCompat (`androidx.appcompat`) | `abc_*`, `Widget.AppCompat.*` |
+| AndroidX Core (`androidx.core`) | `notification_*`, `compat_*` |
+| AndroidX ConstraintLayout | `constraint_*` |
+| Google Play Services | `common_google_*` |
+
+### Extracting Library Dependencies from build.gradle
+
+Parse `build.gradle` or `build.gradle.kts` to identify declared library dependencies:
+
+```groovy
+// build.gradle
+dependencies {
+    implementation 'com.google.android.material:material:1.9.0'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'androidx.core:core-ktx:1.12.0'
+}
+```
+
+Extract the group:artifact for each dependency. In the conversion report, list these libraries with their likely resource prefixes so the developer knows which libraries contribute which missing resources.
+
+### Resolution Behavior for Missing Resources
+
+When a reference cannot be resolved because the target resource is not in the lookup table:
+
+1. **Keep the HarmonyOS reference syntax** (`$color:name`, `$float:name`, `$media:name`, etc.) in the converted output — this makes the reference visible and searchable
+2. **Log it as an unsatisfied dependency** with:
+   - The reference (`@color/design_default_color_primary`)
+   - The source file where it was found
+   - The likely library source (if identifiable from naming patterns)
+   - The reason: "Library resource not available in source res/"
+3. **Do NOT substitute a default or placeholder value** — keeping the reference intact is more useful because:
+   - The developer can see exactly what's missing
+   - If the build is later fixed and resources re-converted from the APK, the output will be correct
+   - The reference name itself carries meaning for the developer
+
+### Categorizing Unresolved References
+
+In the report, separate unresolved references into categories:
+
+1. **Missing library resources** — references to resources that likely come from declared library dependencies. These are expected when converting from source `res/`.
+2. **Theme attributes** (`?attr/name`) — cannot be statically resolved regardless of resource source.
+3. **System resources** (`@android:type/name`) — Android framework resources, not migrated.
+4. **Truly missing** — references that don't match any known library pattern and aren't in the lookup table. These may indicate a project misconfiguration or an undeclared dependency.

package/skills/migrate-core/references/topics/resources/material-design-icons.md

@@ -0,0 +1,173 @@
+# Material Design Icon Download and Integration
+
+When Android source code uses Material Design `imageVector` (such as `Icons.Outlined.Home`) to reference icons, you need to download the corresponding SVG from Google Fonts and integrate it into the HarmonyOS project.
+
+---
+
+## Complete Workflow
+
+### 1. Identify Icon References in Android Source Code
+
+Search for icon definition files in the Android source code (usually enum classes or sealed classes) to identify two types of icons:
+
+| Reference Type | Example | Source |
+|---------------|---------|--------|
+| `imageVector = Icons.Outlined.Xxx` | `Icons.Outlined.Share` | Material Design icon library, download from Google Fonts |
+| `iconResId = R.drawable.xxx` | `R.drawable.ic_touch_enabled` | Project custom drawable, extract from Android `res/drawable/` |
+
+**Typical Source Code Example** (Kotlin sealed class):
+
+```kotlin
+data object Share : ToolbarAction(
+    title = R.string.share,
+    iconResId = R.drawable.ic_share,          // Custom icon
+    imageVector = Icons.Outlined.Share,        // Material Design icon
+)
+```
+
+When both `iconResId` and `imageVector` exist, **prefer the Material Design icon corresponding to `imageVector`** (more standardized, clearer).
+
+### 2. Map Icon Names
+
+Convert `Icons.Outlined.Xxx` camelCase names from Kotlin to snake_case used by Google Fonts:
+
+| Kotlin Name | snake_case Name | Download File Name |
+|-------------|-----------------|-------------------|
+| `Icons.Outlined.Share` | `share` | `md_share.svg` |
+| `Icons.Outlined.AddHome` | `add_home` | `md_add_home.svg` |
+| `Icons.Outlined.EditNote` | `edit_note` | `md_edit_note.svg` |
+| `Icons.Outlined.ChromeReaderMode` | `chrome_reader_mode` | `md_chrome_reader_mode.svg` |
+| `Icons.Outlined.LibraryBooks` | `library_books` | `md_library_books.svg` |
+
+**Conversion Rule**: camelCase → lowercase + underscore separation (`AddHome` → `add_home`).
+
+### 3. Download SVG
+
+**Download source**: https://fonts.google.com/icons?icon.size=24&icon.color=%231f1f1f
+
+**Manual download method**:
+1. Open the Google Fonts Icons webpage above
+2. Search for icon name (e.g., `share`, `add_home`)
+3. Select **Outlined** style (corresponds to `Icons.Outlined`)
+4. Click to download SVG, choose 24px size, color `#1f1f1f` (dark black)
+
+**Download URL pattern** (can be used for batch download scripts):
+```
+https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/{icon_name}/default/24px.svg
+```
+
+Example:
+```
+https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/share/default/24px.svg
+https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/add_home/default/24px.svg
+```
+
+**Note**:
+- The SVG downloaded from this URL has `fill="#000000"` (pure black)
+- Downloaded SVG size is `viewBox="0 -960 960 960"` (Google standard Material Symbols coordinate system), renders correctly in HarmonyOS
+- If an icon name doesn't exist in `materialsymbolsoutlined`, try `materialsymbolsrounded` or `materialsymbolssharp`
+
+### 4. Rename and Store
+
+**Naming rule**: Add `md_` prefix + snake_case name uniformly
+
+```
+Downloaded share.svg     → md_share.svg
+Downloaded add_home.svg  → md_add_home.svg
+```
+
+**Storage location**: `entry/src/main/resources/base/media/`
+
+**Key constraints**:
+- `media/` directory **does not support subdirectories** (e.g., `media/icons/` will cause `CompileResource` error "invalid path, not a file")
+- File names only allow lowercase letters, numbers, underscores
+- All icon files must be placed directly at the root level of `media/` directory
+
+### 5. Reference in ArkTS
+
+```typescript
+// Reference method: $r('app.media.filename_without_extension')
+Image($r('app.media.md_share'))
+Image($r('app.media.md_add_home'))
+```
+
+Typical icon mapping function pattern:
+
+```typescript
+private getIconResource(action: string): Resource {
+  switch (action) {
+    case 'share':
+      return $r('app.media.md_share')
+    case 'add_home':
+      return $r('app.media.md_add_home')
+    case 'settings':
+      return $r('app.media.md_settings')
+    default:
+      return $r('app.media.icon_default')
+  }
+}
+```
+
+---
+
+## Batch Download Script Example
+
+Python script for batch downloading multiple icons:
+
+```python
+import urllib.request
+import os
+
+icons = [
+    'share', 'add_home', 'edit_note', 'logout', 'bookmark_add',
+    'add_link', 'apps', 'copy_all', 'library_books', 'pdf',
+    'download', 'rule_settings', 'settings', 'chrome_reader_mode',
+    'record_voice_over', 'invert_colors', 'format_size', 'view_column',
+    'chat', 'cancel_presentation', 'cloud_upload', 'bookmarks'
+]
+
+output_dir = 'material_icons_svg'
+os.makedirs(output_dir, exist_ok=True)
+
+base_url = 'https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/{}/default/24px.svg'
+
+for icon in icons:
+    url = base_url.format(icon)
+    out_path = os.path.join(output_dir, f'md_{icon}.svg')
+    try:
+        urllib.request.urlretrieve(url, out_path)
+        print(f'OK: {icon}')
+    except Exception as e:
+        print(f'FAIL: {icon} - {e}')
+```
+
+---
+
+## Common Icon Mapping Reference
+
+Typical Material Design icon mappings for Android toolbar/menu items:
+
+| Kotlin imageVector | snake_case Name | Download SVG | HarmonyOS Reference |
+|-------------------|-----------------|-------------|---------------------|
+| `Icons.Outlined.Share` | `share` | `md_share.svg` | `$r('app.media.md_share')` |
+| `Icons.Outlined.Settings` | `settings` | `md_settings.svg` | `$r('app.media.md_settings')` |
+| `Icons.Outlined.Home` | `home` | `md_home.svg` | `$r('app.media.md_home')` |
+| `Icons.Outlined.Add` | `add` | `md_add.svg` | `$r('app.media.md_add')` |
+| `Icons.Outlined.Edit` | `edit` | `md_edit.svg` | `$r('app.media.md_edit')` |
+| `Icons.Outlined.Delete` | `delete` | `md_delete.svg` | `$r('app.media.md_delete')` |
+| `Icons.Outlined.Search` | `search` | `md_search.svg` | `$r('app.media.md_search')` |
+| `Icons.Outlined.ArrowBack` | `arrow_back` | `md_arrow_back.svg` | `$r('app.media.md_arrow_back')` |
+| `Icons.Outlined.Bookmark` | `bookmark` | `md_bookmark.svg` | `$r('app.media.md_bookmark')` |
+| `Icons.Outlined.BookmarkAdd` | `bookmark_add` | `md_bookmark_add.svg` | `$r('app.media.md_bookmark_add')` |
+| `Icons.Outlined.Favorite` | `favorite` | `md_favorite.svg` | `$r('app.media.md_favorite')` |
+| `Icons.Outlined.Share` | `share` | `md_share.svg` | `$r('app.media.md_share')` |
+| `Icons.Outlined.Download` | `download` | `md_download.svg` | `$r('app.media.md_download')` |
+| `Icons.Outlined.Upload` | `upload` | `md_upload.svg` | `$r('app.media.md_upload')` |
+| `Icons.Outlined.Refresh` | `refresh` | `md_refresh.svg` | `$r('app.media.md_refresh')` |
+| `Icons.Outlined.Menu` | `menu` | `md_menu.svg` | `$r('app.media.md_menu')` |
+| `Icons.Outlined.MoreVert` | `more_vert` | `md_more_vert.svg` | `$r('app.media.md_more_vert')` |
+| `Icons.Outlined.Close` | `close` | `md_close.svg` | `$r('app.media.md_close')` |
+| `Icons.Outlined.Check` | `check` | `md_check.svg` | `$r('app.media.md_check')` |
+| `Icons.Outlined.Visibility` | `visibility` | `md_visibility.svg` | `$r('app.media.md_visibility')` |
+
+Note: `Icons.AutoMirrored.Outlined.*` variants use the same icon name as their non-mirrored counterparts (e.g., `Icons.AutoMirrored.Outlined.ArrowBack` → `arrow_back`).

package/skills/migrate-core/references/topics/resources/svg-fix-patterns.md

@@ -0,0 +1,175 @@
+# SVG Display Issue Fix Patterns
+
+Common display abnormalities and fixes when migrating SVG/Vector Drawables from Android projects or manually creating SVGs.
+
+---
+
+## Issue 1: viewBox Does Not Match Path Coordinates
+
+### Symptoms
+Icon does not display at all, or only shows a blank area.
+
+### Cause
+The coordinate range defined by `viewBox` does not match the coordinate data in the `d` attribute of `<path>`.
+
+For example: path data is based on a 512×512 coordinate system (coordinate values range from 85 to 448), but `viewBox` is set to `0 0 24 24`, causing all paths to exceed the visible area.
+
+### Fix
+
+**Option A: Adjust viewBox to Match Path Coordinates (Recommended for Simple Cases)**
+```xml
+<!-- Wrong: viewBox too small -->
+<svg viewBox="0 0 24 24">
+  <path d="M101.51,411.23 Q85.21,395.05 ..." />  <!-- coordinates far exceed 24 -->
+</svg>
+
+<!-- Fixed: viewBox matches coordinate system, use width/height to control render size -->
+<svg width="24" height="24" viewBox="0 0 512 512">
+  <path d="M101.51,411.23 Q85.21,395.05 ..." />
+</svg>
+```
+
+> Note: `viewBox` defines the path coordinate space, while `width`/`height` define the render size. They are independent.
+
+**Option B: Scale Path Coordinates Proportionally (Recommended for Standardization)**
+
+Scale all values in the path proportionally to the target coordinate system. For example, scaling from 512 to 24:
+
+```python
+import re
+
+scale = 24.0 / 512.0  # 0.046875
+
+def scale_number(match):
+    num = float(match.group(0))
+    scaled = round(num * scale, 2)
+    return '{:.2f}'.format(scaled).rstrip('0').rstrip('.')
+
+path_data = "M101.51,411.23Q85.21,395.05 85.22,371.75..."
+result = re.sub(r'[0-9]+\.?[0-9]*', scale_number, path_data)
+```
+
+After scaling, you can use the standard `viewBox="0 0 24 24"`, consistent with other Material Design icons.
+
+---
+
+## Issue 2: Android Vector Drawable Syntax Remnants
+
+### Symptoms
+The SVG file contains Android-specific XML attributes that standard SVG renderers cannot parse.
+
+### Common Remnant Syntax
+
+| Android Syntax | Standard SVG Equivalent |
+|---------------|----------------------|
+| `<group android:translateX="24" android:rotation="90">` | `<g transform="translate(24,0) rotate(90)">` |
+| `android:fillColor="#FF000000"` | `fill="#000000"` |
+| `android:pathData="..."` | `d="..."` |
+| `android:viewportWidth="24"` | Part of `viewBox="0 0 24 24"` |
+| `<vector>` root element | `<svg>` root element |
+| `<clip-path android:pathData="..."/>` | `<defs><clipPath id="..."><path d="..."/></clipPath></defs>` |
+
+### Fix
+
+Fully convert Android `<group>` transform attributes to SVG `transform`:
+
+```xml
+<!-- Android Vector Drawable -->
+<group
+    android:translateX="24"
+    android:translateY="0"
+    android:rotation="90"
+    android:pivotX="12"
+    android:pivotY="12"
+    android:scaleX="1.5"
+    android:scaleY="1.5">
+  <path android:pathData="M18,12l4,-4..." android:fillColor="#FFFFFF"/>
+</group>
+
+<!-- Converted to Standard SVG -->
+<g transform="translate(24,0) rotate(90,12,12) scale(1.5,1.5)">
+  <path d="M18,12l4,-4..." fill="#FFFFFF"/>
+</g>
+```
+
+Transform order: `translate` → `rotate` (with pivot point) → `scale`
+
+---
+
+## Issue 3: Fill Color is White Causing Invisible Icon
+
+### Symptoms
+SVG file exists and path is correct, but icon does not display (invisible on white background).
+
+### Cause
+The original Android drawable's `fillColor` is `#FFFFFF` (white), which is invisible on a white background. Common for icons designed to appear on dark ActionBars.
+
+### Fix
+
+Change `fill="#FFFFFF"` to `fill="#000000"` (black), or choose a suitable color based on UI needs:
+
+```xml
+<!-- Before fix: white fill invisible on white background -->
+<path fill="#FFFFFF" d="M18,12l4,-4..."/>
+
+<!-- After fix -->
+<path fill="#000000" d="M18,12l4,-4..."/>
+```
+
+---
+
+## Issue 4: Google Material Symbols Coordinate System
+
+### Description
+Material Symbols SVGs downloaded from Google Fonts use a special coordinate system:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000000">
+  <path d="M200-120q-33 0-56.5-23.5T120-200v-560..."/>
+</svg>
+```
+
+- `viewBox="0 -960 960 960"` — Y-axis starts at -960 (positive is upward)
+- Many negative values in path coordinates are normal
+- This format renders correctly in HarmonyOS, **no additional conversion needed**
+
+---
+
+## Issue 5: HarmonyOS media Directory Does Not Support Subdirectories
+
+### Symptoms
+Compilation error: `CompileResource` error "invalid path, not a file"
+
+### Cause
+Created subdirectories under `resources/base/media/` (e.g., `media/icons/`, `media/md/`).
+
+### Fix
+
+Move all files from subdirectories to the `media/` root directory, using file name prefixes to distinguish sources:
+
+```bash
+# Wrong: using subdirectories
+media/
+  md/
+    share.svg
+    home.svg
+
+# Correct: flat storage with prefixes
+media/
+  md_share.svg
+  md_home.svg
+  ic_custom_icon.svg
+```
+
+---
+
+## Quick Diagnosis Checklist
+
+When SVG icon does not display, check in order:
+
+1. **File exists?** — Confirm the file exists under `entry/src/main/resources/base/media/`
+2. **Reference correct?** — `$r('app.media.filename_without_extension')`, filename is case-sensitive
+3. **viewBox matches?** — `viewBox` coordinate range must cover path data coordinate values
+4. **Syntax standard?** — No `android:` namespace attributes, root element is `<svg>` not `<vector>`
+5. **Fill color visible?** — `fill` is not `#FFFFFF` (invisible on white background)
+6. **No subdirectories?** — SVG files are directly under `media/` root directory