@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-ui/references/icons-and-splash-screens.md

@@ -1,438 +1,109 @@
-# Icons and splash screens
+# Icons & launch screens
 
-<!-- TOC-START -->
-## Contents
+> Where the app icon and launch screen come from on each platform, and what sizes to supply.
 
-- [1. Overview](#1-overview)
-- [2. Asset locations](#2-asset-locations)
-- [3. DefaultIcon.png (recommended)](#3-defaulticonpng-recommended)
-- [4. iOS icons](#4-ios-icons)
-- [5. Android icons](#5-android-icons)
-- [6. Android splash screens](#6-android-splash-screens)
-- [7. Localized splash screens](#7-localized-splash-screens)
-- [8. Adaptive icons (Android 8.0+)](#8-adaptive-icons-android-80)
-- [9. Common issues](#9-common-issues)
-- [11. iOS launch files (storyboards)](#11-ios-launch-files-storyboards)
-- [Best practices](#best-practices)
-- [Community-Discovered Patterns](#community-discovered-patterns)
+- Source: https://titaniumsdk.com/docs/build/ui/icons-and-launch-screens
+- Written for Titanium SDK 13.4.0 and later.
+- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
+- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.
 
-<!-- TOC-END -->
+---
 
-## 1. Overview
+The two platforms do not share an icon, despite `DefaultIcon.png` sitting at
+the project root looking like they might. iOS generates its whole icon set from
+that file. **Android never reads it.**
 
-App icons and splash screens are required for app store submissions and give users a branded first impression.
+| | iOS | Android |
+| --- | --- | --- |
+| Source | `DefaultIcon.png` at the project root | `platform/android/res/mipmap-*/` |
+| Generated by Titanium | Yes, every size | No, you supply the set |
+| Named in `tiapp.xml` | No | `android:icon="@mipmap/ic_launcher"` |
 
-Tools for asset generation:
-- [TiCons website](http://ticons.fokkezb.nl/)
-- [TiCons CLI](https://www.npmjs.org/package/ticons)
-- [Android Asset Studio](https://romannurik.github.io/AndroidAssetStudio/index.html)
+`ti create` writes both, so a new project has a working icon on each platform
+before you touch anything.
 
-## 2. Asset locations
+## iOS
 
-| Platform        | Classic project                         | Alloy project                             |
-| --------------- | --------------------------------------- | ----------------------------------------- |
-| Shared          | `Resources/`                            | `app/assets/`                             |
-| iOS             | `Resources/iphone/` or `Resources/ios/` | `app/assets/iphone/` or `app/assets/ios/` |
-| Android         | `Resources/android/`                    | `app/assets/android/`                     |
-| Android density | `platform/android/res/drawable-*dpi/`   | `app/platform/android/res/drawable-*dpi/` |
+Put a square PNG at `DefaultIcon.png` in the project root and Titanium resizes
+it into the app icon set at build time. **1024x1024** is the size to supply,
+because that is what the App Store listing needs and every other size is
+reduced from it.
 
-## 3. DefaultIcon.png (recommended)
+Alpha is flattened for the icon, so a transparent background becomes white.
+Design on an opaque background rather than being surprised.
 
-Place a single `DefaultIcon.png` (1024x1024 px) in the project root. Titanium auto-generates missing icon sizes.
+To differ from Android, add `DefaultIcon-ios.png`. It takes precedence over the
+shared file.
 
-Requirements:
-- Square (equal height and width)
-- No alpha channel
-- PNG format
-- At least 1024x1024 px
+### Dark and tinted appearances
 
-## 4. iOS icons
+iOS 18 asks for three appearances. Add them beside the default one and
+Titanium picks them up:
 
-### App icons
+| File | Appearance |
+| ---- | ---------- |
+| `DefaultIcon.png` | Light, and the fallback for the others |
+| `DefaultIcon-Dark.png` | Dark mode |
+| `DefaultIcon-Tinted.png` | Tinted mode |
 
-| Device          | Dimensions | Filename              |
-| --------------- | ---------- | --------------------- |
-| iPhone 4/5/6    | 120x120    | `appicon-60@2x.png`   |
-| iPhone 6 Plus+  | 180x180    | `appicon-60@3x.png`   |
-| iPad non-retina | 76x76      | `appicon-76.png`      |
-| iPad retina     | 152x152    | `appicon-76@2x.png`   |
-| iPad Pro        | 167x167    | `appicon-83.5@2x.png` |
+For the released SDK 13.4.1 baseline, supply the PNG appearances above.
+Check the selected SDK release before using a different icon input format.
 
-### Spotlight and Settings icons
+### Launch screens
 
-| Device               | Purpose   | Dimensions | Filename                  |
-| -------------------- | --------- | ---------- | ------------------------- |
-| Universal non-retina | Spotlight | 40x40      | `appicon-Small-40.png`    |
-| Universal retina     | Spotlight | 80x80      | `appicon-Small-40@2x.png` |
-| iPhone 6 Plus+       | Spotlight | 120x120    | `appicon-Small-40@3x.png` |
-| Universal non-retina | Settings  | 29x29      | `appicon-Small.png`       |
-| Universal retina     | Settings  | 58x58      | `appicon-Small@2x.png`    |
-| iPhone 6 Plus+       | Settings  | 87x87      | `appicon-Small@3x.png`    |
-
-App thinning note: Application icons and launch images are added to the Asset Catalog. You cannot reference launch image assets from the filesystem, so you cannot set `backgroundImage` to a launch image file.
-
-### iOS splash screens
-
-| Device                                  | Dimensions | Filename                         |
-| --------------------------------------- | ---------- | -------------------------------- |
-| iPhone 4/4S                             | 640x960    | `Default@2x.png`                 |
-| iPhone 5/5C/5S                          | 640x1136   | `Default-568h@2x.png`            |
-| iPhone 6/7/8 portrait                   | 750x1334   | `Default-667h@2x.png`            |
-| iPhone 6/7/8 landscape                  | 1334x750   | `Default-Landscape-1134@2x.png`  |
-| iPhone 6/7/8 Plus portrait              | 1242x2208  | `Default-Portrait-736h@3x.png`   |
-| iPhone 6/7/8 Plus landscape             | 2208x1242  | `Default-Landscape-736h@3x.png`  |
-| iPhone X/Xs portrait                    | 1125x2436  | `Default-Portrait-2436h@3x.png`  |
-| iPhone X/Xs landscape                   | 2436x1125  | `Default-Landscape-2436h@3x.png` |
-| iPhone Xr portrait                      | 828x1792   | `Default-Portrait-1792h@2x.png`  |
-| iPhone Xr landscape                     | 1792x828   | `Default-Landscape-1792h@2x.png` |
-| iPhone Xs Max portrait                  | 1242x2688  | `Default-Portrait-2688h@3x.png`  |
-| iPhone Xs Max landscape                 | 2688x1242  | `Default-Landscape-2688h@3x.png` |
-| iPhone 12/13/14 portrait                | 1170x2532  | `Default-Portrait-2532@3x.png`   |
-| iPhone 12/13/14 landscape               | 2532x1170  | `Default-Landscape-2532@3x.png`  |
-| iPhone 12/13 Pro Max, 14 Plus portrait  | 1284x2778  | `Default-Portrait-2778@3x.png`   |
-| iPhone 12/13 Pro Max, 14 Plus landscape | 2778x1284  | `Default-Landscape-2778@3x.png`  |
-| iPhone 14 Pro portrait                  | 1179x2556  | `Default-Portrait-2556@3x.png`   |
-| iPhone 14 Pro landscape                 | 2556x1179  | `Default-Landscape-2556@3x.png`  |
-| iPhone 14 Pro Max portrait              | 1290x2796  | `Default-Portrait-2796@3x.png`   |
-| iPhone 14 Pro Max landscape             | 2796x1290  | `Default-Landscape-2796@3x.png`  |
-| iPad non-retina landscape               | 1024x768   | `Default-Landscape.png`          |
-| iPad non-retina portrait                | 768x1024   | `Default-Portrait.png`           |
-| iPad retina landscape                   | 2048x1536  | `Default-Landscape@2x.png`       |
-| iPad retina portrait                    | 1536x2048  | `Default-Portrait@2x.png`        |
-
-### iTunes artwork (ad-hoc builds)
-
-| Dimensions | Filename                          |
-| ---------- | --------------------------------- |
-| 512x512    | `iTunesArtwork` (no extension)    |
-| 1024x1024  | `iTunesArtwork@2x` (no extension) |
-
-Note: Do not include in App Store builds.
-
-### iTunes Connect requirements
-
-| Purpose        | Dimensions      | Format                   |
-| -------------- | --------------- | ------------------------ |
-| Large app icon | 1024x1024       | JPG/PNG, no transparency |
-| Screenshots    | Device-specific | JPG/PNG, no transparency |
-
-## 5. Android icons
-
-### Launcher icons
-
-| Density | DPI | Dimensions | Location                                            |
-| ------- | --- | ---------- | --------------------------------------------------- |
-| ldpi    | 120 | 36x36      | `platform/android/res/drawable-ldpi/appicon.png`    |
-| mdpi    | 160 | 48x48      | `platform/android/res/drawable-mdpi/appicon.png`    |
-| hdpi    | 240 | 72x72      | `platform/android/res/drawable-hdpi/appicon.png`    |
-| xhdpi   | 320 | 96x96      | `platform/android/res/drawable-xhdpi/appicon.png`   |
-| xxhdpi  | 480 | 144x144    | `platform/android/res/drawable-xxhdpi/appicon.png`  |
-| xxxhdpi | 640 | 512x512    | `platform/android/res/drawable-xxxhdpi/appicon.png` |
-
-The filename must match the `icon` element in your `tiapp.xml`. By default, new projects use `Resources/android/appicon.png`.
-
-### Action bar icons
-
-| Density | Dimensions | Classic location                        | Alloy location                           |
-| ------- | ---------- | --------------------------------------- | ---------------------------------------- |
-| ldpi    | 18x18      | `Resources/android/images/res-ldpi/`    | `app/assets/android/images/res-ldpi/`    |
-| mdpi    | 24x24      | `Resources/android/images/res-mdpi/`    | `app/assets/android/images/res-mdpi/`    |
-| hdpi    | 36x36      | `Resources/android/images/res-hdpi/`    | `app/assets/android/images/res-hdpi/`    |
-| xhdpi   | 48x48      | `Resources/android/images/res-xhdpi/`   | `app/assets/android/images/res-xhdpi/`   |
-| xxhdpi  | 72x72      | `Resources/android/images/res-xxhdpi/`  | `app/assets/android/images/res-xxhdpi/`  |
-| xxxhdpi | 144x144    | `Resources/android/images/res-xxxhdpi/` | `app/assets/android/images/res-xxxhdpi/` |
-
-### Small and contextual icons
-
-Used for status bar icons and other small UI elements:
-
-| Density | Dimensions |
-| ------- | ---------- |
-| ldpi    | 12x12      |
-| mdpi    | 16x16      |
-| hdpi    | 24x24      |
-| xhdpi   | 32x32      |
-
-### Notification icons
-
-Important: Use white-only shapes on transparent backgrounds.
-
-Same density and location structure as action bar icons, but in `platform/android/res/drawable-*dpi/`.
-
-### Google Play requirements
-
-| Purpose         | Dimensions | Format              |
-| --------------- | ---------- | ------------------- |
-| Large app icon  | 512x512    | PNG/JPG, max 1024KB |
-| Screenshots     | 320-3840px | PNG/JPG, no alpha   |
-| Feature graphic | 1024x500   | PNG/JPG, no alpha   |
-| Promotional     | 180x120    | PNG/JPG, no alpha   |
-
-## 6. Android splash screens
-
-### Android 12+ (SDK 12.0.0+)
-
-Android 12 uses the app icon as the splash screen automatically. Use adaptive icons for best results.
-
-Customize splash background color via theme:
-
-```xml
-<!-- tiapp.xml -->
-<android xmlns:android="http://schemas.android.com/apk/res/android">
-  <manifest>
-    <application>
-      <activity android:name="com.myapp.MyAppActivity"
-                android:theme="@style/Theme.Custom.Splash" />
-    </application>
-  </manifest>
-</android>
-```
-
-```xml
-<!-- platform/android/res/values/splash_theme.xml -->
-<resources>
-  <style name="Theme.Custom.Splash" parent="@style/Theme.MaterialComponents.NoActionBar">
-    <item name="android:windowBackground">@drawable/background_splash</item>
-    <item name="android:windowSplashScreenBackground">@color/splash_bg</item>
-  </style>
-
-  <color name="splash_bg">#FF5722</color>
-</resources>
-```
-
-```xml
-<!-- platform/android/res/drawable/background_splash.xml -->
-<?xml version="1.0" encoding="utf-8"?>
-<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
-  <item android:drawable="@color/splash_bg"/>
-  <item>
-    <bitmap android:src="@drawable/splash_logo" android:gravity="center"/>
-  </item>
-</layer-list>
-```
-
-### Android < 12 (legacy)
-
-Use `default.png` or nine-patch images. Android expects `default.png` (lowercase d) for splash screens. iOS uses `Default.png` with an uppercase D.
-
-Warning: Do not use `<supports-screens/>` with `android:anyDensity` set to false. It can cause scaling issues with splash screens.
-
-#### Nine-patch images (recommended)
-
-Nine-patch images define stretchable regions for different screen sizes.
-
-Creating:
-1. Create a PNG with a 1 px transparent or white border.
-2. Mark stretchable areas with black pixels on the top and left borders.
-3. Mark content areas with black pixels on the right and bottom borders.
-4. Name the file with a `.9.png` extension.
-
-Usage:
-```javascript
-// Reference without .9 in code
-const button = Ti.UI.createButton({
-  backgroundImage: '/images/myimage.png'  // myimage.9.png on disk
-});
-```
-
-#### Density-specific splash screens
-
-```
-platform/android/res/
-├── drawable-ldpi/background.9.png
-├── drawable-mdpi/background.9.png
-├── drawable-hdpi/background.9.png
-├── drawable-xhdpi/background.9.png
-├── drawable-xxhdpi/background.9.png
-├── drawable-xxxhdpi/background.9.png
-└── drawable-nodpi/background.9.png  (universal fallback)
-```
-
-Warning: Do not use `drawable/` (without suffix). It causes scaling issues. Use `drawable-nodpi/` for universal images.
-
-#### Custom theme splash screen
+Titanium builds a launch screen storyboard by default, controlled in
+`tiapp.xml`:
 
 ```xml
-<!-- platform/android/res/values/mytheme.xml -->
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-  <style name="Theme.MyTheme" parent="Theme.AppCompat">
-    <item name="windowBackground">@drawable/background</item>
-    <item name="android:windowBackground">@drawable/background</item>
-  </style>
-</resources>
+<ios>
+  <enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+</ios>
 ```
 
-```xml
-<!-- tiapp.xml - override root activity theme -->
-<android xmlns:android="http://schemas.android.com/apk/res/android">
-  <manifest>
-    <application>
-      <activity android:name=".YourapplicationnameActivity"
-                android:theme="@style/Theme.MyTheme"
-                android:configChanges="keyboardHidden|orientation|screenSize">
-        <intent-filter>
-          <action android:name="android.intent.action.MAIN"/>
-          <category android:name="android.intent.category.LAUNCHER"/>
-        </intent-filter>
-      </activity>
-    </application>
-  </manifest>
-</android>
-```
+With it on, the launch image is generated by centring your icon on a plain
+background, which is why a new project launches to its own icon without you
+supplying anything. Turn it off and iOS falls back to the fixed-size
+`Default-*.png` images in `Resources/iphone/`, which is the pre-storyboard
+approach and means one file per device size.
 
-## 7. Localized splash screens
+Leave the storyboard on unless you have a reason. Apple has required one for
+new App Store submissions since 2020.
 
-### Android localization
+## Android
 
-Place images in `res-<lang>` folders:
+Android uses adaptive icons: a foreground layer, a background layer, and a
+monochrome layer for themed icons, composited by the launcher into whatever
+shape the device uses. `ti create` writes all three at every density:
 
-```
-Resources/android/images/
-├── res-en/default.png
-├── res-es/default.png
-├── res-fr-long-land-hdpi/default.png
-└── res-long-land-hdpi/default.png
-```
-
-Localized images take precedence over non-localized ones.
-
-### iOS localization
-
-Place them in `i18n/<lang>/`:
-
-```
-i18n/
-├── en/
-│   ├── Default@2x.png
-│   └── Default-568h@2x.png
-└── es/
-    ├── Default@2x.png
-    └── Default-568h@2x.png
-```
-
-## 8. Adaptive icons (Android 8.0+)
-
-Adaptive icons use foreground and background layers.
-
-Structure:
 ```
 platform/android/res/
-├── mipmap-anydpi-v26/
-│   └── appicon.xml
-├── drawable/
-│   ├── ic_launcher_foreground.xml
-│   └── ic_launcher_background.xml
-```
-
-appicon.xml:
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-  <background android:drawable="@drawable/ic_launcher_background"/>
-  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
-</adaptive-icon>
-```
-
-## 9. Common issues
-
-### Build fails - missing icons
-
-If any app icon files are missing, the build fails. If launch image files (prefixed with `Default`) are missing, the build does not fail. If you have a `DefaultIcon.png` in the project root, the Titanium SDK auto-generates missing iTunesArtwork files.
-
-Solution: Add `DefaultIcon.png` (1024x1024) to the project root for auto-generation.
-
-### Android splash stretched or distorted
-
-Solution: Use nine-patch images or the `drawable-nodpi` folder.
-
-### iOS icons not updating
-
-Solution:
-1. Clean the project.
-2. Delete the `build/` folder.
-3. Rebuild.
-
-### Android 12 splash not showing custom image
-
-Solution: Android 12+ uses the app icon by default. You can only customize the background color via `windowSplashScreenBackground`.
-
-## 11. iOS launch files (storyboards)
-
-Since iOS 8, Apple recommends launch storyboards instead of multiple `Default*.png` images. You get one file that works across device sizes and a smaller IPA.
-
-### Enabling launch storyboards
-
-In the `<ios>` section of `tiapp.xml`:
-
-```xml
-<enable-launch-screen-storyboard>true</enable-launch-screen-storyboard>
+  mipmap-anydpi-v26/ic_launcher.xml     which layers to composite
+  mipmap-mdpi/      ic_launcher_foreground.png  48px
+  mipmap-hdpi/      ...                         72px
+  mipmap-xhdpi/     ...                         96px
+  mipmap-xxhdpi/    ...                        144px
+  mipmap-xxxhdpi/   ...                        192px
 ```
 
-### Customizing background color
-
-Set a default background color for the launch screen and the gap before the first view opens:
-
-```xml
-<default-background-color>#C7172C</default-background-color>
-```
-
-### Using images in storyboards
-
-To use an image in a native Storyboard:
-1. Set the Image View's `Image` property to the path under `app/assets/` without extension or modifiers.
-2. App thinning note: If `use-app-thinning` is enabled, use the generated asset catalog name.
-   - Build the app.
-   - Find the `[hash].imageset` under `build/iphone/Assets.xcassets/`.
-   - Use that hash value in the Storyboard.
-
-### Launch file cache
-
-iOS caches launch screen snapshots. If changes do not appear:
-1. Reset Content and Settings in the Simulator.
-2. Run `ti clean` or Project > Clean.
-
-## Best practices
-
-1. Use `DefaultIcon.png` for automatic icon generation.
-2. Use nine-patch for Android splash screens.
-3. Test on multiple densities, especially Android.
-4. Keep icons simple. Details vanish at small sizes.
-5. No alpha channel on app icons.
-6. Square icons only.
-7. Clean the project after icon changes.
-8. Use adaptive icons for Android 8.0+.
-
-## Community-Discovered Patterns
-
-### Android 12+ splash: the theme's parent decides whether any of it applies
-
-Verified against SDK 13.4.1.GA, reading the generated `build/android/app/src/main/res/values*/ti_styles.xml` and `res/values-v31/` inside `titanium-13.4.1.aar`.
-
-Titanium writes `android:theme="@style/Theme.Titanium"` onto the launcher Activity it generates, and builds this chain, where the last link is whatever theme the app declared on `<application>`:
-
-```text
-Theme.Titanium
-└── Base.Theme.Titanium.Splash
-    └── Theme.AppDerived
-        └── the app's <application> theme
-```
+Replace the PNGs at every density. The launcher crops the outer edge of an
+adaptive icon to whatever shape it wants, so keep anything that must stay
+visible inside the middle two-thirds.
 
-An `<application>` theme therefore ends up an *ancestor* of `Theme.Titanium`, and loses every attribute the two links below it already set. On API 31+ those are `android:windowBackground` and `android:windowSplashScreenBackground`, so a splash color declared on `<application>` silently does nothing. A custom theme must inherit from `@style/Theme.Titanium` and be assigned to the launcher Activity, which is what section 6's `tiapp.xml` snippet does — but its companion style inherits from `Theme.MaterialComponents.NoActionBar`, which detaches from the chain and drops the app's own theme with it.
+In an Alloy project these live under `app/platform/android/res/`, because
+`alloy new` moved `platform/` there. See
+[project structure](https://titaniumsdk.com/docs/build/project-structure.md).
 
-Three attributes, one color:
+### Splash screen
 
-| Attribute | Consumer |
-|---|---|
-| `android:windowSplashScreenBackground` | The API 31+ system splash. |
-| `android:windowBackground` | The native window between the system splash and Titanium's first Window. |
-| `android:colorBackground` | `Base.Theme.Titanium.Splash` points `windowSplashScreenBackground` at `?android:attr/colorBackground` on API 31+, and the launch status and navigation bars read it. |
+Android's splash is a theme, not an image set. It is generated from the same
+launcher icon, so replacing the icon replaces what shows on launch.
 
-Two consequences worth knowing before choosing a value:
+## Changing the name under the icon
 
-- **Setting only the first two leaves the inherited color showing.** `colorBackground` is the one that is easy to miss.
-- **A flat color for `windowBackground` replaces `@drawable/titanium_splash_icon_background`**, the layer-list Titanium uses on API 31+. That drawable paints a 160 dp white circle behind the icon, which is invisible on a white background and obvious on any other. Replacing it with a plain color removes the circle and the icon along with it.
+That is `<name>` in `tiapp.xml`, not an icon setting. Both platforms read it
+from there.
 
-Section 6's troubleshooting entry says the background color is the only customizable part. `android:windowSplashScreenAnimatedIcon` replaces the icon too — it is an icon slot, not a full-screen image, so the color around it still comes from the attributes above.
+## Next
 
-The `purgetss` skill's [launch-background.md](../../purgetss/references/launch-background.md) carries the full version of this, including the interaction with the legacy `res-*/default.png` artwork, and `purgetss brand --notes` prints the setup with the project's own brand color already substituted.
+[Platform conventions](platform-conventions.md) covers the places
+iOS and Android expect different things of an app.