purgetss 7.6.2 → 7.7.0

package/README.md

@@ -10,13 +10,14 @@
 
 </div>
 
-**PurgeTSS** is a toolkit for building mobile apps with the [Titanium framework](https://titaniumsdk.com). It provides utility classes, icon font support, an Animation module, a grid system, and color generation commands (`shades` for tonal palettes, `semantic` for Light/Dark mode semantic colors).
+**PurgeTSS** is a toolkit for building mobile apps with the [Titanium framework](https://titaniumsdk.com). It gives you utility classes, icon font support, an Animation module, a grid system, and color generation commands (`shades` for tonal palettes, `semantic` for Light/Dark mode semantic colors).
 
 ---
 
 - 23,300+ utility classes for styling Titanium views
 - Parses XML files to generate a clean `app.tss` with only the classes your project uses
 - Customizable defaults via `config.cjs`, with JIT classes for arbitrary values
+- `brand` command for Titanium icons and branding assets, including Android launcher variants, optional Android 12+ splash artwork, and legacy `default.png` fallback generation
 - Icon font support: Font Awesome, Material Icons, Material Symbols, Framework7-Icons
 - `build-fonts` command generates `fonts.tss` with class definitions and fontFamily selectors
 - `shades` command generates color shades from any hex color
@@ -374,6 +375,18 @@ Button: {
 - **Alloy Framework** (for most commands)
 - **Node.js 20+** (required for the CLI tool)
 
+## Recent changes
+
+### v7.7.0
+
+- `brand` now uses grouped config sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`.
+- `brand` supports separate Android artwork through `brand.logos.androidLauncher` / `--icon-logo` and `brand.logos.androidSplash` / `--splash-logo`.
+- `brand` regenerates `app/assets/android/default.png` in Alloy projects, or `Resources/android/default.png` in Classic projects, so older Android splash paths still have a fallback.
+- `cleanup-legacy` no longer removes `default.png`.
+- Branding help and docs now spell out the difference between Android launcher icons, Android 12+ `splash_icon.png`, and legacy Android splash assets.
+
+See the full release notes in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Table of Content
 
 - [Installation](https://purgetss.com/docs/installation)

package/bin/purgetss

@@ -262,11 +262,14 @@ program
 Writes directly into the current project (Alloy or Classic — auto-detected).
 Logos auto-discovered from ${chalk.cyan('purgetss/brand/')}:
   ${chalk.yellow('logo.{svg,png}')}          required — main logo
+  ${chalk.yellow('logo-icon.{svg,png}')}     optional — square Android launcher mark
   ${chalk.yellow('logo-mono.{svg,png}')}     optional — monochrome layer + notifications
   ${chalk.yellow('logo-dark.{svg,png}')}     optional — iOS 18+ dark variant
   ${chalk.yellow('logo-tinted.{svg,png}')}   optional — iOS 18+ tinted variant
+  ${chalk.yellow('logo-splash.{svg,png}')}   optional — Android 12+ splash icon override
 
 Defaults come from the ${chalk.cyan('brand:')} section in ${chalk.cyan('purgetss/config.cjs')}.
+The recommended workflow is: put files in ${chalk.cyan('purgetss/brand/')}, then only use config/CLI for overrides.
 CLI flags always win over config values.
 
 Generates:
@@ -276,6 +279,8 @@ Generates:
   ${chalk.yellow('mipmap-*/ic_launcher_{foreground,background,monochrome}.png')}  Android adaptive × 5
   ${chalk.yellow('mipmap-*/ic_launcher.png')}                           Android legacy × 5
   ${chalk.yellow('mipmap-anydpi-v26/ic_launcher.xml')}                  Adaptive icon binder
+  ${chalk.yellow('drawable-*/splash_icon.png')}                         Android 12+ splash icon (with ${chalk.cyan('--splash')})
+  ${chalk.yellow('app/assets/android/default.png')}                     Android <12 legacy splash fallback
 
 Android dark/light mode is handled by the ${chalk.yellow('monochrome')} adaptive layer
 (Android 13+ tints it from the wallpaper + theme). No separate dark file exists.
@@ -284,16 +289,22 @@ Examples:
   ${chalk.cyan('purgetss brand')}                                           # uses purgetss/brand/logo.svg + config
   ${chalk.cyan('purgetss brand')} logo.svg                                  # explicit logo path
   ${chalk.cyan('purgetss brand')} --bg-color "#0B1326"                      # override config bg
+  ${chalk.cyan('purgetss brand')} --android-adaptive-padding 22             # more breathing room for adaptive icons
+  ${chalk.cyan('purgetss brand')} --icon-logo app-icon.svg                  # separate square Android icon
   ${chalk.cyan('purgetss brand')} --dark-bg-color "#1C1C1E" --no-tinted     # customize dark, skip tinted
   ${chalk.cyan('purgetss brand')} --dry-run                                 # preview without writing
   ${chalk.cyan('purgetss brand')} --cleanup-legacy --dry-run                # preview legacy cleanup
 `)
   .option('--bg-color <hex>', 'Background color for Android adaptive + iOS flatten (default: #FFFFFF)')
-  .option('--padding <n>', 'Android safe-zone % (range 12-20, default: 15)', (v) => parseInt(v, 10))
+  .option('--padding <n>', 'Shortcut: sets both Android paddings to the same value', (v) => parseInt(v, 10))
+  .option('--android-adaptive-padding <n>', 'Adaptive icon safe-zone % (default: 19)', (v) => parseInt(v, 10))
+  .option('--android-legacy-padding <n>', 'Legacy ic_launcher.png padding % (default: 10)', (v) => parseInt(v, 10))
   .option('--ios-padding <n>', 'iOS aesthetic % (typical 2-6, default: 4)', (v) => parseInt(v, 10))
   .option('--notification', 'Also generate ic_stat_notify.png × 5 densities')
   .option('--splash', 'Also generate Android 12+ splash_icon.png × 5 densities')
+  .option('--icon-logo <path>', 'Override the Android launcher icon logo (otherwise purgetss/brand/logo-icon.{svg,png})')
   .option('--monochrome-logo <path>', 'Override the monochrome logo (otherwise purgetss/brand/logo-mono.{svg,png})')
+  .option('--splash-logo <path>', 'Override the Android 12+ splash icon logo (otherwise purgetss/brand/logo-splash.{svg,png})')
   .option('--dark-bg-color <hex>', 'Opt into opaque dark bg for DefaultIcon-Dark.png (default: transparent per Apple HIG)')
   .option('--dark-logo <path>', 'Override the dark logo (otherwise purgetss/brand/logo-dark.{svg,png})')
   .option('--tinted-logo <path>', 'Override the tinted logo (otherwise purgetss/brand/logo-tinted.{svg,png})')

package/dist/purgetss.ui.js

@@ -1,4 +1,4 @@
-// PurgeTSS v7.6.0
+// PurgeTSS v7.7.0
 // Created by César Estrada
 // https://purgetss.com
 

package/experimental/completions2.js

@@ -30,6 +30,182 @@ const logger = {
   file: (...args) => console.log(purgeLabel, chalk.yellow(args.join(' ')), 'file created!')
 }
 
+// Keys whose numeric values are interpreted with `ti.ui.defaultunit` from tiapp.xml.
+// The glossary .md files for these keys receive an inline "// Unit: ..." note
+// so Context7 (and humans) always retrieve the unit clarification alongside the values.
+// Keep this list in sync with `docs/best-practices/4-values-and-units.md` in purgetss-docs.
+const UNIT_DEPENDENT_KEYS = new Set([
+  // configurableProperties (Ti.UI.* native dimensional properties)
+  'backgroundLeftCap', 'backgroundPaddingBottom', 'backgroundPaddingLeft',
+  'backgroundPaddingRight', 'backgroundPaddingTop', 'backgroundTopCap',
+  'borderRadius', 'borderWidth', 'bottom', 'contentHeight', 'contentWidth',
+  'elevation', 'height', 'imageHeight', 'imagePadding', 'keyboardToolbarHeight',
+  'left', 'leftButtonPadding', 'leftTrackLeftCap', 'leftTrackTopCap', 'leftWidth',
+  'letterSpacing', 'lineSpacing', 'maxElevation', 'maximumLineHeight',
+  'maxRowHeight', 'minimumLineHeight', 'minRowHeight', 'padding', 'paddingBottom',
+  'paddingLeft', 'paddingRight', 'paddingTop', 'pageHeight', 'pageWidth',
+  'pagingControlHeight', 'paragraphSpacingAfter', 'paragraphSpacingBefore',
+  'right', 'rightButtonPadding', 'rightTrackLeftCap', 'rightTrackTopCap',
+  'rightWidth', 'rowHeight', 'sectionHeaderTopPadding', 'separatorHeight',
+  'shadowRadius', 'statusBarHeight', 'targetImageHeight', 'targetImageWidth',
+  'titlePadding', 'top', 'uprightHeight', 'uprightWidth', 'width',
+  'xOffset', 'yOffset',
+  // compoundClasses that bundle dimensional properties
+  'borderRadius-alternative', 'borderRadius-full', 'content-height-and-width',
+  'dropShadow', 'fontSize', 'margin', 'margin-alternative', 'minimumFontSize',
+  'padding-alternative', 'size', 'titleAttributesShadow-alternative',
+  'viewShadowOffset', 'widthHeight'
+])
+
+const UNIT_NOTE_LINES = [
+  '// Unit: numeric values are unitless. Titanium interprets them using ti.ui.defaultunit in tiapp.xml (Alloy template default: dp, not pixels).',
+  '// Docs: /docs/best-practices/values-and-units'
+]
+
+function injectUnitNote(key, classes) {
+  if (!UNIT_DEPENDENT_KEYS.has(key)) return classes
+  const lines = classes.split('\n')
+  let lastCommentIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    if (trimmed.startsWith('//')) {
+      lastCommentIdx = i
+    } else if (trimmed !== '' && lastCommentIdx !== -1) {
+      break
+    }
+  }
+  if (lastCommentIdx === -1) return classes
+  lines.splice(lastCommentIdx + 1, 0, ...UNIT_NOTE_LINES)
+  return lines.join('\n')
+}
+
+// Scaffolding metadata for the glossary subfolders. Every field here drives
+// what the generator writes for each category — update this array and rerun
+// the build to refresh both the subfolder `index.md` and its entry in the
+// root `index.md`.
+//
+// Fields:
+//   id              folder name (matches purgetss-docs/glossary/<id>/)
+//   label           Sidebar label (used in `_category_.json` and subfolder H1)
+//   intro           Paragraph shown at the top of the subfolder's own index.md
+//   rootDescription Longer paragraph shown under the category in the root index.md
+//   rootLinkText    (optional) Override for the link text in the root index.md
+//                   — use this when the link text on the landing page differs
+//                   from the sidebar label. Falls back to `label` when absent.
+//   unitsCallout    (optional) If present, adds a `:::info Units` admonition
+//                   to the subfolder's index.md pointing at the canonical
+//                   values-and-units page.
+const GLOSSARY_SUBFOLDERS = [
+  {
+    id: 'booleanProperties',
+    label: 'Boolean Properties',
+    intro: 'Use these properties when a setting is strictly true/false. Entries cover accessibility flags, UI state toggles, media permissions, and similar binary behaviors. Browse the list in the sidebar for the complete catalog.',
+    rootDescription: 'Properties that can only have two values: true or false. These properties are fundamental for controlling the behavior and appearance of elements in your application. Includes over 200 properties organized into categories such as accessibility, interface controls, media, and security.'
+  },
+  {
+    id: 'colorProperties',
+    label: 'Color Properties',
+    intro: 'Color properties control text, backgrounds, borders, icons, and state colors. Values accept hex, RGB, named colors, and platform-supported formats. Use the sidebar list to jump to a specific property.',
+    rootDescription: 'Properties that allow you to customize your application\'s colors. Accepts various color formats (hex, RGB, predefined names) and covers everything from basic element colors to complex visual effects, including backgrounds, borders, text, icons, and element states.'
+  },
+  {
+    id: 'compoundClasses',
+    label: 'Compound Properties',
+    rootLinkText: 'Compound Classes',
+    intro: 'Compound classes bundle multiple style attributes into one utility for faster styling. They cover layout, typography, spacing, and effects with alternative syntaxes where supported. See the sidebar for each entry.',
+    rootDescription: 'Advanced classes that combine multiple style attributes into a single property. These classes provide sophisticated styling capabilities for layout, positioning, typography, and visual effects, with multiple variations and alternative syntaxes.',
+    unitsCallout: 'Many compound classes on this page produce dimensional values (margins, paddings, sizes, radii, shadow offsets, font sizes, translations). Those numbers are **unitless** — Titanium resolves them using `ti.ui.defaultunit` in `tiapp.xml`. The Alloy template default is `dp` (density-independent pixels), **not raw pixels**. See [Values and Units](/docs/best-practices/values-and-units) for the full rules and exceptions.'
+  },
+  {
+    id: 'configurableProperties',
+    label: 'Configurable Properties',
+    intro: 'These properties accept numeric or measurable values such as sizes, spacing, opacity, durations, and weights. Use them to fine-tune UI details with precise values. The sidebar lists all available properties.',
+    rootDescription: 'Numeric or measurable properties that allow you to fine-tune the appearance and behavior of UI elements. Includes dimensions, spacing, visual effects, typography, and animations, all accepting specific values like numbers, dimensions, or durations.',
+    unitsCallout: 'Dimensional values on this page (sizes, spacing, radii, font sizes, shadow radii, elevation, offsets, line heights, letter spacing) are **unitless**. Titanium resolves them at runtime using `ti.ui.defaultunit` in `tiapp.xml`. The Alloy template default is `dp` (density-independent pixels), **not raw pixels**. See [Values and Units](/docs/best-practices/values-and-units) for the full rules and exceptions.'
+  },
+  {
+    id: 'constantProperties',
+    label: 'Constant Properties',
+    intro: 'Constant properties accept predefined values or enumerations (e.g., modes, types, categories). Use them to enforce valid states and platform-specific options. Browse the sidebar for the full list.',
+    rootDescription: 'Predefined values or enumerations that determine specific behaviors, styles, or states of UI elements. These properties only accept predefined values to ensure consistency and functionality, covering interface states, user input, media, authorizations, and notifications.'
+  }
+]
+
+// Header + global units callout for the root `glossary/index.md`. The list of
+// categories below `## Categories` is derived from GLOSSARY_SUBFOLDERS by
+// `buildRootIndex()` — add a subfolder to the array and it will appear here.
+const GLOSSARY_ROOT_HEADER = `---
+sidebar_position: 1
+---
+
+# Glossary of Terms
+
+Welcome to the PurgeTSS glossary. Here you'll find a complete list of terms, properties, and concepts used throughout our documentation, organized into categories for easy reference.
+
+:::info Units — read this first
+Numeric values shown in the property pages below are **unitless**. Titanium interprets them using \`ti.ui.defaultunit\` in \`tiapp.xml\` — the Alloy template ships with \`dp\` (density-independent pixels), **not raw pixels**. See [Values and Units](/docs/best-practices/values-and-units) for the full explanation.
+:::
+
+## Categories
+`
+
+function buildRootIndex() {
+  let content = GLOSSARY_ROOT_HEADER
+  for (const folder of GLOSSARY_SUBFOLDERS) {
+    const linkText = folder.rootLinkText ?? folder.label
+    content += `\n### [${linkText}](./${folder.id}/index.md)\n`
+    content += `${folder.rootDescription}\n`
+  }
+  return content
+}
+
+function buildSubfolderIndex(folder) {
+  let content = '---\n'
+  content += `title: ${folder.label}\n`
+  content += `slug: /glossary/${folder.id}\n`
+  content += '---\n\n'
+  content += folder.intro + '\n'
+  if (folder.unitsCallout) {
+    content += '\n:::info Units — important\n'
+    content += folder.unitsCallout + '\n'
+    content += ':::\n'
+  }
+  return content
+}
+
+function glossaryBaseFolder() {
+  if (!fs.existsSync(projectsConfigJS)) return path.resolve(__dirname, '../dist/glossary/')
+  if (saveGlossary) return cwd + '/purgetss/glossary/'
+  return ''
+}
+
+function scaffoldGlossary() {
+  const baseFolder = glossaryBaseFolder()
+  if (!baseFolder) return
+
+  // Wipe the output tree so stale property files from prior runs don't linger.
+  if (fs.existsSync(baseFolder)) fs.rmSync(baseFolder, { recursive: true })
+  makeSureFolderExists(baseFolder)
+
+  // Root-level files
+  saveFile(path.join(baseFolder, '_category_.json'), JSON.stringify({
+    label: 'Glossary of Terms',
+    position: 1
+  }, null, 2) + '\n')
+  saveFile(path.join(baseFolder, 'index.md'), buildRootIndex())
+
+  // Subfolders with their _category_.json and index.md
+  for (const folder of GLOSSARY_SUBFOLDERS) {
+    const sub = path.join(baseFolder, folder.id)
+    makeSureFolderExists(sub)
+    saveFile(path.join(sub, '_category_.json'), JSON.stringify({
+      label: folder.label,
+      link: { type: 'doc', id: `${folder.id}/index` }
+    }, null, 2) + '\n')
+    saveFile(path.join(sub, 'index.md'), buildSubfolderIndex(folder))
+  }
+}
+
 let configFile = getConfigFile()
 configFile.purge = configFile.purge ?? { mode: 'all' }
 configFile.theme = configFile.theme ?? {}
@@ -59,6 +235,7 @@ function autoBuildUtilitiesTSS(options = {}) {
   }
 
   saveGlossary = options.glossary ?? false
+  scaffoldGlossary()
   let tailwindStyles = fs.readFileSync(path.resolve(__dirname, '../lib/templates/tailwind/custom-template.tss'), 'utf8')
   tailwindStyles += (fs.existsSync(projectsConfigJS)) ? `// config.js file updated on: ${getFileUpdatedDate(projectsConfigJS)}\n` : '// default config.js file\n'
 
@@ -161,7 +338,7 @@ function generateGlossary(_key, _theClasses, _keyName = null) {
     }
 
     makeSureFolderExists(destinationFolder)
-    saveFile(`${destinationFolder}/${_key}.md`, '```css' + _theClasses + '```\n')
+    saveFile(`${destinationFolder}/${_key}.md`, '```css' + injectUnitNote(_key, _theClasses) + '```\n')
   }
 
   return _theClasses

package/lib/templates/purgetss.config.js.cjs

@@ -13,12 +13,33 @@ module.exports = {
     }
   },
   brand: {
-    splash: false,           // also generate splash_icon.png × 5
-    padding: '15%',          // Android safe-zone. Range: 12% tight (mature logos) — 20% conservative. Spec floor 19.44%.
-    iosPadding: '4%',        // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
-    darkBgColor: null,       // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-    bgColor: '#FFFFFF',      // Android adaptive bg + iOS/marketplace flatten
-    notification: false,     // also generate ic_stat_notify.png × 5
+    logos: {
+      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
+      // primary: './docs/logo.svg',
+      // androidLauncher: './docs/app-icon.svg',
+      // androidSplash: './docs/splash.svg',
+      // monochrome: './docs/logo-mono.svg',
+      // iosDark: './docs/logo-dark.svg',
+      // iosTinted: './docs/logo-tinted.svg'
+    },
+    padding: {
+      ios: '4%',             // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
+      androidLegacy: '10%',  // legacy ic_launcher.png padding
+      androidAdaptive: '19%' // adaptive foreground padding near the Android safe-zone
+    },
+    android: {
+      splash: false,         // also generate splash_icon.png × 5
+      notification: false    // also generate ic_stat_notify.png × 5
+    },
+    colors: {
+      background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+    },
+    // Optional iOS overrides:
+    // ios: {
+    //   dark: false,
+    //   tinted: false,
+    //   darkBackground: '#111111'
+    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "purgetss",
-  "version": "7.6.2",
+  "version": "7.7.0",
   "main": "src/index.js",
   "bin": {
     "purgetss": "bin/purgetss"

package/src/cli/commands/brand.js

@@ -64,6 +64,6 @@ function printMissingLogoHelp(projectRoot) {
   console.log()
   console.log('  Alternatives:')
   console.log(`    ${chalk.gray('•')} Pass the logo explicitly:       ${chalk.cyan('purgetss brand path/to/logo.svg')}`)
-  console.log(`    ${chalk.gray('•')} Point to it from config.cjs:    ${chalk.gray('brand: { logo: \'./docs/logo.svg\' }')}`)
+  console.log(`    ${chalk.gray('•')} Point to it from config.cjs:    ${chalk.gray('brand: { logos: { primary: \'./docs/logo.svg\' } }')}`)
   console.log()
 }

package/src/core/branding/brand-config.js

@@ -9,9 +9,11 @@
  * Also auto-discovers logo images inside `./purgetss/brand/` following the
  * project convention:
  *   logo.{svg,png}          → required (main logo)
+ *   logo-icon.{svg,png}     → optional (square launcher/splash mark for Android)
  *   logo-mono.{svg,png}     → optional (monochrome layer + notifications)
  *   logo-dark.{svg,png}     → optional (iOS 18+ dark variant)
  *   logo-tinted.{svg,png}   → optional (iOS 18+ tinted variant)
+ *   logo-splash.{svg,png}   → optional (Android 12+ splash icon override)
  *
  * CLI --monochrome-logo / --dark-logo / --tinted-logo always override
  * discovery, and the positional argument overrides the main logo.
@@ -52,26 +54,55 @@ function findLogoFile(baseDir, baseName) {
 export function resolveBrandConfig(cliOptions, cliLogo, projectRoot) {
   const brandConfig = loadBrandSection()
   const brandDir = path.join(projectRoot, BRAND_DIR)
+  const logos = brandConfig.logos || {}
+  const padding = brandConfig.padding || {}
+  const android = brandConfig.android || {}
+  const ios = brandConfig.ios || {}
+  const colors = brandConfig.colors || {}
+
+  const androidAdaptivePadding = cliOptions.androidAdaptivePadding
+    ?? cliOptions.padding
+    ?? padding.androidAdaptive
+    ?? 19
+
+  const androidLegacyPadding = cliOptions.androidLegacyPadding
+    ?? padding.androidLegacy
+    ?? 10
+
+  const iosPadding = cliOptions.iosPadding
+    ?? padding.ios
+    ?? 4
+
+  const bgColor = cliOptions.bgColor
+    ?? colors.background
+    ?? '#FFFFFF'
+
+  const darkBgColor = cliOptions.darkBgColor
+    ?? ios.darkBackground
+    ?? null
 
   const resolved = {
-    logo: pickLogo(cliLogo, brandConfig.logo, brandDir, 'logo', projectRoot),
-    monochromeLogo: pickLogo(cliOptions.monochromeLogo, brandConfig.monochromeLogo, brandDir, 'logo-mono', projectRoot),
-    darkLogo: pickLogo(cliOptions.darkLogo, brandConfig.darkLogo, brandDir, 'logo-dark', projectRoot),
-    tintedLogo: pickLogo(cliOptions.tintedLogo, brandConfig.tintedLogo, brandDir, 'logo-tinted', projectRoot),
+    logo: pickLogo(cliLogo, logos.primary, brandDir, 'logo', projectRoot),
+    iconLogo: pickLogo(cliOptions.iconLogo, logos.androidLauncher, brandDir, 'logo-icon', projectRoot),
+    monochromeLogo: pickLogo(cliOptions.monochromeLogo, logos.monochrome, brandDir, 'logo-mono', projectRoot),
+    darkLogo: pickLogo(cliOptions.darkLogo, logos.iosDark, brandDir, 'logo-dark', projectRoot),
+    tintedLogo: pickLogo(cliOptions.tintedLogo, logos.iosTinted, brandDir, 'logo-tinted', projectRoot),
+    splashLogo: pickLogo(cliOptions.splashLogo, logos.androidSplash, brandDir, 'logo-splash', projectRoot),
 
-    bgColor: cliOptions.bgColor ?? brandConfig.bgColor ?? '#FFFFFF',
-    bgColorExplicit: Boolean(cliOptions.bgColor ?? brandConfig.bgColor),
-    darkBgColor: cliOptions.darkBgColor ?? brandConfig.darkBgColor ?? null,
-    padding: cliOptions.padding ?? brandConfig.padding ?? 15,
-    iosPadding: cliOptions.iosPadding ?? brandConfig.iosPadding ?? 4,
+    bgColor,
+    bgColorExplicit: Boolean(cliOptions.bgColor ?? colors.background),
+    darkBgColor,
+    androidAdaptivePadding,
+    androidLegacyPadding,
+    iosPadding,
 
     // Kitchen-sink defaults: adaptive + marketplace are always generated; only
     // notification and splash are opt-in. Config can pre-enable them.
-    notification: Boolean(cliOptions.notification ?? brandConfig.notification ?? false),
-    splash: Boolean(cliOptions.splash ?? brandConfig.splash ?? false),
+    notification: Boolean(cliOptions.notification ?? android.notification ?? false),
+    splash: Boolean(cliOptions.splash ?? android.splash ?? false),
 
-    withDark: cliOptions.dark !== false && (brandConfig.dark ?? true),
-    withTinted: cliOptions.tinted !== false && (brandConfig.tinted ?? true),
+    withDark: cliOptions.dark !== false && (ios.dark ?? true),
+    withTinted: cliOptions.tinted !== false && (ios.tinted ?? true),
 
     cleanupLegacy: Boolean(cliOptions.cleanupLegacy),
     aggressive: Boolean(cliOptions.aggressive),

package/src/core/branding/cleanup-legacy.js

@@ -57,13 +57,6 @@ export async function cleanupLegacy({ projectRoot, projectType, aggressive = fal
   }
 
   if (adaptive && layout.androidAssets) {
-    const defaultPng = path.join(layout.androidAssets, 'default.png')
-    if (fs.existsSync(defaultPng)) {
-      conditional.push({
-        path: defaultPng,
-        reason: 'Legacy Android splash PNG (adaptive launcher handles splash now)'
-      })
-    }
     const appicon = path.join(layout.androidAssets, 'appicon.png')
     if (fs.existsSync(appicon)) {
       conditional.push({

package/src/core/branding/ensure-brand-section.js

@@ -23,12 +23,33 @@ import { projectsConfigJS, projectsPurge_TSS_Brand_Folder } from '../../shared/c
 import { logger } from './branding-logger.js'
 
 const BRAND_BLOCK = `  brand: {
-    splash: false,           // also generate splash_icon.png × 5
-    padding: '15%',          // Android safe-zone. Range: 12% tight (mature logos) — 20% conservative. Spec floor 19.44%.
-    iosPadding: '4%',        // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
-    darkBgColor: null,       // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-    bgColor: '#FFFFFF',      // Android adaptive bg + iOS/marketplace flatten
-    notification: false,     // also generate ic_stat_notify.png × 5
+    logos: {
+      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
+      // primary: './docs/logo.svg',
+      // androidLauncher: './docs/app-icon.svg',
+      // androidSplash: './docs/splash.svg',
+      // monochrome: './docs/logo-mono.svg',
+      // iosDark: './docs/logo-dark.svg',
+      // iosTinted: './docs/logo-tinted.svg'
+    },
+    padding: {
+      ios: '4%',             // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
+      androidLegacy: '10%',  // legacy ic_launcher.png padding
+      androidAdaptive: '19%' // adaptive foreground padding near the Android safe-zone
+    },
+    android: {
+      splash: false,         // also generate splash_icon.png × 5
+      notification: false    // also generate ic_stat_notify.png × 5
+    },
+    colors: {
+      background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+    },
+    // Optional iOS overrides:
+    // ios: {
+    //   dark: false,
+    //   tinted: false,
+    //   darkBackground: '#111111'
+    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
 `
@@ -70,7 +91,7 @@ export function ensureBrandSection() {
     fs.writeFileSync(projectsConfigJS, patched, 'utf8')
     console.log()
     logger.success(`Added ${chalk.cyan('brand:')} section to ${chalk.cyan('./purgetss/config.cjs')} with default values.`)
-    console.log('  Edit that block to customize brand defaults (bgColor, padding, etc.).')
+    console.log('  Edit that block to customize brand defaults (logos, padding, colors, etc.).')
     console.log('  CLI flags always win over config values.')
     console.log()
   } catch (err) {

package/src/core/branding/gen-android-adaptive.js

@@ -28,8 +28,8 @@ export const DENSITIES = [
   { name: 'xxxhdpi', size: 432 }
 ]
 
-export async function genAndroidAdaptive(tightMaster, bgColor, paddingPct, resRoot, opts = {}) {
-  const { monoTight = null } = opts
+export async function genAndroidAdaptive(masterPng, bgColor, paddingPct, resRoot, opts = {}) {
+  const { monoMaster = null } = opts
   const generated = []
 
   for (const { name, size } of DENSITIES) {
@@ -42,7 +42,7 @@ export async function genAndroidAdaptive(tightMaster, bgColor, paddingPct, resRo
     const monochromePath = path.join(dir, 'ic_launcher_monochrome.png')
 
     // Foreground: logo sized to inner, centered on transparent canvas
-    const innerLogo = await sharp(tightMaster)
+    const innerLogo = await sharp(masterPng)
       .resize({
         width: inner,
         height: inner,
@@ -76,8 +76,8 @@ export async function genAndroidAdaptive(tightMaster, bgColor, paddingPct, resRo
       .toFile(backgroundPath)
 
     // Monochrome: white silhouette with preserved alpha.
-    if (monoTight) {
-      const innerMono = await sharp(monoTight)
+    if (monoMaster) {
+      const innerMono = await sharp(monoMaster)
         .resize({
           width: inner,
           height: inner,

package/src/core/branding/gen-android-default.js

@@ -0,0 +1,52 @@
+/**
+ * PurgeTSS - gen-android-default
+ *
+ * Generates the legacy Android splash fallback used by Titanium projects via
+ * app/assets/android/default.png. This path is still relevant on Android <12
+ * when the app does not provide a custom windowBackground theme.
+ *
+ * Output path:
+ *   Alloy   -> app/assets/android/default.png
+ *   Classic -> Resources/android/default.png
+ *
+ * @fileoverview Legacy Android default.png splash generator
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+
+const DEFAULT_WIDTH = 1440
+const DEFAULT_HEIGHT = 2560
+
+export async function genAndroidDefault(masterPng, bgColor, outDir) {
+  fs.mkdirSync(outDir, { recursive: true })
+
+  const outPath = path.join(outDir, 'default.png')
+  const innerWidth = Math.floor(DEFAULT_WIDTH * 0.72)
+  const innerHeight = Math.floor(DEFAULT_HEIGHT * 0.26)
+
+  const innerLogo = await sharp(masterPng)
+    .resize({
+      width: innerWidth,
+      height: innerHeight,
+      fit: 'inside',
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .toBuffer()
+
+  await sharp({
+    create: {
+      width: DEFAULT_WIDTH,
+      height: DEFAULT_HEIGHT,
+      channels: 4,
+      background: bgColor
+    }
+  })
+    .composite([{ input: innerLogo, gravity: 'center' }])
+    .png({ compressionLevel: 9 })
+    .toFile(outPath)
+
+  return outPath
+}

package/src/core/branding/gen-android-legacy.js

@@ -22,7 +22,7 @@ export const LEGACY_DENSITIES = [
   { name: 'xxxhdpi', size: 192 }
 ]
 
-export async function genAndroidLegacy(tightMaster, bgColor, paddingPct, resRoot) {
+export async function genAndroidLegacy(masterPng, bgColor, paddingPct, resRoot) {
   const generated = []
   // Legacy icons have no adaptive mask — they render as drawn. Use ~60% of
   // the adaptive padding so the logo fills more of the canvas.
@@ -35,7 +35,7 @@ export async function genAndroidLegacy(tightMaster, bgColor, paddingPct, resRoot
 
     const outPath = path.join(dir, 'ic_launcher.png')
 
-    const innerLogo = await sharp(tightMaster)
+    const innerLogo = await sharp(masterPng)
       .resize({
         width: inner,
         height: inner,

package/src/core/branding/gen-splash.js

@@ -26,7 +26,7 @@ export const SPLASH_DENSITIES = [
   { name: 'xxxhdpi', size: 1152 }
 ]
 
-export async function genSplash(tightMaster, resRoot) {
+export async function genSplash(masterPng, resRoot) {
   const generated = []
 
   for (const { name, size } of SPLASH_DENSITIES) {
@@ -36,7 +36,7 @@ export async function genSplash(tightMaster, resRoot) {
 
     const outPath = path.join(dir, 'splash_icon.png')
 
-    const innerLogo = await sharp(tightMaster)
+    const innerLogo = await sharp(masterPng)
       .resize({
         width: inner,
         height: inner,

package/src/core/branding/index.js

@@ -35,6 +35,7 @@
 import fs from 'fs'
 import os from 'os'
 import path from 'path'
+import sharp from 'sharp'
 import { logger } from './branding-logger.js'
 import { logger as mainLogger } from '../../shared/logger.js'
 import { confirmWithAlways } from '../../shared/prompt.js'
@@ -45,6 +46,7 @@ import { genIosDark } from './gen-ios-dark.js'
 import { genIosTinted } from './gen-ios-tinted.js'
 import { genAndroidAdaptive } from './gen-android-adaptive.js'
 import { genAndroidLegacy } from './gen-android-legacy.js'
+import { genAndroidDefault } from './gen-android-default.js'
 import { genMarketplace } from './gen-marketplace.js'
 import { genNotification } from './gen-notification.js'
 import { genSplash } from './gen-splash.js'
@@ -56,6 +58,8 @@ import { printPostGenNotes } from './post-gen-notes.js'
 export async function runBranding(opts) {
   const {
     logo,
+    iconLogo = null,
+    splashLogo = null,
     monochromeLogo = null,
     darkLogo = null,
     darkBgColor = null,
@@ -64,7 +68,8 @@ export async function runBranding(opts) {
     tintedLogo = null,
     bgColor = '#FFFFFF',
     bgColorExplicit = false,
-    padding = 15,
+    androidAdaptivePadding = 19,
+    androidLegacyPadding = 10,
     iosPadding = 4,
     notification = false,
     splash = false,
@@ -79,7 +84,7 @@ export async function runBranding(opts) {
     confirmOverwrites = true
   } = opts
 
-  validateOptions({ logo, bgColor, darkBgColor, padding, iosPadding, cleanupLegacy: runCleanup })
+  validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, cleanupLegacy: runCleanup })
 
   const projectType = detectProjectType(projectRoot)
   const isInPlace = inPlace && !output
@@ -92,7 +97,7 @@ export async function runBranding(opts) {
   if (logo) {
     logger.property('Logo:       ', logo)
     logger.property('Background: ', bgColor)
-    logger.property('Padding:    ', `Android ${padding}% / iOS ${iosPadding}% per side`)
+    logger.property('Padding:    ', `Android adaptive ${androidAdaptivePadding}% / Android legacy ${androidLegacyPadding}% / iOS ${iosPadding}% per side`)
     console.log()
     logger.property(isInPlace ? 'Writing IN PLACE to: ' : 'Staging:    ', isInPlace ? projectRoot : stagingRoot)
   }
@@ -157,6 +162,8 @@ export async function runBranding(opts) {
     lines.push(`${androidResStaging}/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/ic_launcher_{foreground,background,monochrome}.png`)
     lines.push(`${androidResStaging}/mipmap-{...}/ic_launcher.png (legacy)`)
     lines.push(`${androidResStaging}/mipmap-anydpi-v26/ic_launcher.xml`)
+    const androidAssetsStaging = getStagingAndroidAssetsRoot(stagingRoot, projectType)
+    if (androidAssetsStaging) lines.push(`${androidAssetsStaging}/default.png (Android <12 legacy splash fallback)`)
     if (notification) lines.push(`${androidResStaging}/drawable-*/ic_stat_notify.png × 5`)
     if (splash) lines.push(`${androidResStaging}/drawable-*/splash_icon.png × 5`)
     mainLogger.block('[dry-run] Would generate:', ...lines)
@@ -179,9 +186,32 @@ export async function runBranding(opts) {
   logger.section('Logos')
   logger.bullet('Dual logos (square + tight)')
   const logoBase = path.join(tempDir, '_logo')
-  const { tight } = await prepareMaster(logo, logoBase)
+  const { square, tight } = await prepareMaster(logo, logoBase)
 
-  let monoTight = null
+  let iconMaster = square
+  if (iconLogo) {
+    if (!fs.existsSync(iconLogo)) {
+      throw new Error(`Android icon logo not found: ${iconLogo}`)
+    }
+    logger.bullet(`Android icon logo: ${iconLogo}`)
+    const iconBase = path.join(tempDir, '_logo_icon')
+    const iconResult = await prepareMaster(iconLogo, iconBase)
+    iconMaster = iconResult.square
+  }
+  await warnIfLogoAspectIsUnsafeForLauncher(tight)
+
+  let splashMaster = iconMaster
+  if (splashLogo) {
+    if (!fs.existsSync(splashLogo)) {
+      throw new Error(`Android splash logo not found: ${splashLogo}`)
+    }
+    logger.bullet(`Android splash logo: ${splashLogo}`)
+    const splashBase = path.join(tempDir, '_logo_splash')
+    const splashResult = await prepareMaster(splashLogo, splashBase)
+    splashMaster = splashResult.square
+  }
+
+  let monoMaster = null
   if (monochromeLogo) {
     if (!fs.existsSync(monochromeLogo)) {
       throw new Error(`Monochrome logo not found: ${monochromeLogo}`)
@@ -189,13 +219,13 @@ export async function runBranding(opts) {
     logger.bullet(`Monochrome logo: ${monochromeLogo}`)
     const monoBase = path.join(tempDir, '_logo_mono')
     const monoResult = await prepareMaster(monochromeLogo, monoBase)
-    monoTight = monoResult.tight
+    monoMaster = monoResult.square
   }
 
   // ---- Section: iOS & marketplace ----------------------------------------
   logger.section('iOS & marketplace')
-  logger.bullet(`DefaultIcon.png (Android-safe padding ${padding}%) + DefaultIcon-ios.png (iOS padding ${iosPadding}%)`)
-  const ios = await genIos(tight, bgColor, padding, iosPadding, stagingRoot)
+  logger.bullet(`DefaultIcon.png (Android-safe padding ${androidAdaptivePadding}%) + DefaultIcon-ios.png (iOS padding ${iosPadding}%)`)
+  const ios = await genIos(tight, bgColor, androidAdaptivePadding, iosPadding, stagingRoot)
   generated.push(ios.defaultIcon, ios.defaultIconIos)
 
   if (withDark) {
@@ -238,29 +268,36 @@ export async function runBranding(opts) {
   // ---- Section: Android --------------------------------------------------
   logger.section('Android')
 
-  const monoLabel = monoTight ? ', monochrome from --monochrome-logo' : ''
-  logger.bullet(`Adaptive icons (foreground + background + monochrome${monoLabel}) × 5`)
-  const adaptiveFiles = await genAndroidAdaptive(tight, bgColor, padding, androidResStaging, { monoTight })
+  const monoLabel = monoMaster ? ', monochrome from --monochrome-logo' : ''
+  logger.bullet(`Adaptive icons (foreground + background + monochrome${monoLabel}, padding ${androidAdaptivePadding}%) × 5`)
+  const adaptiveFiles = await genAndroidAdaptive(iconMaster, bgColor, androidAdaptivePadding, androidResStaging, { monoMaster })
   generated.push(...adaptiveFiles)
 
-  logger.bullet('Legacy ic_launcher.png × 5')
-  const legacyFiles = await genAndroidLegacy(tight, bgColor, padding, androidResStaging)
+  logger.bullet(`Legacy ic_launcher.png × 5 (padding ${androidLegacyPadding}%)`)
+  const legacyFiles = await genAndroidLegacy(iconMaster, bgColor, androidLegacyPadding, androidResStaging)
   generated.push(...legacyFiles)
 
   const xmlPath = genIcLauncherXml(androidResStaging)
   generated.push(xmlPath)
   logger.bullet(`Adaptive icon XML: ${xmlPath}`)
 
+  const androidDefaultDir = getStagingAndroidAssetsRoot(stagingRoot, projectType)
+  if (androidDefaultDir) {
+    logger.bullet('Legacy Android default.png splash fallback')
+    const defaultSplashPath = await genAndroidDefault(splashMaster, bgColor, androidDefaultDir)
+    generated.push(defaultSplashPath)
+  }
+
   if (notification) {
-    const monoLabelNotif = monoTight ? ' from --monochrome-logo' : ' whitened from logo'
+    const monoLabelNotif = monoMaster ? ' from --monochrome-logo' : ' whitened from logo'
     logger.bullet(`Notification icons (white+alpha, edge-to-edge${monoLabelNotif}) × 5`)
-    const notifFiles = await genNotification(monoTight || tight, androidResStaging)
+    const notifFiles = await genNotification(monoMaster || iconMaster, androidResStaging)
     generated.push(...notifFiles)
   }
 
   if (splash) {
     logger.bullet('Splash icons × 5')
-    const splashFiles = await genSplash(tight, androidResStaging)
+    const splashFiles = await genSplash(splashMaster, androidResStaging)
     generated.push(...splashFiles)
   }
 
@@ -277,12 +314,16 @@ export async function runBranding(opts) {
       const tmpFiles = [
         path.join(tempDir, '_logo_square.png'),
         path.join(tempDir, '_logo_tight.png'),
+        path.join(tempDir, '_logo_icon_square.png'),
+        path.join(tempDir, '_logo_icon_tight.png'),
         path.join(tempDir, '_logo_mono_square.png'),
         path.join(tempDir, '_logo_mono_tight.png'),
         path.join(tempDir, '_logo_dark_square.png'),
         path.join(tempDir, '_logo_dark_tight.png'),
         path.join(tempDir, '_logo_tinted_square.png'),
-        path.join(tempDir, '_logo_tinted_tight.png')
+        path.join(tempDir, '_logo_tinted_tight.png'),
+        path.join(tempDir, '_logo_splash_square.png'),
+        path.join(tempDir, '_logo_splash_tight.png')
       ]
       for (const tmp of tmpFiles) {
         if (fs.existsSync(tmp)) fs.unlinkSync(tmp)
@@ -300,7 +341,8 @@ export async function runBranding(opts) {
     projectRoot,
     stagingRoot,
     bgColor,
-    padding,
+    androidAdaptivePadding,
+    androidLegacyPadding,
     iosPadding,
     withSplash: splash,
     withNotification: notification,
@@ -311,13 +353,39 @@ export async function runBranding(opts) {
   return { stagingRoot, generated }
 }
 
+async function warnIfLogoAspectIsUnsafeForLauncher(tightLogoPath) {
+  const meta = await sharp(tightLogoPath).metadata()
+  const width = meta.width || 0
+  const height = meta.height || 0
+
+  if (!width || !height) return
+
+  const aspect = width / height
+  const isWideWordmark = aspect > 1.25
+  const isTallWordmark = aspect < 0.8
+
+  if (!isWideWordmark && !isTallWordmark) return
+
+  logger.warning('The source logo is not close to square.')
+  logger.warning(`Aspect ratio detected: ${width}×${height} (${aspect.toFixed(2)}:1).`)
+  logger.warning('Launcher icons and Android 12+ system splash screens work best with a square mark.')
+  logger.warning('A wide/tall wordmark can look cramped or cropped once centered inside icon masks.')
+  logger.warning('Recommendation: use a dedicated square app-icon source for `purgetss brand`.')
+}
+
 function getStagingAndroidResRoot(stagingRoot, projectType) {
   if (projectType === 'alloy') return path.join(stagingRoot, 'app', 'platform', 'android', 'res')
   if (projectType === 'classic') return path.join(stagingRoot, 'platform', 'android', 'res')
   return path.join(stagingRoot, 'standalone', 'platform', 'android', 'res')
 }
 
-function validateOptions({ logo, bgColor, darkBgColor, padding, iosPadding, cleanupLegacy }) {
+function getStagingAndroidAssetsRoot(stagingRoot, projectType) {
+  if (projectType === 'alloy') return path.join(stagingRoot, 'app', 'assets', 'android')
+  if (projectType === 'classic') return path.join(stagingRoot, 'Resources', 'android')
+  return null
+}
+
+function validateOptions({ logo, bgColor, darkBgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, cleanupLegacy }) {
   if (!logo && !cleanupLegacy) {
     throw new Error('Logo image path is required (unless using --cleanup-legacy alone).')
   }
@@ -327,8 +395,11 @@ function validateOptions({ logo, bgColor, darkBgColor, padding, iosPadding, clea
   if (darkBgColor && !/^#[0-9A-Fa-f]{6}$/.test(darkBgColor)) {
     throw new Error(`--dark-bg-color must be a 6-digit hex like #1C1C1E (got: ${darkBgColor}).`)
   }
-  if (padding < 0 || padding > 40) {
-    throw new Error(`--padding must be between 0 and 40 (got: ${padding}).`)
+  if (androidAdaptivePadding < 0 || androidAdaptivePadding > 40) {
+    throw new Error(`--android-adaptive-padding must be between 0 and 40 (got: ${androidAdaptivePadding}).`)
+  }
+  if (androidLegacyPadding < 0 || androidLegacyPadding > 40) {
+    throw new Error(`--android-legacy-padding must be between 0 and 40 (got: ${androidLegacyPadding}).`)
   }
   if (iosPadding < 0 || iosPadding > 40) {
     throw new Error(`--ios-padding must be between 0 and 40 (got: ${iosPadding}).`)

package/src/core/branding/post-gen-notes.js

@@ -23,11 +23,11 @@ export function printPostGenNotes(opts) {
 }
 
 function printCompactSummary(opts) {
-  const { projectType, projectRoot, stagingRoot, bgColor, padding, iosPadding, inPlace } = opts
+  const { projectType, projectRoot, stagingRoot, bgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, inPlace } = opts
 
   logger.section('Summary')
   logger.bullet(`Background: ${chalk.cyan(bgColor)}`)
-  logger.bullet(`Padding: Android ${chalk.cyan(padding + '%')} / iOS ${chalk.cyan(iosPadding + '%')}`)
+  logger.bullet(`Padding: Android adaptive ${chalk.cyan(androidAdaptivePadding + '%')} / Android legacy ${chalk.cyan(androidLegacyPadding + '%')} / iOS ${chalk.cyan(iosPadding + '%')}`)
   logger.bullet(`${inPlace ? 'Written in place to' : 'Staged at'}: ${chalk.cyan(inPlace ? projectRoot : stagingRoot)}`)
 
   logger.section('Next steps')
@@ -56,7 +56,7 @@ function printCompactSummary(opts) {
 function printFullNotes(opts) {
   const {
     projectType, projectRoot, stagingRoot,
-    bgColor, padding, iosPadding, withSplash, withNotification, inPlace
+    bgColor, androidAdaptivePadding, androidLegacyPadding, iosPadding, withSplash, withNotification, inPlace
   } = opts
 
   const code = (s) => chalk.gray(s)
@@ -66,17 +66,20 @@ function printFullNotes(opts) {
   logger.section('Notes on what was generated')
   logger.bullet(`Brand color ${chalk.cyan(bgColor)} was baked into Android adaptive background layer`)
   console.log('    and iOS/marketplace flattened masters (Apple rejects alpha).')
-  logger.bullet(`Android padding:  ${chalk.cyan(padding + '%')}  (logo fills ${100 - 2 * padding}% of each mipmap canvas)`)
-  logger.bullet(`iOS padding:      ${chalk.cyan(iosPadding + '%')}  (logo fills ${100 - 2 * iosPadding}% of DefaultIcon-ios and marketplace art)`)
+  logger.bullet(`Android adaptive padding: ${chalk.cyan(androidAdaptivePadding + '%')}  (logo fills ${100 - 2 * androidAdaptivePadding}% of each adaptive foreground canvas)`)
+  logger.bullet(`Android legacy padding:   ${chalk.cyan(androidLegacyPadding + '%')}  (logo fills ${100 - 2 * androidLegacyPadding}% of each legacy launcher canvas)`)
+  logger.bullet(`iOS padding:              ${chalk.cyan(iosPadding + '%')}  (logo fills ${100 - 2 * iosPadding}% of DefaultIcon-ios and marketplace art)`)
 
   console.log()
   console.log('  If the logo looks cramped: re-run with higher padding')
-  console.log(`      ${flag('--padding 25-30')}       (Android)`)
-  console.log(`      ${flag('--ios-padding 10-14')}   (iOS)`)
+  console.log(`      ${flag('--android-adaptive-padding 25-30')}   (adaptive icon)`)
+  console.log(`      ${flag('--android-legacy-padding 14-18')}     (legacy icon)`)
+  console.log(`      ${flag('--ios-padding 10-14')}                (iOS)`)
   console.log()
   console.log('  If the logo looks too small: re-run with lower padding')
-  console.log(`      ${flag('--padding 19')}          (Android spec floor)`)
-  console.log(`      ${flag('--ios-padding 2-3')}     (matches first-party apps like Mail, Safari)`)
+  console.log(`      ${flag('--android-adaptive-padding 19')}      (adaptive spec floor)`)
+  console.log(`      ${flag('--android-legacy-padding 8-12')}      (legacy icon)`)
+  console.log(`      ${flag('--ios-padding 2-3')}                  (matches first-party apps like Mail, Safari)`)
 
   logger.section('Configuration reminders')
   console.log('  The tool does NOT auto-edit tiapp.xml. Snippets below are optional —')
@@ -105,17 +108,28 @@ function printFullNotes(opts) {
     console.log()
     console.log(`  ${num('3.')} ${chalk.cyan('Android 12+ splash screen')} — ${chalk.yellow('OPTIONAL, advanced')}`)
     console.log()
+    console.log('     Generated files: @drawable/splash_icon.png across densities.')
     console.log('     Titanium SDK 13.x shows a system splash automatically using your')
-    console.log('     launcher icon. For most apps THE DEFAULT IS ENOUGH — do nothing.')
+    console.log('     launcher icon unless you wire a custom splash theme.')
+    console.log('     If you want the Android 12+ splash to use splash_icon instead of')
+    console.log('     ic_launcher, add a custom theme and point')
+    console.log(code('       <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>'))
   }
 
+  console.log()
+  console.log(`  ${num(withSplash ? '4.' : '3.')} ${chalk.cyan('Android <12 legacy splash')}`)
+  console.log('     PurgeTSS brand now regenerates app/assets/android/default.png as')
+  console.log('     a legacy fallback splash for Titanium projects.')
+  console.log('     If your app uses a custom windowBackground / background.9.png theme,')
+  console.log('     that custom theme still takes precedence.')
+
   if (withNotification) {
     const colorsDir = projectType === 'classic'
       ? 'platform/android/res/values'
       : 'app/platform/android/res/values'
 
     console.log()
-    console.log(`  ${num('4.')} ${chalk.cyan('FCM notification icon + tint')}`)
+    console.log(`  ${num(withSplash ? '5.' : '4.')} ${chalk.cyan('FCM notification icon + tint')}`)
     console.log('     Only needed if you use firebase.cloudmessaging for push.')
     console.log()
     console.log(`     Create ${flag(colorsDir + '/colors.xml')} (or merge):`)

package/src/shared/config-manager.js

@@ -34,11 +34,11 @@ const require = createRequire(import.meta.url)
  *   '20'   → 20
  *   '20%'  → 20
  *
- * Used for `brand.padding` and `brand.iosPadding` so users can write
- * self-documenting values like `padding: '25%'` in their config.
+ * Used for the `brand.padding.*` values so users can write
+ * self-documenting values like `androidAdaptive: '19%'` in their config.
  *
  * @param {number|string} value
- * @param {string} fieldName - Config path for error messages (e.g. 'brand.padding')
+ * @param {string} fieldName - Config path for error messages (e.g. 'brand.padding.androidAdaptive')
  * @returns {number} Integer 0-40
  */
 function parsePadding(value, fieldName) {
@@ -128,12 +128,20 @@ export function getConfigFile() {
   configFile.purge.options.plugins = configFile.purge.options.plugins ?? []
 
   configFile.brand = configFile.brand ?? {}
-  configFile.brand.bgColor = configFile.brand.bgColor ?? '#FFFFFF'
-  configFile.brand.padding = parsePadding(configFile.brand.padding ?? 15, 'brand.padding')
-  configFile.brand.iosPadding = parsePadding(configFile.brand.iosPadding ?? 4, 'brand.iosPadding')
-  configFile.brand.darkBgColor = configFile.brand.darkBgColor ?? null
-  configFile.brand.notification = configFile.brand.notification ?? false
-  configFile.brand.splash = configFile.brand.splash ?? false
+  configFile.brand.logos = configFile.brand.logos ?? {}
+  configFile.brand.padding = configFile.brand.padding ?? {}
+  configFile.brand.padding.ios = parsePadding(configFile.brand.padding.ios ?? 4, 'brand.padding.ios')
+  configFile.brand.padding.androidLegacy = parsePadding(configFile.brand.padding.androidLegacy ?? 10, 'brand.padding.androidLegacy')
+  configFile.brand.padding.androidAdaptive = parsePadding(configFile.brand.padding.androidAdaptive ?? 19, 'brand.padding.androidAdaptive')
+  configFile.brand.android = configFile.brand.android ?? {}
+  configFile.brand.android.notification = configFile.brand.android.notification ?? false
+  configFile.brand.android.splash = configFile.brand.android.splash ?? false
+  configFile.brand.ios = configFile.brand.ios ?? {}
+  configFile.brand.ios.dark = configFile.brand.ios.dark ?? true
+  configFile.brand.ios.tinted = configFile.brand.ios.tinted ?? true
+  configFile.brand.ios.darkBackground = configFile.brand.ios.darkBackground ?? null
+  configFile.brand.colors = configFile.brand.colors ?? {}
+  configFile.brand.colors.background = configFile.brand.colors.background ?? '#FFFFFF'
 
   configFile.images = configFile.images ?? {}
   configFile.images.quality = configFile.images.quality ?? 85