@maccesar/titools 2.7.2 → 2.9.0

package/skills/purgetss/references/semantic-colors.md

@@ -0,0 +1,386 @@
+# Semantic Colors
+
+Semantic colors let your app respond to Light / Dark mode changes without any extra runtime code. You define color **names** once, give each name a `light` and `dark` hex value, and Titanium resolves the right one at render time based on `Ti.UI.overrideUserInterfaceStyle`. PurgeTSS's contribution is the `theme.extend.colors` mapping in `config.cjs` that turns those names into utility classes like `bg-surface` or `text-on-surface`.
+
+This file covers the full workflow: the JSON schema, the `config.cjs` mapping, nesting rules (and the `[object Object]` trap), the numeric 11-step tonal-inversion pattern, alpha transparency, the `purgetss semantic` CLI, and three patterns for consuming semantic colors from controllers at runtime.
+
+For the mode-switching runtime that drives all of this (`Appearance.init()`, `Appearance.set(...)`, persistence), see [appearance-module.md](./appearance-module.md).
+
+> **INFO**
+>
+> Semantic color resolution is a **Titanium** feature, not PurgeTSS magic. Titanium natively reads `semantic.colors.json` (at `app/assets/` on Alloy, `Resources/` on Classic) and resolves any color-accepting property whose value matches a key in that file. PurgeTSS only generates the utility classes that point *at* those keys — the switching behavior is 100% native.
+
+## Setting up `semantic.colors.json`
+
+Create the `semantic.colors.json` file with your color definitions. The file location depends on your project type, per the TiDev convention:
+
+- **Alloy** → `app/assets/semantic.colors.json`
+- **Classic** → `Resources/semantic.colors.json`
+
+> **INFO**
+>
+> The `semantic` command (covered later on this page) auto-detects the project layout and writes to the right location — you don't need to specify it manually. The path examples below use the Alloy location; Classic users get their output under `Resources/` automatically.
+
+Each top-level key is a color name; each value is an object with `light` and `dark` hex strings.
+
+`app/assets/semantic.colors.json`
+```json
+{
+  "surfaceColor": {
+    "light": "#F9FAFB",
+    "dark":  "#0f172a"
+  },
+  "surfaceHighColor": {
+    "light": "#FFFFFF",
+    "dark":  "#1e293b"
+  },
+  "textColor": {
+    "light": "#111827",
+    "dark":  "#f1f5f9"
+  },
+  "textSecondaryColor": {
+    "light": "#6B7280",
+    "dark":  "#94a3b8"
+  },
+  "borderColor": {
+    "light": "#E5E7EB",
+    "dark":  "#334155"
+  },
+  "accentColor": {
+    "light": "#3B82F6",
+    "dark":  "#60a5fa"
+  }
+}
+```
+
+This is a reasonable 6-color starter palette: background, elevated surfaces, primary text, secondary text, borders, and an accent. Most apps can ship with just these and extend later.
+
+### Alpha transparency — the 8-digit format
+
+Titanium accepts the `#RRGGBBAA` 8-digit hex format anywhere a color is expected. Use it in either mode to produce translucent surfaces like overlays or glass sheets:
+
+```json
+{
+  "overlayColor": {
+    "light": "#00000080",
+    "dark":  "#000000CC"
+  },
+  "glassColor": {
+    "light": "#FFFFFFB3",
+    "dark":  "#0F172AB3"
+  }
+}
+```
+
+The last two hex digits are the alpha channel: `00` is fully transparent, `FF` is fully opaque, `80` is ~50%, `B3` is ~70%, `CC` is ~80%.
+
+## Registering in `config.cjs`
+
+Titanium resolves `surfaceColor` at runtime, but PurgeTSS needs to know which **class name** should emit that color. Map the JSON keys to class names under `theme.extend.colors`:
+
+`purgetss/config.cjs`
+```js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        surface: {
+          DEFAULT: 'surfaceColor',
+          high:    'surfaceHighColor'
+        },
+        'on-surface':         'textColor',
+        'on-surface-variant': 'textSecondaryColor',
+        border:               'borderColor',
+        accent:               'accentColor'
+      }
+    }
+  }
+}
+```
+
+This generates `bg-surface`, `bg-surface-high`, `text-on-surface`, `text-on-surface-variant`, `bg-border`, `text-accent`, `bg-accent`, etc. Any utility that takes a color — `bg-*`, `text-*`, `border-*`, `placeholder-*`, tint classes — can reference the name.
+
+### Nested pattern with `DEFAULT`
+
+One level of nesting is supported, and it must include a `DEFAULT` key for the base variant:
+
+```js
+// Correct -- generates bg-surface and bg-surface-high
+surface: {
+  DEFAULT: 'surfaceColor',
+  high:    'surfaceHighColor'
+}
+```
+
+`bg-surface` resolves to `surfaceColor` (the `DEFAULT`), and `bg-surface-high` resolves to `surfaceHighColor`.
+
+> **DANGER**
+>
+> Common error: nested objects without `DEFAULT`
+>
+> ```js
+> // Wrong -- generates [object Object] instead of a color
+> surface: {
+>   regular: 'surfaceColor',
+>   high:    'surfaceHighColor'
+> }
+> ```
+>
+> If you nest without a `DEFAULT` key and then use the base class (`bg-surface`), PurgeTSS serializes the whole nested object with `String(...)`, producing the literal string `[object Object]` as the color value. Titanium can't parse that, and the view renders with whatever fallback the platform has. Always include `DEFAULT` for the base variant, or use a flat structure.
+
+### Flat structure alternative
+
+If you prefer not to nest at all, every class name is a top-level key:
+
+```js
+colors: {
+  surface:        'surfaceColor',
+  'surface-high': 'surfaceHighColor',
+  'on-surface':   'textColor',
+  border:         'borderColor',
+  accent:         'accentColor'
+}
+```
+
+Both approaches work. The nested form groups related shades under one namespace; the flat form avoids the `DEFAULT` trap. Pick whichever reads better in your `config.cjs`.
+
+## Numeric 11-step tonal-inversion palette
+
+Instead of purpose-based names, you can model a color as an 11-step tonal scale (`50` through `950`) where each light-mode value **inverts** in dark mode. This gives you a full tonal range from a single palette and keeps dark-mode contrast in lockstep with light mode.
+
+`app/assets/semantic.colors.json`
+```json
+{
+  "color50":  { "light": "#030712", "dark": "#f9fafb" },
+  "color100": { "light": "#111827", "dark": "#f3f4f6" },
+  "color200": { "light": "#1f2937", "dark": "#e5e7eb" },
+  "color300": { "light": "#374151", "dark": "#d1d5db" },
+  "color400": { "light": "#4b5563", "dark": "#9ca3af" },
+  "color500": { "light": "#6b7280", "dark": "#6b7280" },
+  "color600": { "light": "#9ca3af", "dark": "#4b5563" },
+  "color700": { "light": "#d1d5db", "dark": "#374151" },
+  "color800": { "light": "#e5e7eb", "dark": "#1f2937" },
+  "color900": { "light": "#f3f4f6", "dark": "#111827" },
+  "color950": { "light": "#f9fafb", "dark": "#030712" }
+}
+```
+
+Mapped as a nested `primary` palette:
+
+`purgetss/config.cjs`
+```js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50:  'color50',
+          100: 'color100',
+          200: 'color200',
+          300: 'color300',
+          400: 'color400',
+          500: 'color500',
+          600: 'color600',
+          700: 'color700',
+          800: 'color800',
+          900: 'color900',
+          950: 'color950'
+        }
+      }
+    }
+  }
+}
+```
+
+You get `bg-primary-50`, `text-primary-950`, `border-primary-500`, etc. — and the tonal contrast automatically flips with the appearance.
+
+### How the inversion works
+
+| Role                  | Light     | Dark      | Notes                                       |
+| --------------------- | --------- | --------- | ------------------------------------------- |
+| `color50`  (extreme)  | `#030712` | `#f9fafb` | Darkest in light mode, lightest in dark     |
+| `color500` (middle)   | `#6b7280` | `#6b7280` | Anchor — identical in both modes            |
+| `color950` (mirror)   | `#f9fafb` | `#030712` | Mirror of `color50` — extremes reversed     |
+
+The stops mirror by index: `50` <-> `950`, `100` <-> `900`, `200` <-> `800`, and so on. `500` is the anchor and is identical in both modes.
+
+> **INFO**
+>
+> The numeric pattern and the purpose-based pattern can coexist in the same project. A common layout is: numeric scale for one brand family (`primary`, `secondary`), purpose-based names for surfaces and text (`surfaceColor`, `textColor`, `borderColor`). Use whichever expresses intent most clearly per role.
+
+## The `semantic` CLI command
+
+Writing the 11 JSON entries by hand (palette) or each purpose-based color (single) is mechanical and error-prone. The `purgetss semantic` command does both. Dispatch is by `--single` — omit it for palette mode, include it for single mode.
+
+### Palette mode — auto-generated tonal scale
+
+One base hex plus a family name produces 11 JSON entries with mirror inversion, plus a matching `config.cjs` mapping, in one step:
+
+```bash
+purgetss semantic '#15803d' amazon
+```
+
+This:
+
+1. Generates `amazon50` through `amazon950` using the same algorithm as the `shades` command.
+2. Writes `semantic.colors.json` at the project's canonical location (`app/assets/` on Alloy, `Resources/` on Classic) with mirror-by-index values — 50 ↔ 950, 100 ↔ 900, …, 500 as the identical anchor.
+3. Writes the `{ 50: 'amazon50', 100: 'amazon100', ... }` mapping into `config.cjs`.
+4. Strips any prior keys for the `amazon` family before writing — re-runs cleanly replace, never duplicate.
+
+Useful flags:
+
+- `--log` (`-l`) — preview the JSON on the console without writing anything.
+- `--override` (`-o`) — place the mapping in `theme.colors` instead of `theme.extend.colors`.
+- `--random` (`-r`) with `--name` (`-n`) — pick a random base color for a named family.
+
+```bash
+purgetss semantic '#15803d' amazon --log         # preview only
+purgetss semantic '#15803d' amazon --override    # goes into theme.colors
+purgetss semantic --random --name brand          # random base, named family
+```
+
+### Single mode — purpose-based with explicit per-mode hex
+
+For colors like `surfaceColor`, `textColor`, `borderColor`, or `overlayColor` — where light and dark values are hand-picked from the design system, not derived algorithmically. Pass `--single`, the light hex, the name, and optionally `--dark` and `--alpha`:
+
+```bash
+purgetss semantic --single '#F9FAFB' surfaceColor       --dark '#0f172a'
+purgetss semantic --single '#FFFFFF' surfaceHighColor   --dark '#1e293b'
+purgetss semantic --single '#111827' textColor          --dark '#f1f5f9'
+purgetss semantic --single '#6B7280' textSecondaryColor --dark '#94a3b8'
+purgetss semantic --single '#E5E7EB' borderColor        --dark '#334155'
+purgetss semantic --single '#3B82F6' accentColor        --dark '#60a5fa'
+purgetss semantic --single '#000000' overlayColor       --alpha 50
+```
+
+The name is preserved verbatim as the JSON key (camelCase is respected). When `--dark` is omitted, it defaults to the light hex — useful for overlays where alpha is the only variation between modes.
+
+Single mode writes **both files** in one shot. The class name is auto-derived from the semantic key by stripping the conventional `Color` suffix and kebab-casing the rest, so `surfaceHighColor` becomes the `surface-high` class:
+
+`./purgetss/config.cjs` (auto-generated)
+```js
+theme: {
+  extend: {
+    colors: {
+      surface:          'surfaceColor',
+      'surface-high':   'surfaceHighColor',
+      text:             'textColor',
+      'text-secondary': 'textSecondaryColor',
+      border:           'borderColor',
+      accent:           'accentColor',
+      overlay:          'overlayColor'
+    }
+  }
+}
+```
+
+After the batch above you can use `bg-surface`, `bg-surface-high`, `text-text`, `bg-accent`, `bg-overlay`, etc. immediately. If your design system uses different class names (for example `on-surface` instead of `text`, or the nested `surface: { DEFAULT, high }` form from earlier in this page), edit `config.cjs` after running the commands.
+
+> **INFO**
+>
+> Smart in-place updates
+>
+> If a `--single` name matches an existing palette shade — for example `pt semantic --single '#000' amazon500` while the `amazon` palette exists — the entry is updated in place in the JSON (preserving its position) and `config.cjs` is left untouched. The palette already maps to that key, so the operation is interpreted as "edit one shade", not "create a duplicate top-level color".
+
+### Alpha details
+
+Alpha follows the Titanium spec exactly: range `0.0-100.0`, stored as a **string**, wrapped per-mode as `{ color, alpha }`. Without `--alpha`, values stay as bare hex strings. Out-of-range values are rejected before any file is written.
+
+## Using semantic classes in views
+
+Once the JSON and the `config.cjs` mapping are in place, you use the semantic classes like any other PurgeTSS utility:
+
+```xml
+<Window class="bg-surface" title="Settings">
+  <ScrollView class="vertical content-w-screen content-h-auto">
+    <Label class="text-on-surface font-bold" text="Title" />
+    <Label class="text-on-surface-variant text-sm" text="Subtitle" />
+    <View class="h-px w-screen bg-border" />
+  </ScrollView>
+</Window>
+```
+
+When the appearance changes — whether from `Appearance.set(...)` or a system-level toggle — Titanium resolves each semantic color name to its `light` or `dark` value automatically. No event listeners, no manual repaint.
+
+## Using semantic colors in controllers
+
+Semantic colors also work from JavaScript. Three patterns cover the cases you'll hit.
+
+### Option 1 — Direct assignment by semantic name
+
+Titanium resolves the semantic name at runtime, so you can assign it straight to any color-accepting property. This skips PurgeTSS entirely and is the shortest path when you only need one or two changes:
+
+```js
+$.titleLabel.color           = 'textColor'
+$.card.backgroundColor       = 'surfaceHighColor'
+$.divider.backgroundColor    = 'borderColor'
+```
+
+### Option 2 — `$.UI.create()` with PurgeTSS classes
+
+When you build a component dynamically and want the full set of utilities (colors included), use `$.UI.create()`:
+
+```js
+const card = $.UI.create('View', {
+  classes: ['bg-surface-high', 'rounded-lg', 'mx-4', 'my-2']
+})
+
+const title = $.UI.create('Label', {
+  text:    'Settings',
+  classes: ['text-on-surface', 'font-bold', 'text-lg']
+})
+
+card.add(title)
+```
+
+### Option 3 — `Alloy.createStyle()` + `applyProperties()`
+
+To swap styles on an **existing** component — reacting to a state change, for example — build the style and apply it:
+
+```js
+const setActive = (isActive) => {
+  const style = Alloy.createStyle('index', {
+    apiName: 'Ti.UI.Label',
+    classes: isActive
+      ? ['text-accent', 'font-bold']
+      : ['text-on-surface-variant', 'font-normal']
+  })
+
+  $.statusLabel.applyProperties(style)
+}
+```
+
+> **INFO**
+>
+> When to use which
+>
+> - **Option 1** — single property change, no other utilities needed.
+> - **Option 2** — creating new components from scratch.
+> - **Option 3** — restyling components that already exist in the view.
+
+## Recommended starter palette
+
+A minimal semantic palette that covers most app surfaces:
+
+| Purpose            | Semantic name        | Light     | Dark      | Classes generated          |
+| ------------------ | -------------------- | --------- | --------- | -------------------------- |
+| Background         | `surfaceColor`       | `#F9FAFB` | `#0f172a` | `bg-surface`               |
+| Cards / elevated   | `surfaceHighColor`   | `#FFFFFF` | `#1e293b` | `bg-surface-high`          |
+| Primary text       | `textColor`          | `#111827` | `#f1f5f9` | `text-on-surface`          |
+| Secondary text     | `textSecondaryColor` | `#6B7280` | `#94a3b8` | `text-on-surface-variant`  |
+| Borders / dividers | `borderColor`        | `#E5E7EB` | `#334155` | `bg-border`                |
+| Accent             | `accentColor`        | `#3B82F6` | `#60a5fa` | `text-accent`, `bg-accent` |
+
+Start with these 5-6 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
+
+## Related
+
+- [appearance-module.md](./appearance-module.md) — `Appearance.init()`, `set(...)`, `get()`, `toggle()` — the runtime that switches the whole palette.
+- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — full reference for `purgetss semantic` (palette and single modes, all flags).
+- [customization-deep-dive.md](./customization-deep-dive.md) — full `config.cjs` structure, including `theme.extend` vs `theme.colors` and the rest of the extendable keys.
+
+## Community-Discovered Patterns
+
+- **The `[object Object]` crash is always a missing `DEFAULT`.** Any time a view renders with a mysterious fallback color and the class was something like `bg-surface`, check `config.cjs` first: if `surface` is a nested object without a `DEFAULT` key, PurgeTSS serializes the whole object and emits `[object Object]` as the color value. The fix is either to add `DEFAULT: 'surfaceColor'` inside the nested object or flatten the structure.
+- **Semantic resolution is Titanium-native, not PurgeTSS.** This matters when debugging: if a semantic name doesn't resolve, the problem is usually the `semantic.colors.json` file (wrong filename, wrong key, malformed JSON, or file in the wrong location — Alloy expects `app/assets/`, Classic expects `Resources/`), not PurgeTSS. PurgeTSS's job ends at generating the class that points at the name.
+- **Re-running `purgetss semantic` on the same family is safe.** The CLI strips prior keys for that family from both the JSON and `config.cjs` before writing, so switching between palette and single forms — or changing the base hex — does not leave orphans. Other palettes and manually-defined entries are untouched.

package/skills/purgetss/references/smart-mappings.md

@@ -1,30 +1,52 @@
 # Smart Mappings & Platform Realities
 
-PurgeTSS maps CSS-like utilities to native Titanium properties. Understanding these "Smart Mappings" is key to predictable layouts and cross-platform consistency.
-
-## 1. The "Gap" Utility (Double Spacing)
-In PurgeTSS, `gap` is mapped to **external margins** (`top`, `right`, `bottom`, `left`) because Titanium lacks a native CSS-style gap property.
-- **Behavior**: `.gap-4` adds 16dp to **all** sides of the element.
-- **Critical Difference**: In web CSS, gap only exists *between* elements. In PurgeTSS, two siblings with `.gap-4` will have **32dp** of space between them (16dp from each).
-- **Solution**: Use `.gap-x-` or `.gap-y-` for more granular control, or use specific margins (`ml-`, `mt-`) if you need exact CSS-style spacing.
-
-## 2. Hybrid Shadows (iOS vs. Android)
-Shadow utilities (`.shadow-md`, etc.) provide a cross-platform visual depth by mapping different native properties in a single class:
-- **iOS**: Uses `viewShadowOffset`, `viewShadowRadius`, and `viewShadowColor`.
-- **Android**: Uses the `elevation` property.
-- **Z-Order Warning**: On Android, `elevation` also affects the **Z-order** (stacking) of the view, causing it to appear on top of siblings without elevation. This behavior does **not** happen on iOS.
-
-## 3. Grid Container Width
-The `.grid` and `.grid-flow-col` classes automatically include `width: '100%'`.
-- **Why**: Since PurgeTSS resets `View` to `SIZE`, a grid container must be forced to `100%` (or `FILL`) so that children using percentage widths (like `.col-span-6`) have a parent dimension to calculate against.
-- **Manual Overrides**: If you need a grid that only occupies the size of its content, you must explicitly use `wh-auto`.
-
-## 4. Native Rotations
-The `.rotate-X` utilities map directly to Titanium's `rotate` property.
-- **Anchor**: By default, Titanium rotates around the **center** of the component.
-- **Matrix**: Unlike web CSS where transformations are often chained (e.g., `transform: rotate(45deg) scale(1.5)`), PurgeTSS/Titanium treats these as direct, separate properties of the view.
-
-## 5. Z-Index vs Stacking Order
-- **Class**: `.z-10`, `.z-50`, etc.
-- **Mapping**: Maps directly to Titanium's `zIndex` property.
-- **Note**: In Titanium, the order in which views are **added** to a parent determines their base stacking order (last added is on top). `zIndex` should be used sparingly for explicit overlays.
+Platform-bridge knowledge: how PurgeTSS utility classes translate to Titanium native properties under the hood. This is a curated synthesis — class names resemble Tailwind, but the values they emit target Titanium SDK properties (`zIndex`, `viewShadowOffset`, `elevation`, `anchorPoint`, `rotate`, `layout`, etc.), not CSS.
+
+For the full inventory of every available class, see [`class-index.md`](./class-index.md) and [`class-categories.md`](./class-categories.md).
+
+## Community-Discovered Patterns
+
+### 1. The "Gap" Utility (External Margins, Not CSS Gap)
+
+In PurgeTSS, `gap` is mapped to **external margins** on the element itself (`top`, `right`, `bottom`, `left`) because Titanium lacks a native CSS-style gap property.
+
+- **Behavior**: `.gap-4` emits `{ top: 16, right: 16, bottom: 16, left: 16 }` on the element — 16dp of margin on **all four sides**.
+- **Critical Difference from CSS**: In web CSS, `gap` only renders *between* flex/grid children. Here, two siblings each carrying `.gap-4` will show **32dp** of total space between them (16dp contributed by each).
+- **Directional variants** (verified in `lib/templates/` → compiled `dist/utilities.tss`):
+  - `.gap-x-{size}` — emits `right` and `left` only (horizontal margins).
+  - `.gap-y-{size}` — emits `top` and `bottom` only (vertical margins).
+  - `.gap-{t|r|b|l}-{size}` — single-side gap (e.g. `.gap-t-4`).
+- **Evidence**: Official [`purgetss-docs-context7/docs/grid-system.md`](https://github.com/macCesar/purgeTSS) § "Gutter utilities".
+
+### 2. Hybrid Shadows (iOS vs. Android in One Class)
+
+Shadow utilities (`.shadow-xs`, `.shadow-sm`, `.shadow`, `.shadow-md`, `.shadow-lg`, `.shadow-xl`, `.shadow-2xl`, `.shadow-inner`, `.shadow-outline`, `.shadow-none`) emit cross-platform depth by setting iOS and Android properties simultaneously:
+
+- **iOS**: `viewShadowOffset`, `viewShadowRadius`, `viewShadowColor`.
+- **Android**: `elevation`.
+- **Z-Order Warning (Android-only)**: On Android, `elevation` doubles as a stacking-order hint — an elevated view renders *on top of* siblings with lower or no elevation. iOS shadows do **not** affect z-order. If you apply `.shadow-md` to one card in a list, it may unexpectedly cover adjacent cards on Android.
+- **Evidence**: `dist/utilities.tss` (see `'.shadow-md': { viewShadowOffset: ..., elevation: 24 }`), cross-referenced against Titanium SDK `Ti.UI.View` property behavior.
+
+### 3. Grid Container Auto-Width
+
+The `.grid` and `.grid-flow-col` classes emit **both** `layout: 'horizontal'` **and** `width: '100%'` (`.grid-flow-row` emits `layout: 'vertical', height: '100%'`).
+
+- **Why the width is baked in**: PurgeTSS resets `View` defaults to `SIZE`. A grid container needs an explicit dimension so that percentage-based children (e.g. `.col-span-6` emitting `width: '50%'`) have a parent measurement to resolve against.
+- **Official docs** ([`grid-system.md`](https://github.com/macCesar/purgeTSS)) only document the `layout: 'horizontal'` half. The `width: '100%'` behavior is **verified against `lib/templates/` → `dist/utilities.tss`** (lines emit `'.grid': { layout: 'horizontal', width: '100%' }`).
+- **Manual override**: If you need a grid sized to its content only, pair it with `.wh-auto` or an explicit sizing utility.
+
+### 4. Native Rotations via `rotate` (Not CSS Transform)
+
+The `.rotate-{n}` utilities (`rotate-0`, `rotate-1`, `rotate-2`, `rotate-3`, `rotate-6`, `rotate-12`, `rotate-45`, `rotate-90`, `rotate-135`, `rotate-180`, `rotate-225`, `rotate-270`, `rotate-315`, `rotate-360`) map **directly** to Titanium's `rotate` property — a plain numeric degree value on the view.
+
+- **Default anchor**: Titanium rotates around the view's **center**. To change this, use an `.origin-*` utility (`.origin-top`, `.origin-top-left`, `.origin-center`, `.origin-bottom-right`, etc.) which emits `anchorPoint: { x, y }`.
+- **No chained transforms**: Unlike CSS (`transform: rotate(45deg) scale(1.5)`), Titanium treats each transformation as an independent view property. For combined transforms you must build a `Ti.UI.2DMatrix`/`Ti.UI.Matrix2D` and assign it to `transform`.
+- **Evidence**: `dist/utilities.tss` lines `'.rotate-45': { rotate: 45 }` and `'.origin-center': { anchorPoint: { x: 0.5, y: 0.5 } }`.
+
+### 5. Z-Index Uses the Full `z-index-*` Prefix
+
+- **Classes**: `.z-index-0`, `.z-index-10`, `.z-index-20`, `.z-index-30`, `.z-index-40`, `.z-index-50` (six values total).
+- **Mapping**: Each emits the Titanium `zIndex` property with the numeric suffix (`.z-index-10` → `{ zIndex: 10 }`).
+- **Important — no Tailwind-style `z-10` shorthand exists.** The full `z-index-` prefix is required. See [`class-index.md`](./class-index.md) (under `zIndex`) and [`class-categories.md`](./class-categories.md) (row "`z-index-*`").
+- **Titanium stacking note**: In a Titanium parent, the **order in which children are added** sets the base stacking (last `add()`ed is on top). `zIndex` should be used sparingly for explicit overlays; for Android, remember that `elevation` (from `.shadow-*` or `.elevation-*`) also influences rendering order.
+- **Evidence**: `dist/utilities.tss` lines 7952–7957.

package/skills/purgetss/references/tikit-components.md

@@ -316,7 +316,9 @@ Colors: `black`, `dark`, `light`, and `white` themes that affect background and
 
 Use this for code examples. Set `copy="true"` to add a copy button.
 
-**Pro tip:** For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config.
+> **Community-Discovered Pattern — Pro tip**
+>
+> For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config.
 
 **Localization:** The copy button uses `L('copy', 'Copy')` for its title and `L('code_copied', 'Code copied!')` for the confirmation message. Add these keys to your `strings.xml` files for translation.
 

package/skills/purgetss/references/titanium-resets.md

@@ -30,16 +30,7 @@ The most important reset is for the `View` element. By default, `View` is set to
 - Grow to accommodate explicit dimensions (`w-64`, `h-32`, etc.)
 - Expand to fill margins (`m-4`, `mx-2`, `mt-6 mb-4`, etc.)
 
-> **💡 EXPLICIT SIZE VS NATIVE UNDEFINED**
-> In Titanium, components like `Label`, `Button`, and `Switch` default to `SIZE` behavior, but their property values are `undefined`. This applies to **any component whose default size is `Ti.UI.SIZE`**, not just `Label` and `Button`.
->
-> According to the **UI Composite Layout Behavior Spec**, if a dimension is `undefined` and you apply two opposite pins (e.g., `left` and `right` via `mx-*`, or `top` and `bottom` via `my-*`), the motor will **compute the dimension based on the pins**, causing the element to stretch.
->
-> **PurgeTSS** recommends adding an explicit `SIZE` reset on the affected axis:
->
-> - Use `h-auto` when `mt-*` + `mb-*` or `my-*` would otherwise stretch the height.
-> - Use `w-auto` when `ml-*` + `mr-*` or `mx-*` would otherwise stretch the width.
-> - Use `wh-auto` as the safe reset when both axes may be affected.
+> **See also**: the "Explicit SIZE vs native undefined" callout under [Community-Discovered Patterns](#community-discovered-patterns) explains when to use `h-auto`, `w-auto`, and `wh-auto` to prevent unwanted stretching.
 
 ### Practical Examples
 
@@ -273,7 +264,7 @@ This generates classes for ALL color properties:
 When PurgeTSS generates your `app.tss`, these resets appear first:
 
 ```tss
-/* PurgeTSS v7.2.7 */
+/* PurgeTSS v7.6.0 */
 /* Created by César Estrada */
 /* https://purgetss.com */
 
@@ -291,6 +282,43 @@ When PurgeTSS generates your `app.tss`, these resets appear first:
 
 These are **always included** - they're fundamental to how PurgeTSS works.
 
+## Default font family classes (v7.5.3+)
+
+Starting with PurgeTSS v7.5.3, three `fontFamily` utility classes are auto-generated even when `theme.fontFamily` is not defined in `config.cjs`. Each class maps to a different per-platform value so iOS and Android each pick a native system font family:
+
+| Class        | iOS              | Android      |
+| ------------ | ---------------- | ------------ |
+| `font-sans`  | `Helvetica Neue` | `sans-serif` |
+| `font-serif` | `Georgia`        | `serif`      |
+| `font-mono`  | `monospace`      | `monospace`  |
+
+Usage:
+
+```xml
+<Label class="font-sans text-lg text-gray-800" text="System sans font" />
+<Label class="font-serif text-lg text-gray-800" text="System serif font" />
+<Label class="font-mono text-sm text-gray-700" text="Monospaced code" />
+```
+
+### Override behavior
+
+If you define `sans`, `serif`, or `mono` under `theme.fontFamily` (or `theme.extend.fontFamily`), your value replaces the default on **both** platforms — you no longer need a per-platform fork:
+
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: 'Inter-Regular'   // replaces Helvetica Neue / sans-serif on both platforms
+      }
+    }
+  }
+};
+```
+
+This keeps `font-serif` and `font-mono` at their defaults while `font-sans` now resolves to `Inter-Regular` on iOS and Android.
+
 ## Overriding Resets
 
 If you need different default behavior, add custom rules to `_app.tss` or `config.cjs`:
@@ -304,12 +332,12 @@ If you need different default behavior, add custom rules to `_app.tss` or `confi
 }
 ```
 
-**In `config.cjs` (preferred):**
+**In `config.cjs` (preferred, v7.5.0+):**
 ```javascript
 module.exports = {
   theme: {
-    View: {
-      DEFAULT: {
+    extend: {
+      View: {
         width: Ti.UI.FILL,
         height: Ti.UI.SIZE
       }
@@ -318,8 +346,11 @@ module.exports = {
 }
 ```
 
+> **⚠️ DEPRECATED SHAPE (pre-v7.5.0)**
+> The older `theme.View.DEFAULT` shape is deprecated as of PurgeTSS v7.5.0. Migrate to `theme.extend.View` shown above. The same extend-based shape works for any Ti element default (`Window`, `Label`, `ImageView`, etc.).
+
 > **💡 TIP**
-> Prefer `config.cjs` for custom defaults because they're preserved when PurgeTSS regenerates `app.tss`.
+> Prefer `config.cjs` for custom defaults because they're preserved when PurgeTSS regenerates `app.tss`. For advanced overrides — including per-platform defaults, `apply` shorthand, and pseudo-class targeting — see `customization-deep-dive.md`.
 
 ## Summary Table
 

package/skills/purgetss/references/ui-ux-design.md

@@ -10,6 +10,16 @@ This guide collects practical UI patterns that stay aligned with Titanium layout
 - Prefer `w-screen` over `w-full` when you need `Ti.UI.FILL`.
 - For dynamic components, prefer `$.UI.create()` over manual `Ti.UI.create*()` styling.
 
+## Related References
+
+- **iOS Large Titles**: For windows inside a `NavigationWindow` or `TabGroup` that use iOS large titles, pair `content-w-screen` + `content-h-auto` on the `ScrollView` with `extendEdges`, `autoAdjustScrollViewInsets`, and `largeTitleEnabled` on the `Window`. See `ios-large-titles.md` for the full three-property pattern and `config.cjs` global defaults.
+- **Light / Dark mode**: For automatic theme switching, see `appearance-module.md` (runtime appearance detection) and `semantic-colors.md` (adaptive color tokens). These pair with PurgeTSS utility classes to produce UIs that respect system appearance.
+- **Customizing resets and defaults**: See `titanium-resets.md` and `customization-deep-dive.md` for overriding the `View`, `Window`, and `ImageView` defaults via `theme.extend.View`.
+
+## Community-Discovered Patterns
+
+The catalog below collects real-world UI patterns verified against Titanium's composite/horizontal/vertical layout behavior and PurgeTSS's utility classes. These are not copied from the upstream docs — they are curated, production-tested combinations.
+
 ## Cards
 
 ### Elevated Card
@@ -156,11 +166,24 @@ This guide collects practical UI patterns that stay aligned with Titanium layout
 
 ### Icon Button
 
+In Titanium, a `Button` with an icon typically uses a single icon-font `Button` (no adjacent `Label`). Set the icon font on the button and use the glyph as the `title`:
+
 ```xml
-<Button class="rounded-lg bg-blue-500 text-white" title="Save" />
-<Label class="fas fa-save ml-2 text-white" />
+<!-- Icon-only button using Font Awesome solid -->
+<Button class="fas rounded-lg bg-blue-500 text-white" title="&#xf0c7;" />
 ```
 
+For an icon-with-text pair, use a horizontal `View` containing an icon `Label` and a text `Label`, then bind a `touchstart`/`click` handler on the container:
+
+```xml
+<View onClick="doSave" class="horizontal rounded-lg bg-blue-500">
+  <Label class="fas ml-4 my-3 text-white" text="&#xf0c7;" />
+  <Label class="mx-3 my-3 text-base font-semibold text-white" text="Save" />
+</View>
+```
+
+> **Note**: The Font Awesome `fas` class only applies the font family. Glyphs are passed as Unicode in `title`/`text`. See the PurgeTSS Font Awesome integration docs for the full glyph map.
+
 ## Navigation Patterns
 
 ### Top Bar with Title and Action
@@ -247,15 +270,18 @@ This guide collects practical UI patterns that stay aligned with Titanium layout
       <Label class="left-4 center text-xl font-bold text-gray-800" text="Screen Title" />
     </View>
 
-    <ScrollView class="h-screen w-screen">
-      <View class="vertical">
-        <Label class="mx-4 mt-4 text-base text-gray-700" text="Main content goes here." />
-      </View>
+    <ScrollView class="vertical content-w-screen content-h-auto">
+      <Label class="mx-4 mt-4 text-base text-gray-700" text="Main content goes here." />
     </ScrollView>
   </View>
 </Window>
 ```
 
+> **ScrollView sizing (PurgeTSS v7.3+)**
+> The recommended pattern for a vertically scrolling `ScrollView` is `class="vertical content-w-screen content-h-auto"`. This sets `layout=vertical`, `contentWidth=Ti.UI.FILL`, and `contentHeight=Ti.UI.SIZE` so the content region grows to fit its children. Older examples using `h-screen w-screen` on the `ScrollView` itself describe the viewport, not the content — use the `content-*` variants to describe how the scrollable content flows.
+>
+> For iOS windows with large titles, also apply `extendEdges`, `autoAdjustScrollViewInsets`, and `largeTitleEnabled` on the `Window`. See `ios-large-titles.md`.
+
 ### Two-Column Tablet Layout
 
 ```xml