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

./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

:::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:

// 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

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

• utilities.tss is the current generated utilities file (update any scripts or references that still use the old filename).
• 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:

// ✅ 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 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):

<ScrollView class="vertical">
  <View class="mb-4">Item 1</View>
  <View class="mb-4">Item 2</View>
  <View>Item 3</View>
</ScrollView>

horizontal - Arrange elements left to right:

<View class="horizontal w-screen">
  <Label text="Left" />
  <View class="w-screen" />  <!-- Spacer -->
  <Label text="Right" />
</View>

composite (default) - Absolute positioning with top, left, etc.:

<View class="h-screen w-screen">
  <View class="wh-12 absolute left-0 top-0 bg-red-500" />
  <View class="wh-12 absolute bottom-0 right-0 bg-blue-500" />
</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):

// ❌ 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 -->
<Window class="ios:status-bar-light android:status-bar-dark">

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. :::

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 opposite margins cause a Label or Button to stretch unexpectedly, it is due to Titanium's Edge Pinning rule (2 opposite pins = computed dimension).

• 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. :::

• 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:

<View class="flex-row justify-between">  <!-- Flexbox doesn't exist -->
<View class="p-4">  <!-- No padding on Views -->
<View class="composite">  <!-- Never add composite explicitly -->

CORRECT:

<View class="horizontal">
<View class="m-4">  <!-- Use margins on children -->
<View>  <!-- Omit layout = composite by default -->

WRONG (Dynamic Components):

// Manual styling with Ti.UI.create()
const view = Ti.UI.createView({
  width: Ti.UI.FILL,
  backgroundColor: '#fff',
  borderRadius: 8
})

CORRECT (Dynamic Components):

// 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
   • Common mistakes: flex-row, justify-between, p-4 on Views (p-* not supported on Views)

2. Check the Class Index

   • See Class Index for available patterns
   • Constant properties like keyboard-type-*, return-key-type-* have dedicated classes

3. 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
   

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

:::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 - Quick patterns, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
• Dynamic Component Creation - $.UI.create() and Alloy.createStyle() for creating components in Controllers (READ FIRST for dynamic components)

Setup & Configuration

• Installation & Setup - First run, VS Code, LiveView
• CLI Commands - All purgetss commands
• Migration Guide - Migrating existing apps from manual TSS to PurgeTSS

Customization

• Deep Customization - config.cjs, colors, spacing, Ti Elements
• Custom Rules - Styling Ti Elements, IDs, classes
• Apply Directive - Extracting utility combinations
• Configurable Properties - All 80+ customizable properties

Layout & Styling

• UI/UX Design Patterns - Complete guide to mobile UI components with PurgeTSS (cards, lists, forms, buttons, navigation, modals, accessibility)
• Grid Layout System - 12-column grid, responsive layouts
• Smart Mappings - How gap, shadows, and grid work under the hood
• Arbitrary Values - Parentheses notation for custom values
• Platform Modifiers - ios:, android:, tablet:, handheld:
• Opacity Modifier - Color transparency with /50 syntax
• Titanium Resets - Default styles for Ti elements

Performance

• Performance Tips - Optimizing PurgeTSS apps (bridge crossings, ListView, animations)

Components

• TiKit UI Components - Ready-to-use Alerts, Avatars, Buttons, Cards, Tabs built with PurgeTSS

Fonts & Animations

• Icon Fonts - Font Awesome 7, Material Icons, custom icon libraries
• Animation Component - Declarative <Animation> API

:::tip TEXT FONTS (Google Fonts, Roboto, etc.) For text fonts, see CLI Commands → build-fonts. :::

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 and Dynamic Component Creation

Related Skills

For tasks beyond styling, use these complementary skills: