@maccesar/titools 2.8.0 → 2.10.0

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

@@ -1,12 +1,17 @@
 # PurgeTSS CLI Commands
 
-> **Info: What's new in v7.2.x**
-> - Node.js 20+ required (due to the "inquirer" v13 upgrade).
-> - Font Awesome 7 support, including the CSS custom properties format.
-> - Titanium SDK 13.1.x support, with new properties from 13.1.0.GA.
-> - **Removed deprecated commands:** `copy-fonts` and `build-legacy` are no longer available.
-> - Install size reduced by ~45MB (non-essential assets moved to dev dependencies).
-> - Improved Unicode extraction for more formats and direct character mappings.
+> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0**
+> - **`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).
+> - **`brand:` and `images:` config sections** auto-injected into `purgetss/config.cjs` on first run. Percentages may be written as quoted strings like `'15%'` or as plain numbers.
+> - **Default font family classes (v7.5.3)** — `font-sans`, `font-serif`, and `font-mono` generated automatically with platform-appropriate values.
+> - **XML validation (v7.5.3)** — detects illegal `--` sequences inside XML comments during pre-validation.
 
 This page lists the commands available in PurgeTSS.
 
@@ -14,6 +19,8 @@ This page lists the commands available in PurgeTSS.
 
 - `init`: Initializes PurgeTSS on an existing Alloy project.
 - `create`: Creates a new Alloy project with PurgeTSS already set up.
+- `brand`: Generates the Titanium branding set from a single logo. See [`brand` Command](#brand-command).
+- `images`: Generates multi-density UI images from sources in `./purgetss/images/`. See [`images` Command](#images-command).
 
 ## Development Commands
 
@@ -28,6 +35,7 @@ This page lists the commands available in PurgeTSS.
 ## Utility Commands
 
 - `shades`: Generates shades and tints for a color and writes the palette to `config.cjs`.
+- `semantic`: Generates Titanium semantic colors (Light/Dark) into `app/assets/semantic.colors.json`. See [`semantic` Command](#semantic-command).
 - `color-module`: Creates `./app/lib/purgetss.colors.js` with the colors defined in `config.cjs`.
 - `module`: Installs `purgetss.ui.js` in the `lib` folder.
 
@@ -64,14 +72,51 @@ module.exports = {
       plugins: [] // Array of properties to ignore
     }
   },
+  brand: {
+    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
+    },
+    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: {
+    quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+    format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
   theme: {
     extend: {}
   }
 };
 ```
 
+`init` also creates empty `purgetss/fonts/`, `purgetss/brand/`, and `purgetss/images/` folders so you can see where each kind of asset goes.
+
 > **Tip**
-> PurgeTSS looks for `./purgetss/config.cjs`. Each section is optional and can be customized. Missing sections use the default configuration.
+> PurgeTSS looks for `./purgetss/config.cjs`. Each section is optional and can be customized. Missing sections use the default configuration. The `brand:` and `images:` sections are auto-injected into older configs on first run in v7.6.0+.
 
 ## `create` Command
 
@@ -143,6 +188,249 @@ Recommended VSCode extensions:
 
 `purgetss create "Name of the Project" [--dependencies --vendor=fa,mi,ms,f7]` runs: `ti config` (reads idprefix/workspace), `ti create -t app -p all -n "Name"`, `alloy new`, `purgetss w`, `purgetss b`, optional `--vendor` (copies fonts + CommonJS module), optional `--dependencies` (installs Tailwind CSS, ESLint with Titanium plugins, and config files), then opens the project in VS Code, Sublime Text, or Finder.
 
+## `brand` Command
+
+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.
+
+```bash
+purgetss brand                              # uses purgetss/brand/logo.{svg,png} + config
+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>` | 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`. |
+
+**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. |
+
+### Positional argument
+
+- `[logo-path]` (optional) — overrides auto-discovery of `purgetss/brand/logo.{svg,png}`.
+
+### Config block (v7.7.0 grouped structure)
+
+Defaults live under `brand:` in `purgetss/config.cjs` and are injected automatically:
+
+```javascript
+brand: {
+  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
+  },
+  colors: {
+    background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+  },
+  // Optional iOS overrides:
+  // ios: {
+  //   dark: false,           // skip DefaultIcon-Dark.png
+  //   tinted: false,         // skip DefaultIcon-Tinted.png
+  //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png
+  // },
+  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.
+
+### Examples
+
+```bash
+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.
+
+> **Tip**
+> This is a quick reference. See [multi-density-images.md](./multi-density-images.md) for the complete guide — 4× source convention, re-processing single files, format conversion, subdirectory preservation, and troubleshooting.
+
+```bash
+purgetss images                                       # uses purgetss/images/ + config
+purgetss images background/pink-texture.png           # re-process one file (short path)
+purgetss images background/                           # re-process one subfolder
+```
+
+### Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--android` | Only emit Android density variants. Mutually exclusive with `--ios`. |
+| `--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`. |
+| `--dry-run` | Preview without writing any files. |
+| `--project <path>` | Project root (defaults to cwd). |
+| `-y, --yes` | Skip the overwrite confirmation prompt. |
+| `--debug` | Print extra diagnostics. |
+
+### Positional argument
+
+- `[source]` (optional) — path to override auto-discovery. Resolves first against `purgetss/images/` (short paths like `buttons/btn.png`), then against cwd.
+
+### Config block
+
+Defaults live under `images:` in `purgetss/config.cjs`:
+
+```javascript
+images: {
+  quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+  format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' | 'avif' | 'gif' | 'tiff'
+  confirmOverwrites: true  // prompt before overwriting files
+}
+```
+
+Like `brand`, `images` writes in place and asks `Continue? [y/N/a]` before overwriting. Selecting `a` flips `confirmOverwrites: false` in `config.cjs`. Skipped automatically when `stdin` is not a TTY, when `-y`/`--yes` is passed, or when `PURGETSS_YES=1` is set.
+
+### Examples
+
+```bash
+purgetss images                                        # uses purgetss/images/ + config
+purgetss images background/pink-texture.png            # re-process one file (short path)
+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 --dry-run                              # preview
+```
+
+## `semantic` Command
+
+Introduced in v7.6.0. Generates Titanium semantic colors (Light/Dark mode aware) into `app/assets/semantic.colors.json`. The command dispatches between two distinct modes based on whether `--single` is passed.
+
+> **Tip**
+> This is a quick reference. See [semantic-colors.md](./semantic-colors.md) for the complete guide — mirror inversion math, Titanium semantic color spec, class mapping conventions, and strategies for purpose-based design systems.
+
+### Palette mode (no `--single`)
+
+One base hex, 11-shade tonal palette with mirror-by-index Light/Dark inversion anchored at shade `500`. Writes both files in one step: the JSON gets 11 entries, and `config.cjs` gets the family mapped to those semantic keys.
+
+```bash
+purgetss semantic <hex> <name>
+purgetss semantic '#15803d' amazon
+```
+
+Usage produces classes like `bg-amazon-50`, `text-amazon-500`, `border-amazon-950` that flip tonal contrast automatically with the system appearance.
+
+### Single mode (`--single`)
+
+Explicit per-mode hex values for purpose-based semantic colors (`surfaceColor`, `textColor`, `borderColor`, `overlayColor`, etc.). Writes the JSON entry AND auto-maps it to a class in `config.cjs` by stripping the conventional `Color` suffix (e.g. `surfaceColor` → class `surface`).
+
+```bash
+purgetss semantic --single <hex> <name> [--dark <hex>] [--alpha <0-100>]
+
+# Examples:
+purgetss semantic --single '#F9FAFB' surfaceColor     --dark '#0f172a'
+purgetss semantic --single '#111827' textColor        --dark '#f1f5f9'
+purgetss semantic --single '#3B82F6' accentColor      --dark '#60a5fa' --alpha 80
+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.
+
+### 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).
+
+Re-running on the same palette family fully replaces it: PurgeTSS strips prior keys belonging to that family (bare name + 11 shade keys) before writing the new entries. Unrelated palettes and manually-defined entries survive.
+
+### Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `-s, --single` | Generate a single purpose-based semantic color (requires explicit per-mode hex). |
+| `-d, --dark <hex>` | With `--single`, the dark-mode hex (defaults to the light value). |
+| `-a, --alpha <0-100>` | With `--single`, wraps both modes in `{ color, alpha }` per the Titanium spec. |
+| `-n, --name <name>` | Specify the name (alternative to the positional argument). |
+| `-r, --random` | Palette mode — use a random base color. |
+| `-o, --override` | Place the mapping in `theme.colors` instead of `theme.extend.colors`. |
+| `-q, --quotes` | Keep double quotes in `config.cjs`. |
+| `-l, --log` | Preview the JSON without writing any files. |
+
 ## `install-dependencies` Command
 
 This command installs dev dependencies and configuration files in existing PurgeTSS projects, and sets up Visual Studio Code support.
@@ -795,3 +1083,16 @@ purgetss sudo-update
 # alias:
 purgetss su
 ```
+
+## Community-Discovered Patterns
+
+### v7.2.x environment notes
+
+These items were surfaced in community threads during the v7.2.x rollout and remain relevant operational context for anyone upgrading from pre-v7.2 installs:
+
+- Node.js 20+ required (due to the `inquirer` v13 upgrade).
+- Font Awesome 7 support, including the CSS custom properties format.
+- Titanium SDK 13.1.x support, with new properties from 13.1.0.GA.
+- Removed deprecated commands: `copy-fonts` and `build-legacy` are no longer available — scripts referencing either will fail.
+- Install size reduced by ~45MB (non-essential assets moved to dev dependencies).
+- Improved Unicode extraction for more formats and direct character mappings in `build-fonts`.

package/skills/purgetss/references/configurable-properties.md

@@ -65,9 +65,6 @@ You can customize any of the following properties individually by adding them in
 - `trackTintColor`
 - `viewShadowColor`
 
-> **ℹ️ `backgroundGradient`**
-> For custom gradient rules, `backgroundGradient.colors` can use arrays of `{ color, offset }` objects. PurgeTSS v7.4.0 fixed serialization for those nested object arrays in `utilities.tss`.
-
 ## Configurable Properties
 
 - `activeTab`
@@ -152,12 +149,19 @@ You can customize any of the following properties individually by adding them in
 - `zIndex`
 - `zoomScale`
 
+## Custom Rules and Ti Elements
+
+Create your own custom rules and include Ti Elements with any number of attributes or conditional statements. See [Custom Rules](./custom-rules.md) for rule syntax and examples.
+
+## Community-Discovered Patterns
+
+The following notes come from community experience applying PurgeTSS configurable properties against Titanium's native layout constraints. They are not part of the official reference but prevent common mistakes.
+
+> **ℹ️ `backgroundGradient`**
+> For custom gradient rules, `backgroundGradient.colors` can use arrays of `{ color, offset }` objects. PurgeTSS v7.4.0 fixed serialization for those nested object arrays in `utilities.tss`.
+
 > **WARNING: Titanium Padding Constraint**
 > Titanium does not support native `padding` on `View`, `Window`, `ScrollView`, or `TableView`. Even if `padding*` is configurable, use margins on children for those elements.
 
 > **WARNING: Width Fill Constraint**
 > For full-width Titanium layouts, prefer `w-screen` (`Ti.UI.FILL`) instead of `w-full` (`100%`).
-
-## Custom Rules and Ti Elements
-
-Create your own custom rules and include Ti Elements with any number of attributes or conditional statements. See [Custom Rules](./custom-rules.md) for rule syntax and examples.

package/skills/purgetss/references/custom-rules.md

@@ -31,9 +31,6 @@ Whether you want to style a Ti Element (also known as a markup element), a custo
   - `em` or `rem` values are converted with this formula: `value * 16`.
   - `dp` removes the unit and keeps the value as-is.
 
-> **Platform-Specific Constants**
-> If a rule uses `Ti.UI.iOS.*` or `Ti.UI.Android.*` constants, keep that property inside the matching `ios` or `android` block to avoid cross-platform compilation failures.
-
 ## `config.cjs` File Example
 
 `./purgetss/config.cjs`
@@ -102,3 +99,10 @@ module.exports = {
 '.gallery[formFactor=handheld]': { width: '250px' }
 '.gallery[formFactor=tablet]': { width: '500px' }
 ```
+
+## Community-Discovered Patterns
+
+The following guidance comes from community experience using PurgeTSS custom rules in real projects. It is not part of the official reference but addresses common pitfalls.
+
+> **Platform-Specific Constants**
+> If a rule uses `Ti.UI.iOS.*` or `Ti.UI.Android.*` constants, keep that property inside the matching `ios` or `android` block to avoid cross-platform compilation failures.

package/skills/purgetss/references/customization-deep-dive.md

@@ -18,7 +18,7 @@ If you want a clean `config.cjs`, delete the existing one and run:
 purgetss init
 ```
 
-This creates a minimal `./purgetss/config.cjs` file:
+This creates a `./purgetss/config.cjs` file with the default sections:
 
 ```javascript
 module.exports = {
@@ -34,17 +34,56 @@ module.exports = {
       plugins: [] // Array of properties to ignore
     }
   },
+  brand: {
+    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
+    },
+    colors: {
+      background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+    },
+    // Optional iOS overrides:
+    // ios: {
+    //   dark: false,           // skip DefaultIcon-Dark.png
+    //   tinted: false,         // skip DefaultIcon-Tinted.png
+    //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
+    // },
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
+  images: {
+    quality: 85,             // JPEG/WebP/AVIF quality (0-100)
+    format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
+    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+  },
   theme: {
     extend: {}
   }
 };
 ```
 
+`init` also creates empty `purgetss/fonts/`, `purgetss/brand/`, and `purgetss/images/` folders on first run, so you can see where each kind of asset goes.
+
 Every section is optional. Only add what you want to change. Anything missing falls back to the defaults.
 
 ## Structure
 
-The config file has two main sections: `purge` and `theme`.
+The config file has four main sections: `purge`, `brand`, `images`, and `theme`.
+
+`brand:` and `images:` configure the matching CLI commands — see [CLI Commands: `brand`](./cli-commands.md#brand-command) and [CLI Commands: `images`](./cli-commands.md#images-command) for the full option lists. The rest of this page covers `purge` and `theme`.
 
 ### `purge` Section
 
@@ -177,6 +216,31 @@ module.exports = {
 };
 ```
 
+### Default `font-sans`, `font-serif`, `font-mono`
+
+PurgeTSS generates three `fontFamily` classes by default, even when `theme.fontFamily` is not set in `config.cjs`. iOS and Android get different values on purpose so each platform picks its native system font:
+
+| Class        | iOS              | Android      |
+| ------------ | ---------------- | ------------ |
+| `font-sans`  | `Helvetica Neue` | `sans-serif` |
+| `font-serif` | `Georgia`        | `serif`      |
+| `font-mono`  | `monospace`      | `monospace`  |
+
+If you define a value for `sans`, `serif`, or `mono` in `theme.fontFamily` (or `theme.extend.fontFamily`), your value replaces the default on both platforms — no per-platform fork needed:
+
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: 'Inter-Regular' // replaces Helvetica Neue / sans-serif on both platforms
+      }
+    }
+  }
+};
+```
+
 ## Overriding and Extending Properties
 
 By default, your project inherits values from the default theme. You have two options depending on your goal.
@@ -462,8 +526,13 @@ module.exports = {
 
 This generates classes like `p-72`, `m-84`, and `h-96` in addition to all of the default spacing and sizing utilities.
 
-> **WARNING: Titanium Layout Constraint**
-> Titanium does not support native `padding` on `View`, `Window`, `ScrollView`, or `TableView`. Even if PurgeTSS can generate spacing-related utilities, prefer margins on children for those elements.
+## Community-Discovered Patterns
+
+### Titanium Layout Constraint: `padding` on View / Window / ScrollView / TableView
+
+Titanium does not support native `padding` on `View`, `Window`, `ScrollView`, or `TableView`. Even if PurgeTSS generates spacing-related utilities (`p-*`, `px-*`, `py-*`), applying them to those elements is silently ignored at runtime. Prefer margins on the children of those containers instead — `m-*`, `mt-*`, `mb-*`, etc. — which Titanium honors correctly.
+
+This is a Titanium platform constraint, not a PurgeTSS bug. `Button`, `Label`, and `TextField` do accept `padding` natively.
 
 ## List of Customizable Properties
 

package/skills/purgetss/references/dynamic-component-creation.md

@@ -1,5 +1,15 @@
 # Dynamic Component Creation with PurgeTSS
 
+> **SCOPE NOTE**
+>
+> This reference covers dynamic component creation using **Alloy's `$.UI.create()` helper** and **`Alloy.createStyle()` + `applyProperties()`**, both combined with PurgeTSS utility classes. It is an Alloy + PurgeTSS integration guide, **not** documentation for the `purgetss.ui` native module (see [animation-system.md](./animation-system.md) and [animation-advanced.md](./animation-advanced.md) for that module).
+>
+> For general Alloy controller and view patterns, refer to the `alloy-guides` and `alloy-howtos` skills.
+
+## Community-Discovered Patterns
+
+The guidance in this file reflects patterns that PurgeTSS users have converged on when building components imperatively from Alloy controllers. It complements — but is not a substitute for — official Alloy documentation.
+
 ## Overview
 
 When creating components dynamically in Controllers (not declaratively in XML), PurgeTSS provides two methods to apply utility classes:
@@ -7,8 +17,9 @@ When creating components dynamically in Controllers (not declaratively in XML),
 1. **`$.UI.create()`** - Create components with PurgeTSS classes (Recommended)
 2. **`Alloy.createStyle()` + `applyProperties()`** - Apply PurgeTSS styles to existing components
 
-> **💡 BEST PRACTICE**
-> **Always prefer `$.UI.create()` for dynamic components** - it's cleaner, more readable, and PurgeTSS will process the classes automatically during build.
+> **BEST PRACTICE**
+>
+> Always prefer `$.UI.create()` for dynamic components — it's cleaner, more readable, and PurgeTSS will process the classes automatically during build.
 
 ---
 
@@ -333,24 +344,25 @@ function createIconGrid(items) {
 
 ### PurgeTSS Processes Classes During Build
 
-> **️ℹ️ HOW IT WORKS**
+> **NOTE — HOW IT WORKS**
+>
 > When you use `$.UI.create()` or `Alloy.createStyle()` with classes:
 >
 > 1. PurgeTSS scans your controllers for these class references
 > 2. It adds the classes to the generated `app.tss`
 > 3. At runtime, Alloy applies the styles to your components
 >
-> This means you get **full PurgeTSS power** even with dynamic components!
+> This means you get the full PurgeTSS utility surface even with dynamic components.
 
 ### Class Verification
 
-Just like with XML views, **always verify classes exist** before using them:
+Just like with XML views, always verify classes exist before using them:
 
 ```javascript
-// ✅ CORRECT - Verified classes
+// CORRECT - Verified classes
 classes: ['w-screen', 'h-auto', 'bg-white', 'rounded-lg']
 
-// ❌ WRONG - These classes don't exist
+// WRONG - These classes don't exist
 classes: ['flex-row', 'justify-center', 'p-4']  // No flexbox, no p-* on View
 ```
 
@@ -425,7 +437,8 @@ function setState(state) {
 }
 ```
 
-> **💡 When to Use `classes` vs `applyProperties`**
+> **NOTE — When to use `classes` vs `applyProperties`**
+>
 > - Use `classes` when you want to swap entire style sets (e.g., active/inactive states)
 > - Use `applyProperties` with direct values when changing individual properties (e.g., text, enabled)
 > - Combine both for complex state changes
@@ -434,7 +447,7 @@ function setState(state) {
 
 ## Anti-Patterns to Avoid
 
-### ❌ Don't Use `Ti.UI.create()` with Manual Styles
+### Don't use `Ti.UI.create()` with Manual Styles
 
 ```javascript
 // WRONG - Manual styling, no PurgeTSS benefits
@@ -446,7 +459,7 @@ const view = Ti.UI.createView({
 })
 ```
 
-### ✅ Use `$.UI.create()` with PurgeTSS Classes
+### Use `$.UI.create()` with PurgeTSS classes
 
 ```javascript
 // CORRECT - Full PurgeTSS power
@@ -455,7 +468,7 @@ const view = $.UI.create('View', {
 })
 ```
 
-### ❌ Don't Mix Styles and Classes
+### Don't mix inline styles and classes
 
 ```javascript
 // CONFUSING - Mix of styles and classes
@@ -465,7 +478,7 @@ const view = $.UI.create('View', {
 })
 ```
 
-### ✅ Use Only Classes (or Only Styles)
+### Use only classes (or only styles)
 
 ```javascript
 // CORRECT - Pure PurgeTSS
@@ -494,8 +507,10 @@ view.applyProperties(Alloy.createStyle('index', {
 | **`Alloy.createStyle()`** | Styling existing components | `Alloy.createStyle('view', { classes: 'bg-white' })` |
 | **`applyProperties()`**   | Apply style to component    | `component.applyProperties(style)`                   |
 
-> **💡 REMEMBER**
-> Both methods give you **full access to PurgeTSS utilities**:
+> **NOTE — REMEMBER**
+>
+> Both methods give you full access to PurgeTSS utilities:
+>
 > - All color classes (`bg-*`, `text-*`, `border-*`)
 > - All spacing classes (`m-*`, `gap-*`, and `p-*` where the Titanium component supports padding)
 > - All layout classes (`horizontal`, `vertical`)