purgetss

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

:::

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

```bash

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

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

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.

:::

```bash

purgetss create 'MyApp' -d -v fa

# -d: Install dev dependencies (ESLint, Tailwind)

# -v: Copy icon fonts (fa, mi, ms, f7)

```

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

:::

⭐ 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](references/dynamic-component-creation.md) 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.

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

Item 1

Item 2

Item 3

```

horizontal - Arrange elements left to right:

```xml

```

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

```xml

```

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

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

```

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](references/platform-modifiers.md).

:::

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

WRONG:

```xml

```

CORRECT:

```xml

```

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

})

```

:::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](references/class-index.md#prohibited-tailwind-classes-that-do-not-exist)

- Common mistakes: flex-row, justify-between, p-4 on Views (p-* not supported on Views)

1. Check the Class Index

- See [Class Index](references/class-index.md) for available patterns

- Constant properties like keyboard-type-, return-key-type- have dedicated classes

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

```

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

:::

Load these only when needed:

Essential References

• [Class Index](references/class-index.md) - Quick patterns, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
• [Dynamic Component Creation](references/dynamic-component-creation.md) - $.UI.create() and Alloy.createStyle() for creating components in Controllers (READ FIRST for dynamic components)

Setup & Configuration

• [Installation & Setup](references/installation-setup.md) - First run, VS Code, LiveView
• [CLI Commands](references/cli-commands.md) - All purgetss commands
• [Migration Guide](references/migration-guide.md) - Migrating existing apps from manual TSS to PurgeTSS

Customization

• [Deep Customization](references/customization-deep-dive.md) - config.cjs, colors, spacing, Ti Elements
• [Custom Rules](references/custom-rules.md) - Styling Ti Elements, IDs, classes
• [Apply Directive](references/apply-directive.md) - Extracting utility combinations
• [Configurable Properties](references/configurable-properties.md) - All 80+ customizable properties

Layout & Styling

• [UI/UX Design Patterns](references/ui-ux-design.md) - Complete guide to mobile UI components with PurgeTSS (cards, lists, forms, buttons, navigation, modals, accessibility)
• [Grid Layout System](references/grid-layout.md) - 12-column grid, responsive layouts
• [Smart Mappings](references/smart-mappings.md) - How gap, shadows, and grid work under the hood
• [Arbitrary Values](references/arbitrary-values.md) - Parentheses notation for custom values
• [Platform Modifiers](references/platform-modifiers.md) - ios:, android:, tablet:, handheld:
• [Opacity Modifier](references/opacity-modifier.md) - Color transparency with /50 syntax
• [Titanium Resets](references/titanium-resets.md) - Default styles for Ti elements

Performance

• [Performance Tips](references/performance-tips.md) - Optimizing PurgeTSS apps (bridge crossings, ListView, animations)

Components

• [TiKit UI Components](references/tikit-components.md) - Ready-to-use Alerts, Avatars, Buttons, Cards, Tabs built with PurgeTSS

Fonts & Animations

• [Icon Fonts](references/icon-fonts.md) - Font Awesome 7, Material Icons, custom icon libraries
• [Animation Component](references/animation-system.md) - Declarative API

:::tip TEXT FONTS (Google Fonts, Roboto, etc.)

For text fonts, see [CLI Commands → build-fonts](references/cli-commands.md#purgetss-build-fonts-alias-bf).

:::

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](references/EXAMPLES.md) and [Dynamic Component Creation](references/dynamic-component-creation.md)

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 |