Use when working with PurgeTSS, Titanium's utility-first styling toolkit — styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, grid layouts, icon fonts, or TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, invoke BEFORE writing ANY styling code. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists.
Use when working with PurgeTSS, Titanium's utility-first styling toolkit — styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, grid layouts, icon fonts, or TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, invoke BEFORE writing ANY styling code. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists.
Utility-first styling toolkit for Titanium/Alloy mobile apps.
Required workflow (read before responding)
The SKILL.md alone is an index of references. The detail you need to give accurate answers lives in the reference files. Reading this SKILL.md is not enough.
Not detected → Does NOT suggest PurgeTSS utility classes, does NOT recommend $.UI.create(), does NOT reference PurgeTSS-specific patterns
Core Workflow
Setup: purgetss create 'name' or purgetss init for existing projects
Build: Write XML with utility classes → PurgeTSS auto-generates app.tss
Configure: Customize via purgetss/config.cjs
Project Structure
./purgetss/
├─ fonts/ # Custom font files (.ttf, .otf)
├─ styles/
│ ├─ definitions.css # For VS Code IntelliSense
│ └─ utilities.tss # All PurgeTSS utility classes
└─ 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
⚠️ CRITICAL: app.tss IS AUTO-GENERATEDapp.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.
️ℹ️ 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:
Scans XMLs and Controllers for used classes
Regenerates app.tss from scratch
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
🚨 ALWAYS CHECK app.tss FOR ERRORS
At the end of every generated app.tss, look for this section:
// 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:
You have a typo in your class name
You're using a class that doesn't exist in PurgeTSS
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
️ℹ️ 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.
💡 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
💡 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:
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
🚨 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):
// ❌ BAD - Adds Ti.UI.iOS to Android project
"#mainWindow": {
statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
CORRECT - Use platform modifiers in TSS:
// ✅ GOOD - Only adds to iOS
"#mainWindow[platform=ios]": {
statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}
OR use PurgeTSS platform modifier classes:
<!-- ✅ GOOD - Platform-specific classes --><Windowclass="ios:status-bar-light android:status-bar-dark">
Properties that ALWAYS require platform modifiers:
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.
💡 LAYOUT TIP: EDGE PINNING
If opposite margins cause a Label, Button, or Switch to stretch unexpectedly, it is due to Titanium's Edge Pinning rule (2 opposite pins = computed dimension). This applies to any component whose default size is Ti.UI.SIZE.
mt-* + mb-* or my-* can stretch the component vertically. Add h-auto.
ml-* + mr-* or mx-* can stretch the component horizontally. Add w-auto.
If margins affect both axes, use wh-auto to force SIZE for both width and height.
Constant properties like keyboard-type-*, return-key-type-* have dedicated classes
Search the project when unsure
# 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
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 - Naming conventions, prohibited classes, prefix inventory, verification commands (LOAD FIRST when unsure about a class)
Migration Guide - Migrating existing apps from manual TSS to PurgeTSS
Values and Units - How ti.ui.defaultunit in tiapp.xml interprets the unitless numeric values PurgeTSS writes (foundational concept for spacing, sizes, typography)
