@maccesar/titools 2.2.4 → 2.2.8

package/skills/ti-howtos/references/webpack-build-pipeline.md

@@ -1,21 +1,22 @@
-# Webpack Build Pipeline
+# Webpack build pipeline
 
-Webpack integration is available as an **alternative build pipeline** starting with Titanium SDK 9.1.0. It is not mandatory — projects work without it. When enabled, Webpack manages your project's assets and code bundling.
+Webpack integration is an alternative build pipeline starting with Titanium SDK 9.1.0. It is optional. When enabled, Webpack manages asset and code bundling.
 
-## 1. Key Benefits
-- **Lightning-Fast Incremental Builds**: Only what changes is processed.
-- **Native NPM Support**: Install any NPM library in the root and use it directly.
-- **Build-Time Resolution**: `require` calls are resolved during compilation, not at runtime.
+## 1. Key benefits
+- Fast incremental builds: only changed files are processed.
+- npm support: install packages in the root and import them directly.
+- Build-time resolution: `require` calls are resolved during compilation, not at runtime.
 
-## 2. The `@` Alias
-Webpack introduces the `@` alias to reference the source code root without using complex relative paths (`../../`).
+## 2. The `@` alias
+Webpack adds the `@` alias to reference the source root without deep relative paths.
 
-| Project Type | Path mapped by `@` |
+| Project type | Path mapped by `@` |
 | :----------- | :----------------- |
-| **Alloy**    | `app/lib`          |
-| **Classic**  | `src`              |
+| Alloy        | `app/lib`          |
+| Classic      | `src`              |
+
+Usage example:
 
-**Usage Example:**
 ```javascript
 // Before (without webpack)
 import Utils from '../../utils/helper';
@@ -24,33 +25,36 @@ import Utils from '../../utils/helper';
 import Utils from '@/utils/helper';
 ```
 
-## 3. NPM Dependency Management
-Simply install your favorite package in the project root:
+## 3. npm dependency management
+Install a package in the project root:
+
 ```bash
 npm install lodash
 ```
-And use it in your Titanium code:
+
+Use it in Titanium code:
+
 ```javascript
 import _ from 'lodash';
 const data = _.chunk(['a', 'b', 'c', 'd'], 2);
 ```
 
-## 4. Platform-Specific Files
-Webpack automatically detects platform-specific files using the `filename.<platform>.js` pattern.
+## 4. Platform-specific files
+Webpack detects platform-specific files using the `filename.<platform>.js` pattern.
 
-**Example:**
+Example:
 - `utils.js` (common)
 - `utils.ios.js` (iOS only)
 - `utils.android.js` (Android only)
 
-When doing `import { func } from '@/utils'`, Webpack will select the correct version based on the build target.
+When you `import { func } from '@/utils'`, Webpack picks the correct version for the build target.
 
-## 5. Diagnostic Web UI
-Webpack includes a web interface to analyze the build and asset sizes.
+## 5. Diagnostic web UI
+Webpack includes a web interface to analyze builds and asset sizes.
 Default URL: `http://localhost:1732/webpack/latest/web`
 
-## 6. Project Plugins
-Webpack support is powered by plugins that handle different project types. Plugins are automatically selected based on your project:
+## 6. Project plugins
+Webpack support is powered by plugins chosen based on project type:
 
 | Plugin                             | Purpose                 |
 | ---------------------------------- | ----------------------- |
@@ -59,25 +63,26 @@ Webpack support is powered by plugins that handle different project types. Plugi
 | `@appcd/webpack-plugin-babel`      | Babel transpilation     |
 | `@appcd/webpack-plugin-typescript` | TypeScript support      |
 
-### Custom Plugin Configuration
-Plugins can be customized using the `webpack-chain` API in your project's `webpack.config.js`:
+### Custom plugin configuration
+Customize with the `webpack-chain` API in `webpack.config.js`:
 
 ```javascript
 module.exports = (api) => {
-    // Add a custom alias
-    api.chainWebpack((config) => {
-        config.resolve.alias.set('@utils', api.resolve('app/lib/utils'));
-    });
+  // Add a custom alias
+  api.chainWebpack((config) => {
+    config.resolve.alias.set('@utils', api.resolve('app/lib/utils'));
+  });
 };
 ```
 
 Common customizations:
-- **Add alias**: `config.resolve.alias.set(name, path)`
-- **Add loader**: `config.module.rule(name).use(name).loader(loader)`
-- **Delete plugin**: `config.plugins.delete(name)`
+- Add alias: `config.resolve.alias.set(name, path)`
+- Add loader: `config.module.rule(name).use(name).loader(loader)`
+- Delete plugin: `config.plugins.delete(name)`
+
+## 7. Advanced configuration
+Extend configuration via plugins in `package.json`:
 
-## 7. Advanced Configuration
-You can extend the configuration via plugins in `package.json`:
 ```json
 {
   "appcdWebpackPlugins": [
@@ -86,29 +91,32 @@ You can extend the configuration via plugins in `package.json`:
 }
 ```
 
-## 8. Global Configuration
+## 8. Global configuration
 Configure Webpack daemon settings in `~/.appcelerator/appcd/config.json`:
+
 ```json
 {
-    "webpack": {
-        "inactivityTimeout": 600000
-    }
+  "webpack": {
+    "inactivityTimeout": 600000
+  }
 }
 ```
 
 ## 9. Troubleshooting
 
-**Build seems stuck**: The Webpack daemon may need a restart:
+Build seems stuck: the Webpack daemon may need a restart.
+
 ```bash
 appcd exec /webpack/latest/stop
 ```
 
-**View build logs**:
+View build logs:
+
 ```bash
 appcd logcat "*webpack*"
 ```
 
-## 10. Known Limitations
-- **Hyperloop**: Currently not compatible with the Webpack pipeline.
-- **Alloy.jmk**: Build hooks are not supported — use Webpack plugins instead.
-- First build may be slower due to daemon startup.
+## 10. Known limitations
+- Hyperloop is not compatible with the Webpack pipeline.
+- Alloy.jmk build hooks are not supported. Use Webpack plugins instead.
+- The first build may be slower due to daemon startup.

package/skills/ti-ui/SKILL.md

@@ -5,154 +5,154 @@ argument-hint: "[component]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---
 
-# Titanium SDK UI Expert
+# Titanium SDK UI expert
 
-Comprehensive expert covering all official Titanium SDK UI how-to guides. Provides guidance on cross-platform UI/UX, event handling, animations, performance optimization, and platform-specific components.
+A practical guide to Titanium SDK UI. Covers layouts, event handling, animations, performance, and platform-specific components for iOS and Android.
 
-## Project Detection
+## Project detection
 
-:::info AUTO-DETECTS TITANIUM PROJECTS
-This skill automatically detects Titanium projects when invoked and provides UI/UX component guidance.
+:::info auto-detects titanium projects
+This skill detects Titanium projects and provides UI guidance.
 
-**Detection occurs automatically** - no manual command needed.
+Detection happens automatically. You do not need to run a command.
 
-**Titanium project indicator:**
-- `tiapp.xml` file (required for all Titanium projects)
+Titanium project indicator:
+- `tiapp.xml` (required for all Titanium projects)
 
-**Applicable to BOTH:**
-- **Alloy projects** (app/ folder structure)
-- **Classic projects** (Resources/ folder)
+Applicable to both:
+- Alloy projects (app/ folder structure)
+- Classic projects (Resources/ folder)
 
-**Behavior based on detection:**
-- **Titanium detected** → Provides UI component guidance for both Alloy and Classic, ListView/TableView patterns, platform-specific UI differences
-- **Not detected** → Indicates this is for Titanium projects only, does NOT provide Titanium UI guidance
+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
 :::
 
-## Quick Reference
+## Quick reference
 
 | Topic                            | Reference                                                               |
 | -------------------------------- | ----------------------------------------------------------------------- |
-| **App Structures**               | [application-structures.md](references/application-structures.md)       |
+| 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) |
+| 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)                     |
+| 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)     |
 
-## Critical Rules (Low Freedom)
+## Critical rules
 
 ### Performance
-- **NO `Ti.UI.SIZE` in ListViews**: Causes jerky scrolling. Use fixed heights.
-- **Prefer ListView over TableView** for new apps with large datasets.
-- **Batch updates**: Use `applyProperties` to reduce bridge crossing overhead.
-- **WebView in TableView**: Anti-pattern causing severe scrolling issues.
+- 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.
 
-### iOS Accessibility
-- **NO accessibility properties on container views**: Blocks children interaction.
-- **NO accessibilityLabel on text controls** (Android): Overrides visible text.
+### 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**: Vertical OR horizontal, not both. Set `scrollType`.
+- Use `dp` units for cross-platform consistency.
+- Android ScrollView is vertical or horizontal, not both. Set `scrollType`.
 
-### Platform-Specific Properties
+### Platform-specific properties
 
-:::danger CRITICAL: Platform-Specific Properties Require Modifiers
-Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties WITHOUT platform modifiers causes cross-platform compilation failures.
+:::danger 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:**
+Example of the damage:
 ```javascript
-// ❌ WRONG - Adds Ti.UI.iOS to Android project
+// Wrong: adds Ti.UI.iOS to an Android build
 const win = Ti.UI.createWindow({
-  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
+  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
 })
 ```
 
-**CORRECT approaches:**
+Correct approaches:
 
-**Option 1 - TSS modifier (Alloy projects):**
+Option 1: TSS modifier (Alloy projects):
 ```tss
 "#mainWindow[platform=ios]": {
   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
 }
 ```
 
-**Option 2 - Conditional code:**
+Option 2: Conditional code:
 ```javascript
 if (OS_IOS) {
   $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT
 }
 ```
 
-**Properties that ALWAYS require platform modifiers:**
+Properties that always require platform modifiers:
 - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
 - Android: `actionBar` config, any `Ti.UI.Android.*` constant
 
-**For complete platform-specific UI patterns, see** [Platform UI - iOS](references/platform-ui-ios.md) and [Platform UI - Android](references/platform-ui-android.md).
+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.
-- **Event bubbling**: Input events bubble up; system events do not.
+### 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 less** for better UX across platforms.
-- **Use NavigationWindow for iOS** hierarchical navigation.
-- **Handle androidback** to prevent unexpected app exits.
+### 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
+## Platform differences summary
 
 | Feature                | iOS                          | Android                 |
 | ---------------------- | ---------------------------- | ----------------------- |
-| 3D Matrix              | ✅ Full support               | ❌ No                    |
-| Pinch gesture          | ✅ Full support               | ⚠️ Limited               |
+| 3D Matrix              | Full support                 | No support              |
+| Pinch gesture          | Full support                 | Limited                 |
 | ScrollView             | Bidirectional                | Unidirectional          |
-| TableView              | ✅ Full support               | ✅ Full support          |
-| ListView               | ✅ Full support               | ✅ Full support          |
+| TableView              | Full support                 | Full support            |
+| ListView               | Full support                 | Full support            |
 | Default template image | Left side                    | Right side              |
-| ListView action items  | ✅ Swipe actions              | ❌ No                    |
+| 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 (most common) or Window-based
-2. **Layout Selection**: Choose mode (composite/vertical/horizontal) based on structure
-3. **Sizing Strategy**: Assign `SIZE` or `FILL` based on component defaults
-4. **Event Architecture**: Plan bubbling, app-level events, lifecycle
-5. **Performance**: Use ListView/TableView templates, batch updates
-6. **Accessibility**: Apply a11y properties per platform requirements
-7. **Motion**: Add animations, 2D/3D transforms, transitions
-
-## Searching References
-
-When looking for specific patterns, grep these terms in 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`
-
-## Related Skills
-
-For tasks beyond UI components, use these complementary skills:
-
-| Task                                            | Use This Skill |
+## 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`
+
+## 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`    |

package/skills/ti-ui/references/accessibility-deep-dive.md

@@ -1,18 +1,18 @@
-# Accessibility (a11y) Deep Dive
+# Accessibility (a11y) deep dive
 
 ## 1. Overview
 
-Accessibility ensures your app is usable by everyone, including users with visual, hearing, and motor disabilities. Titanium supports both Android TalkBack and iOS VoiceOver spoken feedback systems.
+Accessibility makes your app usable for people with visual, hearing, and motor disabilities. Titanium works with Android TalkBack and iOS VoiceOver for spoken feedback.
 
-### Design Considerations Beyond Screen Readers
+### Design considerations beyond screen readers
 
-- **Motor disabilities**: Provide larger tap targets (minimum 44x44 points on iOS, 48x48 dp on Android). Support alternative input methods. Avoid interactions that require precise gestures or rapid timing.
-- **Color-blindness**: Never rely on color alone to convey information. Use text labels, icons, or patterns alongside color indicators. Test your UI with grayscale to verify usability.
-- **Screen magnifiers**: Users with low vision may use the built-in zoom features (iOS Zoom, Android Magnification). Ensure your layout remains functional when magnified — avoid absolute positioning that breaks at large zoom levels.
+- Motor disabilities often require larger tap targets (minimum 44x44 points on iOS, 48x48 dp on Android). Support alternative input methods and avoid gestures that demand precision or fast timing.
+- Color-blindness means color alone cannot carry meaning. Use text labels, icons, or patterns alongside color indicators. Test the UI in grayscale to check usability.
+- Screen magnifiers are common for low-vision users (iOS Zoom, Android Magnification). Keep layouts functional when magnified and avoid absolute positioning that breaks at large zoom levels.
 
-## 2. Core Accessibility Properties
+## 2. Core accessibility properties
 
-All Titanium view elements support these accessibility properties:
+All Titanium view elements support these accessibility properties.
 
 | Property              | Default Value                 | Description                                                                     |
 | --------------------- | ----------------------------- | ------------------------------------------------------------------------------- |
@@ -21,9 +21,9 @@ All Titanium view elements support these accessibility properties:
 | `accessibilityHint`   | -                             | Briefly describes what performing an action will do (e.g., "Closes the window") |
 | `accessibilityValue`  | State or value of the control | String describing current state (e.g., "Selected", "50 percent")                |
 
-> **Android note**: On Android, `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` are combined (in that order) and mapped to Android's native `contentDescription` property. This means TalkBack reads all three as a single string, while VoiceOver on iOS reads them as separate announcements.
+> Android note: On Android, `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` are combined (in that order) and mapped to the native `contentDescription`. TalkBack reads them as one string. VoiceOver on iOS reads them as separate announcements.
 
-### Basic Usage
+### Basic usage
 
 ```javascript
 const button = Ti.UI.createButton({
@@ -83,7 +83,7 @@ container.add(emailField);
 container.add(submitButton);
 ```
 ...
-### Star Rating Example
+### Star rating example
 
 ```javascript
 const starView = Ti.UI.createView({
@@ -105,7 +105,7 @@ for (let i = 0; i < 5; i++) {
 }
 ```
 
-### Toggle Button Example
+### Toggle button example
 
 ```javascript
 let isMuted = false;
@@ -122,9 +122,9 @@ muteButton.addEventListener('click', () => {
 });
 ```
 
-## 6. System-Level Accessibility Events
+## 6. System-level accessibility events
 
-### Monitor Accessibility Changes
+### Monitor accessibility changes
 
 ```javascript
 Ti.App.addEventListener('accessibilitychanged', (e) => {
@@ -136,9 +136,9 @@ Ti.App.addEventListener('accessibilitychanged', (e) => {
 });
 ```
 ...
-### Code Patterns
+### Code patterns
 
-**DO**:
+Do:
 ```javascript
 // Provide meaningful labels
 const iconButton = Ti.UI.createButton({
@@ -153,7 +153,7 @@ checkbox.accessibilityValue = isChecked ? 'Checked' : 'Unchecked';
 decorativeIcon.accessibilityHidden = true;
 ```
 
-**DON'T**:
+Don't:
 ```javascript
 // Don't set accessibilityLabel for text controls (Android)
 const label = Ti.UI.createLabel({
@@ -168,9 +168,9 @@ const container = Ti.UI.createView({
 });
 ```
 
-### Accessibility First Development
+### Accessibility-first development
 
-When designing complex UIs, consider accessibility from the start:
+When designing complex UIs, plan accessibility at the start.
 
 ```javascript
 function createAccessibleListItem(title, subtitle, action) {
@@ -196,9 +196,9 @@ function createAccessibleListItem(title, subtitle, action) {
 }
 ```
 
-## 9. Platform Behavior Comparison
+## 9. Platform behavior comparison
 
-TalkBack (Android) and VoiceOver (iOS) interpret accessibility properties differently:
+TalkBack (Android) and VoiceOver (iOS) interpret accessibility properties differently.
 
 | Element                          | TalkBack Response                                 | VoiceOver Response                                      |
 | -------------------------------- | ------------------------------------------------- | ------------------------------------------------------- |
@@ -208,31 +208,31 @@ TalkBack (Android) and VoiceOver (iOS) interpret accessibility properties differ
 | Checkbox, checked                | "Checked, checkbox, double-tap to toggle"         | "Checked, tick box"                                     |
 | Image with label "Profile photo" | "Profile photo"                                   | "Profile photo, image"                                  |
 
-> On Android, the three accessibility properties are concatenated into `contentDescription`, so they are always read as one utterance. On iOS, VoiceOver reads them as distinct pieces with brief pauses between them.
+> On Android, the three accessibility properties are concatenated into `contentDescription`, so they are read as one utterance. On iOS, VoiceOver reads them as distinct pieces with short pauses between them.
 
-## 10. Testing Procedures
+## 10. Testing procedures
 
-### Android Emulator
+### Android emulator
 
-The Android emulator does not provide a built-in method to test accessibility. You must test on a physical device for accurate TalkBack behavior.
+The Android emulator has no built-in way to test accessibility. Use a physical device for accurate TalkBack behavior.
 
-### Android Device (TalkBack)
+### Android device (TalkBack)
 
 1. Open **Settings > Accessibility > TalkBack**
 2. Toggle TalkBack **On**
-3. A confirmation dialog appears — confirm to enable
+3. A confirmation dialog appears; confirm to enable
 
-**TalkBack gestures**:
-- **Tap**: Select and hear the element described
-- **Double-tap**: Activate the selected element
-- **Swipe left/right**: Navigate to the previous/next element
-- **Swipe up/down**: Change reading granularity (characters, words, headings)
+TalkBack gestures:
+- Tap: Select and hear the element described
+- Double-tap: Activate the selected element
+- Swipe left/right: Navigate to the previous/next element
+- Swipe up/down: Change reading granularity (characters, words, headings)
 
-To disable TalkBack, navigate to the same setting and toggle it off. You can also set a hardware shortcut (hold both volume keys for 3 seconds) for quick toggling during development.
+To disable TalkBack, go to the same setting and toggle it off. You can also set a hardware shortcut (hold both volume keys for 3 seconds) for quick toggling during development.
 
-### iOS Simulator (Accessibility Inspector)
+### iOS simulator (Accessibility Inspector)
 
-Use the Accessibility Inspector to examine elements without enabling VoiceOver:
+Use the Accessibility Inspector to examine elements without enabling VoiceOver.
 
 1. In Xcode, go to **Xcode > Open Developer Tool > Accessibility Inspector**
 2. Select the Simulator as the target device
@@ -240,49 +240,49 @@ Use the Accessibility Inspector to examine elements without enabling VoiceOver:
 
 This is the fastest way to verify properties during development.
 
-### iOS Device (VoiceOver)
+### iOS device (VoiceOver)
 
 1. Open **Settings > Accessibility > VoiceOver**
 2. Toggle VoiceOver **On**
 
-**VoiceOver gestures**:
-- **Tap**: Select and hear the element described
-- **Double-tap**: Activate the selected element
-- **Swipe left/right**: Navigate to the previous/next element
-- **Three-finger swipe**: Scroll content
-- **Two-finger tap**: Pause/resume speech
+VoiceOver gestures:
+- Tap: Select and hear the element described
+- Double-tap: Activate the selected element
+- Swipe left/right: Navigate to the previous/next element
+- Three-finger swipe: Scroll content
+- Two-finger tap: Pause/resume speech
 
-To disable VoiceOver, navigate to the same setting and toggle it off. You can also configure the Accessibility Shortcut (triple-click the side button) for quick toggling.
+To disable VoiceOver, go to the same setting and toggle it off. You can also configure the Accessibility Shortcut (triple-click the side button) for quick toggling.
 
-## 11. External Resources
+## 11. External resources
 
 - [Accessibility Programming Guide for iOS](https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/iPhoneAccessibility/Introduction/Introduction.html)
 - [Android Accessibility API Guide](http://developer.android.com/guide/topics/ui/accessibility/index.html)
 - [Android Accessibility Design Guide](http://developer.android.com/design/patterns/accessibility.html)
 - [W3C Web Content Accessibility Guidelines](http://www.w3.org/WAI/WCAG20/quickref/)
 
-## 12. Common Issues
+## 12. Common issues
 
-### Issue: VoiceOver Can't Access Children
+### Issue: VoiceOver cannot access children
 
-**Cause**: Container view has accessibility properties set
+Cause: A container view has accessibility properties set.
 
-**Solution**: Remove all accessibility properties from container views
+Solution: Remove all accessibility properties from container views.
 
-### Issue: TalkBack Doesn't Speak Text
+### Issue: TalkBack does not speak text
 
-**Cause**: `accessibilityLabel` set on Label/Button overrides visible text
+Cause: `accessibilityLabel` on a Label/Button overrides visible text.
 
-**Solution**: Don't set `accessibilityLabel` on textual controls unless intentionally overriding
+Solution: Do not set `accessibilityLabel` on textual controls unless you are intentionally overriding.
 
-### Issue: Complex Custom Controls Not Accessible
+### Issue: Complex custom controls are not accessible
 
-**Cause**: No accessibility properties set on custom-drawn views
+Cause: Custom-drawn views have no accessibility properties.
 
-**Solution**: Always provide `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` for custom controls
+Solution: Provide `accessibilityLabel`, `accessibilityValue`, and `accessibilityHint` for custom controls.
 
-### Issue: State Changes Not Announced
+### Issue: State changes are not announced
 
-**Cause**: `accessibilityValue` not updated when state changes
+Cause: `accessibilityValue` is not updated when state changes.
 
-**Solution**: Always update `accessibilityValue` in change event handlers
+Solution: Update `accessibilityValue` in change event handlers.