chore: add documentation for app icon (#45)

Co-authored-by: André Costa Lima <[email protected]>

Author: ubmit

docusaurus/docs/welcome/instructions/app-icon.md

@@ -0,0 +1,193 @@
+---
+id: app-icon
+title: App icon
+sidebar_label: App icon
+---
+
+Every app should have an impactul icon that stands out from all the others apps available on the user's device.
+
+An app icon is a graphic that represents your app to users. It can:
+
+- Appear in the list of apps installed on a device and on the Home screen.
+- Represent shortcuts into your app (for example, a contact shortcut icon that opens detail information for a contact).
+- Help users find your app on Google Play and App Store.
+
+> ℹ️  An app icon is mandatory to publish the app to TestFlight/App Store and Google Play.
+
+### How to generate the assets
+
+First and foremost, we need to take into consideration that automatic generation won't work everytime.
+Sometimes, small adjustments to an icon may be necessary and that should probably be done manually so it looks exactly how it is supposed to.
+There are design tools that solve this problem, e.g. Sketch and Adobe Illustrator, which allow further customization and can assist designers in automatically exporting the icons.
+Nonetheless, automatic generation from a single asset should always be the first step to take as it is the most efficient and effective for most use cases.
+
+> ❗️ The raw app icon asset's resolution should be 1024x1024px or bigger, so it can be used to generate both Android and iOS icons through the recommended generators.
+
+#### Android
+
+> ❗️ Android 8.0 Oreo introduced adaptive icons and apps running on it or later versions are ought to support them.
+
+Android assets can be generated using [Image Asset Studio](https://developer.android.com/studio/write/image-asset-studio).
+
+To start Image Asset Studio, follow these steps:
+
+1. Open the project on Android Studio.
+2. In the **Project** window, select the [Android view](https://developer.android.com/studio/projects#ProjectFiles).
+3. Right-click the **res** folder and select **New > Image Asset**.
+
+![Image Asset Studio](/img/image-asset-studio.png)
+
+The app icon should have both a square and a round version.
+The tool offers a few options which you can tweak as much as you like, but we only cover the necessary ones.
+
+> ℹ️  The following instructions don't cover how to generate [adaptive icons](https://developer.android.com/guide/practices/ui_guidelines/icon_design_adaptive), which are icons that can display a variety of shapes across different device models.
+> However it isn't much different, actually. To generate those, you should use the **Launcher Icons (Adaptive and Legacy)** option for the **Icon Type**.
+
+##### Square icons
+
+-   **Icon Type** should be the **Launcher Icons (Legacy only)** option.
+-   **Name** should be renamed from `ic_launcher` to `app_icon`.
+-   **Asset Type** should be **Image** and the raw app icon path should be given.
+-   **Shape** should be **Square**.
+
+![Image Asset Studio - Launcher Icons (Legacy only) with Square shape](/img/image-asset-studio-launcher-icons-legacy-only-square.png)
+
+After that you should click on **Next** and finally on the **Finish** button.
+
+##### Round icons
+
+-   **Icon Type** should be the **Launcher Icons (Legacy only)** option.
+-   **Name** should be renamed from `ic_launcher` to `app_icon_round`.
+-   **Asset Type** should be **Image** and the raw app icon path should be given.
+-   **Shape** should be **Circle**.
+
+![Image Asset Studio - Launcher Icons (Legacy only) with Circle shape](/img/image-asset-studio-launcher-icons-legacy-only-circle.png)
+
+After that you should click on **Next** and finally on the **Finish** button.
+
+##### Google Play icon
+
+Having a proper Google Play icon can help your app attract new users.
+This icon won't replace your app's launcher icon, it will be used in various locations on Google Play instead.
+
+> 💡 Note that the Google Play icon isn't generated by the Image Asset Studio, so it should be manually created by following the [official design specifications](https://developer.android.com/google-play/resources/icon-design-specifications).
+
+How to upload the icon:
+
+1. Sign in to your [Play Console](https://play.google.com/apps/publish/).
+2. Click **All Applications**.
+3. Select an app.
+4. On the left menu, click **Store Presence > Store listing**.
+5. Under "Graphic Assets" you can upload your images, including the Google Play icon (Hi-res icon).
+
+#### iOS
+
+iOS assets can be generated using [App Icon Generator](https://appicon.co/).
+In the "iOS and macOS" section, only `iPhone` and `iPad` should be selected.
+It is possible to either click and browse the image source or simply drag and drop it.
+After selecting the image, click on the "Generate" button to download the assets.
+
+We can also recommend the [Fueled/ios-icon-generator](https://github.com/Fueled/ios-icon-generator) tool, which is a command line interface (CLI) that generates the icons.
+
+Although not mandatory, we recommend to rename the generated assets according to the following pattern: `<resolution>@x<multiplier>`.
+This way, it becomes makes easier to identify the attributes of each icon and their purpose simply by glancing at its name.
+
+### Output assets location
+
+#### Android
+
+> 💡 Note that if you used Image Asset Studio, you won't have to bother about this, because the tool automatically places the assets into the correct locations.
+
+##### Square icons:
+
+-   **mdpi (48x48@1x):** `android/app/src/main/res/mipmap-mdpi/app_icon.png`
+-   **hdpi (72x72@1\.5x):** `android/app/src/main/res/mipmap-hdpi/app_icon.png`
+-   **xhdpi (96x96@2x):** `android/app/src/main/res/mipmap-xhdpi/app_icon.png`
+-   **xxhdpi (144x144@3x):** `android/app/src/main/res/mipmap-xxhdpi/app_icon.png`
+-   **xxxhdpi (192x192@4x):** `android/app/src/main/res/mipmap-xxxhdpi/app_icon.png`
+
+##### Round icons:
+
+-   **mdpi (48x48@1x):** `android/app/src/main/res/mipmap-mdpi/app_icon_round.png`
+-   **hdpi (72x72@1\.5x):** `android/app/src/main/res/mipmap-hdpi/app_icon_round.png`
+-   **xhdpi (96x96@2x):** `android/app/src/main/res/mipmap-xhdpi/app_icon_round.png`
+-   **xxhdpi (144x144@3x):** `android/app/src/main/res/mipmap-xxhdpi/app_icon_round.png`
+-   **xxxhdpi (192x192@4x):** `android/app/src/main/res/mipmap-xxxhdpi/app_icon_round.png`
+
+After moving the assets to the following locations, there is nothing more to do.
+
+#### iOS
+
+There are two options: either you manually move the icons and reflect the changes on the `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/Contents.json` file or
+drag and drop the assets using XCode, which will automatically update it.
+
+Using XCode:
+
+In the project tree, navigate to `reactNativeWithMoxy > Images.xcassets`.
+
+![XCode AppIcon](/img/xcode-app-icon.png)
+
+Now you should be able to drag and drop each asset to its correct location.
+
+> ❗️ When the drag and drop approach is used, XCode will change a file's name if it's already being used for another purpose.
+> Be sure to manually rename it to its original name on `Contents.json`.
+
+|                               Before                                |                                          After                                          |
+| :-----------------------------------------------------------------: | :-------------------------------------------------------------------------------------: |
+| ![XCode AppIcon Drag and Drop](/img/xcode-app-icon-drag-n-drop.png) | ![XCode AppIcon Drag and Drop Completed](/img/xcode-app-icon-drag-n-drop-completed.png) |
+
+##### iPhone Notifications (iOS 7-13 20pt)
+
+-   **40x40@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **60x60@3x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPhone Settings (iOS 7-13 29pt)
+
+-   **58x58@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **87x87@3x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPhone Spotlight (iOS 7-13 40pt)
+
+-   **80x80@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **120x120@3x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPhone App (iOS 7-13 60pt)
+
+-   **120x120@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **180x180@3x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPad Notifications (iOS 7-13 20pt)
+
+-   **20x20@1x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **40x40@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPad Settings (iOS 7-13 29pt)
+
+-   **29x29@1x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **58x58@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPad Spotlight (iOS 7-13 40pt)
+
+-   **40x40@1x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **80x80@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPad App (iOS 7-13 76pt)
+
+-   **76x76@1x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+-   **152x152@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### iPad Pro App (iOS 7-13 83.5pt)
+
+-   **167x167@2x**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/[email protected]`
+
+##### App Store (iOS 1024pt)
+
+-   **1024x1024**: `ios/reactNativeWithMoxy/Images.xcassets/AppIcon.appiconset/1024x1024.png`
+
+### References
+
+-   [App Icon - Icons and Images - iOS - Human Interface guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/icons-and-images/app-icon/)
+-   [Google Play icon design specifications](https://developer.android.com/google-play/resources/icon-design-specifications)
+-   [Understanding Android Adaptive Icons - Google Design](https://medium.com/google-design/understanding-android-adaptive-icons-cee8a9de93e2)
+-   [Designing Adaptive Icons - Google Design](https://medium.com/google-design/designing-adaptive-icons-515af294c783)
+-   [Implementing Adaptive Icons - Android Developers](https://medium.com/androiddevelopers/implementing-adaptive-icons-1e4d1795470e)

docusaurus/docs/welcome/instructions/project-setup.md

@@ -22,6 +22,7 @@ Follow the links in the order listed below to prepare your app for production:
 
 - [Configure app signing for Android release builds](android-app-signing.md)
 - [Create a splash screen](splash-screen.md)
+- [Create app icons](app-icon.md)
 
 ## 2. Replace the root README.md
 

docusaurus/sidebars.js

@@ -14,6 +14,7 @@ module.exports = {
                         'welcome/instructions/project-setup',
                         'welcome/instructions/android-app-signing',
                         'welcome/instructions/splash-screen',
+                        'welcome/instructions/app-icon',
                     ],
                 },
                 'welcome/conventions',