PurgeTSS Expert

PurgeTSS is a utility-first styling toolkit for Titanium Alloy and a standalone asset/CommonJS generator for Alloy and Classic projects. The project layout determines which half of the toolkit is valid.

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.

Step 1 — Detect the project type

Before recommending a command, class, output path, $.UI.create(), TSS file, or build hook, determine whether the project is Alloy (app/views/, app/controllers/, app/styles/) or Classic (Resources/ without the Alloy tree).

Alloy: utility classes and every standalone command are available.
Classic: only the supported standalone commands are available. Do not introduce app/, alloy.jmk, generated TSS, utility classes, or $.UI.create().

Step 2 — Open the relevant reference files

| Task involves | Required reading | |---|---| | Alloy vs. Classic support or output paths | references/classic-projects.md, references/cli-commands.md | | Setup, auto-purge, or watch diagnostics | references/installation-setup.md, references/cli-commands.md | | Choosing utility classes | references/class-index.md | | Layout (horizontal/vertical/composite, grid) | references/grid-layout.md, references/ui-ux-design.md | | Dynamic components in controllers | references/dynamic-component-creation.md | | App branding or artwork geometry | references/app-branding.md, references/cli-commands.md | | SVG / multi-density image assets | references/svg-pipeline.md, references/multi-density-images.md | | Custom values / arbitrary syntax | references/arbitrary-values.md | | Platform-specific styles (ios:, android:) | references/platform-modifiers.md | | Dark/Light mode | references/semantic-colors.md, references/appearance-module.md | | Apply directive / class extraction | references/apply-directive.md | | Custom or icon fonts | references/custom-fonts.md, references/icon-fonts.md | | Animations in Alloy | references/animation-system.md, references/animation-advanced.md | | purgetss.ui in Classic | references/purgetss-ui-classic.md, references/classic-projects.md |

Step 3 — Output contract

Every utility class you suggest and every styling pattern you describe MUST be backed by a citation in the form:

[source: references/<file>.md]

Example: "Use wh-12 to set width and height to 48 [source: references/class-index.md]"

Step 4 — If you must answer from memory

If you write a claim without having read the reference that backs it, prepend FROM_MEMORY (unverified): to that claim. Do not hide it.

Banned behaviors

❌ Writing utility classes "from memory" without citing any reference
❌ Confusing PurgeTSS classes with Tailwind — they share naming but differ
❌ Marking the answer complete without listing which reference files you read
❌ Suggesting a class without first verifying it exists in class-index.md
❌ Applying Alloy utility classes, generated TSS, alloy.jmk, or $.UI.create() to a Classic project

Project Detection and Mode Selection

️ℹ️ 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 indicators:

purgetss/ folder

purgetss/config.cjs configuration file

purgetss/styles/utilities.tss utility classes

A generated app/styles/app.tss whose header names PurgeTSS

app/lib/purgetss.{ui,colors,fonts}.js or Resources/lib/purgetss.{ui,colors,fonts}.js

app/styles/app.tss by itself is not proof: ordinary Alloy projects can have that file.

Behavior based on detection and layout:

Alloy + PurgeTSS utility lifecycle detected → Provides utility-class guidance and may suggest $.UI.create() for dynamic components

Classic + PurgeTSS standalone command detected/requested → Provides only asset, color, font, branding, or CommonJS command guidance with Resources/ destinations

Not detected → Does NOT suggest PurgeTSS utility classes, does NOT recommend $.UI.create(), does NOT reference PurgeTSS-specific patterns

Core Workflows

Alloy utility-class workflow

Setup: purgetss create 'name' or purgetss init for an existing Alloy project.
Build: Write Alloy XML/controller classes; PurgeTSS generates app/styles/app.tss.
Configure: Customize utilities through purgetss/config.cjs.

Classic standalone workflow

Run only a command marked Classic-compatible in Classic Project Support. Generated files are ordinary Titanium resources under Resources/; the app does not need a PurgeTSS hook or runtime dependency.

Alloy Utility 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-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.

️ℹ️ 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.

Alloy Quick Start

purgetss create 'MyApp' -d -v fa
# -d: Install dev dependencies (ESLint, Tailwind)
# -v: Copy icon fonts (fa, mi, ms, f7)

💡 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)

⭐ ALLOY ONLY: 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:
// ✅ 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 (full workflow and translation tables in adopting-purgetss.md):

ONLY replace custom classes with PurgeTSS utility classes if the user explicitly requests it.
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.
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

🚨 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)

💡 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="First" />
  <Label class="ml-4" text="Second" />  
</View>
composite (default) - Absolute positioning with top, left, etc. (to pin one child left and another right, use a composite parent with left-0 / right-0):
<View class="h-screen w-screen">
  <View class="wh-12 left-0 top-0 bg-red-500" />
  <View class="wh-12 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

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

<Window class="status-bar-light">


<Window class="ios:bg-white android:bg-gray-100">
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:

Check if user's project supports that platform

ALWAYS use [platform=ios] or [platform=android] TSS modifier

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: On its own it is a fixed 8×8 circle (width: 8, height: 8, borderRadius: 4). For any other size, use rounded-full-XX (where XX is the spacing-scale size 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.

<Switch class="my-1 mr-2" />


<Switch class="my-1 mr-2 h-auto" />
<Label class="my-1 ml-2 h-auto" text="Option" />

NEVER add composite class explicitly - That's the default, use horizontal/vertical when needed
Arbitrary values use parentheses: w-(100), bg-(#ff0000) - NO square brackets. A unitless value is resolved through ti.ui.defaultunit (see values-and-units.md); w-(100px) is explicit pixels, valid again since v7.18.0 after stopping the build from v7.8.0 through v7.17.1
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

🚨 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

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)
Check the Class Index
- See Class Index for available patterns
- 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 | flex-row → use horizontal | | bg-blue-500 | justify-between → use positioning | | w-screen (Ti.UI.FILL), w-full ('100%') | p-4 on View → use m-4 on children | | wh-16, rounded-lg, m-4, gap-4 | | | autocorrect, autocorrect-false | | | autocapitalization-text-none (also normal-case, uppercase, capitalize, sentences) | |

💡 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)
Class Index — Properties (A–Z) - Every Titanium property with the class families that set it, generated from utilities.tss
Class Categories - Every class family grouped by kind of value: colors, dimensions, constants, booleans
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
Color Commands - semantic, shades and color-module: Light/Dark semantic colors, palettes in config.cjs, and the CommonJS color module
Adopting PurgeTSS - Moving an existing Alloy app from hand-written .tss files to utility classes: the style-priority trap, view-by-view workflow, and property-to-class translation tables
Migration Guide - Upgrading between PurgeTSS versions (v7.2.6 → v7.18.0): breaking changes and what to review after each upgrade
Values and Units - How ti.ui.defaultunit in tiapp.xml interprets the unitless numeric values PurgeTSS writes (foundational concept for spacing, sizes, typography)

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

Appearance & Theming

Appearance Module - Light/Dark/System mode switching with persistence (v7.5.3)
Semantic Colors - semantic command + runtime usage for Light/Dark mode (v7.6.0)

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:, and stacked ios:tablet: (v7.18.0)
Opacity Modifier - Color transparency with /50 syntax
Titanium Resets - Default styles for Ti elements
iOS Large Titles - Best practice for iOS Large Title navigation

App Assets

App Branding - brand command: 14 pieces, per-piece config, selection, optimization, launch assets, FCM notification icon, and troubleshooting
Brand Padding & Geometry - Per-piece padding, master sizing, splash sizing rule, rounded non-icon artwork (v7.16.0), and adaptive-mask math for brand
Launch Background - Carrying brand.background into the iOS LaunchScreen and a launcher-only Android theme (--notes output)
Multi-Density Images - images command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
SVG Pipeline - SVG-aware compile-time image pipeline: .svg refs + numeric w-*/h-* classes compile to 8 density PNGs; images.files/images.autoSync (v7.11.0–v7.11.1)

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

Custom Fonts - build-fonts command for Google Fonts, brand typefaces, and community icon fonts (.ttf + .css)
Icon Fonts - The 4 official families (Font Awesome 7, Material Icons, Material Symbols, Framework7) — variant tables + icon-library install flow + recreating removed libraries
Animation System - 15 methods including collision detection, transitions, and sequential animations
Animation Advanced - Property forwarding, runtime rules, utility classes, and platform behavior
PurgeTSS UI in Classic - Native JavaScript setup, public exports, animation objects, cleanup, and platform notes

Release Notes

Version History - Release-by-release feature additions and behavior changes (v7.4.0 → v7.18.0)

💡 TEXT FONTS (Google Fonts, Roboto, etc.) For text fonts, see Custom 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:

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