@maccesar/titools 2.8.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.8.0",
+  "version": "2.10.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

@@ -112,6 +112,30 @@ purgetss create 'MyApp' -d -v fa
 # -v: Copy icon fonts (fa, mi, ms, f7)
 ```
 
+## 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`
@@ -380,11 +404,14 @@ purgetss create 'MyApp' -d -v fa
 > - **[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
@@ -392,6 +419,10 @@ purgetss create 'MyApp' -d -v fa
 > - [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
@@ -400,6 +431,11 @@ purgetss create 'MyApp' -d -v fa
 > - [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)

package/skills/purgetss/references/EXAMPLES.md

@@ -2,7 +2,11 @@
 
 Complete examples of common patterns with anti-patterns and correct implementations.
 
-## Titanium Layout Patterns
+## Community-Discovered Patterns
+
+The examples below catalog anti-patterns observed in real Titanium + PurgeTSS projects, paired with the correct approach. They are not exhaustive rules from official docs — they reflect pitfalls the community has hit often enough to warrant dedicated guidance.
+
+### Titanium Layout Patterns
 
 > **🚨 NO FLEXBOX IN TITANIUM**
 > Titanium does NOT support CSS Flexbox. All examples use `horizontal`, `vertical`, or `composite` layouts.
@@ -108,7 +112,7 @@ Complete examples of common patterns with anti-patterns and correct implementati
 
 ---
 
-## Manual .tss Files Anti-Pattern
+### Manual .tss Files Anti-Pattern
 
 **❌ WRONG (Creating manual .tss files):**
 ```xml
@@ -158,7 +162,7 @@ alloy compile
 
 ---
 
-## Grid with Percentages
+### Grid with Percentages
 
 **❌ WRONG (Children with % widths, parent without w-screen):**
 ```xml
@@ -179,7 +183,7 @@ alloy compile
 
 ---
 
-## Gap Usage
+### Gap Usage
 
 **❌ WRONG (gap adds margin all around, breaks % widths):**
 ```xml
@@ -200,7 +204,7 @@ alloy compile
 
 ---
 
-## Padding on Container Views
+### Padding on Container Views
 
 **❌ WRONG (Padding on Views doesn't work in Titanium):**
 ```xml
@@ -220,7 +224,7 @@ alloy compile
 
 ---
 
-## `w-full` vs `w-screen`
+### `w-full` vs `w-screen`
 
 **❌ WRONG (Using percentage-based width):**
 ```xml
@@ -244,7 +248,7 @@ alloy compile
 
 ---
 
-## `rounded-full` Without Size
+### `rounded-full` Without Size
 
 **❌ WRONG (rounded-full alone doesn't exist):**
 ```xml
@@ -266,7 +270,7 @@ alloy compile
 
 ---
 
-## Square Brackets for Arbitrary Values
+### Square Brackets for Arbitrary Values
 
 **❌ WRONG (Using square brackets like Tailwind CSS):**
 ```xml
@@ -288,7 +292,7 @@ alloy compile
 
 ---
 
-## Layout Defaults
+### Layout Defaults
 
 **❌ WRONG (Explicit composite class):**
 ```xml
@@ -318,18 +322,76 @@ alloy compile
 
 ---
 
-## Quick Reference Table
-
-| Anti-Pattern          | Why It Fails             | Correct Approach         |
-| --------------------- | ------------------------ | ------------------------ |
-| `flex-row`            | Flexbox not supported    | `horizontal`             |
-| `flex-col`            | Flexbox not supported    | `vertical`               |
-| `justify-*`           | Flexbox not supported    | Use margins/positioning  |
-| `items-center`        | Flexbox mental model     | Use layout + positioning |
-| `p-4` on View         | No padding on containers | `m-4` on children        |
-| `w-full`              | Percentage-based         | `w-screen` (Ti.UI.FILL)  |
-| `rounded-full`        | Needs size suffix        | `rounded-full-12`        |
-| `composite` class     | Already default          | Omit it                  |
-| `w-[100px]`           | Wrong syntax             | `w-(100px)`              |
-| Manual `.tss`         | Overwritten by PurgeTSS  | Use utility classes      |
-| `gap` with `%` widths | Total exceeds 100%       | Use explicit margins     |
+### ScrollView Without `content-w-screen` / `content-h-auto`
+
+**WRONG (ScrollView with children that overflow horizontally or never scroll vertically):**
+```xml
+<ScrollView class="w-screen h-screen">
+  <View class="vertical">
+    <Label text="Very long content..." />
+    <!-- many items -->
+  </View>
+</ScrollView>
+```
+
+**CORRECT (Explicit content sizing on the ScrollView itself):**
+```xml
+<ScrollView class="w-screen h-screen content-w-screen content-h-auto">
+  <View class="vertical">
+    <Label text="Very long content..." />
+    <!-- many items -->
+  </View>
+</ScrollView>
+```
+
+**Why:** `content-w-screen` sets `contentWidth: Ti.UI.FILL` so the scroll area matches the viewport horizontally; `content-h-auto` sets `contentHeight: Ti.UI.SIZE` so vertical scroll expands to fit children. Omitting these often produces a ScrollView that never scrolls or clips content unexpectedly.
+
+---
+
+### Deprecated `theme.View.DEFAULT` vs `theme.extend.View`
+
+**WRONG (old shape — deprecated in recent PurgeTSS):**
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    View: {
+      DEFAULT: { backgroundColor: '#ffffff' }
+    }
+  }
+}
+```
+
+**CORRECT (new `extend` shape):**
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    extend: {
+      View: { backgroundColor: '#ffffff' }
+    }
+  }
+}
+```
+
+**Why:** The nested `DEFAULT` key is a legacy artifact. Component-level theme overrides now live directly under `theme.extend.<Component>` and are merged with built-in defaults. Using the old shape silently produces unexpected styles on newer PurgeTSS versions.
+
+---
+
+### Quick Reference Table
+
+| Anti-Pattern                          | Why It Fails                         | Correct Approach                             |
+| ------------------------------------- | ------------------------------------ | -------------------------------------------- |
+| `flex-row`                            | Flexbox not supported                | `horizontal`                                 |
+| `flex-col`                            | Flexbox not supported                | `vertical`                                   |
+| `justify-*`                           | Flexbox not supported                | Use margins/positioning                      |
+| `items-center`                        | Flexbox mental model                 | Use layout + positioning                     |
+| `p-4` on View                         | No padding on containers             | `m-4` on children                            |
+| `w-full`                              | Percentage-based                     | `w-screen` (Ti.UI.FILL)                      |
+| `rounded-full`                        | Needs size suffix                    | `rounded-full-12`                            |
+| `composite` class                     | Already default                      | Omit it                                      |
+| `w-[100px]`                           | Wrong syntax                         | `w-(100px)`                                  |
+| Manual `.tss`                         | Overwritten by PurgeTSS              | Use utility classes                          |
+| `gap` with `%` widths                 | Total exceeds 100%                   | Use explicit margins                         |
+| ScrollView without `content-*` sizing | No/unexpected scroll                 | Add `content-w-screen` + `content-h-auto`    |
+| `theme.View.DEFAULT`                  | Legacy shape in newer PurgeTSS       | `theme.extend.View`                          |