@maccesar/titools 2.8.0 → 2.9.0

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.

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,35 @@ 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 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 +195,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 +505,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`)

package/skills/purgetss/references/grid-layout.md

@@ -2,9 +2,6 @@
 
 The grid system is a small layout tool that lets you build rows and columns with utility classes.
 
-> **WARNING**
-> PurgeTSS grid is not CSS Grid. It is a Titanium-oriented layout helper built around horizontal and vertical layout behavior.
-
 The snippet below shows the simplest layout. From there, you can mix columns and rows as needed.
 
 ```xml
@@ -85,10 +82,25 @@ These are the available utilities to control the grid.
 
 Control horizontal alignment of elements within a row:
 
-| Class | Effect | Use case |
-| --- | --- | --- |
-| `start` | Align to the start of the row | Left-aligned content |
-| `end` | Align to the end of the row | Right-aligned buttons or labels |
-| `center` | Align to the center of the row | Centered content blocks |
+| Class | Effect |
+| --- | --- |
+| `start` | Align to the start of the row |
+| `end` | Align to the end of the row |
+| `center` | Align to the center of the row |
 
 These apply to child views inside a `grid-cols-*` container and control horizontal placement within the grid cell.
+
+## Community-Discovered Patterns
+
+The following notes come from community experience using the PurgeTSS grid system in Titanium projects. They clarify how the grid relates to Titanium's layout engine (not CSS Grid) and offer common use cases for row placement.
+
+> **WARNING**
+> PurgeTSS grid is not CSS Grid. It is a Titanium-oriented layout helper built around horizontal and vertical layout behavior.
+
+### Common Use Cases for Row Placement
+
+| Class | Use case |
+| --- | --- |
+| `start` | Left-aligned content |
+| `end` | Right-aligned buttons or labels |
+| `center` | Centered content blocks |

package/skills/purgetss/references/icon-fonts.md

@@ -166,5 +166,9 @@ exports.icons = icons;
 > **DANGER**
 > Make sure the new prefix remains unique to avoid conflicts with other class prefixes.
 
+## Community-Discovered Patterns
+
+The following note reflects community experience working with icon fonts that depend on multiple glyphs per icon.
+
 > **Font Awesome Duotone**
 > Titanium cannot render Font Awesome duotone icons correctly because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.

package/skills/purgetss/references/installation-setup.md

@@ -12,16 +12,11 @@ Install PurgeTSS globally on your machine using [NPM](https://www.npmjs.com/).
 > Node.js 20+ required.
 > PurgeTSS requires Node 20.0.0 or higher.
 
-## Upgrade Notes
+## XML Validation
 
-- `utilities.tss` is the generated utilities file. Update any scripts or docs that still use the previous output filename.
-- `deviceInfo()` now works in Alloy and Classic Titanium projects.
-- If an upgrade behaves unexpectedly, a clean reinstall is the recommended recovery step:
+PurgeTSS v7.5.3 added XML validation that flags any `--` (double-dash) sequence inside XML comments. Titanium's XML parser treats `--` in comments as invalid, and PurgeTSS now detects those sequences before they break the compile step.
 
-```bash
-npm uninstall -g purgetss
-npm install -g purgetss
-```
+If you see a validation warning from PurgeTSS pointing at a view file, replace the offending comment with an alternative marker (for example, `//` or `==`) and re-run the build.
 
 ## Run PurgeTSS the First Time