purgetss

PurgeTSS Expert

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.

Step 1 — Open the relevant reference files

Task involves	Required reading
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
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
Animations	references/animation-system.md

Step 2 — 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 48px [source: references/class-index.md]"

Step 3 — 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

Project Detection

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

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

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

🚨 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

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

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

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

🚨 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="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

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

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

<!-- WRONG: my-1 creates vertical pins → Switch stretches to fill parent height -->
<Switch class="my-1 mr-2" />

<!-- CORRECT: h-auto prevents vertical stretch -->
<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-(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

🚨 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

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, 416-property table, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
• Class Categories - Complete prefix inventory by category (layout, colors, typography, states, etc.)
• Dynamic Component Creation - $.UI.create() and Alloy.createStyle() for creating components in Controllers (READ FIRST for dynamic components)
• Appearance Module - Light/Dark/System mode switching with persistence (v7.5.3)
• Semantic Colors - Titanium semantic colors for Light/Dark mode via semantic command (v7.6.0)

Setup & Configuration

• Installation & Setup - First run, VS Code, LiveView
• CLI Commands - All purgetss commands
• 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)

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:
• 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 for launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace assets (v7.6.0)
• Multi-Density Images - images command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)

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 inheritance, utility classes, implementation rules, complex UI example

Release Notes

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

💡 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