What it does:

• 23,300+ utility classes for colors, spacing, typography, layout, and more.
• Parses XML files and writes an app.tss with only the classes you use.
• Customizable through config.cjs, with arbitrary values for one-off sizes and colors.
• Icon fonts for Buttons and Labels: Font Awesome, Material Icons, Material Symbols, and Framework7-Icons.
• build-fonts command generates fonts.tss with class definitions and fontFamily selectors for any font you drop in.
• shades command generates color palettes from a hex value.
• Animation module with 2D transforms, draggable views with collision detection, sequential animations, and position utilities.
• Grid system for aligning and distributing elements in rows and columns.

Table of Contents​

• Installation
• Commands
• App Assets
  • App icons and branding
  • Multi-density images
• Customization
  • The Config File
  • Custom Rules
  • The apply Directive
  • The opacity Modifier
  • Arbitrary Values
  • Platform and Device Modifiers
  • Icon Fonts Libraries
• The UI Module
  • Introduction
  • The play Method
  • The apply Method
  • The open and close Methods
  • The draggable Method
  • Complex UI Elements
  • Additional Methods
  • Available Utilities
  • Implementation Rules
  • Appearance
• Best Practices
  • Appearance Setup
  • Semantic Colors
  • Large Titles on iOS
  • Values and Units
• Grid System

Changelog​

v7.9.0​

• Opacity modifiers now work on classes that resolve to a semantic color. Writing bg-surface/65 (or any other opacity modifier on a class mapped to a name in semantic.colors.json) produces a working rule with Light/Dark switching preserved. PurgeTSS derives a new <originalKey>_<alphaPercent> entry with the original light/dark hex values and the requested alpha for both modes, writes it back to semantic.colors.json, and emits the rule against the derived key. Re-runs are idempotent; manual edits with conflicting values halt the build with a Conflict error. New alpha entries require one full Titanium build to be picked up — Liveview hot-reload alone does not refresh semantic.colors.json. See Semantic Colors.
• Several fixes around semantic colors, gradients, and Ti Element defaults: the semantic tonal palette was inverting Light and Dark; the gradient from/to color order was position-dependent and could swap after sort(); the bg-gradient-to-X direction was silently dropped when combined with from-X to-Y colors in the same apply string; theme.Window / theme.View / theme.ImageView no longer leak the framework presets (white background, Ti.UI.SIZE, iOS hires: true) when defined at the top level (replace mode), so a Window declared at theme.Window with a backgroundGradient no longer ghosts on top of a default backgroundColor: '#FFFFFF'. theme.extend.Window keeps merging with the defaults as before. See Apply directive — extend mode vs replace mode.
• Breaking: the user-facing glossary output path was renamed from purgetss/experimental/tailwind-classes/ to purgetss/glossary/tailwind-classes/. Any tooling or CI that reads from the old path needs to be updated on upgrade — no transition shim was added on purpose. The --glossary flag and command surface are unchanged.

v7.8.0​

• images now has a --width <n> flag. It pins Android mdpi (= iPhone @1x) to a specific pixel width, for example purgetss images logo.svg --width 256. Larger scales derive at ×1.5, ×2, ×3, and ×4, with height staying proportional to the source's aspect ratio. Use this for SVG sources from vector editors with disproportionate viewBoxes, such as Affinity or Illustrator. Without the flag, every scale derives from the source's viewBox as a 4× master, which can produce unpredictable sizes when the viewBox does not match the intended display size. When you pass an SVG without --width, the command prints a one-time hint and then falls back to the legacy 4× behavior. This is CLI-only; there is no matching images: config property because the right width is per-asset.
• Class syntax pre-validation now stops purgetss with a structured Class Syntax Error block (file + line + suggested fix) when it detects known class-name mistakes: inverted negative sign (top-(-10) → -top-(10)), Tailwind-style brackets (top-[10px] → top-(10px)), empty parentheses (wh-()), whitespace inside parentheses (wh-( 200 )), and redundant px unit (top-(10px) → top-(10)). All offenders are reported in one run. Generic unknown classes, such as typos, vendor utilities not enabled, or custom classes not declared yet, are not flagged. They still flow into the // Unused or unsupported classes block in app.tss.
• The arbitrary-value parser no longer crashes on negative values inside parentheses. Classes like top-(-10), mt-(-5), and origin-(-10,-20) used to trigger a Cannot read properties of null (reading 'pop') exception. The parser now extracts the (...) portion first, so a - inside the value does not break the split.

v7.7.0​

• The brand config was cleaned up before stabilizing. Branding settings now live under grouped sections: brand.logos, brand.padding, brand.android, brand.ios, and brand.colors.
• brand can now use separate Android inputs: one logo for the general brand set, another for Android launcher icons, and another for Android 12+ splash artwork. Use brand.logos.androidLauncher / --icon-logo and brand.logos.androidSplash / --splash-logo, or drop logo-icon.* and logo-splash.* into purgetss/brand/.
• purgetss brand now regenerates the legacy Android splash fallback: app/assets/android/default.png in Alloy projects and Resources/android/default.png in Classic projects.
• cleanup-legacy no longer removes default.png, because that file can still matter on older Titanium Android splash paths.
• The branding docs now explain what uses ic_launcher, what uses splash_icon.png, and what still falls back to default.png.

v7.6.2​

• The semantic command now works in Classic Titanium projects. It writes to Resources/semantic.colors.json; Alloy keeps writing to app/assets/semantic.colors.json. Existing unrelated entries, such as the default backgroundColor / textColor values that ship with Classic templates, are preserved in both project types. See Semantic Colors
• Fixed a UX bug where the "not an Alloy project" error was immediately followed by the palette preview JSON, making it look like the command half-succeeded.

v7.6.1​

• brand and images now ask before destructive writes (y / N / a for "always"). The prompt is skipped when stdin is not a TTY (alloy.jmk hook, CI, pipes), when -y / --yes is passed, or when PURGETSS_YES=1 is set. Set confirmOverwrites: false on the matching config section to silence it permanently.
• SVG logos and images now get a disproportionate-viewBox warning. The command detects viewBoxes above 4096 pt on any side, common in Affinity and Illustrator exports, and rasterizes with adaptive density to stay within Sharp's pixel budget.
• init now creates purgetss/{fonts,brand,images}/ subfolders.
• Multi-line command output is now grouped under a single ::PurgeTSS:: header with indented continuation lines. This applies across purge, fonts, icon-library, brand, images, and most warnings.

v7.6.0​

• The new brand command generates the Titanium branding set from logos auto-discovered in ./purgetss/brand/: launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, and optional notification/splash assets. Works on Alloy and Classic projects. See App icons and branding
• The new images command generates multi-density UI images from sources in ./purgetss/images/: Android res-* densities and iPhone @1x/@2x/@3x scales. Subdirectories are preserved, and short paths can target individual files for re-processing. See Multi-density images
• brand: and images: config sections were added to purgetss/config.cjs. Percentages can be written as '15%' strings for clarity; plain numbers are also accepted. Older configs get these sections on first run.
• The new semantic command generates Titanium semantic colors (Light/Dark mode) into app/assets/semantic.colors.json. --single switches between a tonal palette (one base hex → 11 shades with mirror inversion + auto config mapping) and a purpose-based color (explicit per-mode hex + optional alpha). The JSON entry and class mapping in config.cjs are written in one shot. Class names are derived by stripping the Color suffix, for example surfaceColor → surface. Smart in-place updates run when a single name matches an existing palette shade. See Semantic Colors: generating semantic colors with the semantic command

v7.5.3​

• New Appearance export for Light/Dark/System mode switching with persistence. Methods: init(), set(mode), get(), toggle(). See Appearance Setup
• Default font family classes are generated automatically with platform-appropriate values: font-sans, font-serif, and font-mono.
• XML validation now detects illegal -- inside XML comments during pre-validation.

v7.5.0​

• extend support for Window, View, and ImageView. Component defaults can now be customized from theme.extend in config.cjs.
• Shorthand apply: { apply: '...' } is automatically normalized, so the default: wrapper is optional.
• Property deduplication: applied values win over static defaults instead of duplicating.
• Automatic platform resolution: classes inside ios: / android: blocks find their platform-specific version automatically.
• Font Awesome 7.2.0
• Fixed: extend.Window silently ignored, duplicate font properties, array-type properties missing [ ] notation

v7.4.0​

Animation module expansion: 9 new methods bring the module to 15 total.

• transition, pulse, sequence, swap, shake, snapTo, reorder, undraggable, detectCollisions
• New utility classes: snap-back, snap-center, snap-magnet, keep-z-index
• Delta-based drag for transformed views, position normalization, property inheritance from the Animation object

See the UI Module documentation for full details.

v7.3.0​

• BREAKING: tailwind.tss was renamed to utilities.tss.
• XML syntax validation adds pre-validation for Alloy XML files with line numbers and fix suggestions.
• Classic Titanium compatibility: deviceInfo() works without Alloy dependencies.

v7.2.7​

• Security fixes for command injection in glob and prototype pollution in js-yaml.
• Dependency cleanup reduced installation size by about 45MB and removed unused packages.
• Titanium SDK 13.1.0.GA: new utility classes for navBarColor, forceBottomPosition, and multipleWindows.

v7.2.6​

• Updated Font Awesome to version 7.1.0
• Simplified flag property names in utilities.tss