@maccesar/titools 2.9.0 → 2.10.1

package/skills/purgetss/references/appearance-module.md

@@ -2,15 +2,71 @@
 
 The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every controller in the app reads and writes the same state.
 
-This file covers the four public methods, the required setup, a full Settings-view example, and the lifecycle that keeps the saved mode in sync with the UI. For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
+This reference follows the same workflow-first / API-second split the official PurgeTSS documentation now uses:
+
+- **Workflow** — initialize at startup, then build a Settings view that calls `Appearance.set(...)` (mirrors `best-practices/1-appearance-setup.md`).
+- **API reference** — the four public methods, exact signatures, and lifecycle (mirrors `purgetss-ui/10-appearance.md`).
+
+For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
 
 > **INFO**
 >
 > Requires PurgeTSS **>= 7.5.3**. On older versions the `Appearance` export does not exist — the `require('purgetss.ui')` call will succeed, but `Appearance` will be `undefined`. Run `purgetss --version` in the project root to confirm.
 
-## Setup
+## How it fits together
+
+The Appearance module sits between three moving parts: a JS singleton, the OS-level interface style, and the semantic colors generated by PurgeTSS. The diagram below shows how a single `Appearance.init()` call at startup wires them together, and what happens when the user later picks a mode in Settings.
+
+```
+┌─ app/lib/appearance.js (singleton from purgetss.ui) ─────────────────┐
+│                                                                      │
+│   Appearance.init()  ────► reads 'userInterfaceStyle'                │
+│                            from Ti.App.Properties                    │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.set(m)  ────► writes Ti.App.Properties                  │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.get()   ────► returns 'system' | 'light' | 'dark'       │
+│   Appearance.toggle()────► flips between 'light' and 'dark'          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Ti.UI.semanticColorType (runtime) ──────────────────────────────────┐
+│                                                                      │
+│   Light mode  ─►  resolves bg-surface       to surfaceColor.light    │
+│                   resolves text-on-surface  to textColor.light       │
+│                                                                      │
+│   Dark mode   ─►  resolves bg-surface       to surfaceColor.dark     │
+│                   resolves text-on-surface  to textColor.dark        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Utility classes in views ───────────────────────────────────────────┐
+│                                                                      │
+│   bg-surface, text-on-surface, bg-border, bg-surface-high, ...       │
+│   Repaint instantly on every Appearance.set(...) call.               │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
+
+## Workflow
+
+The fastest path from zero to a working Light / Dark toggle is three steps. Each one maps to one section of the official `best-practices/1-appearance-setup.md` guide.
 
-Call `Appearance.init()` **once** at app startup, before opening the first window. The standard place is the top of `app/controllers/index.js`.
+### 1. Define semantic colors
+
+Create `app/assets/semantic.colors.json` and register the color names under `theme.extend.colors` in `purgetss/config.cjs`. The class names you use in XML (`bg-surface`, `text-on-surface`, `bg-border`, ...) come from this mapping.
+
+See [semantic-colors.md](./semantic-colors.md) for the JSON schema, the `config.cjs` mapping, nesting rules, and alpha transparency.
+
+### 2. Initialize Appearance at startup
+
+Call `Appearance.init()` **once** before opening the first window. The standard place is the top of `app/controllers/index.js`:
 
 `app/controllers/index.js`
 ```js
@@ -27,22 +83,11 @@ $.navWin.open()
 >
 > Call `Appearance.init()` **before** `$.navWin.open()` (or whichever window you open first). If the window opens first, it will render once against the system default and then flicker to the saved mode when `init()` runs — a visible flash on cold launch.
 
-## Methods
-
-| Method       | Description                                                                 |
-| ------------ | --------------------------------------------------------------------------- |
-| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
-| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
-| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
-| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
-
-All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
-
-## Full Settings-view example
+### 3. Build an Appearance toggle
 
-A three-row settings panel — System / Light / Dark — where each row shows a `fa-solid fa-circle-check` icon next to the currently active mode. Tapping a row calls `Appearance.set(...)` and updates the check icons.
+Build a Settings view where users pick `System`, `Light`, or `Dark`. Tapping a row calls `Appearance.set(...)` and updates the check icons.
 
-### View
+#### View
 
 `app/views/settings.xml`
 ```xml
@@ -86,7 +131,7 @@ A three-row settings panel — System / Light / Dark — where each row shows a
 </Alloy>
 ```
 
-### Controller
+#### Controller
 
 `app/controllers/settings.js`
 ```js
@@ -95,16 +140,16 @@ const { Appearance } = require('purgetss.ui')
 // Sync check icons with the mode saved at app startup.
 updateUI(Appearance.get())
 
-const selectDark   = () => selectAppearance('dark')
-const selectLight  = () => selectAppearance('light')
-const selectSystem = () => selectAppearance('system')
+function selectDark()   { selectAppearance('dark') }
+function selectLight()  { selectAppearance('light') }
+function selectSystem() { selectAppearance('system') }
 
-const selectAppearance = (value) => {
+function selectAppearance(value) {
   Appearance.set(value)
   updateUI(value)
 }
 
-const updateUI = (value) => {
+function updateUI(value) {
   $.themeDarkCheck.visible   = (value === 'dark')
   $.themeLightCheck.visible  = (value === 'light')
   $.themeSystemCheck.visible = (value === 'system')
@@ -113,9 +158,24 @@ const updateUI = (value) => {
 
 The background, text, border, and icon colors in the XML come from semantic color classes (`bg-surface`, `bg-surface-high`, `text-on-surface`, `bg-border`, etc.) — see [semantic-colors.md](./semantic-colors.md) for how to wire those up so the whole view flips when `Appearance.set('dark')` fires.
 
-## Lifecycle
+> **Why named functions in Alloy controllers?** Alloy resolves `onClick="selectDark"` by looking up a top-level identifier on the controller scope. Named function declarations (`function selectDark() { ... }`) hoist and are reliably resolvable; arrow functions assigned to `const` are not hoisted and tend to bite you when an XML attribute fires before the binding has executed. The official setup guide uses named functions for this reason.
 
-How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate:
+## API reference
+
+### Methods
+
+| Method       | Description                                                                 |
+| ------------ | --------------------------------------------------------------------------- |
+| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
+| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
+| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
+| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
+
+All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
+
+### Lifecycle
+
+How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate during a typical session:
 
 ```
 app startup
@@ -143,8 +203,6 @@ app startup
           +-- Preference survives the next cold launch
 ```
 
-`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
-
 > **INFO**
 >
 > `toggle()` intentionally skips `'system'`. If the current mode is `'system'`, calling `toggle()` produces `'dark'`. If you want a three-way cycle (System -> Light -> Dark -> System), build it in userland with `Appearance.get()` + `Appearance.set(...)`; do not expect `toggle()` to do it.

package/skills/purgetss/references/apply-directive.md

@@ -254,6 +254,66 @@ Window: { default: { apply: 'exit-on-close-false bg-blue-500' } }
 
 Use the explicit `default:` wrapper when you also need platform blocks (`ios:`, `android:`) next to it. For the common case of one bundle of defaults, the shorthand reads better.
 
+### Extend mode vs replace mode
+
+> **HEADLINE CHANGE — v7.9.0**
+> This is the headline change of PurgeTSS v7.9.0. Before v7.9.0, `theme.Window` / `theme.View` / `theme.ImageView` still had the framework defaults merged in, which caused gradient ghosting and other surprising overrides. v7.9.0 makes top-level (non-`extend`) configs behave as true replace mode.
+>
+> If you previously used `theme.Window` (no `extend`) and depended on the white background or the iOS `hires: true` / `Ti.UI.SIZE` defaults still being there, you will need to either move that config under `theme.extend.Window` (extend mode) or add the previously-implicit utilities back into your `apply` string.
+
+PurgeTSS follows the Tailwind convention for the three Ti Elements that ship with framework defaults — `Window`, `View`, and `ImageView`:
+
+- **Extend mode** — `theme.extend.Window`, `theme.extend.View`, `theme.extend.ImageView`. Your customization **merges** with the framework defaults. The white Window `backgroundColor`, `Ti.UI.SIZE` width/height on `View`, and iOS `hires: true` on `ImageView` stay in place unless you override them with `apply`. Use this when you want to add to the defaults, not replace them.
+- **Replace mode** — `theme.Window`, `theme.View`, `theme.ImageView` (top level, no `extend`). Your config **replaces** the framework defaults entirely. The white Window background is omitted, the `Ti.UI.SIZE` width/height on `View` is omitted, and the iOS `hires: true` on `ImageView` is omitted. Your `apply` becomes the source of truth for that Ti Element.
+
+Use replace mode when you want full control and do not want a preset mixed in. The canonical case is a Window declared at `theme.Window` with a `backgroundGradient`, where the previously-merged white `backgroundColor` would render on top of the gradient and produce a "ghost" white wash.
+
+`./purgetss/config.cjs - replace mode (v7.9.0+)`
+```javascript
+module.exports = {
+  theme: {
+    Window: {
+      apply: 'bg-gradient-to-b from-blue-500 to-purple-600'
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+'Window': { backgroundGradient: { type: 'linear', colors: [...], startPoint: ..., endPoint: ... } }
+```
+
+Note the missing `backgroundColor: '#FFFFFF'`. Replace mode skipped the framework default, so the gradient renders cleanly. Before v7.9.0 the same config produced:
+
+```tss
+/* Pre-v7.9.0 — ghost white background covering the gradient */
+'Window': { backgroundColor: '#FFFFFF', backgroundGradient: { type: 'linear', colors: [...] } }
+```
+
+If you wanted the framework white background **and** something else on top, that is what extend mode is for:
+
+`./purgetss/config.cjs - extend mode`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      Window: {
+        apply: 'exit-on-close-false'
+      }
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+/* Framework default backgroundColor is preserved, exitOnClose merged in */
+'Window': { backgroundColor: '#FFFFFF', exitOnClose: false }
+```
+
+The same extend-vs-replace distinction applies to `View` (`Ti.UI.SIZE` width/height defaults) and `ImageView` (iOS `hires: true` default).
+
 ### Apply Wins Over Static Defaults
 
 If `apply` sets a property that the component already has as a built-in default, the applied value replaces the original instead of both ending up in the final TSS:

package/skills/purgetss/references/arbitrary-values.md

@@ -7,6 +7,47 @@ When you need a one-off value that is not in the defaults, use arbitrary values
 >
 > You cannot use square bracket notation like in Tailwind because Titanium handles platform and conditional statements in `.tss` files differently.
 
+## Class syntax pre-validation
+
+Starting with PurgeTSS v7.8.0, the build runs a pre-validation pass over class names found in XML views and JS controllers before purging. When it spots a malformed arbitrary-value utility, it stops and prints a structured `Class Syntax Error` block so the offending class can be fixed before any TSS is generated. If multiple errors are present, all of them are reported in the same run.
+
+Each error block includes:
+
+- The file path where the offending class lives
+- The line number inside that file
+- The offending class name (as authored)
+- A `Fix:` suggestion with the corrected class name
+
+Example shape:
+
+```
+Class Syntax Error
+  File: app/views/index.xml
+  Line: 12
+  Found: top-(-10)
+  Fix:   -top-(10)
+```
+
+### Detected patterns
+
+The validator catches five narrow, actionable mistakes:
+
+| Pattern                       | Offending input | Suggested fix | Notes                                                            |
+| ----------------------------- | --------------- | ------------- | ---------------------------------------------------------------- |
+| Inverted negative sign        | `top-(-10)`     | `-top-(10)`   | The `-` prefix goes before the rule, not inside the value        |
+| Tailwind-style brackets       | `top-[10px]`    | `top-(10px)`  | PurgeTSS uses parentheses, not square brackets, for arbitrary values |
+| Empty parentheses             | `wh-()`         | (flagged, no auto-fix) | Add a value such as `wh-(10)`                           |
+| Whitespace inside parentheses | `wh-( 200 )`    | `wh-(200)`    | No spaces allowed between `(`, the value, and `)`                |
+| Redundant `px` unit           | `top-(10px)`    | `top-(10)`    | PurgeTSS treats unit-less arbitrary values as pixels             |
+
+### Unknown classes are still silently dropped
+
+The pre-validator only fires on the five patterns above. Any other unknown class — typos, custom utilities not yet declared, vendor classes that are not enabled in `config.cjs` — is **not** reported as a `Class Syntax Error`. Those classes continue to flow into the `// Unused or unsupported classes` comment block in `app.tss`, exactly like before. This keeps the validator focused on actionable mistakes and avoids noise while you sketch out class names.
+
+### v7.8.0 parser fix for negatives inside parentheses
+
+Before v7.8.0, an inverted negative such as `top-(-10)` could be silently misparsed by the arbitrary-value pipeline (the `-` inside the parentheses confused the token matcher, producing wrong or missing TSS output without any warning). v7.8.0 hardens that path: the parser now correctly recognizes `top-(-10)` as authored, classifies it as an inverted-negative-sign error, and surfaces the `Class Syntax Error` block with the `-top-(10)` fix instead of producing silent garbage.
+
 ## Color Properties
 
 You can set arbitrary color values for all available color properties using `hex`, `rgb`, or `rgba` values, directly in XML files or in `config.cjs`.

package/skills/purgetss/references/cli-commands.md

@@ -1,6 +1,17 @@
 # PurgeTSS CLI Commands
 
-> **Info: What's new in v7.5.3 / v7.6.0**
+> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0 / v7.8.0 / v7.9.0**
+> - **Opacity modifiers on semantic colors (v7.9.0)** — writing `bg-surface/65` (or any opacity modifier on a class mapped to a name in `semantic.colors.json`) now produces a working rule with Light/Dark switching preserved. PurgeTSS auto-derives a `<originalKey>_<alphaPercent>` entry in `semantic.colors.json` with the original `light`/`dark` hex values plus the requested alpha for both modes, then emits the rule against the derived key. Re-runs are idempotent; manual edits with conflicting values halt the build with a `Conflict` error. New alpha entries require one full Titanium build to be picked up — Liveview hot-reload alone does not refresh `semantic.colors.json`.
+> - **Gradient + Window/View/ImageView preset fixes (v7.9.0)** — `theme.Window` / `theme.View` / `theme.ImageView` no longer leak the framework presets (white background, `Ti.UI.SIZE`, iOS `hires: true`) when defined at the top level (replace mode), so a Window declared at `theme.Window` with a `backgroundGradient` no longer ghosts on top of a default `backgroundColor: '#FFFFFF'`. `theme.extend.Window` keeps merging with the defaults as before. Also fixed: tonal palette inversion bug, position-dependent `from`/`to` color ordering after `sort()`, and `bg-gradient-to-X` direction silently dropped when combined with `from-X to-Y` colors.
+> - **Glossary path renamed (v7.9.0, breaking)** — the user-facing glossary output path was renamed from `purgetss/experimental/tailwind-classes/` to `purgetss/glossary/tailwind-classes/`. Tooling or CI that reads from the old path needs updating on upgrade — no transition shim. The `--glossary` flag and command surface are unchanged.
+> - **`images --width <n>` flag (v7.8.0)** — pins Android `mdpi` (= iPhone `@1x`) to a specific pixel width, with larger scales deriving as ×1.5, ×2, ×3, ×4 from that base. Use it for SVG sources from vector editors with disproportionate viewBoxes (Affinity, Illustrator). CLI-only; there is no matching `images:` config property because the right width is per-asset. See [`images` Command](#images-command).
+> - **Class syntax pre-validation (v7.8.0)** — `purgetss` now stops with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known class-name mistakes: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind-style brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`). All offenders are reported in one run. Generic unknown classes still flow into the `// Unused or unsupported classes` block in `app.tss`.
+> - **Negative-values-in-parens parser fix (v7.8.0)** — classes like `top-(-10)`, `mt-(-5)`, and `origin-(-10,-20)` no longer crash with `Cannot read properties of null (reading 'pop')`. The parser now extracts the `(...)` portion first, so a `-` inside the value does not break the split.
+> - **`brand:` config grouped (v7.7.0)** — the flat `brand:` block from v7.6.0 was reorganized into purpose-based sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`. Old projects keep working — newly-generated configs use the grouped form.
+> - **Separate Android brand inputs (v7.7.0)** — `brand` can now use one logo for the general brand set, another for Android launcher icons (`logos.androidLauncher` / `--icon-logo`), and another for Android 12+ splash artwork (`logos.androidSplash` / `--splash-logo`). Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/` or set the paths in `config.cjs`.
+> - **Legacy Android splash fallback (v7.7.0)** — `purgetss brand` now regenerates `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`.
+> - **`semantic` works in Classic projects (v7.6.2)** — writes to `Resources/semantic.colors.json` for Classic, keeps writing to `app/assets/semantic.colors.json` for Alloy.
+> - **Confirmation prompt for destructive writes (v7.6.1)** — `brand` and `images` ask `[y/N/a]` before overwriting (auto-skipped on non-TTY, with `-y`/`--yes`, or `PURGETSS_YES=1`).
 > - **New `brand` command (v7.6.0)** — generates the complete Titanium branding set (launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, optional notification/splash) from a single SVG or PNG logo. See [`brand` Command](#brand-command) and the deep-dive [app-branding.md](./app-branding.md).
 > - **New `images` command (v7.6.0)** — generates multi-density UI images (Android `res-*` densities + iPhone `@1x`/`@2x`/`@3x` scales) from sources in `./purgetss/images/`. See [`images` Command](#images-command) and the deep-dive [multi-density-images.md](./multi-density-images.md).
 > - **New `semantic` command (v7.6.0)** — generates Titanium semantic colors (Light/Dark) into `app/assets/semantic.colors.json` with two modes (tonal palette vs. single purpose-based color). See [`semantic` Command](#semantic-command) and the deep-dive [semantic-colors.md](./semantic-colors.md).
@@ -68,12 +79,32 @@ 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 padding. Range 2-8%.
+      androidLegacy: '10%',  // legacy ic_launcher.png padding %
+      androidAdaptive: '19%' // adaptive icon safe-zone %. Spec floor 19.44%.
+    },
+    android: {
+      splash: false,         // also generate splash_icon.png × 5
+      notification: false    // also generate ic_stat_notify.png × 5
+    },
+    ios: {
+      dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+      tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+      darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111111' for an opaque dark bg
+    },
+    colors: {
+      background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+    },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -164,7 +195,7 @@ Recommended VSCode extensions:
 
 ## `brand` Command
 
-Introduced in v7.6.0. Generates the complete Titanium branding set (launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, optional notification/splash icons) from a single logo image. Alloy and Classic projects are auto-detected.
+Introduced in v7.6.0, restructured in v7.7.0. Generates the complete Titanium branding set (launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, optional notification/splash icons) from a single logo image — with optional Android-specific logo overrides when you need them. Alloy and Classic projects are auto-detected.
 
 > **Tip**
 > This is a quick reference. See [app-branding.md](./app-branding.md) for the complete guide — workflow, padding guidance, Android dark mode, iOS 18+ variants, alpha channel handling, and troubleshooting.
@@ -176,25 +207,56 @@ purgetss brand path/to/logo.svg             # positional logo path override
 
 ### Flags
 
+**Project & output**
+
 | Flag | Purpose |
 | --- | --- |
 | `--project <path>` | Project root (defaults to cwd). |
 | `--dry-run` | Preview what would be generated without writing any files. |
 | `--output <dir>` | Stage into `<dir>` instead of writing in place. |
 | `-y, --yes` | Skip the overwrite confirmation prompt for this invocation. |
+
+**Visual customization**
+
+| Flag | Purpose |
+| --- | --- |
 | `--bg-color <hex>` | Background color for Android adaptive + iOS/marketplace flatten. |
-| `--padding <n>` | Android safe-zone percentage (range `12-20`, default `15`). |
-| `--ios-padding <n>` | iOS aesthetic padding percentage (range `2-8`, default `4`). |
+| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. |
+| `--android-adaptive-padding <n>` | Adaptive icon safe-zone % (default `19`). |
+| `--android-legacy-padding <n>` | Legacy `ic_launcher.png` padding % (default `10`). |
+| `--ios-padding <n>` | iOS aesthetic padding % (range `2-8`, default `4`). |
+
+**Optional asset types**
+
+| Flag | Purpose |
+| --- | --- |
 | `--notification` | Also emit `ic_stat_notify.png × 5`. |
 | `--splash` | Also emit `splash_icon.png × 5`. |
+
+**Logo variants & overrides**
+
+| Flag | Purpose |
+| --- | --- |
+| `--icon-logo <path>` | Override `purgetss/brand/logo-icon.{svg,png}` for Android launcher icons (square mark for non-square main logos). |
 | `--monochrome-logo <path>` | Override `purgetss/brand/logo-mono.{svg,png}`. |
 | `--dark-logo <path>` | Override `purgetss/brand/logo-dark.{svg,png}`. |
 | `--dark-bg-color <hex>` | Opaque dark bg for `DefaultIcon-Dark.png` (default: transparent per Apple HIG). |
+| `--splash-logo <path>` | Override `purgetss/brand/logo-splash.{svg,png}` for Android 12+ splash artwork. |
 | `--tinted-logo <path>` | Override `purgetss/brand/logo-tinted.{svg,png}`. |
 | `--no-dark` | Skip `DefaultIcon-Dark.png`. |
 | `--no-tinted` | Skip `DefaultIcon-Tinted.png`. |
-| `--cleanup-legacy` | Remove obsolete branding artifacts (reads `tiapp.xml` for safety rules). |
+
+**Legacy cleanup**
+
+| Flag | Purpose |
+| --- | --- |
+| `--cleanup-legacy` | Remove obsolete branding artifacts (reads `tiapp.xml` for safety rules). Keeps `default.png` on purpose. |
 | `--aggressive` | With `--cleanup-legacy`, also remove `ldpi` density folders. |
+
+**Diagnostics**
+
+| Flag | Purpose |
+| --- | --- |
 | `--notes` | Print full `tiapp.xml` snippets + padding tuning guide. |
 | `--debug` | Print extra diagnostics. |
 
@@ -202,22 +264,44 @@ purgetss brand path/to/logo.svg             # positional logo path override
 
 - `[logo-path]` (optional) — overrides auto-discovery of `purgetss/brand/logo.{svg,png}`.
 
-### Config block
+### Config block (v7.7.0 grouped structure)
 
 Defaults live under `brand:` in `purgetss/config.cjs` and are injected automatically:
 
 ```javascript
 brand: {
-  splash: false,           // also generate splash_icon.png × 5
-  padding: '15%',          // Android safe-zone. Range 12-20%.
-  iosPadding: '4%',        // iOS aesthetic padding. Range 2-8%.
-  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 padding. Range 2-8%.
+    androidLegacy: '10%',  // legacy ic_launcher.png padding %
+    androidAdaptive: '19%' // adaptive icon safe-zone %. Spec floor 19.44%.
+  },
+  android: {
+    splash: false,         // also generate splash_icon.png × 5
+    notification: false    // also generate ic_stat_notify.png × 5
+  },
+  ios: {
+    dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+    tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+    darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111' for an opaque dark bg
+  },
+  colors: {
+    background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+  },
   confirmOverwrites: true  // prompt before overwriting files
 }
 ```
 
+The recommended workflow is convention-first: drop files in `purgetss/brand/`, let auto-discovery pick them up. Treat `brand.logos.*` as optional overrides for one-off paths or when masters live outside `purgetss/brand/`.
+
 ### Confirmation prompt
 
 `brand` writes in place, so it asks `Continue? [y/N/a]` before overwriting anything. Choose `a` (always) to write `confirmOverwrites: false` into `config.cjs` and silence the prompt on future runs. The prompt is skipped automatically when `stdin` is not a TTY (`alloy.jmk` hook, CI, pipes), when `-y`/`--yes` is passed, or when `PURGETSS_YES=1` is set.
@@ -225,14 +309,24 @@ brand: {
 ### Examples
 
 ```bash
-purgetss brand                                         # uses purgetss/brand/logo.svg + config
-purgetss brand --bg-color "#0B1326"                    # override bg color
-purgetss brand --notification --splash                 # add notification + splash
-purgetss brand --no-tinted                             # skip iOS 18+ tinted variant
-purgetss brand --dry-run                               # preview without writing
-purgetss brand --cleanup-legacy --dry-run              # preview legacy cleanup
+purgetss brand                                          # uses purgetss/brand/logo.svg + config
+purgetss brand --bg-color "#0B1326"                     # override bg color
+purgetss brand --icon-logo ./docs/app-icon.svg          # dedicated square Android launcher mark
+purgetss brand --splash --splash-logo ./docs/splash.svg # custom Android 12+ splash artwork
+purgetss brand --notification --splash                  # add notification + splash
+purgetss brand --no-tinted                              # skip iOS 18+ tinted variant
+purgetss brand --dry-run                                # preview without writing
+purgetss brand --cleanup-legacy --dry-run               # preview legacy cleanup
 ```
 
+### Android output groups
+
+`brand` writes three Android-facing asset groups, each with a different job:
+
+- `ic_launcher*` for the app icon and the default Android 12+ system splash path
+- `splash_icon.png` when you pass `--splash` and want custom Android 12+ splash artwork
+- `default.png` as the older Titanium Android splash fallback (regenerated since v7.7.0)
+
 ## `images` Command
 
 Introduced in v7.6.0. Generates multi-density variants of your UI images (buttons, illustrations, logos, screen graphics) from a single high-resolution source per image. Alloy and Classic projects are auto-detected.
@@ -254,6 +348,7 @@ purgetss images background/                           # re-process one subfolder
 | `--ios` | Only emit iPhone scale variants. Mutually exclusive with `--android`. |
 | `--format <ext>` | Convert all outputs to `webp`, `jpeg`, `png`, `avif`, `gif`, or `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0-100` for lossy formats. Default `85`. |
+| `--width <n>` | (v7.8.0) Pin Android `mdpi` (= iPhone `@1x`) to `<n>` pixels wide. Larger scales derive as ×1.5, ×2, ×3, ×4 from that base; height stays proportional to the source's aspect ratio. Integer in `[1, 8192]`. |
 | `--dry-run` | Preview without writing any files. |
 | `--project <path>` | Project root (defaults to cwd). |
 | `-y, --yes` | Skip the overwrite confirmation prompt. |
@@ -263,6 +358,12 @@ purgetss images background/                           # re-process one subfolder
 
 - `[source]` (optional) — path to override auto-discovery. Resolves first against `purgetss/images/` (short paths like `buttons/btn.png`), then against cwd.
 
+### When to use `--width`
+
+Use `--width <n>` for SVG sources from vector editors with disproportionate viewBoxes — common in Affinity, Illustrator, and other design tools where the viewBox does not match the intended display size. Without the flag, every scale derives from the source's natural pixel size as a 4× master, which can produce unexpected output sizes.
+
+When you pass an SVG without `--width`, the command prints a one-time hint and falls back to the legacy 4× behavior. This is CLI-only; there is no matching `images:` config property because the right width is per-asset.
+
 ### Config block
 
 Defaults live under `images:` in `purgetss/config.cjs`:
@@ -285,6 +386,7 @@ purgetss images background/pink-texture.png            # re-process one file (sh
 purgetss images background/                            # re-process one subfolder
 purgetss images --android                              # only Android densities
 purgetss images --format webp --quality 90             # convert all outputs to WebP
+purgetss images logo.svg --width 256                   # pin SVG output to 256 px @1x/mdpi
 purgetss images --dry-run                              # preview
 ```
 
@@ -322,6 +424,29 @@ purgetss semantic --single '#000000' overlayColor     --alpha 50
 
 When `--dark` is omitted, it defaults to the light hex — useful for overlays/glass surfaces where alpha is the only variation.
 
+### Customizing the class name
+
+The auto-mapping uses the most literal Titanium-style transform: strip `Color`, then kebab-case the rest (e.g. `surfaceColor` → `surface`, `textSecondaryColor` → `text-secondary`). If your design system prefers different names — for example `on-surface` instead of `text`, or nesting the surface family under `DEFAULT` / `high` — edit `config.cjs` after running the `--single` batch:
+
+`./purgetss/config.cjs`
+```javascript
+theme: {
+  extend: {
+    colors: {
+      surface: { DEFAULT: 'surfaceColor', high: 'surfaceHighColor' },
+      'on-surface': 'textColor',
+      'on-surface-variant': 'textSecondaryColor',
+      muted: 'textMutedColor',
+      border: 'borderColor',
+      accent: 'accentColor',
+      overlay: 'overlayColor'
+    }
+  }
+}
+```
+
+The next `purgetss build` picks up the renamed classes. Editing one generated mapping is faster than typing the whole structure from scratch. See [semantic-colors.md](./semantic-colors.md) for the full nested-vs-flat discussion (including the `[object Object]` pitfall when nesting without `DEFAULT`).
+
 ### Smart in-place updates
 
 If a `--single` name matches an existing palette shade — e.g. `purgetss semantic --single '#000' amazon500` while palette `amazon` exists — PurgeTSS narrows the operation to an in-place JSON value edit. The entry stays in its original position, and `config.cjs` is left untouched (the palette already maps to that key).
@@ -392,10 +517,10 @@ After copying the fonts, you can use them in Buttons and Labels. For example, fo
 
 ### Available Font Classes
 
-- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/fontawesome.tss)
-- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialicons.tss)
-- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialsymbols.tss)
-- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/framework7icons.tss)
+- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
+- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
+- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
+- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
 
 ### Copying Specific Font Vendors