@maccesar/titools 2.7.2 → 2.9.0

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

@@ -203,6 +203,81 @@ theme: {
 '.btn[if=Alloy.Globals.iPhoneX]': { bottom: 48 }
 ```
 
+## Customizing Window, View, and ImageView
+
+`Window`, `View`, and `ImageView` have built-in defaults (white Window background, `Ti.UI.SIZE` on View, `hires: true` on ImageView for iOS). To change those defaults globally, put the customization under `theme.extend` — the same place you would extend `colors` or `spacing`:
+
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      Window: {
+        apply: 'exit-on-close-false bg-blue-500'
+      }
+    }
+  }
+};
+```
+
+Now every `<Window>` in the project picks up `backgroundColor: '#3b82f6'` and `exitOnClose: false`.
+
+The same pattern works for `View` and `ImageView`. For example, to make all `ImageView` elements use `hires: true` on iOS (which PurgeTSS already does by default on iOS), or to set a different default for `View`:
+
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      ImageView: {
+        ios: {
+          apply: 'hires-true'
+        }
+      },
+      View: {
+        apply: 'wh-auto'
+      }
+    }
+  }
+};
+```
+
+### Shorthand: no `default:` wrapper needed
+
+The examples above use `{ apply: '...' }` directly. Internally that gets normalized to `{ default: { apply: '...' } }`, so both forms produce the same TSS:
+
+```javascript
+// Both of these work
+Window: { apply: 'exit-on-close-false bg-blue-500' }
+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.
+
+### 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:
+
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      Window: { apply: 'bg-blue-500' }
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+/* Before dedup: { backgroundColor: '#FFFFFF', backgroundColor: '#3b82f6' } */
+/* After dedup:                                                           */
+'Window': { backgroundColor: '#3b82f6' }
+```
+
+Without the dedup, both `backgroundColor` entries would land in the file; the last one would win at runtime anyway, but reading the TSS with two copies of the same property is confusing. The builder keeps only the applied value.
+
 ## Platform-Specific Classes
 
 Several classes in `utilities.tss` are platform-specific (e.g., `clip-enabled`, `status-bar-style-light-content`). These only exist with a `[platform=ios]` or `[platform=android]` suffix.
@@ -276,16 +351,21 @@ module.exports = {
 '.my-view': { backgroundColor: '#22c55e', width: 128, height: 128 }
 ```
 
-> **Titanium Fill Rule**
-> When composing layout utilities inside `apply`, prefer `w-screen` for fill behavior. `w-full` maps to `100%`, not `Ti.UI.FILL`.
-
 ## Community-Discovered Patterns
 
+### Titanium Fill Rule
+
+When composing layout utilities inside `apply`, prefer `w-screen` for fill behavior. `w-full` maps to `100%`, not `Ti.UI.FILL`. In Titanium, `Ti.UI.FILL` is the layout primitive that makes a view fill its parent; a literal `100%` can behave unexpectedly inside nested containers.
+
+### Platform-Specific Constants in `apply`
+
+Constants like `Ti.UI.iOS.CLIP_MODE_ENABLED` or `Ti.UI.iOS.StatusBar.LIGHT_CONTENT` only exist on the platform that defines them. PurgeTSS utility classes such as `clip-enabled` or `status-bar-style-light-content` therefore only exist with a `[platform=ios]` or `[platform=android]` suffix in `utilities.tss`. When you reference them from `apply`, put them inside the correct platform block (`ios:` / `android:`) so PurgeTSS resolves them — otherwise the class silently drops on the wrong platform and can throw a runtime error if it reaches it. See the "Platform-Specific Classes" section above for the resolution rules.
+
 ### Global Window defaults for Large Titles + ScrollView (iOS)
 
-When using `largeTitleEnabled` with a ScrollView inside NavigationWindow or TabGroup, three Window properties must work together: `auto-adjust-scroll-view-insets`, `extend-edges-all`, and `large-title-enabled`. Without all three, the ScrollView content overlaps behind the navigation bar — or the large title renders with a visible delay.
+**See the dedicated reference: [`ios-large-titles.md`](./ios-large-titles.md)** — it covers the full pattern (three-property pairing, global-defaults recipe, TabGroup implicit NavigationWindow behavior, detail-window opt-out, and the ScrollView `content-w-screen` / `content-h-auto` pairing).
 
-Instead of repeating these classes on every Window XML, use `apply` in `config.cjs` to set the base properties as global defaults:
+Minimal recap — when Large Titles are in use, set the base iOS Window defaults once via `apply` in `config.cjs` rather than repeating them in every XML view:
 
 `./purgetss/config.cjs`
 ```javascript
@@ -293,35 +373,11 @@ module.exports = {
   theme: {
     Window: {
       ios: {
-        apply: 'auto-adjust-scroll-view-insets extend-edges-all status-bar-style-light-content'
+        apply: 'auto-adjust-scroll-view-insets extend-edges-all large-title-enabled'
       }
     }
   }
 };
 ```
 
-`./purgetss/styles/utilities.tss`
-```tss
-'Window[platform=ios]': { autoAdjustScrollViewInsets: true, extendEdges: [ Ti.UI.EXTEND_EDGE_ALL ], statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT }
-```
-
-Then in each view XML, only add `largeTitleEnabled` and `largeTitleDisplayMode` as needed:
-
-```xml
-<Window title="Home" class="large-title-enabled">
-  <ScrollView class="vertical w-screen" contentHeight="Ti.UI.SIZE">
-    <!-- Content starts below the nav bar automatically -->
-  </ScrollView>
-</Window>
-```
-
-This works for both NavigationWindow and TabGroup — on iOS, TabGroup wraps each Tab in an implicit NavigationWindow.
-
-| Class | Property | Value |
-|---|---|---|
-| `auto-adjust-scroll-view-insets` | `autoAdjustScrollViewInsets` | `true` |
-| `extend-edges-all` | `extendEdges` | `[ Ti.UI.EXTEND_EDGE_ALL ]` |
-| `large-title-enabled` | `largeTitleEnabled` | `true` |
-| `large-title-display-mode` | `largeTitleDisplayMode` | Uses `LARGE_TITLE_DISPLAY_MODE_*` constants |
-
-> **Why `ios:` block instead of inline `ios:` prefix?** The three classes (`auto-adjust-scroll-view-insets`, `extend-edges-all`, `status-bar-style-light-content`) are platform-specific — they only exist with `[platform=ios]` suffix in `utilities.tss`. Using the `ios:` block in `config.cjs` ensures PurgeTSS resolves them correctly. See "Platform-Specific Classes" above.
+The `ios:` block (not an inline `ios:` prefix) is required because these classes only exist with a `[platform=ios]` suffix — see "Platform-Specific Classes" above. The *why* (rendering delay vs content-behind-nav-bar), the display-mode constants, and per-window overrides live in [`ios-large-titles.md`](./ios-large-titles.md) and in the official PurgeTSS docs at [Best Practices → Large Titles on iOS](https://purgetss.com/docs/best-practices/3-large-titles-on-ios).

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

@@ -306,6 +306,10 @@ Try this example on an iPad or tablet.
 </Alloy>
 ```
 
+## Community-Discovered Patterns
+
+These constraints reflect community experience using arbitrary values against the realities of the Titanium layout engine. They are not part of the official reference but prevent common mistakes.
+
 > **Titanium Layout Constraint**
 > Prefer `w-screen` instead of `w-full` when you need fill behavior. `w-full` maps to `100%`, not `Ti.UI.FILL`.
 

package/skills/purgetss/references/class-categories.md

@@ -21,12 +21,13 @@ Complete inventory of all class prefixes organized by functional category. For n
 | `content-*` | ~20 | `content-h-*`, `content-w-*` |
 | `aspect-*` | 2 | `aspect-ratio-16-9`, `aspect-ratio-4-3` |
 
-**Important: `w-full` vs `w-screen`**
-- `w-full` → `width: '100%'` — 100% of parent container
-- `w-screen` → `width: Ti.UI.FILL` — Fills all available space in parent
-- `h-full` → `height: '100%'` — 100% of parent container
-- `h-screen` → `height: Ti.UI.FILL` — Fills all available space in parent
-- `wh-full` → Both `'100%'`
+> **Community-Discovered Pattern: `w-full` vs `w-screen`**
+>
+> - `w-full` → `width: '100%'` — 100% of parent container
+> - `w-screen` → `width: Ti.UI.FILL` — Fills all available space in parent
+> - `h-full` → `height: '100%'` — 100% of parent container
+> - `h-screen` → `height: Ti.UI.FILL` — Fills all available space in parent
+> - `wh-full` → Both `'100%'`
 
 ### Spacing (Margins & Padding)
 
@@ -108,7 +109,7 @@ Complete inventory of all class prefixes organized by functional category. For n
 | Prefix | Count | Examples |
 | --- | --- | --- |
 | `text-*` | 273 | Text colors, sizes, alignment |
-| `font-*` | 9 | `font-thin`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black` |
+| `font-*` | 12 | Weights: `font-thin`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`. Families (v7.5.3+): `font-sans`, `font-serif`, `font-mono` |
 | `line-h-multiple-*` | ~85 | Line height as multiple |
 | `line-spacing-*` | ~85 | Line spacing |
 | `line-break-mode-*` | 7 | `line-break-mode-attribute-by-word-wrapping`, etc. |
@@ -192,6 +193,8 @@ Complete inventory of all class prefixes organized by functional category. For n
 | `duration-*` | 22 | `duration-0`, `duration-50` to `duration-5000` |
 | `delay-*` | 22 | `delay-0`, `delay-50` to `delay-5000` |
 | `repeat-*` | ~31 | `repeat-*` variants |
+| `snap-*` (v7.4.0+) | 6 | `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false` — drop behaviors for draggable views |
+| `keep-z-index` (v7.4.0+) | 2 | `keep-z-index`, `keep-z-index-false` — preserves z-order during drag when using `transition` layouts |
 
 ### Shadows & Elevation
 

package/skills/purgetss/references/class-index.md

@@ -120,10 +120,11 @@ Some PurgeTSS classes combine multiple Titanium properties under a single class
 | `dragging-*`             | `draggingType`                                                 | Animation module dragging  |
 | `filter-attribute-*`     | `filterAttribute`                                              | ListView filtering         |
 | `flip-*`                 | `flip`                                                         | Animation flipping         |
-| `font-*`                 | `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`            | Typography                 |
+| `font-*`                 | `fontFamily`, `fontSize`, `fontStyle`, `fontWeight`            | Typography (v7.5.3+: `font-sans`, `font-serif`, `font-mono` family classes) |
 | `grid-*`                 | Various                                                        | Grid layout system         |
 | `h-*`                    | `height`                                                       | All components             |
 | `hint-*`                 | `hintTextColor`                                                | TextField placeholder      |
+| `keep-z-index`           | `animationProperties.keepZIndex` (v7.4.0+)                     | Preserves z-order during drag when used with `transition` |
 | `layout-*`               | `layout`                                                       | View layout modes          |
 | `minimum-font-size-*`    | `minimumFontSize`                                              | Label auto-shrink          |
 | `navigation-*`           | `navigationMode`                                               | Navigation modes           |
@@ -135,6 +136,7 @@ Some PurgeTSS classes combine multiple Titanium properties under a single class
 | `scroll-type-*`          | `scrollType`                                                   | Android scroll type        |
 | `shadow-*`               | `shadowOffset`, `shadowRadius`, `shadowColor`                  | Box shadows                |
 | `show-*scroll-indicator` | `showHorizontalScrollIndicator`, `showVerticalScrollIndicator` | ScrollView                 |
+| `snap-*`                 | `animationProperties.snap.{back, center, magnet}` (v7.4.0+)    | Draggable drop behaviors   |
 | `status-bar-style-*`     | `statusBarStyle`                                               | iOS status bar             |
 | `tint-*`                 | `tintColor`                                                    | View/Button tinting        |
 | `title-*`                | `titleAttributes: color/shadow`                                | iOS title styling          |
@@ -759,7 +761,11 @@ For the complete prefix inventory organized by category (Layout, Spacing, Colors
 
 ---
 
-## PROHIBITED: CSS Classes (DO NOT EXIST)
+## Community-Discovered Patterns
+
+The rest of this document collects conventions, prohibitions, and insights surfaced by PurgeTSS users in real Titanium projects. They reflect how the utility system is actually used, not just how it is defined.
+
+### PROHIBITED: CSS Classes (DO NOT EXIST)
 
 | CSS Class         | Issue                             | PurgeTSS Alternative                        |
 | ----------------- | --------------------------------- | ------------------------------------------- |
@@ -779,10 +785,26 @@ For the complete prefix inventory organized by category (Layout, Spacing, Colors
 | `leading-*`       | Uses different prefix             | Use `line-h-multiple-*` or `line-spacing-*` |
 | `tracking-*`      | Uses different prefix             | Use `letter-spacing-*`                      |
 
+### Key Insights from Real Data
+
+1. **21,236 unique classes** across **364 unique prefixes** - Far more than initially documented
+2. **Extensive state management** - Hundreds of `*enabled`, `*-false` classes for UI states
+3. **Platform-specific classes** - Many iOS/Android specific variants (like `[platform=ios]`)
+4. **Complete color coverage** - All 22 Tailwind v3 colors with 11 shades each (50-950) = 242 color variants per prefix
+5. **Boolean class pattern** - For properties like `editable`, `enabled`, `visible` → `class` and `class-false`
+6. **UI component state variants** - `selected-*`, `badge-*`, `title-*`, `disabled-*` with full color coverage
+7. **Keyboard toolbar styling** - Extensive `keyboard-toolbar-*` classes for custom keyboard accessories
+8. **Status bar & navigation** - `status-bar-*`, `tabs-*`, `nav-*` for system UI customization
+9. **Accessibility support** - `accessibility-*` classes for a11y properties
+10. **Animation system** - `duration-*`, `delay-*`, `rotate-*`, `scale-*` for PurgeTSS Animation component
+
 ---
 
 ## All 364 Unique Prefixes (Alphabetical)
 
+> **NOTE**: Recent additions — v7.4.0 introduced `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false`, `keep-z-index`, and `keep-z-index-false` for the Animation module drop/drag system. v7.5.3 introduced font-family classes `font-sans`, `font-serif`, `font-mono` alongside the existing weight classes.
+
+
 ```
 accessibility, accessory, accuracy, action, active, activity, alignment, all, allow, allows,
 amber, anchor, animated, app, arrow, aspect, audio, authentication, auto, autocapitalization,
@@ -809,7 +831,7 @@ pl, placeholder, platform, playback, pointer, portrait, position, pr, prevent, p
 prune, pt, pull, purple, px, py, ready, recording, red, remote, repeat, requires, results,
 return, reverse, right, role, rose, rotate, rounded, row, running, save, scale, scales,
 scaling, scroll, scrollable, scrolling, scrolls, search, section, secure, selected, selection,
-sentences, separator, shadow, shift, show, shows, shuffle, size, sky, slate, smooth, sorted,
+sentences, separator, shadow, shift, show, shows, shuffle, size, sky, slate, smooth, snap, sorted,
 source, split, state, status, stone, stopped, style, submit, subtitle, success, suppress,
 suppresses, sustained, swipe, swipeable, tab, tabs, target, teal, text, theme, throw, thumb,
 timeout, tint, title, tls, to, toggle, toolbar, top, torch, touch, trace, track, translucent,
@@ -868,18 +890,3 @@ These properties are NOT styled with classes in PurgeTSS - use as XML attributes
 | `bindId`       | `bindId="myData"`                 | ListView data binding    |
 
 **Note:** For `autocapitalization`, `editable`, `enabled`, `visible`, `autocorrect` - PurgeTSS DOES have classes (see above), so you CAN use either the class or the attribute depending on your preference.
-
----
-
-## Key Insights from Real Data
-
-1. **21,236 unique classes** across **364 unique prefixes** - Far more than initially documented
-2. **Extensive state management** - Hundreds of `*enabled`, `*-false` classes for UI states
-3. **Platform-specific classes** - Many iOS/Android specific variants (like `[platform=ios]`)
-4. **Complete color coverage** - All 22 Tailwind v3 colors with 11 shades each (50-950) = 242 color variants per prefix
-5. **Boolean class pattern** - For properties like `editable`, `enabled`, `visible` → `class` and `class-false`
-6. **UI component state variants** - `selected-*`, `badge-*`, `title-*`, `disabled-*` with full color coverage
-7. **Keyboard toolbar styling** - Extensive `keyboard-toolbar-*` classes for custom keyboard accessories
-8. **Status bar & navigation** - `status-bar-*`, `tabs-*`, `nav-*` for system UI customization
-9. **Accessibility support** - `accessibility-*` classes for a11y properties
-10. **Animation system** - `duration-*`, `delay-*`, `rotate-*`, `scale-*` for PurgeTSS Animation component

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

@@ -1,12 +1,12 @@
 # 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.0**
+> - **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 +14,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 +30,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 +67,30 @@ module.exports = {
       plugins: [] // Array of properties to ignore
     }
   },
+  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
+    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 +162,185 @@ 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. 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.
+
+> **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
+
+| 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. |
+| `--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`). |
+| `--notification` | Also emit `ic_stat_notify.png × 5`. |
+| `--splash` | Also emit `splash_icon.png × 5`. |
+| `--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). |
+| `--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). |
+| `--aggressive` | With `--cleanup-legacy`, also remove `ldpi` density folders. |
+| `--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
+
+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
+  confirmOverwrites: true  // prompt before overwriting files
+}
+```
+
+### 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 --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
+```
+
+## `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 +993,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.