@maccesar/titools 5.0.0 → 5.1.0

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

@@ -84,7 +84,7 @@ After running `purgetss build-fonts` with the Bevan and Dancing Script example a
 `./purgetss/styles/fonts.tss`
 ```css
 // Fonts TSS file generated with PurgeTSS
-// https://purgetss.com/docs/customization/custom-fonts
+// https://purgetss.com/docs/commands#build-fonts-command
 
 '.bevan-italic': { font: { fontFamily: 'Bevan-Italic' } }
 '.bevan-regular': { font: { fontFamily: 'Bevan-Regular' } }
@@ -95,11 +95,13 @@ After running `purgetss build-fonts` with the Bevan and Dancing Script example a
 '.dancingscript-semibold': { font: { fontFamily: 'DancingScript-SemiBold' } }
 ```
 
+The generated file also places a `/** … */` metadata comment (full name, version, vendor, license) before each font class; it is omitted from these excerpts.
+
 You can now use these classes on any Titanium component with a `font` property: Labels, Buttons, TextFields, TextAreas, ListItems, TableViewRows, and ActivityIndicators.
 
 ### Renaming the class
 
-To use a shorter or different class name, rename the font file. For example:
+By default the class name is the lowercased PostScript name, so renaming the font file alone changes nothing. The file name drives the class only with `-f, --font-class-from-filename`. For example, rename the files:
 
 `./purgetss/fonts/`
 ```bash
@@ -112,7 +114,7 @@ purgetss
       └─ Script-SemiBold.ttf
 ```
 
-Running `build-fonts` produces:
+Running `purgetss build-fonts -f` produces:
 
 `./purgetss/styles/fonts.tss`
 ```css
@@ -149,29 +151,29 @@ After `purgetss build-fonts`, the generated `fonts.tss` includes the family clas
 `./purgetss/styles/fonts.tss`
 ```css
 // Fonts TSS file generated with PurgeTSS
-// https://purgetss.com/docs/customization/custom-fonts
+// https://purgetss.com/docs/commands#build-fonts-command
 
 '.map-icons': { font: { fontFamily: 'map-icons' } }
 '.microns': { font: { fontFamily: 'microns' } }
 
-/* Unicode Characters */
-/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+// Unicode Characters
+// To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties
 
-/* map-icons/map-icons.css */
+// map-icons/map-icons.css
 '.map-icon-abseiling': { text: '\ue800', title: '\ue800' }
 '.map-icon-accounting': { text: '\ue801', title: '\ue801' }
 '.map-icon-airport': { text: '\ue802', title: '\ue802' }
 '.map-icon-amusement-park': { text: '\ue803', title: '\ue803' }
 '.map-icon-aquarium': { text: '\ue804', title: '\ue804' }
-/* ... */
+// ...
 
-/* microns/microns.css */
+// microns/microns.css
 '.mu-arrow-left': { text: '\ue700', title: '\ue700' }
 '.mu-arrow-right': { text: '\ue701', title: '\ue701' }
 '.mu-arrow-up': { text: '\ue702', title: '\ue702' }
 '.mu-arrow-down': { text: '\ue703', title: '\ue703' }
 '.mu-left': { text: '\ue704', title: '\ue704' }
-/* ... */
+// ...
 ```
 
 ## Options
@@ -192,6 +194,10 @@ $ purgetss bf -m
 
 The module is generated for text-only font collections too. By default, every TTF/OTF contributes a camel-cased PostScript-name key to `families`; with `--font-class-from-filename`, that key comes from the filename instead. Icon CSS can add a shorter family alias and a nested `icons` map. Both singular and plural export names remain available.
 
+Once `purgetss.fonts.js` exists, later `build-fonts` runs regenerate it even without `--module`; if no font or icon data remains, the file is deleted.
+
+The module also appends the `getIcon`, `setText`, `setTitle`, `getRandomKey`, and `getRandomValue` helpers. They look up top-level `icons` keys, which in this module are library prefixes, so read a glyph directly as `icons.<prefix>.<name>`.
+
 `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic)
 ```javascript
 const icons = {
@@ -264,25 +270,24 @@ purgetss
 
 `./purgetss/styles/fonts.tss`
 ```css
-/* "fontFamily" classes use the font's filename */
 '.map': { font: { fontFamily: 'map-icons' } }
 '.mic': { font: { fontFamily: 'microns' } }
 
-/* map-icons/mp.css */
+// map-icons/mp.css
 '.mp-abseiling': { text: '\ue800', title: '\ue800' }
 '.mp-accounting': { text: '\ue801', title: '\ue801' }
 '.mp-airport': { text: '\ue802', title: '\ue802' }
 '.mp-amusement-park': { text: '\ue803', title: '\ue803' }
 '.mp-aquarium': { text: '\ue804', title: '\ue804' }
-/* ... */
+// ...
 
-/* microns/mc.css */
+// microns/mc.css
 '.mc-arrow-left': { text: '\ue700', title: '\ue700' }
 '.mc-arrow-right': { text: '\ue701', title: '\ue701' }
 '.mc-arrow-up': { text: '\ue702', title: '\ue702' }
 '.mc-arrow-down': { text: '\ue703', title: '\ue703' }
 '.mc-left': { text: '\ue704', title: '\ue704' }
-/* ... */
+// ...
 ```
 
 `app/lib/purgetss.fonts.js` (Alloy) or `Resources/lib/purgetss.fonts.js` (Classic)
@@ -338,4 +343,4 @@ The following notes reflect community experience with `build-fonts` against real
 > Titanium cannot render Font Awesome duotone icons because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.
 
 > **💡 Use `--module` to set `text`/`title` from JavaScript**
-> Hardcoding `` in a controller is brittle. The `-m` flag generates a `purgetss.fonts.js` you can `require()` and reference by friendly name: `label.text = icons.fa.home`. Combine with `families` to set `font.fontFamily` programmatically.
+> Hardcoding `'\uf015'` in a controller is brittle. The `-m` flag generates a `purgetss.fonts.js` you can `require()` and reference by friendly name: `label.text = icons.fa.home`. Combine with `families` to set `font.fontFamily` programmatically.

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

@@ -20,8 +20,8 @@ Whether you want to style a Ti Element (a markup element such as `Label`), a cus
 >
 > 1. **Audit current usage.** Set `purge.options.missing` to `true` in `config.cjs`. PurgeTSS will append a list of missing classes at the end of `app.tss` after the next compile — every entry is a class name you still need to migrate.
 > 2. **Rename selectors.** Convert every `.myCustomClassName` to `.my-custom-class-name` in both XML markup and `config.cjs`. The old camelCase names will not match anymore.
-> 3. **Convert config to `.cjs`.** If your project still uses `purgetss.config.js` or a CommonJS-style file with the old layout, rename the file to `config.cjs` and ensure it sits in `./purgetss/`. The single export must be `module.exports = { theme: { ... } }`.
-> 4. **Re-run `purgetss build`.** Verify the missing-classes list at the end of `app.tss` is empty before turning `missing` back off.
+> 3. **Let PurgeTSS rename the config.** If the project still has `./purgetss/config.js`, the next PurgeTSS run renames it to `./purgetss/config.cjs` automatically. If both files exist, PurgeTSS reads only `config.cjs` and leaves `config.js` untouched, so merge any settings it holds into `config.cjs` and delete it.
+> 4. **Re-run `purgetss`** (or build the Alloy project, which runs it through the auto-purge hook). Verify the missing-classes list at the end of `app.tss` is empty before turning `missing` back off. `purgetss build` only regenerates `utilities.tss`; it does not write `app.tss`.
 >
 > Skipping any of these steps tends to surface as silently dropped styles at runtime — the app compiles, but selectors no longer match.
 
@@ -43,7 +43,7 @@ The way you write property values determines how PurgeTSS emits them in the gene
 - For `spacing` values you can mix unit types. Each unit follows a specific conversion rule:
   - `%`, `px`, `cm`, and `in` are passed through to TSS without conversion.
   - `em` and `rem` values are converted with the formula `value * 16` (so `1rem` becomes `16`).
-  - `dp` removes the unit and keeps the numeric value as-is, since Titanium treats unit-less numeric values as density-independent pixels by default.
+  - `dp` removes the unit and keeps the numeric value as-is. Titanium resolves unit-less numbers with `ti.ui.defaultunit` in `tiapp.xml` (the Alloy template default is `dp`).
 
 ## `config.cjs` File Example
 
@@ -100,21 +100,21 @@ module.exports = {
 PurgeTSS reads `config.cjs` and emits a single `utilities.tss` file that Alloy then merges with the rest of the project's styling. The file below shows what the example above generates — note how block keys translate into TSS query suffixes (`[platform=android]`, `[formFactor=tablet]`, `[if=...]`).
 
 ```tss
-/* Property: TextField */
-/* Description: A single line text field. */
+// Property: TextField
+// Description: A single line text field.
 'TextField': { top: 10, left: 20, right: 20, bottom: 0 }
 'TextField[if=Alloy.Globals.iPhoneX]': { bottom: Alloy.CFG.iPhoneXNotchSize }
 'TextField[platform=android]': { touchFeedback: true }
 
-/* Custom Classes */
+// Custom Classes
 '#main-banner': { width: '300px', height: '80px' }
 '#main-banner[platform=ios]': { clipMode: Ti.UI.iOS.CLIP_MODE_DISABLED }
-
 '.gallery': { height: Ti.UI.SIZE }
 '.gallery[platform=ios]': { clipMode: Ti.UI.iOS.CLIP_MODE_ENABLED }
 '.gallery[platform=android]': { hiddenBehavior: Ti.UI.HIDDEN_BEHAVIOR_GONE }
 '.gallery[formFactor=handheld]': { width: '250px' }
 '.gallery[formFactor=tablet]': { width: '500px' }
+// End of Custom Classes
 ```
 
 ## Community-Discovered Patterns

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

@@ -36,10 +36,11 @@ purgetss init
 This creates a `./purgetss/config.cjs` file with the default sections:
 
 ```javascript
+// ./purgetss/config.cjs
 module.exports = {
   purge: {
     mode: 'all',
-    method: 'sync', // How to execute the auto-purging task: sync or async
+    method: 'sync', // set how to execute auto-purging: sync or async
 
     // These options are passed directly to PurgeTSS
     options: {
@@ -50,14 +51,17 @@ module.exports = {
     }
   },
   brand: {
-    background: '#FFFFFF',      // inherited by every piece that doesn't set its own
-    artworkCornerRadius: '0%',  // rounded non-icon artwork: splashes, Feature Graphic and LaunchLogo
-    confirmOverwrites: true,    // prompt before overwriting files (set false to skip)
-    optimize: false,            // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
+    // Opaque fallback fill; configurable, not required to be white by either platform.
+    background: '#FFFFFF',     // inherited by pieces that use an opaque background canvas
+    artworkCornerRadius: '0%', // rounded non-icon artwork: splashes, Feature Graphic and LaunchLogo (0-50)
+    confirmOverwrites: true,   // prompt before overwriting files (set false to skip)
+    optimize: false,           // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
 
     // One block per piece. Artwork comes from purgetss/brand/logo-<piece>.{svg,png};
     // these keys are for numbers, colors and activation. Padding is never inherited.
-    // Only iosSplash, androidSplash, featureGraphic and launchLogo accept cornerRadius.
+    // iosSplash, androidSplash, featureGraphic and launchLogo accept cornerRadius.
+    // Store and launcher icons stay square for platform masking.
+    // iOS/store icons are full-bleed by default; increase padding only for logo artwork.
     icon:             { padding: '0%' },    // DefaultIcon.png + DefaultIcon-ios.png
     dark:             { background: null }, // DefaultIcon-Dark.png
     tinted:           {},                   // DefaultIcon-Tinted.png
@@ -86,18 +90,17 @@ module.exports = {
     autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
     confirmOverwrites: true, // prompt before overwriting files (set false to skip)
     files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
-    // Note: --width (v7.8.0) and --opacity / --padding / --output (v7.10.0) are CLI-only
-    //       by design — those decisions are per-asset, not project-wide. Since v7.17.0
-    //       writing any of them here aborts the run instead of being ignored.
   },
   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.
 
+`--width` (v7.8.0) and `--opacity` / `--padding` / `--output` (v7.10.0) are CLI-only flags of `purgetss images`, by design: those decisions are per-asset, not project-wide. Since v7.17.0 the `images:` section rejects unknown keys, so writing any of them in `config.cjs` aborts the run instead of being ignored.
+
 Every section is optional. Only add what you want to change. Anything missing falls back to the defaults.
 
 ## Structure
@@ -533,7 +536,7 @@ module.exports = {
 This generates classes like `bg-regal-blue` in addition to all of Tailwind's default colors.
 
 > **ℹ️ INFO**
-> You can use the `shades` command to generate a range of shades for a color and add them to `config.cjs`. See [CLI Commands](./cli-commands.md#shades-command).
+> You can use the `shades` command to generate a range of shades for a color and add them to `config.cjs`. See [Color Commands](./color-commands.md#shades-command).
 
 ## Customize Spacing
 

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

@@ -2,7 +2,7 @@
 
 > **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 Alloy animation usage, or [purgetss-ui-classic.md](./purgetss-ui-classic.md) for the generated Classic runtime).
+> This reference covers dynamic component creation using **Alloy's `$.UI.create()` helper** and **`$.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 Alloy animation usage, or [purgetss-ui-classic.md](./purgetss-ui-classic.md) for the generated Classic runtime).
 >
 > For general Alloy controller and view patterns, refer to the `alloy-guides` and `alloy-howtos` skills.
 
@@ -12,11 +12,11 @@
 - [Community-Discovered Patterns](#community-discovered-patterns)
 - [Overview](#overview)
 - [Method 1: `$.UI.create()` (Recommended)](#method-1-uicreate-recommended)
-- [Method 2: `Alloy.createStyle()` + `applyProperties()`](#method-2-alloycreatestyle--applyproperties)
+- [Method 2: `$.createStyle()` + `applyProperties()`](#method-2-createstyle--applyproperties)
 - [Comparison: Which Method to Use?](#comparison-which-method-to-use)
 - [Real-World Examples](#real-world-examples)
 - [Important Notes](#important-notes)
-- [Dynamic Styling with `classes` Property](#dynamic-styling-with-classes-property)
+- [Changing Classes at Runtime](#changing-classes-at-runtime)
 - [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
 - [Summary](#summary)
 
@@ -31,11 +31,11 @@ The guidance in this file reflects patterns that PurgeTSS users have converged o
 When creating components dynamically in Controllers (not declaratively in XML), PurgeTSS provides two methods to apply utility classes:
 
 1. **`$.UI.create()`** - Create components with PurgeTSS classes (Recommended)
-2. **`Alloy.createStyle()` + `applyProperties()`** - Apply PurgeTSS styles to existing components
+2. **`$.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.
+> Always prefer `$.UI.create()` for dynamic components — it's cleaner, more readable, and PurgeTSS picks up the classes during build as long as they are written as literals under a `classes:` key in a controller (see [What the Class Scanner Collects](#what-the-class-scanner-collects)).
 
 ---
 
@@ -62,7 +62,7 @@ $.UI.create('ComponentType', {
 function createThemeCard(themeName, themeTitle, imagePath) {
   return $.UI.create('View', {
     // View properties
-    title: themeTitle, // Add title for TTS support
+    accessibilityLabel: themeTitle, // Read by VoiceOver/TalkBack (Ti.UI.View has no `title` property)
 
     // PurgeTSS utility classes
     classes: [
@@ -102,7 +102,7 @@ classes: ['w-screen', 'h-auto', 'bg-white', 'rounded-lg']
 classes: 'w-screen h-auto bg-white rounded-lg'
 
 // Option 3: Mix arbitrary values with predefined classes
-classes: ['w-(100px)', 'h-auto', 'bg-(#ff0000)', 'rounded-lg']
+classes: ['w-(100)', 'h-auto', 'bg-(#ff0000)', 'rounded-lg']
 ```
 
 ### Platform Modifiers in Dynamic Components
@@ -123,7 +123,7 @@ classes: [
 // Arbitrary values use parentheses notation
 classes: [
   'w-(160)',          // Custom width
-  'h-(200px)',        // Custom height with unit
+  'h-(12.5rem)',      // Custom height with a unit (not px: a px suffix stops the build)
   'bg-(#3b82f6)',     // Custom hex color
   'm-(10dp)',         // Custom margin with unit
   'border-(2)'        // Custom border width
@@ -157,21 +157,21 @@ function createListItem(text, icon) {
 
 ---
 
-## Method 2: `Alloy.createStyle()` + `applyProperties()`
+## Method 2: `$.createStyle()` + `applyProperties()`
 
 ### When to Use This Method
 
-Use `Alloy.createStyle()` when you need to:
+Use the controller's `createStyle()` method when you need to:
 - Apply PurgeTSS styles to an **existing component** (created without `$.UI.create()`)
-- Modify styles dynamically after component creation
-- Apply styles from a different view/controller
+- Build a style dictionary once and apply it to several components
+- Style a view of another controller (`Alloy.createController('dialog').createStyle(...)`, as in the Alloy dynamic styles guide)
 
 ### Basic Syntax
 
 ```javascript
 // Create style object
-const style = Alloy.createStyle('viewName', {
-  apiName: 'Ti.UI.View',
+const style = $.createStyle({
+  apiName: 'View',
   classes: 'bg-white rounded-lg'
 })
 
@@ -185,8 +185,8 @@ $.myView.applyProperties(style)
 // controllers/form/validation.js
 function showError(inputField, errorMessage) {
   // Create error style
-  const errorStyle = Alloy.createStyle('index', {
-    apiName: 'Ti.UI.TextField',
+  const errorStyle = $.createStyle({
+    apiName: 'TextField',
     classes: ['border-2', 'border-red-500', 'bg-red-50']
   })
 
@@ -196,8 +196,8 @@ function showError(inputField, errorMessage) {
 
 function clearError(inputField) {
   // Create normal style
-  const normalStyle = Alloy.createStyle('index', {
-    apiName: 'Ti.UI.TextField',
+  const normalStyle = $.createStyle({
+    apiName: 'TextField',
     classes: ['border-1', 'border-gray-300', 'bg-white']
   })
 
@@ -210,10 +210,11 @@ function clearError(inputField) {
 
 ```javascript
 // String format
-Alloy.createStyle('index', { classes: 'bg-white rounded-lg' })
+$.createStyle({ apiName: 'View', classes: 'bg-white rounded-lg' })
 
 // Array format
-Alloy.createStyle('index', {
+$.createStyle({
+  apiName: 'Label',
   classes: ['bg-white', 'rounded-lg', 'text-center']
 })
 ```
@@ -225,8 +226,8 @@ Alloy.createStyle('index', {
 | Scenario                        | Recommended Method                          | Example                                          |
 | ------------------------------- | ------------------------------------------- | ------------------------------------------------ |
 | **Creating new components**     | `$.UI.create()`                             | `$.UI.create('View', { classes: ['bg-white'] })` |
-| **Styling existing components** | `Alloy.createStyle()` + `applyProperties()` | `view.applyProperties(Alloy.createStyle(...))`   |
-| **Dynamic style changes**       | `Alloy.createStyle()` + `applyProperties()` | Form validation, theme switching                 |
+| **Styling existing components** | `$.createStyle()` + `applyProperties()`     | `view.applyProperties($.createStyle(...))`       |
+| **Swapping classes at runtime** | `$.addClass()` / `$.removeClass()` / `$.resetClass()` | Form validation, active/inactive states |
 | **Component factories**         | `$.UI.create()`                             | Reusable component creators                      |
 
 ---
@@ -236,21 +237,19 @@ Alloy.createStyle('index', {
 ### Example 1: Dynamic Form Fields
 
 ```javascript
-// lib/factories/formFactory.js
-exports.createFormField = function(fieldType, options) {
-  const baseClasses = ['w-screen', 'h-12', 'mx-4', 'border-gray-300', 'border-(1)', 'rounded-lg']
-
+// controllers/form.js
+function createFormField(fieldType, options) {
   switch (fieldType) {
     case 'text':
       return $.UI.create('TextField', {
         hintText: options.hint,
-        classes: [...baseClasses, 'bg-white', 'px-4']
+        classes: ['w-screen', 'h-12', 'mx-4', 'border-gray-300', 'border-(1)', 'rounded-lg', 'bg-white', 'px-4']
       })
 
     case 'textarea':
       return $.UI.create('TextArea', {
         hintText: options.hint,
-        classes: [...baseClasses, 'h-24', 'bg-white', 'px-4']
+        classes: ['w-screen', 'h-24', 'mx-4', 'border-gray-300', 'border-(1)', 'rounded-lg', 'bg-white', 'px-4']
       })
 
     case 'button':
@@ -262,6 +261,12 @@ exports.createFormField = function(fieldType, options) {
 }
 ```
 
+> **NOTE — Keep factories in controllers, with literal class lists**
+>
+> - `$` is the controller instance, so `$.UI.create()` is not available in a plain `app/lib/` CommonJS module, and PurgeTSS does not scan `app/lib/` for classes.
+> - Each class list is written out in full under `classes:`. A shared `baseClasses` array spread into `classes: [...baseClasses, ...]` is invisible to the scanner: spread elements are skipped and the array itself is not under a `classes:` key, so those classes would be purged from `app.tss`.
+> - `px-4` sets `padding`, which exists only on `Ti.UI.TextField`, `Ti.UI.TextArea` (Android and iOS) and `Ti.UI.Android.CardView` (apidoc 13_4_1_GA). The `// padding - Android Only` comment in `utilities.tss` is inaccurate for the two text inputs.
+
 ### Example 2: Dynamic List Items
 
 ```javascript
@@ -306,12 +311,12 @@ function createProductCard(product) {
 function applyTheme(theme) {
   const themes = {
     light: {
-      window: Alloy.createStyle('index', { classes: 'bg-white' }),
-      text: Alloy.createStyle('index', { classes: 'text-gray-900' })
+      window: $.createStyle({ apiName: 'Window', classes: 'bg-white' }),
+      text: $.createStyle({ apiName: 'Label', classes: 'text-gray-900' })
     },
     dark: {
-      window: Alloy.createStyle('index', { classes: 'bg-gray-900' }),
-      text: Alloy.createStyle('index', { classes: 'text-gray-100' })
+      window: $.createStyle({ apiName: 'Window', classes: 'bg-gray-900' }),
+      text: $.createStyle({ apiName: 'Label', classes: 'text-gray-100' })
     }
   }
 
@@ -325,13 +330,19 @@ function applyTheme(theme) {
 ```javascript
 // controllers/dashboard/grid.js
 function createIconGrid(items) {
+  // `grid` goes on the container; `grid-cols-4` (width: 25%) goes on each cell
   const grid = $.UI.create('View', {
-    classes: ['w-screen', 'grid-cols-4', 'gap-4']
+    classes: ['grid']
   })
 
   items.forEach(item => {
+    const cell = $.UI.create('View', {
+      classes: ['grid-cols-4']
+    })
+
+    // Optional gutter: `gap-*` sets margins, so it goes on an inner view
     const icon = $.UI.create('View', {
-      classes: ['vertical']
+      classes: ['gap-1', 'vertical']
     })
 
     const iconView = $.UI.create('Label', {
@@ -346,7 +357,8 @@ function createIconGrid(items) {
 
     icon.add(iconView)
     icon.add(label)
-    grid.add(icon)
+    cell.add(icon)
+    grid.add(cell)
   })
 
   return grid
@@ -361,13 +373,39 @@ function createIconGrid(items) {
 
 > **NOTE — HOW IT WORKS**
 >
-> When you use `$.UI.create()` or `Alloy.createStyle()` with classes:
+> When you use `$.UI.create()` or `$.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 the full PurgeTSS utility surface even with dynamic components.
+> This works only for classes the scanner can see (next section). Anything else is purged from `app.tss` and silently does nothing at runtime.
+
+### What the Class Scanner Collects
+
+PurgeTSS parses every file in `app/controllers/**/*.js`, plus `app/widgets/**/controllers/*.js` when `purge.options.widgets` is `true`. Files in `app/lib/` are not scanned.
+
+It collects class names only from these shapes:
+
+| Shape | Example |
+| --- | --- |
+| Value of a `classes:` or `apply:` property | `classes: ['bg-white', 'rounded-lg']`, `classes: 'bg-white rounded-lg'` |
+| Second argument of any `*Class(target, value)` call, or `resetClass(target, value)` | `$.addClass($.label, 'text-red-500')` |
+
+Inside those, it reads string literals, template literals without `${}`, array elements, and both branches of a ternary (`isActive ? 'text-green-500' : 'text-red-500'`).
+
+It does not see classes held in a variable, built by concatenation or interpolation (`` `bg-${color}-500` ``), added with `.push()`, or spread from another array (`[...baseClasses]`). For classes that must be built dynamically, list them in `purge.options.safelist` in `purgetss/config.cjs`, which keeps them no matter the purge mode (see the PurgeTSS configuring guide, `options.safelist`):
+
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  purge: {
+    options: {
+      safelist: ['bg-red-500', 'bg-green-500', 'bg-blue-500']
+    }
+  }
+}
+```
 
 ### Class Verification
 
@@ -378,7 +416,10 @@ Just like with XML views, always verify classes exist before using them:
 classes: ['w-screen', 'h-auto', 'bg-white', 'rounded-lg']
 
 // WRONG - These classes don't exist
-classes: ['flex-row', 'justify-center', 'p-4']  // No flexbox, no p-* on View
+classes: ['flex-row', 'justify-center']  // No flexbox in Titanium
+
+// NO EFFECT - `p-4` exists, but it sets `padding`, which only TextField, TextArea and Android CardView have
+$.UI.create('View', { classes: ['p-4'] })  // Use margins on the children instead
 ```
 
 See [Class Index](class-index.md) for available classes.
@@ -394,7 +435,7 @@ classes: [
   'bg-white'
 ]
 
-// Avoid: Conditional logic in controllers
+// Avoid: Conditional logic in controllers (the scanner does not see `.push()`, so classes added only this way are purged)
 if (OS_IOS) {
   classes.push('mx-4')
 } else {
@@ -404,20 +445,24 @@ if (OS_IOS) {
 
 ---
 
-## Dynamic Styling with `classes` Property
+## Changing Classes at Runtime
 
-You can change PurgeTSS classes dynamically at runtime using the `classes` property in `applyProperties()`:
+`applyProperties({ classes: [...] })` does not restyle a view: it only sets a `classes` property on the proxy. To change the classes of a view that already exists, use the controller's `addClass`, `removeClass` and `resetClass` methods (Alloy dynamic styles guide). Pass the view, then the classes as an array or space-separated string, and optionally inline properties as a third argument:
 
 ```javascript
 // Toggle status styling dynamically
 function setStatus(isActive) {
-  $.statusLabel.applyProperties({
-    classes: isActive ? ['text-green-500'] : ['text-red-500'],
+  $.removeClass($.statusLabel, isActive ? 'text-red-500' : 'text-green-500')
+  $.addClass($.statusLabel, isActive ? 'text-green-500' : 'text-red-500', {
     text: isActive ? L('active') : L('inactive')
   })
 }
 ```
 
+- `resetClass(view, classes)` replaces every class on the view, including the ones set in XML, so pass the full list.
+- Enable autostyle (`<Alloy autoStyle="true">` in the view, or `autoStyle: true` in `config.json`) so removing a class also reverts its properties. Without it, a removed class leaves its values on the view.
+- The PurgeTSS scanner reads the second argument of these calls, including both branches of a ternary.
+
 ### Conditional Styling Based on State
 
 ```javascript
@@ -452,9 +497,9 @@ function setState(state) {
 }
 ```
 
-> **NOTE — When to use `classes` vs `applyProperties`**
+> **NOTE — When to use `addClass`/`removeClass` vs `applyProperties`**
 >
-> - Use `classes` when you want to swap entire style sets (e.g., active/inactive states)
+> - Use `addClass`/`removeClass`/`resetClass` 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
 
@@ -483,33 +528,30 @@ const view = $.UI.create('View', {
 })
 ```
 
-### Don't mix inline styles and classes
+### Mixing inline properties and classes: keep inline values for runtime data
+
+Alloy supports inline properties next to `classes`, and inline properties take precedence over class styles. Use them for values only known at runtime, and keep static styling in classes so it stays consistent with the rest of the app:
 
 ```javascript
-// CONFUSING - Mix of styles and classes
+// Avoid - a static value that a class already covers
 const view = $.UI.create('View', {
-  backgroundColor: '#ffffff',  // Manual style
-  classes: ['w-screen', 'rounded-lg']  // PurgeTSS classes
+  backgroundColor: '#ffffff',  // Same as `bg-white`
+  classes: ['w-screen', 'rounded-lg']
 })
 ```
 
-### Use only classes (or only styles)
-
 ```javascript
 // CORRECT - Pure PurgeTSS
 const view = $.UI.create('View', {
   classes: ['w-screen', 'h-auto', 'bg-white', 'rounded-lg']
 })
 
-// OR for truly dynamic/runtime-only values
-const view = Ti.UI.createView({
-  backgroundColor: dynamicColor,  // Runtime value
-  width: calculatedWidth
-})
-// Then apply PurgeTSS classes
-view.applyProperties(Alloy.createStyle('index', {
+// CORRECT - Runtime values inline, static styling as classes
+const view = $.UI.create('View', {
+  backgroundColor: dynamicColor,  // Runtime value, overrides any class color
+  width: calculatedWidth,
   classes: ['rounded-lg', 'm-4']
-}))
+})
 ```
 
 ---
@@ -519,8 +561,9 @@ view.applyProperties(Alloy.createStyle('index', {
 | Method                    | Use Case                    | Syntax                                               |
 | ------------------------- | --------------------------- | ---------------------------------------------------- |
 | **`$.UI.create()`**       | Creating new components     | `$.UI.create('View', { classes: ['bg-white'] })`     |
-| **`Alloy.createStyle()`** | Styling existing components | `Alloy.createStyle('view', { classes: 'bg-white' })` |
+| **`$.createStyle()`**     | Styling existing components | `$.createStyle({ apiName: 'View', classes: 'bg-white' })` |
 | **`applyProperties()`**   | Apply style to component    | `component.applyProperties(style)`                   |
+| **`$.addClass()` / `$.removeClass()` / `$.resetClass()`** | Swapping classes at runtime | `$.addClass($.label, 'text-red-500')` |
 
 > **NOTE — REMEMBER**
 >
@@ -531,4 +574,4 @@ view.applyProperties(Alloy.createStyle('index', {
 > - All layout classes (`horizontal`, `vertical`)
 > - All typography classes (`text-*`, `font-*`)
 > - Platform modifiers (`ios:*`, `android:*`)
-> - Arbitrary values (`w-(100px)`, `bg-(#ff0000)`)
+> - Arbitrary values (`w-(100)`, `bg-(#ff0000)`)