@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-ui/SKILL.md

@@ -1,159 +1,44 @@
 ---
 name: ti-ui
-description: "Use when working with, reviewing, analyzing, or examining Titanium SDK UI/UX patterns and components — Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar). AUTO-DETECT: If tiapp.xml exists, invoke BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
-argument-hint: "[component]"
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
+description: 'Use when working with Titanium SDK native UI layouts, ListView or TableView, app icons and launch screens, navigation, tabs, Android back handling, safe areas, or platform-specific UI conventions in Classic or Alloy projects.'
 ---
 
-# Titanium SDK UI expert
+# Titanium SDK user interface
 
-A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.
+Use the current official UI guides for Titanium Classic and Alloy. Titanium controls are native views; its layout system is shared across platforms and differs from CSS.
 
-> **When "new UI" means new files, run the `ti-reuse-first` skill first.** A new window, panel or dialog is often an existing one that needs a parameter, and a layout computed in JavaScript is often a TSS condition. This guide covers how to build whatever survives that question.
+Before creating new UI files, use `ti-reuse-first` to check existing screens and components.
 
-## Project detection
+## Required workflow
 
-> **️ℹ️ auto-detects titanium projects**
-> This skill detects Titanium projects and provides UI guidance.
->
-> Detection happens automatically. You do not need to run a command.
->
-> Titanium project indicator:
-> - `tiapp.xml` (required for all Titanium projects)
->
-> Applicable to both:
-> - Alloy projects (app/ folder structure)
-> - Classic projects (Resources/ folder)
->
-> Behavior based on detection:
-> - Titanium detected: Provide UI guidance for Alloy and Classic, ListView/TableView patterns, and platform differences
-> - Not detected: State this is for Titanium projects only and skip UI guidance
+1. Confirm the project has `tiapp.xml` and identify its selected SDK.
+2. Open the relevant reference below before giving instructions or editing UI.
+3. Cite the reference used as `[source: references/<file>.md]`. Read the linked release-specific API when a property, event, default or platform restriction matters.
+4. For a topic not covered by these guides, consult `ti-api` and the current official API. Do not reconstruct an unpublished guide from archived recipes or memory. Mark an unverified claim `FROM_MEMORY (unverified):` if it cannot be checked.
+5. Verify the affected layout on its intended platform before claiming visual correctness.
 
-## Quick reference
+## Guide routing
 
-| Topic                            | Reference                                                               |
-| -------------------------------- | ----------------------------------------------------------------------- |
-| App structures                   | [application-structures.md](references/application-structures.md)       |
-| Layouts, positioning, units      | [layouts-and-positioning.md](references/layouts-and-positioning.md)     |
-| Events, bubbling, lifecycle      | [event-handling.md](references/event-handling.md)                       |
-| ScrollView vs ScrollableView     | [scrolling-views.md](references/scrolling-views.md)                     |
-| TableView                        | [tableviews.md](references/tableviews.md)                               |
-| ListView templates, performance  | [listviews-and-performance.md](references/listviews-and-performance.md) |
-| Touch, swipe, pinch, gestures    | [gestures.md](references/gestures.md)                                   |
-| Orientation handling             | [orientation.md](references/orientation.md)                             |
-| Custom fonts, attributed strings | [custom-fonts-styling.md](references/custom-fonts-styling.md)           |
-| Animations, 2D/3D matrices       | [animation-and-matrices.md](references/animation-and-matrices.md)       |
-| Icons, splash screens, densities | [icons-and-splash-screens.md](references/icons-and-splash-screens.md)   |
-| Android action bar, themes       | [platform-ui-android.md](references/platform-ui-android.md)             |
-| iOS navigation, 3D Touch         | [platform-ui-ios.md](references/platform-ui-ios.md)                     |
-| VoiceOver, TalkBack, a11y        | [accessibility-deep-dive.md](references/accessibility-deep-dive.md)     |
+| Task | Reference |
+| --- | --- |
+| Native UI model and guide selection | [User interface](references/user-interface.md) |
+| Composite, vertical, horizontal layouts; units, sizing, measurement | [Layout and positioning](references/layouts-and-positioning.md) |
+| ListView templates, sections, items, events; choosing TableView | [Lists and tables](references/listviews-and-performance.md) |
+| iOS and Android app icons, launch screens, app name | [Icons and launch screens](references/icons-and-splash-screens.md) |
+| NavigationWindow, Android activities/back, bars, tabs, safe areas, platform branches | [Platform conventions](references/platform-conventions.md) |
 
-## Critical rules
+## Sources and release scope
 
-### Performance
-- Do not use `Ti.UI.SIZE` in ListViews. It causes jerky scrolling. Use fixed heights.
-- Prefer ListView over TableView for new apps with large datasets.
-- Batch updates with `applyProperties` to reduce bridge overhead.
-- Avoid WebView inside TableView. It kills scrolling performance.
+These references follow the current [official UI documentation](https://titaniumsdk.com/docs/build/ui), maintained in [tidev/titaniumsdk.com](https://github.com/tidev/titaniumsdk.com/tree/main/content/docs/build/ui). Use the pages' `.md` versions when reading them with an agent. The guide corpus identifies SDK 13.4.1; SDK 14-only instructions require its released contracts before use.
 
-### iOS accessibility
-- Do not set accessibility properties on container views. It blocks child interaction.
-- Do not set `accessibilityLabel` on text controls on Android. It overrides visible text.
-
-### Layout
-- Use `dp` units for cross-platform consistency.
-- Android ScrollView is vertical or horizontal, not both. Set `scrollType`.
-
-### Platform-specific properties
-
-> **🚨 critical: platform-specific properties require modifiers**
-> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers will crash cross-platform compilation.
->
-> Example of the damage:
-> ```javascript
-> // Wrong: adds Ti.UI.iOS to an Android build
-> const win = Ti.UI.createWindow({
->   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> })
-> ```
->
-> Correct approaches:
->
-> Option 1: TSS modifier (Alloy projects):
-> ```tss
-> "#mainWindow[platform=ios]": {
->   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> }
-> ```
->
-> Option 2: Conditional code:
-> ```javascript
-> if (OS_IOS) {
->   $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> }
-> ```
->
-> Properties that always require platform modifiers:
-> - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
-> - Android: `actionBar` config, any `Ti.UI.Android.*` constant
->
-> For platform-specific UI patterns, see [platform-ui-ios.md](references/platform-ui-ios.md) and [platform-ui-android.md](references/platform-ui-android.md).
-
-### Event management
-- Remove global listeners (`Ti.App`, `Ti.Gesture`, `Ti.Accelerometer`) on pause to save battery.
-- Input events bubble up. System events do not.
-
-### App architecture
-- Limit tabs to 4 or fewer for better UX across platforms.
-- Use NavigationWindow for iOS hierarchical navigation.
-- Handle `androidback` to prevent unexpected exits.
-
-## Platform differences summary
-
-| Feature                | iOS                          | Android                 |
-| ---------------------- | ---------------------------- | ----------------------- |
-| 3D Matrix              | Full support                 | No support              |
-| Pinch gesture          | Full support                 | Limited                 |
-| ScrollView             | Bidirectional                | Unidirectional          |
-| TableView              | Full support                 | Full support            |
-| ListView               | Full support                 | Full support            |
-| Default template image | Left side                    | Right side              |
-| ListView action items  | Swipe actions                | No                      |
-| Modal windows          | Fills screen, covers tab bar | No effect (always full) |
-| Navigation pattern     | NavigationWindow             | Back button + Menu      |
-
-## UI design workflow
-
-1. Choose app structure: tab-based or window-based
-2. Pick a layout mode: composite, vertical, or horizontal
-3. Decide sizing: `SIZE` or `FILL` based on component defaults
-4. Plan events: bubbling, app-level events, lifecycle
-5. Optimize performance: templates, batch updates
-6. Apply accessibility per platform
-7. Add motion: animations, 2D/3D transforms, transitions
-
-## Searching references
-
-When you need specific patterns, grep these terms in the reference files:
-- App structure: `TabGroup`, `NavigationWindow`, `modal`, `execution context`, `androidback`
-- Layouts: `dp`, `Ti.UI.SIZE`, `Ti.UI.FILL`, `composite`, `vertical`, `horizontal`
-- Events: `addEventListener`, `cancelBubble`, `bubbling`, `Ti.App.fireEvent`
-- TableView: `TableView`, `TableViewRow`, `setData`, `appendRow`, `className`
-- ListView: `ItemTemplate`, `bindId`, `setItems`, `updateItemAt`, `marker`
-- Gestures: `swipe`, `pinch`, `longpress`, `shake`, `accelerometer`
-- Animation: `animate`, `create2DMatrix`, `create3DMatrix`, `autoreverse`
-- Fonts: `fontFamily`, `PostScript`, `createAttributedString`, `ATTRIBUTE_`
-- Icons/splash: `DefaultIcon`, `appicon`, `nine-patch`, `drawable`, `splash`, `iTunesArtwork`, `adaptive`
-- Android: `Action Bar`, `onCreateOptionsMenu`, `theme`, `Material3`, `talkback`
-- iOS: `3D Touch`, `Popover`, `SplitWindow`, `badge`, `NavigationWindow`
-- Accessibility: `accessibilityLabel`, `VoiceOver`, `TalkBack`, `accessibilityHidden`
+The [release-specific API](https://titaniumsdk.com/docs/sdk/13.4.1) resolves property and platform details when a guide disagrees. In particular, iOS `Window.extendSafeArea` defaults to `true`; set `false` when content should stay within the safe area. PNG icons are the supported baseline here; do not assume a newer icon format works in SDK 13.4.1.
 
 ## Related skills
 
-For work beyond UI components, use these skills:
-
-| Task                                            | Use this skill |
-| ----------------------------------------------- | -------------- |
-| Project architecture, services, memory cleanup  | `ti-expert`    |
-| Native features (camera, location, push, media) | `ti-howtos`    |
-| Alloy MVC, data binding, widgets                | `alloy-guides` |
+| Task | Skill |
+| --- | --- |
+| Properties, methods, events, accessibility, gestures, animations and other UI API contracts | `ti-api` |
+| Alloy views, styles and data binding | `alloy-guides` |
+| Configuration, SDK setup and distribution | `ti-guides` |
+| Location, media, notifications and other native integrations | `ti-howtos` |
+| Existing component discovery | `ti-reuse-first` |