--- name: purgetss description: "Titanium PurgeTSS utility-first styling toolkit. Use when styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, using grid layouts, setting up icon fonts, or working with TSS styles. Never suggest other CSS framework classes - verify in class-index.md first." argument-hint: "[class-name]" allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *) --- # PurgeTSS Expert Utility-first styling toolkit for Titanium\/Alloy mobile apps. ## Project Detection :::info AUTO-DETECTS PURGETSS PROJECTS This skill automatically detects PurgeTSS usage when invoked and provides utility-first styling guidance. **Detection occurs automatically** - no manual command needed. **PurgeTSS project indicators:** - `purgetss\/` folder - `purgetss\/config.cjs` configuration file - `purgetss\/styles\/utilities.tss` utility classes - `app\/styles\/app.tss` (auto-generated) **Behavior based on detection:** - **PurgeTSS detected** → Provides PurgeTSS-specific guidance, recommends utility classes, suggests `$.UI.create()` for dynamic components - **Not detected** → Does NOT suggest PurgeTSS utility classes, does NOT recommend `$.UI.create()`, does NOT reference PurgeTSS-specific patterns ::: ## Core Workflow 1. **Setup**: `purgetss create 'name'` or `purgetss init` for existing projects 2. **Build**: Write XML with utility classes → PurgeTSS auto-generates `app.tss` 3. **Configure**: Customize via `purgetss\/config.cjs` ## Project Structure ```bash .\/purgetss\/ ├─ fonts\/ # Custom font files (.ttf, .otf) ├─ styles\/ │ ├─ definitions.css # For VS Code IntelliSense │ └─ utilities.tss # All PurgeTSS utility classes (renamed from tailwind.tss in v7.3) └─ config.cjs # Theme configuration .\/app\/styles\/ ├─ app.tss # AUTO-GENERATED - DO NOT EDIT DIRECTLY └─ _app.tss # YOUR CUSTOM STYLES (persists across runs) ``` ### Understanding `app.tss` vs `_app.tss` :::warning CRITICAL: app.tss IS AUTO-GENERATED **`app.tss` is ALWAYS regenerated** every time the app compiles. PurgeTSS scans ALL XMLs and Controllers for utility classes, then generates a fresh `app.tss` containing only the classes actually used. **NEVER edit `app.tss` directly** - your changes WILL be overwritten on the next build. ::: :::info THE `_app.tss` BACKUP FILE On **first run**, PurgeTSS backs up your original `app.tss` to `_app.tss`. **`_app.tss` is your custom styles file** - it persists across all PurgeTSS runs. Every build, PurgeTSS: 1. Scans XMLs and Controllers for used classes 2. Regenerates `app.tss` from scratch 3. Copies `_app.tss` content into the generated `app.tss` Better approach: define custom classes in `config.cjs` instead of `_app.tss`. ::: ### Checking for Unused\/Unsupported Classes :::danger ALWAYS CHECK `app.tss` FOR ERRORS At the **end of every generated `app.tss`**, look for this section: ```tss \/\/ Unused or unsupported classes \/\/ .my-typo-class \/\/ .non-existent-utility ``` **These are classes used in your XMLs or Controllers that have NO definition anywhere:** - Not in `utilities.tss` (generated from PurgeTSS utilities) - Not in `_app.tss` (your custom styles) - Not in any other `.tss` file in the `styles\/` folder **This means:** 1. You have a **typo** in your class name 2. You're using a class that **doesn't exist** in PurgeTSS 3. You need to **define the class** in `_app.tss` or `config.cjs` **As part of any analysis, ALWAYS check the end of `app.tss` and report any unused\/unsupported classes to the user!** ::: ### How `utilities.tss` Works :::info UTILITIES.TSS REGENERATION `.\/purgetss\/styles\/utilities.tss` contains ALL available PurgeTSS utility classes. **It regenerates when `.\/purgetss\/config.cjs` changes** - this is where you define: - Custom colors - Custom spacing scales - Ti Element styles - Any project-specific utilities If a class appears in "Unused or unsupported classes" in `app.tss`, it means it's truly not defined anywhere - not even in your `config.cjs` customizations. ::: ## Quick Start ```bash purgetss create 'MyApp' -d -v fa # -d: Install dev dependencies (ESLint, Tailwind) # -v: Copy icon fonts (fa, mi, ms, f7) ``` ## What's New in v7.3.x - `tailwind.tss` was renamed to `utilities.tss` (update any scripts or references). - XML syntax validation now runs before processing and reports line-level errors (for example, missing `<`). - `deviceInfo()` works in both Alloy and Classic (no `Alloy.isTablet`\/`Alloy.isHandheld` dependency). - Node.js 20+ is required. - Font Awesome 7 is supported, including the new `--fa:` CSS custom properties. - VS Code: `KevinYouu.tailwind-raw-reorder-tw4` is recommended for class ordering. - If you hit issues after upgrading, try: `npm uninstall -g purgetss && npm install -g purgetss`. :::tip NEW PROJECT: Clean Up Default app.tss For new projects created with `purgetss create`, the default `app\/styles\/app.tss` contains a large commented template. **You can safely DELETE this file** - PurgeTSS will regenerate it on the first build with only the classes you actually use, and create a clean `_app.tss` backup. This prevents carrying around unnecessary commented code and ensures a fresh start. ::: ## Critical Rules (Low Freedom) ### ⭐ PREFER `$.UI.create()` for Dynamic Components :::tip RECOMMENDED FOR DYNAMIC COMPONENTS When creating components dynamically in Controllers, **use `$.UI.create()` instead of `Ti.UI.create()`** to get full PurgeTSS utility class support: ```javascript \/\/ ✅ RECOMMENDED - Full PurgeTSS support const view = $.UI.create('View', { classes: ['w-screen', 'h-auto', 'bg-white', 'rounded-lg'] }) \/\/ ❌ AVOID - No PurgeTSS classes const view = Ti.UI.createView({ width: Ti.UI.FILL, height: Ti.UI.SIZE, backgroundColor: '#ffffff', borderRadius: 8 }) ``` See [Dynamic Component Creation](references\/dynamic-component-creation.md) for complete guide. ::: ### 🚨 RESPECT USER FILES **NEVER delete any existing `.tss` files** (like `index.tss`, `detail.tss`) or other project files without explicit user consent. **How to handle migration to PurgeTSS:** 1. **ONLY** replace custom classes with PurgeTSS utility classes if the user explicitly requests it. 2. When requested: - Analyze the definitions in the existing `.tss` files. - Update the XML\/Controller components with equivalent PurgeTSS utility classes. - **WAIT** for user confirmation before suggesting or performing any file deletion. 3. If the user prefers keeping manual `.tss` files for specific styles, respect that choice and only use PurgeTSS for new or requested changes. ### 🚨 NO FLEXBOX - Titanium Doesn't Support It :::danger FLEXBOX CLASSES DO NOT EXIST The following are **NOT supported**: - ❌ `flex`, `flex-row`, `flex-col` - ❌ `justify-between`, `justify-center`, `justify-start`, `justify-end` - ❌ `items-center` for alignment (exists but sets `width\/height: FILL`) **Use Titanium layouts instead:** - ✅ `horizontal` - Children left to right - ✅ `vertical` - Children top to bottom - ✅ Omit layout class - Defaults to `composite` (absolute positioning) :::tip CRITICAL: Understanding Layout Composition When building complex UIs, carefully choose the layout mode for each container: **`vertical`** - Stack elements top to bottom (most common): ```xml Item 1<\/View> Item 2<\/View> Item 3<\/View> <\/ScrollView> ``` **`horizontal`** - Arrange elements left to right: ```xml <\/View> ``` **`composite`** (default) - Absolute positioning with `top`, `left`, etc.: ```xml <\/View> ``` **Common Issue:** If you see elements appearing in unexpected positions (e.g., a header bar "behind" content), check if parent containers have conflicting layout modes. Each container's layout affects its direct children only. ::: ### 🚨 PLATFORM-SPECIFIC PROPERTIES REQUIRE MODIFIERS :::danger CRITICAL: Platform-Specific Properties Require Modifiers Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties WITHOUT platform modifiers causes cross-platform compilation failures. **WRONG - Adds iOS code to Android (causes failure):** ```tss \/\/ ❌ BAD - Adds Ti.UI.iOS to Android project "#mainWindow": { statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT } ``` **CORRECT - Use platform modifiers in TSS:** ```tss \/\/ ✅ GOOD - Only adds to iOS "#mainWindow[platform=ios]": { statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT } ``` **OR use PurgeTSS platform modifier classes:** ```xml ``` **Properties that ALWAYS require platform modifiers:** - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, `systemButton` - Android: `actionBar` configuration - ANY `Ti.UI.iOS.*`, `Ti.UI.Android.*` constant **When suggesting platform-specific code:** 1. Check if user's project supports that platform 2. ALWAYS use `[platform=ios]` or `[platform=android]` TSS modifier 3. OR use PurgeTSS platform classes like `ios:bg-blue-500` **For complete reference on platform modifiers, see** [Platform Modifiers](references\/platform-modifiers.md). ::: ### Other Mandatory Rules - **NO `p-` padding classes**: Titanium does NOT support a native `padding` property on `View`, `Window`, `ScrollView`, or `TableView`. Always use **margins on children** (`m-`) to simulate internal spacing. - **View defaults to `SIZE`**: Use `w-screen`\/`h-screen` to fill space when needed. - **`rounded-full`**: To get a perfect circle, use `rounded-full-XX` (where XX is the width\/height of the square element). - **`rounded-full-XX` includes size**: These classes already set `width`, `height`, and `borderRadius`. Do **not** add `w-XX h-XX`\/`wh-XX` unless you need to override. - **`m-xx` on FILL elements**: Adding `m-4` to a `w-screen` element pins it to all four edges (top, bottom, left, right). This will **stretch the component vertically** to fill the parent unless you explicitly add `h-auto` (`Ti.UI.SIZE`) to constrain it to its content. - **`w-XX` + `h-XX` → `wh-XX`**: If both width and height use the same scale value, prefer a single `wh-XX` (order doesn't matter: `w-10 h-10` and `h-10 w-10` are equivalent). - **Use `wh-` shortcuts**: PurgeTSS provides a complete scale of combined width\/height utilities: - **Numeric Scale**: `wh-0` to `wh-96` (e.g., `wh-16` sets both to 64px). - **Fractions**: `wh-1\/2`, `wh-3\/4`, up to `wh-11\/12` for proportional sizing. - **Special Values**: `wh-auto` (explicit `SIZE`), `wh-full` (`100%`), and `wh-screen` (`FILL`). - Using these instead of separate `w-` and `h-` classes improves XML readability and reduces generated TSS size. :::tip LAYOUT TIP: EDGE PINNING If using margins (`m-`) causes your `Label` or `Button` to stretch unexpectedly, it is due to Titanium's **Edge Pinning** rule (2 opposite pins = computed dimension). Use the `wh-auto` class to explicitly force `SIZE` behavior and prevent stretching. ::: - **NEVER add `composite` class explicitly** - That's the default, use `horizontal`\/`vertical` when needed - **Arbitrary values use parentheses**: `w-(100px)`, `bg-(#ff0000)` - NO square brackets - **`mode: 'all'` required** in `config.cjs` for Ti Elements styling - **Classes use `kebab-case`**: `.my-class`, IDs use `camelCase`: `#myId` ## Common Anti-Patterns **WRONG:** ```xml ``` **CORRECT:** ```xml ``` **WRONG (Dynamic Components):** ```javascript \/\/ Manual styling with Ti.UI.create() const view = Ti.UI.createView({ width: Ti.UI.FILL, backgroundColor: '#fff', borderRadius: 8 }) ``` **CORRECT (Dynamic Components):** ```javascript \/\/ PurgeTSS classes with $.UI.create() const view = $.UI.create('View', { classes: ['w-screen', 'bg-white', 'rounded-lg'] }) ``` ## Class Verification Workflow :::danger CRITICAL: VERIFY CLASSES BEFORE SUGGESTING **NEVER guess or hallucinate classes based on other CSS Frameworks knowledge!** PurgeTSS shares naming with some CSS Frameworks but has DIFFERENT classes for Titanium. Always verify a class exists before suggesting it. ::: ### Verification Steps 1. **Check if it's a KNOWN anti-pattern** - See [PROHIBITED Classes](references\/class-index.md#prohibited-tailwind-classes-that-do-not-exist) - Common mistakes: `flex-row`, `justify-between`, `p-4` on Views (p-* not supported on Views) 2. **Check the Class Index** - See [Class Index](references\/class-index.md) for available patterns - Constant properties like `keyboard-type-*`, `return-key-type-*` have dedicated classes 3. **Search the project when unsure** ```bash # Search for a class pattern in the project's utilities.tss grep -E "keyboard-type-" .\/purgetss\/styles\/utilities.tss grep -E "return-key-type-" .\/purgetss\/styles\/utilities.tss grep -E "^'bg-" .\/purgetss\/styles\/utilities.tss ``` 4. **After making changes** - Check `app.tss` for "Unused or unsupported classes" section at the end - Report any typos or non-existent classes to the user ### What HAS Classes vs What DOESN'T | Has Classes in PurgeTSS | Does NOT Have Classes | | ----------------------- | ------------------------------------- | | `keyboard-type-email` | `hintText` (use attribute) | | `return-key-type-next` | `passwordMask` (use attribute) | | `text-center` | `autocorrect` (use attribute) | | `bg-blue-500` | `autocapitalization` (use attribute) | | `w-screen` | `flex-row` → use `horizontal` | | `wh-16` | `justify-between` → use margins | | `rounded-lg` | `w-full` → use `w-screen` | | `m-4`, `gap-4` | `p-4` on View → use `m-4` on children | :::tip When in doubt, prefer using the search command above to verify. It's better to spend 5 seconds verifying than suggesting a class that doesn't exist and will appear in the "unused classes" warning. ::: ## Reference Guides Load these only when needed: ### Essential References - **[Class Index](references\/class-index.md)** - Quick patterns, prohibited classes, verification commands (LOAD FIRST when unsure about a class) - **[Dynamic Component Creation](references\/dynamic-component-creation.md)** - `$.UI.create()` and `Alloy.createStyle()` for creating components in Controllers (READ FIRST for dynamic components) ### Setup & Configuration - [Installation & Setup](references\/installation-setup.md) - First run, VS Code, LiveView - [CLI Commands](references\/cli-commands.md) - All `purgetss` commands - [Migration Guide](references\/migration-guide.md) - Migrating existing apps from manual TSS to PurgeTSS ### Customization - [Deep Customization](references\/customization-deep-dive.md) - config.cjs, colors, spacing, Ti Elements - [Custom Rules](references\/custom-rules.md) - Styling Ti Elements, IDs, classes - [Apply Directive](references\/apply-directive.md) - Extracting utility combinations - [Configurable Properties](references\/configurable-properties.md) - All 80+ customizable properties ### Layout & Styling - **[UI\/UX Design Patterns](references\/ui-ux-design.md)** - Complete guide to mobile UI components with PurgeTSS (cards, lists, forms, buttons, navigation, modals, accessibility) - [Grid Layout System](references\/grid-layout.md) - 12-column grid, responsive layouts - [Smart Mappings](references\/smart-mappings.md) - How gap, shadows, and grid work under the hood - [Arbitrary Values](references\/arbitrary-values.md) - Parentheses notation for custom values - [Platform Modifiers](references\/platform-modifiers.md) - ios:, android:, tablet:, handheld: - [Opacity Modifier](references\/opacity-modifier.md) - Color transparency with \/50 syntax - [Titanium Resets](references\/titanium-resets.md) - Default styles for Ti elements ### Performance - [Performance Tips](references\/performance-tips.md) - Optimizing PurgeTSS apps (bridge crossings, ListView, animations) ### Components - [TiKit UI Components](references\/tikit-components.md) - Ready-to-use Alerts, Avatars, Buttons, Cards, Tabs built with PurgeTSS ### Fonts & Animations - [Icon Fonts](references\/icon-fonts.md) - Font Awesome 7, Material Icons, custom icon libraries - [Animation Component](references\/animation-system.md) - Declarative `` API :::tip TEXT FONTS (Google Fonts, Roboto, etc.) For text fonts, see [CLI Commands → build-fonts](references\/cli-commands.md#purgetss-build-fonts-alias-bf). ::: ## Examples For complete WRONG vs CORRECT examples including: - Titanium layout patterns (horizontal, vertical, composite) - Grid with percentages - Gap usage - Manual .tss anti-patterns - Dynamic component creation with `$.UI.create()` and `Alloy.createStyle()` See [EXAMPLES.md](references\/EXAMPLES.md) and [Dynamic Component Creation](references\/dynamic-component-creation.md) ## Related Skills For tasks beyond styling, use these complementary skills: | Task | Use This Skill | | -------------------------------------------- | -------------- | | Project architecture, services, controllers | `ti-expert` | | Complex UI components, ListViews, gestures | `ti-ui` | | Alloy MVC concepts, data binding, TSS syntax | `alloy-guides` | | Native features (camera, location, push) | `ti-howtos` |