@maccesar/titools 2.0.7 → 2.2.0

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

@@ -14,47 +14,6 @@ PurgeTSS provides a comprehensive suite of CLI commands for project setup, asset
 - **Improved Unicode Extraction**: Enhanced support for various Unicode formats and direct character mappings
 :::
 
-## Table of Contents
-
-- [PurgeTSS CLI Commands Guide](#purgetss-cli-commands-guide)
-  - [Table of Contents](#table-of-contents)
-  - [Setup Commands](#setup-commands)
-    - [`purgetss init` (alias: `i`)](#purgetss-init-alias-i)
-    - [`purgetss create` (alias: `c`)](#purgetss-create-alias-c)
-    - [`purgetss install-dependencies` (alias: `id`)](#purgetss-install-dependencies-alias-id)
-  - [Development Commands](#development-commands)
-    - [`purgetss build` (alias: `b`)](#purgetss-build-alias-b)
-    - [`purgetss watch` (alias: `w`)](#purgetss-watch-alias-w)
-  - [Asset Commands](#asset-commands)
-    - [`purgetss icon-library` (alias: `il`)](#purgetss-icon-library-alias-il)
-      - [CommonJS Module](#commonjs-module)
-      - [Font Awesome Pro](#font-awesome-pro)
-      - [Font Awesome 7 Beta](#font-awesome-7-beta)
-      - [Font Example File](#font-example-file)
-    - [`purgetss build-fonts` (alias: `bf`)](#purgetss-build-fonts-alias-bf)
-      - [For Text Fonts (Google Fonts, etc.)](#for-text-fonts-google-fonts-etc)
-      - [For Icon Fonts (Custom Libraries)](#for-icon-fonts-custom-libraries)
-      - [CommonJS Module for Custom Fonts](#commonjs-module-for-custom-fonts)
-  - [Utility Commands](#utility-commands)
-    - [`purgetss shades` (alias: `s`)](#purgetss-shades-alias-s)
-    - [`purgetss color-module` (alias: `cm`)](#purgetss-color-module-alias-cm)
-    - [`purgetss module` (alias: `m`)](#purgetss-module-alias-m)
-  - [Maintenance Commands](#maintenance-commands)
-    - [`purgetss update` (alias: `u`)](#purgetss-update-alias-u)
-    - [`purgetss sudo-update` (alias: `su`)](#purgetss-sudo-update-alias-su)
-  - [Command Quick Reference](#command-quick-reference)
-  - [Advanced Usage](#advanced-usage)
-    - [Combining Commands for New Projects](#combining-commands-for-new-projects)
-    - [Setting Up an Existing Project](#setting-up-an-existing-project)
-    - [Quick Reference: New Project Setup Commands](#quick-reference-new-project-setup-commands)
-    - [Safelist for Large Projects](#safelist-for-large-projects)
-    - [Disabling Specific Classes](#disabling-specific-classes)
-  - [Troubleshooting Commands](#troubleshooting-commands)
-    - [Verifying Installation](#verifying-installation)
-    - [Debug Mode](#debug-mode)
-
----
-
 ## Setup Commands
 
 ### `purgetss init` (alias: `i`)

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

@@ -2,61 +2,6 @@
 
 Complete list of all properties that can be customized in `config.cjs` under the `theme` section.
 
-## Table of Contents
-
-- [Configurable Properties Reference](#configurable-properties-reference)
-  - [Table of Contents](#table-of-contents)
-  - [Color Properties (50+ properties)](#color-properties-50-properties)
-    - [Background Colors](#background-colors)
-    - [Text Colors](#text-colors)
-    - [UI Element Colors](#ui-element-colors)
-    - [Border \& Separator Colors](#border--separator-colors)
-    - [Navigation \& Button Colors](#navigation--button-colors)
-    - [Indicator Colors](#indicator-colors)
-    - [Badge \& Notification Colors](#badge--notification-colors)
-    - [Miscellaneous Colors](#miscellaneous-colors)
-  - [Spacing \& Size Properties](#spacing--size-properties)
-    - [Dimensions](#dimensions)
-    - [Margin](#margin)
-    - [Padding](#padding)
-    - [Background Padding](#background-padding)
-    - [Content Size](#content-size)
-    - [Gaps](#gaps)
-  - [Border Properties](#border-properties)
-    - [Background Caps](#background-caps)
-  - [Positioning Properties](#positioning-properties)
-  - [Typography Properties](#typography-properties)
-  - [Layout Properties](#layout-properties)
-  - [Opacity \& Visibility](#opacity--visibility)
-  - [Transformation Properties](#transformation-properties)
-  - [Animation Properties](#animation-properties)
-  - [Z-Index \& Layering](#z-index--layering)
-  - [Shadow Properties](#shadow-properties)
-  - [Section Properties](#section-properties)
-  - [Separator Properties](#separator-properties)
-  - [Paging Properties](#paging-properties)
-  - [Zoom Properties](#zoom-properties)
-  - [Button Properties](#button-properties)
-  - [Left/Right Width](#leftright-width)
-  - [Cache Properties](#cache-properties)
-  - [Other Properties](#other-properties)
-  - [Quick Reference Table](#quick-reference-table)
-  - [Customizing in config.cjs](#customizing-in-configcjs)
-    - [Override Default Values](#override-default-values)
-    - [Extend Default Values](#extend-default-values)
-    - [Mix Override and Extend](#mix-override-and-extend)
-  - [Practical Examples](#practical-examples)
-    - [Complete Brand Color System](#complete-brand-color-system)
-    - [Custom Spacing Scale](#custom-spacing-scale)
-    - [Custom Font Family System](#custom-font-family-system)
-    - [Custom Border Radius Scale](#custom-border-radius-scale)
-    - [Complete Card Component via Ti Element](#complete-card-component-via-ti-element)
-    - [Button System with Variants](#button-system-with-variants)
-    - [Form Input System](#form-input-system)
-  - [Related References](#related-references)
-
----
-
 ## Color Properties (50+ properties)
 
 All color properties inherit values from `theme.colors` and support a full color palette plus any custom colors you define.

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

@@ -6,20 +6,6 @@ Custom rules in PurgeTSS allow you to style **Titanium elements**, **IDs**, and
 This feature is particularly useful for meeting visual and design requirements across multiple platforms (iOS and Android).
 :::
 
-## Table of Contents
-
-- [Custom Rules for Ti Elements, IDs, and Classes](#custom-rules-for-ti-elements-ids-and-classes)
-  - [Table of Contents](#table-of-contents)
-  - [Naming Conventions](#naming-conventions)
-  - [Modifier Keys](#modifier-keys)
-    - [Platform, Device, and Conditional Blocks](#platform-device-and-conditional-blocks)
-  - [Property Values](#property-values)
-  - [Config Example](#config-example)
-  - [Generated TSS Output](#generated-tss-output)
-  - [Complete Styling Example](#complete-styling-example)
-
----
-
 ## Naming Conventions
 
 | Target Type     | Naming Convention  | Example                             |

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

@@ -8,55 +8,6 @@ PurgeTSS allows for extreme customization through its configuration file, custom
 **Legacy Mode Removed**: Legacy mode has been completely removed from PurgeTSS v7.2.x. All legacy-related options have been eliminated for a cleaner, modern codebase.
 :::
 
-## Table of Contents
-
-- [PurgeTSS Deep Customization](#purgetss-deep-customization)
-  - [Table of Contents](#table-of-contents)
-  - [The `config.cjs` File](#the-configcjs-file)
-    - [File Structure](#file-structure)
-    - [Creating a Fresh config.cjs](#creating-a-fresh-configcjs)
-  - [The `purge` Section](#the-purge-section)
-    - [`mode` Property](#mode-property)
-    - [`method` Property](#method-property)
-    - [`options` Properties](#options-properties)
-  - [The `theme` Section](#the-theme-section)
-    - [Overriding vs Extending](#overriding-vs-extending)
-  - [Customizing Colors](#customizing-colors)
-    - [Color Object Syntax](#color-object-syntax)
-    - [Overriding Default Colors](#overriding-default-colors)
-    - [Extending the Palette](#extending-the-palette)
-  - [Customizing Spacing](#customizing-spacing)
-    - [Shared Spacing Behavior](#shared-spacing-behavior)
-  - [List of Customizable Properties](#list-of-customizable-properties)
-    - [Global Properties](#global-properties)
-    - [Color Properties (50+ properties)](#color-properties-50-properties)
-    - [Configurable Properties (80+ properties)](#configurable-properties-80-properties)
-  - [Custom Rules \& Ti Elements](#custom-rules--ti-elements)
-    - [Modifier Key](#modifier-key)
-    - [Default, Platform, Device, or Conditional Blocks](#default-platform-device-or-conditional-blocks)
-    - [Property Values](#property-values)
-    - [Complete Example](#complete-example)
-  - [The `@apply` Directive](#the-apply-directive)
-    - [Platform-Specific Classes with `@apply`](#platform-specific-classes-with-apply)
-      - [Correct Usage - With Platform Variant](#correct-usage---with-platform-variant)
-      - [Wrong Usage - Omitting Platform Variant](#wrong-usage---omitting-platform-variant)
-      - [Why Platform Variants Are Required](#why-platform-variants-are-required)
-      - [Combining Platform Variants](#combining-platform-variants)
-    - [String vs Array Syntax](#string-vs-array-syntax)
-  - [Platform \& Device Modifiers in XML](#platform--device-modifiers-in-xml)
-    - [Platform Modifiers](#platform-modifiers)
-    - [Device Modifiers](#device-modifiers)
-    - [Custom Conditional Modifiers](#custom-conditional-modifiers)
-  - [Icon Font Support](#icon-font-support)
-  - [Theme Extension Best Practices](#theme-extension-best-practices)
-    - [1. Use `extend` for Additions](#1-use-extend-for-additions)
-    - [2. Use Direct Properties for Overrides](#2-use-direct-properties-for-overrides)
-    - [3. Mix Both When Needed](#3-mix-both-when-needed)
-  - [Summary Checklist](#summary-checklist)
-  - [Related References](#related-references)
-
----
-
 ## The `config.cjs` File
 
 By default, **PurgeTSS** will look for a `./purgetss/config.cjs` file where you can define customizations.

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

@@ -1,42 +1,5 @@
 # Dynamic Component Creation with PurgeTSS
 
-## Table of Contents
-
-- [Dynamic Component Creation with PurgeTSS](#dynamic-component-creation-with-purgetss)
-  - [Table of Contents](#table-of-contents)
-  - [Overview](#overview)
-  - [Method 1: `$.UI.create()` (Recommended)](#method-1-uicreate-recommended)
-    - [Basic Syntax](#basic-syntax)
-    - [Complete Example: Theme Card](#complete-example-theme-card)
-    - [Supported Components](#supported-components)
-    - [Classes Format Options](#classes-format-options)
-    - [Platform Modifiers in Dynamic Components](#platform-modifiers-in-dynamic-components)
-    - [Arbitrary Values](#arbitrary-values)
-    - [Adding Children Dynamically](#adding-children-dynamically)
-  - [Method 2: `Alloy.createStyle()` + `applyProperties()`](#method-2-alloycreatestyle--applyproperties)
-    - [When to Use This Method](#when-to-use-this-method)
-    - [Basic Syntax](#basic-syntax-1)
-    - [Complete Example](#complete-example)
-    - [Classes Format](#classes-format)
-  - [Comparison: Which Method to Use?](#comparison-which-method-to-use)
-  - [Real-World Examples](#real-world-examples)
-    - [Example 1: Dynamic Form Fields](#example-1-dynamic-form-fields)
-    - [Example 2: Dynamic List Items](#example-2-dynamic-list-items)
-    - [Example 3: Dynamic Theme Switching](#example-3-dynamic-theme-switching)
-    - [Example 4: Dynamic Icon Grid](#example-4-dynamic-icon-grid)
-  - [Important Notes](#important-notes)
-    - [PurgeTSS Processes Classes During Build](#purgetss-processes-classes-during-build)
-    - [Class Verification](#class-verification)
-    - [Platform-Specific Best Practices](#platform-specific-best-practices)
-  - [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
-    - [❌ Don't Use `Ti.UI.create()` with Manual Styles](#-dont-use-tiuicreate-with-manual-styles)
-    - [✅ Use `$.UI.create()` with PurgeTSS Classes](#-use-uicreate-with-purgetss-classes)
-    - [❌ Don't Mix Styles and Classes](#-dont-mix-styles-and-classes)
-    - [✅ Use Only Classes (or Only Styles)](#-use-only-classes-or-only-styles)
-  - [Summary](#summary)
-
----
-
 ## Overview
 
 When creating components dynamically in Controllers (not declaratively in XML), PurgeTSS provides two powerful methods to apply utility classes:
@@ -416,6 +379,62 @@ if (OS_IOS) {
 
 ---
 
+## Dynamic Styling with `classes` Property
+
+You can change PurgeTSS classes dynamically at runtime using the `classes` property in `applyProperties()`:
+
+```javascript
+// Toggle status styling dynamically
+function setStatus(isActive) {
+  $.statusLabel.applyProperties({
+    classes: isActive ? ['text-green-500'] : ['text-red-500'],
+    text: isActive ? L('active') : L('inactive')
+  })
+}
+```
+
+### Conditional Styling Based on State
+
+```javascript
+// Loading state button
+function setLoading(isLoading) {
+  $.submitBtn.applyProperties({
+    enabled: !isLoading,
+    title: isLoading ? L('saving') : L('save')
+  })
+}
+
+// Error state on form field
+function showFieldError(field, errorLabel, hasError) {
+  $[field].applyProperties({
+    borderColor: hasError ? '#ef4444' : '#d1d5db'
+  })
+  $[errorLabel].applyProperties({
+    visible: hasError
+  })
+}
+```
+
+### Visibility Toggle Pattern
+
+```javascript
+// Show/hide views based on state
+function setState(state) {
+  const states = ['loadingState', 'contentState', 'errorState']
+  states.forEach(s => {
+    $[s].visible = s === state
+  })
+}
+```
+
+:::tip 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
+:::
+
+---
+
 ## Anti-Patterns to Avoid
 
 ### ❌ Don't Use `Ti.UI.create()` with Manual Styles

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

@@ -6,38 +6,6 @@ The PurgeTSS grid system is a layout tool with utilities to lay out columns and
 **PurgeTSS grid does NOT work like CSS Grid.** Titanium lacks native CSS Grid support. The PurgeTSS grid system is an abstraction using `horizontal` and `vertical` layouts with percentage widths and margins.
 :::
 
-## Table of Contents
-
-- [Grid Layout System](#grid-layout-system)
-  - [Table of Contents](#table-of-contents)
-  - [Basic Structure](#basic-structure)
-  - [Column Grid](#column-grid)
-    - [`.grid-cols-{n}`](#grid-cols-n)
-    - [`.col-span-{n}`](#col-span-n)
-  - [Row Grid](#row-grid)
-    - [`.grid-rows-{n}`](#grid-rows-n)
-    - [`.row-span-{n}`](#row-span-n)
-  - [Gutter Utilities](#gutter-utilities)
-    - [Available Gap Utilities](#available-gap-utilities)
-  - [Direction Utilities](#direction-utilities)
-  - [Alignment Utilities](#alignment-utilities)
-  - [Common Layout Patterns](#common-layout-patterns)
-    - [Two-Column Layout](#two-column-layout)
-    - [Three-Column Layout](#three-column-layout)
-    - [Sidebar + Main Content](#sidebar--main-content)
-    - [Asymmetric Layout](#asymmetric-layout)
-  - [Grid System Pitfalls and Solutions](#grid-system-pitfalls-and-solutions)
-    - [Problem: Gap Breaks Percentage Widths](#problem-gap-breaks-percentage-widths)
-    - [Problem: Grid Without w-screen](#problem-grid-without-w-screen)
-    - [Problem: Missing Gap Container](#problem-missing-gap-container)
-  - [When to Use Grid vs. Manual Layout](#when-to-use-grid-vs-manual-layout)
-    - [Use Grid System When:](#use-grid-system-when)
-    - [Use Manual Layout When:](#use-manual-layout-when)
-  - [Complete Utility Reference](#complete-utility-reference)
-  - [Real-World Example](#real-world-example)
-
----
-
 ## Basic Structure
 
 This is the most basic layout for using the grid system:

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

@@ -19,56 +19,6 @@ Previous versions of PurgeTSS included several icon font libraries such as Boots
 
 :::
 
-## Table of Contents
-
-- [Icon Fonts Libraries](#icon-fonts-libraries)
-  - [Table of Contents](#table-of-contents)
-  - [Installing Official Icon Fonts](#installing-official-icon-fonts)
-  - [Using Icon Fonts in XML](#using-icon-fonts-in-xml)
-    - [Font Awesome 7](#font-awesome-7)
-    - [Material Icons](#material-icons)
-    - [Material Symbols](#material-symbols)
-    - [Framework7 Icons](#framework7-icons)
-  - [Recreating Deleted Libraries](#recreating-deleted-libraries)
-    - [Step 1: Download the Libraries](#step-1-download-the-libraries)
-    - [Step 2: Place in fonts Folder](#step-2-place-in-fonts-folder)
-    - [Step 3: Run build-fonts Command](#step-3-run-build-fonts-command)
-      - [Generated fonts.tss Example](#generated-fontstss-example)
-    - [Renaming the Style Rule Name](#renaming-the-style-rule-name)
-  - [Using Custom Font Modules](#using-custom-font-modules)
-    - [Generated Module Structure](#generated-module-structure)
-    - [Usage in Controllers](#usage-in-controllers)
-  - [The --prefix Option](#the---prefix-option)
-    - [Example with Custom Prefix](#example-with-custom-prefix)
-  - [Icon Font Best Practices](#icon-font-best-practices)
-    - [1. Use Semantic Icon Names](#1-use-semantic-icon-names)
-    - [2. Combine with Styling Classes](#2-combine-with-styling-classes)
-    - [3. Use in Navigation](#3-use-in-navigation)
-    - [4. Dynamic Icons in Controllers](#4-dynamic-icons-in-controllers)
-  - [Font Assets Folder](#font-assets-folder)
-  - [Icon Sizing and Styling](#icon-sizing-and-styling)
-  - [Common Patterns](#common-patterns)
-    - [Icon with Text](#icon-with-text)
-    - [Circular Icon Button](#circular-icon-button)
-    - [Icon Badge](#icon-badge)
-    - [Social Media Icons](#social-media-icons)
-  - [Troubleshooting](#troubleshooting)
-    - [Icons Not Displaying](#icons-not-displaying)
-    - [Wrong Icon Character](#wrong-icon-character)
-    - [Icons Different on iOS vs Android](#icons-different-on-ios-vs-android)
-  - [Vendor-Specific Notes](#vendor-specific-notes)
-    - [Font Awesome 7](#font-awesome-7-1)
-    - [Font Awesome Pro](#font-awesome-pro)
-      - [Setting Up Font Awesome Pro](#setting-up-font-awesome-pro)
-      - [Pro Icon Styles](#pro-icon-styles)
-    - [Font Awesome 7 Beta](#font-awesome-7-beta)
-      - [Setting Up Font Awesome 7 Beta](#setting-up-font-awesome-7-beta)
-      - [Testing Beta Icons](#testing-beta-icons)
-    - [Material Icons vs Material Symbols](#material-icons-vs-material-symbols)
-  - [Complete Command Reference](#complete-command-reference)
-
----
-
 ## Installing Official Icon Fonts
 
 Use the `icon-library` command to download and install official icon fonts:

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

@@ -2,38 +2,6 @@
 
 PurgeTSS must be installed globally and initialized within each Titanium Alloy project to enable its utility-first workflow.
 
-## Table of Contents
-
-- [PurgeTSS Installation \& Setup](#purgetss-installation--setup)
-  - [Table of Contents](#table-of-contents)
-  - [Prerequisites](#prerequisites)
-  - [Global Installation](#global-installation)
-  - [Initial Project Setup](#initial-project-setup)
-    - [Running PurgeTSS for the First Time](#running-purgetss-for-the-first-time)
-    - [What Happens on First Run](#what-happens-on-first-run)
-      - [1. Auto-Run Hook Setup](#1-auto-run-hook-setup)
-      - [2. purgetss Folder Structure](#2-purgetss-folder-structure)
-      - [3. app.tss Backup](#3-apptss-backup)
-  - [Creating a Fresh config.cjs](#creating-a-fresh-configcjs)
-  - [Visual Studio Code Integration](#visual-studio-code-integration)
-    - [Quick Setup with install-dependencies](#quick-setup-with-install-dependencies)
-    - [Manual Extension Setup](#manual-extension-setup)
-    - [Extension Configuration](#extension-configuration)
-    - [Tailwind Config for VS Code](#tailwind-config-for-vs-code)
-  - [LiveView Development](#liveview-development)
-    - [Enabling LiveView](#enabling-liveview)
-    - [LiveView with TiKit Components](#liveview-with-tikit-components)
-    - [LiveView Development Workflow](#liveview-development-workflow)
-    - [Common LiveView Issues](#common-liveview-issues)
-  - [First Run Example](#first-run-example)
-  - [Quick Start with Example Files](#quick-start-with-example-files)
-  - [Troubleshooting](#troubleshooting)
-    - [PurgeTSS Not Running on Compile](#purgetss-not-running-on-compile)
-    - [Classes Not Appearing in IntelliSense](#classes-not-appearing-in-intellisense)
-    - [Missing Classes Report](#missing-classes-report)
-
----
-
 ## Prerequisites
 
 :::caution Node.js 20+ Required
@@ -119,6 +87,67 @@ Alternatively, a better approach is to include your custom values in `config.cjs
 
 Every time `purgetss` runs, it copies the content of `_app.tss` to `app.tss` (if it exists).
 
+## Project Structure with PurgeTSS
+
+Show the complete folder structure highlighting PurgeTSS-specific files:
+
+```
+app/
+├── controllers/
+├── views/                        # XML views styled with PurgeTSS classes
+├── styles/
+│   ├── app.tss                   # GENERATED by PurgeTSS (Do not edit)
+│   ├── _app.tss                  # YOUR custom styles (persists across runs)
+│   └── fonts.tss                 # GENERATED by PurgeTSS build-fonts
+├── widgets/                      # Optional: reusable components
+│   └── myWidget/
+├── config.json                   # Set autoStyle: false for PurgeTSS
+└── alloy.js
+
+./purgetss/
+├── config.cjs                    # PurgeTSS theme configuration
+└── styles/
+    └── utilities.tss             # All utility classes
+```
+
+### Key Files
+
+| File                    | Role                                               | Editable?    |
+| ----------------------- | -------------------------------------------------- | ------------ |
+| `app/styles/app.tss`    | Auto-generated by PurgeTSS with only used classes  | ❌ Never edit |
+| `app/styles/_app.tss`   | Your custom styles, preserved across PurgeTSS runs | ✅ Yes        |
+| `app/styles/fonts.tss`  | Auto-generated by `purgetss build-fonts`           | ❌ Never edit |
+| `./purgetss/config.cjs` | Theme configuration, custom colors, fonts          | ✅ Yes        |
+
+### config.json for PurgeTSS
+
+```json
+{
+  "autoStyle": false
+}
+```
+
+:::caution autoStyle Must Be false
+When using PurgeTSS, set `autoStyle: false` in `config.json`. PurgeTSS handles all style generation.
+:::
+
+### PurgeTSS with Widgets
+
+If widgets use PurgeTSS utility classes, enable widget processing:
+
+```javascript
+// ./purgetss/config.cjs
+module.exports = {
+  purge: {
+    options: {
+      widgets: true  // Enable PurgeTSS class processing for widgets
+    }
+  }
+}
+```
+
+Without this setting, PurgeTSS will NOT process classes in widget files.
+
 ## Creating a Fresh config.cjs
 
 If you need to start with a fresh `config.cjs` file, delete the existing one and run:

package/skills/purgetss/references/migration-guide.md

@@ -0,0 +1,127 @@
+# Migrating to PurgeTSS
+
+Guide for migrating existing Titanium Alloy apps from manual TSS styling to PurgeTSS utility-first workflow.
+
+## Assessment Checklist
+
+Before migrating, evaluate styling in the current codebase:
+
+| Current State                                | Target State                              |
+| -------------------------------------------- | ----------------------------------------- |
+| Manual `.tss` files per controller           | PurgeTSS utility classes in XML           |
+| Inline attributes (`backgroundColor="#fff"`) | PurgeTSS classes (`bg-white`)             |
+| `id`-based styles in `app.tss`               | Class-based utility styling               |
+| Manual 2D Matrix animations                  | PurgeTSS Animation component              |
+| Platform conditionals in controllers         | PurgeTSS platform modifiers (`ios:mt-10`) |
+
+## Step 1: Initialize PurgeTSS
+
+```bash
+cd your-app
+purgetss init
+```
+
+This creates the `./purgetss/` folder with `config.cjs` and sets up the auto-run hook.
+
+## Step 2: Backup Existing Styles
+
+PurgeTSS automatically backs up your existing `app.tss` to `_app.tss`. Your custom styles are preserved and will be merged during compilation.
+
+## Step 3: Migrate Views Incrementally
+
+Migrate one view at a time. Don't try to convert everything at once.
+
+### Before (Manual TSS)
+
+```xml
+<!-- views/index.xml -->
+<View id="header">
+  <Label id="title" text="Welcome" />
+</View>
+```
+
+```tss
+/* styles/index.tss */
+"#header": { backgroundColor: "#fff", height: 60, top: 0 }
+"#title": { color: "#333", font: { fontSize: 18, fontWeight: "bold" } }
+```
+
+### After (PurgeTSS)
+
+```xml
+<!-- views/index.xml -->
+<View class="top-0 h-16 bg-white">
+  <Label class="text-lg font-bold text-gray-800" text="Welcome" />
+</View>
+```
+
+No manual TSS needed — delete the `#header` and `#title` styles.
+
+## Step 4: Remove Manual TSS Files
+
+Once a view is fully migrated to utility classes:
+
+1. Remove corresponding entries from `_app.tss`
+2. Delete any controller-specific `.tss` files (e.g., `styles/login.tss`)
+3. Run `purgetss` to regenerate `app.tss`
+
+## Common Style Translations
+
+| Manual TSS                     | PurgeTSS Class          |
+| ------------------------------ | ----------------------- |
+| `backgroundColor: "#ffffff"`   | `bg-white`              |
+| `backgroundColor: "#f3f4f6"`   | `bg-gray-100`           |
+| `color: "#1f2937"`             | `text-gray-800`         |
+| `font: { fontSize: 18 }`       | `text-lg`               |
+| `font: { fontWeight: "bold" }` | `font-bold`             |
+| `width: Ti.UI.FILL`            | `w-screen`              |
+| `height: Ti.UI.SIZE`           | `h-auto`                |
+| `height: 60`                   | `h-16` (64) or `h-(60)` |
+| `top: 0`                       | `top-0`                 |
+| `left: 16, right: 16`          | `mx-4`                  |
+| `top: 16`                      | `mt-4`                  |
+| `borderRadius: 8`              | `rounded-lg`            |
+| `opacity: 0.5`                 | `opacity-50`            |
+| `layout: "horizontal"`         | `horizontal`            |
+| `layout: "vertical"`           | `vertical`              |
+
+### Platform-Specific Translations
+
+| Manual Code                              | PurgeTSS                         |
+| ---------------------------------------- | -------------------------------- |
+| `if (OS_IOS) { view.top = 40 }`          | `class="ios:mt-10 mt-5"`         |
+| `if (OS_ANDROID) { view.elevation = 4 }` | `class="android:elevation-4"`    |
+| Tablet conditional in controller         | `class="tablet:w-6/12 w-screen"` |
+
+### Animation Translations
+
+| Manual Animation                       | PurgeTSS Animation                                      |
+| -------------------------------------- | ------------------------------------------------------- |
+| `Ti.UI.create2DMatrix()` + `animate()` | `<Animation module="purgetss.ui" class="..." />`        |
+| Manual opacity animation               | `class="close:opacity-0 open:opacity-100 duration-300"` |
+| Manual scale animation                 | `class="close:scale-100 open:scale-95 duration-150"`    |
+
+## Migration Pitfalls
+
+| Pitfall                          | Consequence                       | Prevention                       |
+| -------------------------------- | --------------------------------- | -------------------------------- |
+| Editing `app.tss` directly       | Changes overwritten on next build | Use `_app.tss` for custom styles |
+| Migrating styles without testing | Broken layouts                    | Test each view on both platforms |
+| Using `flex-row`/`justify-*`     | Classes don't exist               | Use `horizontal`/`vertical`      |
+| Using `p-*` on container Views   | No padding on containers          | Use `m-*` on children            |
+| Forgetting `autoStyle: false`    | Style conflicts                   | Set in `config.json`             |
+| Using `w-[100px]` syntax         | Wrong bracket style               | Use `w-(100px)` with parentheses |
+
+## Rollback Strategy
+
+For each view migration:
+
+1. **Create a branch** before starting
+2. **Migrate one view** completely
+3. **Test thoroughly** on both iOS and Android
+4. **Keep legacy styles** in `_app.tss` until stable
+5. **Delete legacy styles** only after confirming utility classes work
+
+:::tip Migration Order
+Start with simple views (static content, few elements) and progress to complex ones (forms, lists). This builds familiarity with PurgeTSS classes before tackling harder views.
+:::

package/skills/purgetss/references/opacity-modifier.md

@@ -6,40 +6,6 @@ The opacity modifier allows you to add transparency to **ANY color property** by
 You can add an **opacity modifier to ANY of the available color properties** by adding an **opacity value** between 0 and 100 to the end of the color name separated by a slash ( / ).
 :::
 
-## Table of Contents
-
-- [Opacity Modifier](#opacity-modifier)
-  - [Table of Contents](#table-of-contents)
-  - [Basic Syntax](#basic-syntax)
-  - [How It Works](#how-it-works)
-  - [Usage in XML](#usage-in-xml)
-    - [Background Colors](#background-colors)
-    - [Text Colors](#text-colors)
-    - [Border Colors](#border-colors)
-    - [All Color Properties](#all-color-properties)
-  - [Usage with `@apply` Directive](#usage-with-apply-directive)
-  - [Complete List of Supported Color Properties](#complete-list-of-supported-color-properties)
-    - [Background Properties](#background-properties)
-    - [Text Properties](#text-properties)
-    - [Border Properties](#border-properties)
-    - [UI Element Properties](#ui-element-properties)
-    - [Navigation Properties](#navigation-properties)
-    - [Indicator Properties](#indicator-properties)
-    - [Tint Properties](#tint-properties)
-    - [Miscellaneous Properties](#miscellaneous-properties)
-  - [Opacity Value Reference](#opacity-value-reference)
-  - [Common Patterns](#common-patterns)
-    - [Hover/Active States](#hoveractive-states)
-    - [Disabled Appearance](#disabled-appearance)
-    - [Overlay/Backdrop](#overlaybackdrop)
-    - [Glassmorphism Effect](#glassmorphism-effect)
-    - [Gradient Fades](#gradient-fades)
-  - [Limitations](#limitations)
-  - [Performance Considerations](#performance-considerations)
-  - [Combining with Arbitrary Colors](#combining-with-arbitrary-colors)
-
----
-
 ## Basic Syntax
 
 ```xml