@maccesar/titools 2.2.12 → 2.4.0

package/skills/purgetss/references/customization-deep-dive.md

@@ -1,673 +1,474 @@
-# PurgeTSS Deep Customization
+# PurgeTSS Configuration Deep Dive
 
-PurgeTSS allows for extreme customization through its configuration file, custom rules for Ti Elements, and advanced class syntaxes.
+## The `config` File
 
-:::info What's New in v7.2.x
-**Configuration File Change**: The configuration file has been renamed from `config.js` to `config.cjs` for better CommonJS compatibility. The content structure remains exactly the same.
+> **ℹ️ INFO**
+> The configuration file is named `config.cjs` (it used to be `config.js`). The structure is the same. Legacy mode was removed in PurgeTSS v7.2.x along with its related options.
 
-**Legacy Mode Removed**: Legacy mode has been completely removed from PurgeTSS v7.2.x. All legacy-related options have been eliminated for a cleaner, modern codebase.
-:::
+By default, PurgeTSS looks for `./purgetss/config.cjs`, where you can define customizations.
 
-## The `config.cjs` File
+## Create the `config.cjs` File
 
-By default, **PurgeTSS** will look for a `./purgetss/config.cjs` file where you can define customizations.
+> **ℹ️ INFO**
+> `config.cjs` is created automatically the first time you run `purgetss` in a project.
 
-### File Structure
+If you want a clean `config.cjs`, delete the existing one and run:
 
-The config file consists of two main sections: `purge` and `theme`.
+```bash
+purgetss init
+```
+
+This creates a minimal `./purgetss/config.cjs` file:
 
 ```javascript
 module.exports = {
   purge: {
     mode: 'all',
-    method: 'sync',
+    method: 'sync', // How to execute the auto-purging task: sync or async
+
+    // These options are passed directly to PurgeTSS
     options: {
-      missing: true,
-      widgets: false,
-      safelist: [],
-      plugins: []
+      missing: true, // Reports missing classes
+      widgets: false, // Purges widgets too
+      safelist: [], // Array of classes to keep
+      plugins: [] // Array of properties to ignore
     }
   },
   theme: {
     extend: {}
   }
-}
+};
 ```
 
-:::info
-Every section of the config file is optional, so you only need to specify what you'd like to change. Any missing sections will fall back to the default configuration.
-:::
+Every section is optional. Only add what you want to change. Anything missing falls back to the defaults.
 
-### Creating a Fresh config.cjs
+## Structure
 
-If you need to start with a fresh `config.cjs` file, delete the existing one and run:
+The config file has two main sections: `purge` and `theme`.
 
-```bash
-purgetss init
-```
-
-## The `purge` Section
+### `purge` Section
 
-The `purge` section controls how **PurgeTSS** will remove unused classes or keep the ones you want.
-
-### `mode` Property
+The `purge` section controls how PurgeTSS removes unused classes or keeps the ones you want.
 
 ```javascript
-purge: {
-  mode: 'all', // or 'class'
-  method: 'sync' // or 'async'
-}
-```
-
-**`mode: 'all'` (default)**
-- Scans EVERYWHERE in XML files (comments, attributes, classes, IDs, Ti Elements)
-- **REQUIRED** if you want PurgeTSS to parse any Ti Elements styled in `config.cjs`
-- Most complete but a bit slower
-
-**`mode: 'class'`**
-- Searches only in `class` and ID attributes in XML files
-- Faster processing
-- Cannot parse Ti Elements from `config.cjs`
-
-:::info
-**This mode is necessary if you want PurgeTSS to parse any Ti Elements that you've styled in `config.cjs`.**
-:::
-
-### `method` Property
-
-Determines how the **auto-purge** task will be executed: `sync` (default) or `async`.
-
-:::tip
-If you don't see any changes reflected when changing and rebuilding a project with TiKit Components and LiveView, set the compile method to `async`.
-:::
-
-### `options` Properties
+module.exports = {
+  purge: {
+    mode: 'all',
+    method: 'sync', // How to execute the auto-purging task: sync or async
 
-```javascript
-purge: {
-  options: {
-    missing: true,      // Reports missing classes
-    widgets: false,     // Purges widgets folder too
-    safelist: [],       // Array of classes to keep
-    plugins: []         // Array of properties to disable
+    // These options are passed through directly to PurgeTSS
+    options: {
+      missing: true, // Reports missing classes
+      widgets: false, // Purges widgets too
+      safelist: [], // Array of classes to keep
+      plugins: [] // Array of properties to ignore
+    }
   }
-}
+};
 ```
 
-**`options.missing`**
-
-Set to `true` to get a list of missing or misspelled classes at the end of `app.tss`.
+- **`mode: 'all'`**
 
-:::info
-This is very useful if you want to check if you forgot to add a class definition or if you forgot to remove non-existing classes from your views, especially if you have upgraded from PurgeTSS v5 to v6.
-:::
+  By default, PurgeTSS searches XML files everywhere: comments, attributes, classes, IDs, and Ti Elements.
 
-**`options.widgets`**
+  Use this mode if you want PurgeTSS to parse Ti Elements you style in `config.cjs`.
 
-Set to `true` to also parse all XML files found in the **Widgets** folder.
+- **`method: 'sync'` or `method: 'async'`**
 
-**`options.safelist`**
+  The `method` setting controls how the auto-purge task runs: `sync` (default) or `async`.
 
-Array of classes and Ti Elements to keep regardless of purge mode or usage in XML files.
+  If changes are not showing up when rebuilding a project with TiKit Components and LiveView, set the method to `async`.
 
-For large safelists, create a separate module:
-
-```javascript
-// ./purgetss/safelist.js
-exports.safelist = [
-  'Label', 'Button', 'Window',
-  'bg-indigo-50', 'bg-indigo-100', /* ... */
-  'bg-indigo-800', 'bg-indigo-900',
-];
-
-// ./purgetss/config.cjs
-module.exports = {
-  purge: {
-    options: {
-      safelist: require('./safelist')
-    }
-  }
-}
-```
+- **`mode: 'class'`**
 
-:::tip
-You should put the safelist inside the `purgetss` folder to keep everything organized.
-:::
+  Use `class` to search only class and ID attributes in XML files.
 
-**`options.plugins`**
+- **`options.missing`**
 
-Array of properties (plugins) to completely disable:
+  Set `missing` to `true` if you want a list of missing or misspelled classes at the end of `app.tss`.
 
-```javascript
-plugins: [
-  'opacity',       // Disable all opacity classes
-  'borderRadius'   // Disable all border-radius classes
-]
-```
+  This is useful when you want to confirm you did not forget class definitions or when upgrading older projects.
 
-## The `theme` Section
+- **`options.widgets`**
 
-The `theme` section is where you define your project's design system - colors, spacing, typography, borders, and more.
+  Set `widgets` to `true` to also parse all XML files under the Widgets folder.
 
-### Overriding vs Extending
+- **`options.safelist`**
 
-**Overriding** - Replaces default values:
+  The `safelist` is a list of classes and Ti Elements you want to keep no matter the purge mode or whether they appear in XML.
 
-```javascript
-theme: {
-  opacity: {
-    15: '0.15',
-    35: '0.35',
-    65: '0.65',
-    85: '0.85'
-  }
-}
-```
+  If the list is large, put it in a CommonJS module and require it in `config.cjs`:
 
-This completely replaces the original default `opacity` values.
+  ```javascript
+  module.exports = {
+    purge: {
+      options: {
+        safelist: require('./safelist')
+      }
+    }
+  };
+  ```
+
+  Keep the safelist inside the `purgetss` folder:
+
+  ```javascript
+  // ./purgetss/safelist.js
+  exports.safelist = [
+    'Label',
+    'Button',
+    'Window',
+    'ListView',
+    'TableView',
+    'ScrollView',
+    'ScrollableView',
+    'bg-indigo-50',
+    'bg-indigo-100',
+    'bg-indigo-800',
+    'bg-indigo-900'
+  ];
+  ```
+
+- **`options.plugins`**
+
+  The `plugins` option lets you disable classes PurgeTSS would normally generate.
+
+  To disable specific classes, provide an array of properties (or plugins) to disable:
+
+  ```javascript
+  module.exports = {
+    purge: {
+      options: {
+        plugins: [
+          'opacity',
+          'borderRadius'
+        ]
+      }
+    }
+  };
+  ```
 
-:::info
-Note that any keys you do not provide will be inherited from the default theme, so in the above example, the default theme configuration for things like colors, spacing, border radius, background position, etc. will be preserved.
-:::
+### `theme` Section
 
-**Extending** - Adds to default values:
+The `theme` section defines your project's color palette, type scale, font stacks, border radius values, and other properties.
 
 ```javascript
-theme: {
-  extend: {
-    colors: {
-      primary: '#002359',
+module.exports = {
+  theme: {
+    fontFamily: {
+      display: 'AlfaSlabOne-Regular',
+      body: 'BarlowSemiCondensed-Regular'
+    },
+    borderWidth: {
+      DEFAULT: 1,
+      0: 0,
+      2: 2,
+      4: 4
+    },
+    extend: {
+      colors: {
+        cyan: '#9cdbff'
+      },
+      spacing: {
+        96: '24rem',
+        128: '32rem'
+      }
     }
   }
-}
+};
 ```
 
-This adds `primary` in addition to all default colors.
+## Overriding and Extending Properties
 
-You can both override and extend in the same config:
+By default, your project inherits values from the default theme. You have two options depending on your goal.
 
-```javascript
-theme: {
-  opacity: { /* ... */ },           // Override
-  extend: {
-    colors: { /* ... */ }          // Extend
-  }
-}
-```
-
-## Customizing Colors
-
-### Color Object Syntax
+### Override Properties
 
-Colors can be defined as simple key-value pairs or nested objects:
+To override a default property, add it directly in the `theme` section.
 
 ```javascript
-theme: {
-  colors: {
-    // Simple values
-    transparent: 'transparent',
-    white: '#ffffff',
-    purple: '#3f3cbb',
-
-    // Nested objects (modifiers)
-    primary: {
-      solid: '#002359',
-      dark: '#000030',
-      transparent: '#D9002359'
-    },
-
-    // Shade scales
-    brand: {
-      50: '#edfaff',
-      100: '#d6f2ff',
-      200: '#b5eaff',
-      300: '#83dfff',
-      400: '#48cbff',
-      500: '#1eacff',
-      600: '#068eff',
-      700: '#007aff',
-      800: '#085dc5',
-      900: '#0d519b',
-      950: '#0e315d',
-      default: '#007aff'
+module.exports = {
+  theme: {
+    // Replaces all of the default `opacity` values
+    opacity: {
+      15: '0.15',
+      35: '0.35',
+      65: '0.65',
+      85: '0.85'
     }
   }
-}
+};
 ```
 
-Nested keys are combined with parent to form classes like `bg-primary-solid` or `text-brand-600`.
+This completely replaces the original default `opacity` values with the new ones.
+
+> **ℹ️ INFO**
+> Keys you do not provide are inherited from the default theme. In the example above, colors, spacing, border radius, background position, and other defaults remain.
+
+### Extend Properties
 
-### Overriding Default Colors
+If you want to keep the defaults and add new values, place them under `theme.extend`.
 
-To override a default color while preserving others:
+For example, if you want to add an extra color but preserve the existing ones, you could extend the `colors` section:
 
 ```javascript
-theme: {
-  extend: {
-    colors: {
-      gray: {
-        50: '#f7f7f7',
-        100: '#ededed',
-        200: '#dfdfdf',
-        300: '#c8c8c8',
-        400: '#adadad',
-        500: '#9e9e9e',
-        600: '#888888',
-        700: '#7b7b7b',
-        800: '#676767',
-        900: '#545454'
+module.exports = {
+  theme: {
+    extend: {
+      // Adds a new color in addition to the default colors
+      colors: {
+        primary: '#002359'
       }
     }
   }
-}
+};
 ```
 
-### Extending the Palette
-
-Add new colors without modifying defaults:
+You can override some parts of the default theme and extend others within the same configuration:
 
 ```javascript
-theme: {
-  extend: {
-    colors: {
-      'regal-blue': '#243c5a',
+module.exports = {
+  theme: {
+    opacity: {
+      15: '0.15',
+      35: '0.35',
+      65: '0.65',
+      85: '0.85'
+    },
+    extend: {
+      colors: {
+        primary: '#002359'
+      }
     }
   }
-}
+};
 ```
 
-:::info
-You can use the `shades` command to generate a range of shades for a given color, automatically adding them to your `config.cjs` file.
-:::
+## Customize Colors
 
-## Customizing Spacing
+PurgeTSS includes Tailwind's default color palette. Customize it under the `colors` key in the `theme` section of your `config.cjs` file.
 
-The `spacing` section is shared by `padding`, `margin`, `width`, `height`, and `gap` properties.
+### Use Custom Colors
 
-```javascript
-theme: {
-  spacing: {
-    sm: 8,
-    md: 12,
-    lg: 16,
-    xl: 24,
-  }
-}
-```
-
-### Shared Spacing Behavior
-
-:::info
-When you include the `spacing` section, PurgeTSS will automatically generate all spacing-related properties and merge them with any other spacing-related properties present in the configuration file.
-:::
-
-For example:
+To replace the default color palette, add your colors directly under `theme.colors`:
 
 ```javascript
-theme: {
-  spacing: {
-    tight: '0.25rem',
-    loose: '1.0rem'
-  },
-  width: {
-    banner: '5rem'
-  },
-  height: {
-    xl: '3rem',
-    '1/3': '33.333333%'
+module.exports = {
+  theme: {
+    colors: {
+      transparent: 'transparent',
+      white: '#ffffff',
+      purple: '#3f3cbb',
+      midnight: '#121063',
+      metal: '#565584',
+      tahiti: '#3ab7bf',
+      silver: '#ecebff',
+      'bubble-gum': '#ff77e9',
+      bermuda: '#78dcca'
+    }
   }
-}
+};
 ```
 
-This generates:
-- `m-tight`, `m-loose`, `p-tight`, `p-loose`, etc.
-- `w-banner`
-- `h-xl`, `h-1/3`
-
-## List of Customizable Properties
-
-### Global Properties
-
-All color properties inherit from `theme.colors`. All spacing properties inherit from `theme.spacing`.
-
-### Color Properties (50+ properties)
-
-All of these support your custom colors:
-- `activeTintColor`, `activeTitleColor`, `backgroundColor`, `backgroundDisabledColor`, `backgroundFocusedColor`, `backgroundSelectedColor`, `backgroundSelectedGradient`, `badgeColor`, `barColor`, `borderColor`, `color`, `colors`, `contentScrimColor`, `currentPageIndicatorColor`, `dateTimeColor`, `disabledColor`, `highlightedColor`, `hintTextColor`, `iconColor`, `imageTouchFeedbackColor`, `indicatorColor`, `keyboardToolbarColor`, `lightColor`, `navigationIconColor`, `navTintColor`, `onTintColor`, `pageIndicatorColor`, `pagingControlColor`, `pullBackgroundColor`, `resultsBackgroundColor`, `resultsSeparatorColor`, `selectedBackgroundColor`, `selectedButtonColor`, `selectedColor`, `selectedSubtitleColor`, `selectedTextColor`, `separatorColor`, `shadowColor`, `statusBarBackgroundColor`, `subtitleColor`, `subtitleTextColor`, `tabsBackgroundColor`, `tabsBackgroundSelectedColor`, `thumbTintColor`, `tint`, `tintColor`, `titleAttributes`, `titleColor`, `titleTextColor`, `touchFeedbackColor`, `trackTintColor`, `viewShadowColor`
+These colors are available across utilities like text, border, and background colors.
 
-### Configurable Properties (80+ properties)
-
-- `activeTab`, `backgroundLeftCap`, `backgroundPaddingBottom`, `backgroundPaddingLeft`, `backgroundPaddingRight`, `backgroundPaddingTop`, `backgroundTopCap`, `borderRadius`, `borderWidth`, `bottom`, `cacheSize`, `columnCount`, `contentHeight`, `contentWidth`, `countDownDuration`, `delay`, `duration`, `elevation`, `fontFamily`, `fontSize`, `horizontalMargin`, `indentionLevel`, `keyboardToolbarHeight`, `left`, `leftButtonPadding`, `leftTrackLeftCap`, `leftTrackTopCap`, `leftWidth`, `lineHeightMultiple`, `lines`, `lineSpacing`, `maxElevation`, `maximumLineHeight`, `maxLines`, `maxRowHeight`, `maxZoomScale`, `minimumFontSize`, `minimumLineHeight`, `minRowHeight`, `minZoomScale`, `opacity`, `padding`, `paddingBottom`, `paddingLeft`, `paddingRight`, `paddingTop`, `pageHeight`, `pageWidth`, `pagingControlAlpha`, `pagingControlHeight`, `pagingControlTimeout`, `paragraphSpacingAfter`, `paragraphSpacingBefore`, `repeat`, `repeatCount`, `right`, `rightButtonPadding`, `rightTrackLeftCap`, `rightTrackTopCap`, `rightWidth`, `rotate`, `rowCount`, `rowHeight`, `scale`, `scalesPageToFit`, `scaleX`, `scaleY`, `sectionHeaderTopPadding`, `separatorHeight`, `shadowRadius`, `shiftMode`, `timeout`, `top`, `uprightHeight`, `uprightWidth`, `verticalMargin`, `width`, `xOffset`, `yOffset`, `zIndex`, `zoomScale`
-
-## Custom Rules & Ti Elements
-
-Style any **Ti Element**, **ID**, or **class** with platform/device specificity.
-
-### Modifier Key
-
-- **Ti Elements**: Use exact name: `Label`, `Button`, `ScrollView`
-- **IDs**: Use `camelCase`: `#mainBanner`, `sidebarWidget`
-- **Classes**: Use `kebab-case`: `.my-custom-class`, `.feature-card` (required for PurgeTSS v6.x+)
-
-:::caution PurgeTSS v5 or earlier projects
-For projects created with PurgeTSS v5 or earlier that are now using version 7.x.x or above, please set `purge.options.missing` to true in `config.cjs` to get a report (at the end of `app.tss`) of any missing classes so you can update them to the new naming convention.
-:::
-
-### Default, Platform, Device, or Conditional Blocks
-
-- **`DEFAULT` or `default`**: Global style
-- **`ios`** or **`android`**: Platform-specific
-- **`tablet`** or **`handheld`**: Device-specific
-- **`[if=globalVariableName]`**: Conditional with global variable
-
-### Property Values
-
-- **Titanium constants**: Enclose in quotes: `'Ti.UI.SIZE'`, `'Ti.UI.FILL'`
-- **Alloy Configuration Values**: Enclose in quotes: `'Alloy.CFG.someValue'`
-- **Global Variables**: Enclose in quotes: `'Alloy.Globals.someValue'`
-- **Colors**: Use `hex`, `8-digit hex`, `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or color names
-- **Spacing values**: Use `em`, `rem`, `%`, `px`, `dp`, `cm`, `in`
-
-**Unit conversions:**
-- `%`, `px`, `cm`, `in` - Passed without conversion
-- `em` or `rem` - Converted: `value * 16`
-- `dp` - Unit removed, value remains intact
+### Color Object Syntax
 
-### Complete Example
+Colors can be defined as a simple list of key-value pairs or as nested objects. Nested keys are added to the base color name as modifiers.
 
 ```javascript
 module.exports = {
   theme: {
-    // Custom ID with platform variants
-    '#main-banner': {
-      DEFAULT: {
-        width: '300px',
-        height: '80px'
-      },
-      ios: {
-        clipMode: 'Ti.UI.iOS.CLIP_MODE_DISABLED'
-      }
-    },
-
-    // Custom class with device variants
-    '.gallery': {
-      DEFAULT: {
-        height: 'Ti.UI.SIZE'
-      },
-      ios: {
-        clipMode: 'Ti.UI.iOS.CLIP_MODE_ENABLED'
-      },
-      android: {
-        hiddenBehavior: 'Ti.UI.HIDDEN_BEHAVIOR_GONE'
-      },
-      handheld: {
-        width: '250px'
-      },
-      tablet: {
-        width: '500px'
-      }
-    },
-
-    // Ti Element styling
-    TextField: {
-      DEFAULT: {
-        top: 10,
-        left: 20,
-        right: 20,
-        bottom: 0
-      },
-      '[if=Alloy.Globals.iPhoneX]': {
-        bottom: 'Alloy.CFG.iPhoneXNotchSize'
+    colors: {
+      highlight: '#ffff00',
+      primary: {
+        solid: '#002359',
+        dark: '#000030',
+        transparent: '#D9002359'
       },
-      android: {
-        touchFeedback: true
+      tahiti: {
+        100: '#cffafe',
+        200: '#a5f3fc',
+        300: '#67e8f9',
+        400: '#22d3ee',
+        500: '#06b6d4',
+        600: '#0891b2',
+        700: '#0e7490',
+        800: '#155e75',
+        900: '#164e63'
       }
     }
   }
-}
+};
 ```
 
-## The `@apply` Directive
-
-Extract repetitive patterns into reusable classes.
-
-```javascript
-'.btn-primary': {
-  apply: 'bg-blue-600 text-white rounded-lg px-4 py-2 font-bold'
-}
-
-'.card-shadow': {
-  apply: 'shadow-md'
-}
-```
-
-:::tip
-The `apply` directive is perfect for creating component-specific utility classes that combine multiple PurgeTSS utilities into a single, semantic class name.
-:::
-
-### Platform-Specific Classes with `@apply`
-
-Several classes in `utilities.tss` are platform-specific to prevent polluting objects with properties that are not specific to a particular platform.
+The nested keys are combined with the parent key to form class names like `bg-tahiti-400` or `text-tahiti-400`.
 
-:::caution IMPORTANT!
-To properly apply these platform styles when creating custom rules, you must specify the platform variant in the `apply` directive.
+### Override a Default Color
 
-**Even if you are not targeting a specific platform, you must specify the platform variant.**
-:::
+If you want to override one of the default colors but keep the rest, provide the new values in `theme.extend.colors`.
 
-#### Correct Usage - With Platform Variant
+For example, replacing the default cool grays with a neutral gray palette:
 
 ```javascript
 module.exports = {
   theme: {
-    '.my-view': {
-      // Targeting iOS with platform variant
-      'ios': {
-        'apply': 'bg-green-500 wh-32 ios:clip-enabled'
+    extend: {
+      colors: {
+        gray: {
+          50: '#f7f7f7',
+          100: '#ededed',
+          200: '#dfdfdf',
+          300: '#c8c8c8',
+          400: '#adadad',
+          500: '#9e9e9e',
+          600: '#888888',
+          700: '#7b7b7b',
+          800: '#676767',
+          900: '#545454'
+        }
       }
     }
-  },
-}
+  }
+};
 ```
 
-**Generated output:**
-```tss
-/* Custom Classes */
-'.my-view[platform=ios]': { backgroundColor: '#22c55e', clipMode: Ti.UI.iOS.CLIP_MODE_ENABLED, width: 128, height: 128 }
-```
+### Extend the Default Palette
 
-#### Wrong Usage - Omitting Platform Variant
+If you want to extend the default color palette, use `theme.extend.colors`.
 
 ```javascript
 module.exports = {
   theme: {
-    // Missing platform variant in clip-enabled
-    '.my-view': {
-      'apply': 'wh-32 clip-enabled bg-green-500'
+    extend: {
+      colors: {
+        'regal-blue': '#243c5a'
+      }
     }
-  },
-}
-```
-
-**Generated output (MISSING the clipMode property):**
-```tss
-/* Omitting the platform variant in config.cjs will not generate the corresponding property. */
-/* Missing the property related to `clip-enabled`. */
-'.my-view': { backgroundColor: '#22c55e', width: 128, height: 128 }
+  }
+};
 ```
 
-#### Why Platform Variants Are Required
-
-Certain Titanium properties are platform-specific and will only work when properly scoped:
+This generates classes like `bg-regal-blue` in addition to all of Tailwind's default colors.
 
-| Property        | Platform             | Class                                   |
-| --------------- | -------------------- | --------------------------------------- |
-| `clipMode`      | iOS only             | `ios:clip-enabled`, `ios:clip-disabled` |
-| `touchFeedback` | Android only         | `android:touch-feedback`                |
-| `hires`         | iOS only (ImageView) | `ios:hires`                             |
+> **ℹ️ INFO**
+> You can use the `shades` command to generate a range of shades for a color and add them to `config.cjs`. See [CLI Commands](./cli-commands.md#shades-command).
 
-When using `@apply` with these properties, you MUST specify the platform variant in the `apply` string so PurgeTSS knows which platform's property to include.
+## Customize Spacing
 
-#### Combining Platform Variants
+The `spacing` section sets the global spacing and sizing scale.
 
 ```javascript
 module.exports = {
   theme: {
-    '.responsive-card': {
-      DEFAULT: {
-        apply: 'bg-white rounded-lg p-4'
-      },
-      ios: {
-        apply: 'shadow-md ios:clip-enabled'
-      },
-      android: {
-        apply: 'android:touch-feedback'
-      },
-      handheld: {
-        apply: 'w-full'
-      },
-      tablet: {
-        apply: 'w-3/4'
-      }
+    spacing: {
+      1: '8px',
+      2: '12px',
+      3: '16px',
+      4: '24px',
+      5: '32px',
+      6: '48px'
     }
   }
-}
-```
-
-**Generated output:**
-```tss
-/* Platform and device specific styles */
-'.responsive-card': { backgroundColor: '#ffffff', borderRadius: 8, top: 16, right: 16, bottom: 16, left: 16 }
-'.responsive-card[platform=ios]': { clipMode: Ti.UI.iOS.CLIP_MODE_ENABLED }
-'.responsive-card[platform=android]': { touchFeedback: true }
-'.responsive-card[formFactor=handheld]': { width: '100%' }
-'.responsive-card[formFactor=tablet]': { width: '75%' }
-```
-
-### String vs Array Syntax
-
-You can use either a string or an array for the `apply` directive:
-
-```javascript
-// String syntax
-'.btn': {
-  apply: 'font-bold border-2 rounded wh-auto my-0.5'
-}
-
-// Array syntax (easier to read for long lists)
-'.btn-corporate': {
-  apply: [
-    'bg-corporate-500',
-    'text-corporate-100',
-    'border-corporate-200'
-  ]
-}
+};
 ```
 
-## Platform & Device Modifiers in XML
-
-Conditional styling directly in the `class` attribute using colon notation.
+By default, the spacing scale is inherited by the padding, margin, width, height, and gap core plugins.
 
-### Platform Modifiers
+### Shared Spacing
 
-```xml
-<!-- iOS-specific styling -->
-<Label class="ios:text-blue-600 android:text-gray-600" />
+The `spacing` section is shared by the `padding`, `margin`, `width`, and `height` properties.
 
-<!-- Multiple platforms -->
-<View class="ios:bg-blue-100 android:bg-gray-100" />
-```
-
-### Device Modifiers
+When you include the `spacing` section, PurgeTSS automatically generates all spacing-related properties and merges them with any other spacing-related properties present in the configuration file.
 
-```xml
-<!-- Tablet vs handheld -->
-<View class="tablet:w-3/4 handheld:w-full" />
-```
-
-### Custom Conditional Modifiers
-
-```xml
-<!-- Using global variables -->
-<View class="[if=Alloy.Globals.isIPhoneX]:pb-24" />
+```javascript
+module.exports = {
+  theme: {
+    spacing: {
+      tight: '0.25rem',
+      loose: '1.0rem'
+    },
+    width: {
+      banner: '5rem'
+    },
+    height: {
+      xl: '3rem',
+      '1/3': '33.333333%'
+    }
+  }
+};
 ```
 
-## Icon Font Support
-
-PurgeTSS automatically maps icon classes to both `text` and `title` properties, making them work on both Labels and Buttons.
-
 ```tss
-/* Auto-generated for FontAwesome */
-'.fa-home': { text: '\uf015', title: '\uf015' }
-'.fas': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
+/* width */
+'.w-tight': { width: 4 }
+'.w-loose': { width: 16 }
+'.w-banner': { width: 80 }
+
+/* height */
+'.h-tight': { height: 4 }
+'.h-loose': { height: 16 }
+'.h-xl': { height: 48 }
+'.h-1/3': { height: '33.333334%' }
+
+/* margin */
+'.m-tight': { top: 4, right: 4, bottom: 4, left: 4 }
+'.m-loose': { top: 16, right: 16, bottom: 16, left: 16 }
+'.my-tight': { top: 4, bottom: 4 }
+'.my-loose': { top: 16, bottom: 16 }
+
+/* padding */
+'.p-tight': { padding: { top: 4, right: 4, bottom: 4, left: 4 } }
+'.p-loose': { padding: { top: 16, right: 16, bottom: 16, left: 16 } }
+'.py-tight': { padding: { top: 4, bottom: 4 } }
+'.py-loose': { padding: { top: 16, bottom: 16 } }
 ```
 
-This allows:
-```xml
-<!-- Works on Labels -->
-<Label class="fas fa-home" />
+### Override the Default Spacing Scale
 
-<!-- Works on Buttons too! -->
-<Button class="fas fa-home" />
-```
-
-## Theme Extension Best Practices
-
-### 1. Use `extend` for Additions
+If you want to override the default spacing scale, use `theme.spacing` in `config.cjs`:
 
 ```javascript
-theme: {
-  extend: {
-    colors: {
-      brand: '#007AFF',  // Adds to existing colors
+module.exports = {
+  theme: {
+    spacing: {
+      sm: 8,
+      md: 12,
+      lg: 16,
+      xl: 24
     }
   }
-}
+};
 ```
 
-### 2. Use Direct Properties for Overrides
+This disables the default spacing scale and generates classes like `p-sm` for padding, `m-md` for margin, `w-lg` for width, and `h-xl` for height.
+
+### Extend the Default Spacing Scale
+
+If you want to extend the default spacing scale, use `theme.extend.spacing`:
 
 ```javascript
-theme: {
-  colors: {
-    // Completely replaces default grays
-    gray: {
-      50: '#f7f7f7',
-      // ... etc
+module.exports = {
+  theme: {
+    extend: {
+      spacing: {
+        72: '18rem',
+        84: '21rem',
+        96: '24rem'
+      }
     }
   }
-}
+};
 ```
 
-### 3. Mix Both When Needed
+This generates classes like `p-72`, `m-84`, and `h-96` in addition to all of the default spacing and sizing utilities.
 
-```javascript
-theme: {
-  // Override some
-  opacity: { /* custom values */ },
+> **WARNING: Titanium Layout Constraint**
+> Titanium does not support native `padding` on `View`, `Window`, `ScrollView`, or `TableView`. Even if PurgeTSS can generate spacing-related utilities, prefer margins on children for those elements.
 
-  // Extend others
-  extend: {
-    colors: { /* additional colors */ }
-  }
-}
-```
-
-## Summary Checklist
+## List of Customizable Properties
 
-- [ ] Set `mode: 'all'` if styling Ti Elements in `config.cjs`
-- [ ] Use `method: 'async'` for LiveView compatibility issues
-- [ ] Enable `missing: true` during development to catch typos
-- [ ] Use `kebab-case` for custom class names (v6.x+ requirement)
-- [ ] Use `camelCase` for IDs
-- [ ] Use exact names for Ti Elements
-- [ ] Prefer `extend` over overriding for colors/spacing
-- [ ] Use `@apply` for component-specific utility combinations
+The official guide ends with an exhaustive list of color and configurable properties. In this skill, that list is maintained separately in [Configurable Properties](./configurable-properties.md) so this guide stays focused on config structure and usage patterns.
 
-## Related References
+## Custom Rules and Ti Elements
 
-- [Opacity Modifier](opacity-modifier.md) - Add transparency to ANY color with `/50` syntax
-- [Configurable Properties](configurable-properties.md) - Complete list of 80+ customizable properties
-- [Custom Rules](custom-rules.md) - Styling Ti Elements, IDs, and classes
-- [Apply Directive](apply-directive.md) - Extracting utility combinations into reusable classes
-- [Platform Modifiers](platform-modifiers.md) - ios:, android:, tablet:, handheld: prefixes
+Create your own custom rules and include Ti Elements with any number of attributes or conditional statements. See [Custom Rules](./custom-rules.md) for the rule syntax and examples.