@maccesar/titools 3.1.0 → 3.3.0

package/README.md

@@ -736,7 +736,7 @@ This pattern is documented across three TiTools skills: `ti-ui`, `ti-expert`, an
 | Skill     | SKILL.md                      | References                                            |
 | --------- | ----------------------------- | ----------------------------------------------------- |
 | ti-expert | Architecture + Implementation | 21 files (patterns, testing, security, etc.)          |
-| purgetss  | Setup + Critical Rules        | 29 files (grid, animations, icons, class-index, etc.) |
+| purgetss  | Setup + Critical Rules        | 31 files (grid, animations, icons, class-index, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: purgetss
-description: "Titanium PurgeTSS utility-first styling toolkit. Use when styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, using grid layouts, setting up icon fonts, or working with TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, this project uses PurgeTSS — invoke this skill BEFORE writing ANY styling code. All styling MUST use PurgeTSS utility classes in XML, NOT custom TSS. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists before using it. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
+description: "Use when working with PurgeTSS, Titanium's utility-first styling toolkit — styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, grid layouts, icon fonts, or TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, invoke BEFORE writing ANY styling code. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
 argument-hint: "[class-name]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 ---
@@ -9,6 +9,46 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 
 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](references/class-index.md) |
+| Layout (horizontal/vertical/composite, grid) | [references/grid-layout.md](references/grid-layout.md), [references/ui-ux-design.md](references/ui-ux-design.md) |
+| Dynamic components in controllers | [references/dynamic-component-creation.md](references/dynamic-component-creation.md) |
+| Custom values / arbitrary syntax | [references/arbitrary-values.md](references/arbitrary-values.md) |
+| Platform-specific styles (`ios:`, `android:`) | [references/platform-modifiers.md](references/platform-modifiers.md) |
+| Dark/Light mode | [references/semantic-colors.md](references/semantic-colors.md), [references/appearance-module.md](references/appearance-module.md) |
+| Apply directive / class extraction | [references/apply-directive.md](references/apply-directive.md) |
+| Animations | [references/animation-system.md](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**
@@ -112,62 +152,6 @@ purgetss create 'MyApp' -d -v fa
 # -v: Copy icon fonts (fa, mi, ms, f7)
 ```
 
-## What's New in v7.9.0
-
-- Opacity modifier on semantic colors — `bg-surface/65` syntax now works for any class mapped through `theme.extend.colors`. PurgeTSS auto-derives `<originalKey>_<alphaPercent>` entries in `semantic.colors.json` per mode (light/dark). See [Semantic Colors → Opacity modifier auto-derivation](references/semantic-colors.md#opacity-modifier-auto-derivation). **Native rebuild required** — Liveview hot-reload alone does not refresh `semantic.colors.json`
-- `theme.Window` / `theme.View` / `theme.ImageView` presets now use **replace mode** — they no longer carry framework defaults (white background, `Ti.UI.SIZE`, iOS `hires: true`). This fixes gradient ghosting where a preset Window with `bg-gradient-*` apply was being covered by the implicit `backgroundColor: '#FFFFFF'`. Use `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` when you want **extend mode** (merge with defaults). See [Apply Directive → Extend mode vs replace mode](references/apply-directive.md#extend-mode-vs-replace-mode)
-- Glossary path renamed: `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`
-
-## What's New in v7.8.0
-
-- `purgetss images --width <n>` — pin SVG output to a specific base width; PurgeTSS derives per-density assets from the multiplier scale (×1 / ×1.5 / ×2 / ×3 / ×4). Range `[1, 8192]`. CLI-only (no `images:` config equivalent — width is per-asset). See [Multi-Density Images → Pinning the output width with --width](references/multi-density-images.md#pinning-the-output-width-with---width)
-- Class syntax pre-validation — the build now emits a `Class Syntax Error` block (file path + line + `Fix:` suggestion) for 5 detected patterns: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace inside parens (`wh-( 200 )` → `wh-(200)`), redundant `px` unit (`top-(10px)` → `top-(10)`). See [Arbitrary Values → Class syntax pre-validation](references/arbitrary-values.md#class-syntax-pre-validation)
-- Parser fix for negative values inside parentheses — `top-(-10)` is now correctly flagged as inverted-negative-sign instead of silently misparsed
-
-## What's New in v7.7.0
-
-- `brand:` config restructured — flat keys replaced by purpose-based groups: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`
-- Separate Android brand inputs — `logos.androidLauncher` / `--icon-logo` for Android launcher icons; `logos.androidSplash` / `--splash-logo` for Android 12+ splash artwork. Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/`
-- `--android-adaptive-padding` (default `19%`) and `--android-legacy-padding` (default `10%`) replace the single `--padding`. The shortcut `--padding` now sets both Android paddings to the same value for one run
-- Legacy Android splash fallback regenerated — `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`
-- New official doc: [Values and Units](references/values-and-units.md) — explains `ti.ui.defaultunit` interpretation of PurgeTSS unitless values
-
-## What's New in v7.6.x
-
-- `brand` command — complete Titanium branding set (launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace) from logos in `./purgetss/brand/` (v7.6.0)
-- `images` command — multi-density UI images (Android res-*dpi + iPhone @1x/@2x/@3x) from `./purgetss/images/` (v7.6.0)
-- `semantic` command — Titanium semantic colors for Light/Dark mode (palette mode + single mode) (v7.6.0)
-- `brand:` and `images:` config sections auto-injected into older configs (v7.6.0)
-- Percentages as strings (`'15%'`) for self-documenting clarity in brand/images configs (v7.6.0)
-- Confirmation prompt for destructive writes in `brand` / `images` (`y` / `N` / `a`); auto-skipped on non-TTY, with `-y`, or `PURGETSS_YES=1` (v7.6.1)
-- `semantic` command works in Classic projects — writes to `Resources/semantic.colors.json` (v7.6.2)
-
-## What's New in v7.5.3
-
-- Appearance module — Light/Dark/System mode switching with persistence
-- Default font family classes (`font-sans`, `font-serif`, `font-mono`) generated automatically with platform-appropriate values
-- XML validation — detects illegal `--` inside XML comments during pre-validation
-
-## What's New in v7.5.0
-
-- `extend` support for Window, View, and ImageView in `config.cjs`
-- Shorthand `apply` directive normalization
-- Apply directive property deduplication
-- Automatic platform resolution in apply directives
-- Updated Font Awesome to 7.2.0
-- Fixed: `extend.Window` was silently ignored
-- Fixed: Array-type properties (`extendEdges`, `mediaTypes`) bracket notation
-
-## What's New in v7.4.0
-
-- 9 new Animation methods: `transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions` (module now has 15 methods total)
-- Snap behavior classes: `snap-back`, `snap-center`, `snap-magnet`
-- `keep-z-index` utility class
-- Enriched callback event object with `action`, `state`, `id`, `targetId`, `index`, `total`, `getTarget()`
-- Delta-based drag for views with rotate/scale transforms
-- Position normalization for draggable views
-- Property inheritance from Animation object for all new methods
-
 > **💡 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.
 >
@@ -253,9 +237,9 @@ purgetss create 'MyApp' -d -v fa
 > ```
 >
 > **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
->
+
+### 🚨 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.
 >
@@ -290,23 +274,23 @@ purgetss create 'MyApp' -d -v fa
 > 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.
->
+
+**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.
+
 > **💡 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`**.
 >
@@ -322,166 +306,169 @@ purgetss create 'MyApp' -d -v fa
 > <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:**
-> ```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
->
+
+- **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
+
 > **🚨 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)
->
-> 2. **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
->
-> 3. **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
->    ```
->
-> 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 |
->
+
+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)
+
+2. **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
+
+3. **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
+   ```
+
+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](references/class-index.md)** - Naming conventions, 416-property table, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
-> - **[Class Categories](references/class-categories.md)** - Complete prefix inventory by category (layout, colors, typography, states, etc.)
-> - **[Dynamic Component Creation](references/dynamic-component-creation.md)** - `$.UI.create()` and `Alloy.createStyle()` for creating components in Controllers (READ FIRST for dynamic components)
-> - **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
-> - **[Semantic Colors](references/semantic-colors.md)** - Titanium semantic colors for Light/Dark mode via `semantic` command (v7.6.0)
->
-> ### 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
-> - **[Values and Units](references/values-and-units.md)** - How `ti.ui.defaultunit` in `tiapp.xml` interprets the unitless numeric values PurgeTSS writes (foundational concept for spacing, sizes, typography)
->
-> ### 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
->
-> ### Appearance & Theming
-> - **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
-> - **[Semantic Colors](references/semantic-colors.md)** - `semantic` command + runtime usage for Light/Dark mode (v7.6.0)
->
-> ### 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
-> - [iOS Large Titles](references/ios-large-titles.md) - Best practice for iOS Large Title navigation
->
-> ### App Assets
-> - [App Branding](references/app-branding.md) - `brand` command for launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace assets (v7.6.0)
-> - [Multi-Density Images](references/multi-density-images.md) - `images` command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
->
-> ### 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 System](references/animation-system.md) - 15 methods including collision detection, transitions, and sequential animations
-> - [Animation Advanced](references/animation-advanced.md) - Property inheritance, utility classes, implementation rules, complex UI example
->
+
+## Reference Guides
+
+Load these only when needed:
+
+### Essential References
+- **[Class Index](references/class-index.md)** - Naming conventions, 416-property table, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
+- **[Class Categories](references/class-categories.md)** - Complete prefix inventory by category (layout, colors, typography, states, etc.)
+- **[Dynamic Component Creation](references/dynamic-component-creation.md)** - `$.UI.create()` and `Alloy.createStyle()` for creating components in Controllers (READ FIRST for dynamic components)
+- **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
+- **[Semantic Colors](references/semantic-colors.md)** - Titanium semantic colors for Light/Dark mode via `semantic` command (v7.6.0)
+
+### 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
+- **[Values and Units](references/values-and-units.md)** - How `ti.ui.defaultunit` in `tiapp.xml` interprets the unitless numeric values PurgeTSS writes (foundational concept for spacing, sizes, typography)
+
+### 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
+
+### Appearance & Theming
+- **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
+- **[Semantic Colors](references/semantic-colors.md)** - `semantic` command + runtime usage for Light/Dark mode (v7.6.0)
+
+### 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
+- [iOS Large Titles](references/ios-large-titles.md) - Best practice for iOS Large Title navigation
+
+### App Assets
+- [App Branding](references/app-branding.md) - `brand` command for launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace assets (v7.6.0)
+- [Multi-Density Images](references/multi-density-images.md) - `images` command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
+
+### 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
+- [Custom Fonts](references/custom-fonts.md) - `build-fonts` command for Google Fonts, brand typefaces, and community icon fonts (.ttf + .css)
+- [Icon Fonts](references/icon-fonts.md) - The 4 official families (Font Awesome 7, Material Icons, Material Symbols, Framework7) — variant tables + `icon-library` install flow + recreating removed libraries
+- [Animation System](references/animation-system.md) - 15 methods including collision detection, transitions, and sequential animations
+- [Animation Advanced](references/animation-advanced.md) - Property inheritance, utility classes, implementation rules, complex UI example
+
+### Release Notes
+- [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.10.2)
+
 > **💡 TEXT FONTS (Google Fonts, Roboto, etc.)**
-> For text fonts, see [CLI Commands → build-fonts](references/cli-commands.md#purgetss-build-fonts-alias-bf).
->
-> ## 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](references/EXAMPLES.md) and [Dynamic Component Creation](references/dynamic-component-creation.md)
->
-> ## 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`    |
->
+> For text fonts, see [Custom Fonts](references/custom-fonts.md).
+
+## 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](references/EXAMPLES.md) and [Dynamic Component Creation](references/dynamic-component-creation.md)
+
+## 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`    |

package/skills/purgetss/references/EXAMPLES.md

@@ -272,7 +272,7 @@ alloy compile
 
 ### Square Brackets for Arbitrary Values
 
-**❌ WRONG (Using square brackets like Tailwind CSS):**
+**❌ WRONG (Square brackets are not supported):**
 ```xml
 <View class="w-[100px] bg-[#ff0000]" />
 ```
@@ -284,6 +284,13 @@ alloy compile
 
 **PurgeTSS syntax for arbitrary values uses `()` not `[]`.**
 
+> **🚨 v7.8.0+ HARD-FAILS THE BUILD ON SQUARE BRACKETS**
+> Since v7.8.0, the build stops with a structured `Class Syntax Error` block (file path + line number + `Fix:` suggestion) the moment it spots `top-[10px]`, `wh-[12]`, or any other square-bracket utility. Pre-v7.8.0, those classes silently dropped into the `// Unused or unsupported classes` block of `app.tss` — easy to miss. Now they're loud and actionable.
+>
+> v7.10.1 reworded the error message from `'Tailwind-style brackets "[ ]" are not supported'` to `'Square brackets "[ ]" are not supported'`. Same enforcement, less framing.
+>
+> See [Arbitrary Values → Class syntax pre-validation](arbitrary-values.md#class-syntax-pre-validation) for the full list of patterns the pre-validator catches (5 total, including inverted negative sign and whitespace inside parentheses).
+
 **Examples:**
 - `w-(100px)` - Custom width
 - `bg-(#ff0000)` - Custom background color