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

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

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

_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

_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

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

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

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

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

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

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

xml

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

xml

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

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

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

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

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

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

xml

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

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

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

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

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

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`

purgetss

NPX Install

Tags

SKILL.md Content

PurgeTSS Expert

Project Detection

Core Workflow

Project Structure

Understanding
`app.tss`
vs
`_app.tss`

Checking for Unused/Unsupported Classes

How
`utilities.tss`
Works

Quick Start

What's New in v7.3.x

Critical Rules (Low Freedom)

⭐ PREFER
`$.UI.create()`
for Dynamic Components

🚨 RESPECT USER FILES

🚨 NO FLEXBOX - Titanium Doesn't Support It

🚨 PLATFORM-SPECIFIC PROPERTIES REQUIRE MODIFIERS

Other Mandatory Rules

Common Anti-Patterns

Class Verification Workflow

Verification Steps

What HAS Classes vs What DOESN'T

Reference Guides

Essential References

Setup & Configuration

Customization

Layout & Styling

Performance

Components

Fonts & Animations

Examples

Related Skills

purgetss

NPX Install

Tags

SKILL.md Content

PurgeTSS Expert

Project Detection

Core Workflow

Project Structure

Understanding app.tss vs _app.tss

Checking for Unused/Unsupported Classes

How utilities.tss Works

Quick Start

What's New in v7.3.x

Critical Rules (Low Freedom)

⭐ PREFER $.UI.create() for Dynamic Components

🚨 RESPECT USER FILES

🚨 NO FLEXBOX - Titanium Doesn't Support It

🚨 PLATFORM-SPECIFIC PROPERTIES REQUIRE MODIFIERS

Other Mandatory Rules

Common Anti-Patterns

Class Verification Workflow

Verification Steps

What HAS Classes vs What DOESN'T

Reference Guides

Essential References

Setup & Configuration

Customization

Layout & Styling

Performance

Components

Fonts & Animations

Examples

Related Skills

Understanding
`app.tss`
vs
`_app.tss`

How
`utilities.tss`
Works

⭐ PREFER
`$.UI.create()`
for Dynamic Components