@maccesar/titools 4.3.0 → 4.4.0

package/skills/ti-expert/references/feedback-migration.md

@@ -0,0 +1,165 @@
+# Migrating feedback surfaces
+
+Migrate semantics, not proxy names. Replacing every native dialog with the same
+custom modal preserves the original design problem.
+
+## Contents
+
+- [Inventory](#inventory)
+- [Classify before replacing](#classify-before-replacing)
+- [Migrate one window at a time](#migrate-one-window-at-a-time)
+- [Deliberate silence](#deliberate-silence)
+- [Contract tests](#contract-tests)
+- [Delivery verification](#delivery-verification)
+- [When to share Widgets between apps](#when-to-share-widgets-between-apps)
+
+## Inventory
+
+Search the application for:
+
+```bash
+rg -n "createAlertDialog|createOptionDialog|createNotification|Toast|toast|snackbar|overlay" app/
+```
+
+Also inspect helpers that wrap these calls, XML overlays, controller timers,
+global events, and callbacks that can present UI indirectly. Record for every
+occurrence:
+
+- trigger and current message;
+- success, information, warning, error, confirmation, or choice;
+- blocking versus non-blocking;
+- reversible versus irreversible;
+- app-owned versus system-owned;
+- callback side effects and cancellation behavior;
+- owning window and cleanup path.
+
+Do not implement the replacement until every occurrence has a semantic target
+from `feedback-surfaces.md`.
+
+## Classify before replacing
+
+Use these defaults:
+
+- ordinary success and undoable actions → Snackbar;
+- recoverable field validation → inline validation;
+- persistent app condition → Banner or inline notice;
+- blocking failure or required acknowledgement → Dialog;
+- uncommon irreversible decision → destructive Dialog;
+- several related actions or app-data choices → Bottom Sheet;
+- long structured content → scrollable sheet or dedicated screen;
+- OS permission, picker, share, date/time, biometric, or purchase flow → keep the
+  system surface.
+
+Preserve domain behavior separately from presentation. Services return results
+or errors; the window/controller that owns visible context chooses the surface.
+Do not let a service create app-owned UI, especially before the root window
+exists.
+
+## Migrate one window at a time
+
+1. Register the required Widget dependencies in `app/config.json`.
+2. Add the Widgets as the final visual children of the window XML.
+3. Attach modal Widgets after the window exists.
+4. Route each old result to its classified surface.
+5. Call Widget `destroy()` from the window close cleanup.
+6. Exercise success, failure, cancel, Back, backdrop, double tap, and consecutive
+   presentation paths.
+7. Remove the old dialog, local overlay, helper, timer, and listener after the
+   migrated window passes verification.
+8. Commit the completed vertical slice before moving to the next window.
+
+Do not keep commented legacy implementations. Version control is the rollback
+mechanism; commented duplicates hide incomplete migrations and stale callbacks.
+
+## Deliberate silence
+
+Cancellation or an unknowable result can be a complete, intentional outcome.
+Model it explicitly and do not infer a message from falsy values.
+
+Example contract for an exported file:
+
+```javascript
+function handleSaveResult(error, result) {
+  if (error) {
+    $.dialog.show({
+      title: L('error'),
+      message: error.message,
+      tone: 'error',
+      confirmTitle: L('close')
+    })
+    return
+  }
+
+  if (result.saved === true) {
+    $.snackbar.show({
+      message: L('file_saved'),
+      tone: 'success'
+    })
+  }
+
+  // saved === false: Android picker was cancelled; the internal original remains.
+  // saved === null: iOS does not report whether the person completed the save.
+  // Both outcomes are deliberately silent.
+}
+```
+
+Do not add "Cancelled" for `saved === false`. Do not claim success for
+`saved === null`. Cover both branches with tests so a future fallback does not
+erase the intended silence.
+
+## Contract tests
+
+Add repository-appropriate static or unit tests for:
+
+- all Widget folders, manifests, XML views, controllers, and dependency entries;
+- each public method documented in `feedback-widget-contracts.md`;
+- the expected Widget declared in every migrated window;
+- absence of app-owned `Ti.UI.createAlertDialog` and
+  `Ti.UI.createOptionDialog` defaults;
+- removal of the previous local Snackbar/overlay and timer;
+- Snackbar replacement and timer reset;
+- Dialog and Bottom Sheet FIFO ordering;
+- exactly-once callbacks under double taps and competing close paths;
+- Android Back and backdrop policy;
+- cleanup of active and queued presentations;
+- explicit silence for cancel and indeterminate save results.
+
+Do not enforce blanket bans on native system surfaces. A remaining native call
+must be tied to an OS-owned interaction or documented fallback.
+
+## Delivery verification
+
+Run the project's real commands rather than assuming names. A complete migration
+normally includes:
+
+1. lint with zero errors and no new warnings;
+2. unit and contract tests with no new failures;
+3. PurgeTSS generation when detected, followed by inspection of unused or
+   unsupported classes at the end of `app.tss`;
+4. Alloy compilation for Android and iOS;
+5. native builds for every supported platform;
+6. manual checks in light, dark, and system appearance;
+7. phone and tablet/large-screen checks;
+8. Back, backdrop, cancel, double tap, long list, and long localized text checks;
+9. VoiceOver and TalkBack focus/traversal checks;
+10. consecutive presentation and window-close cleanup checks.
+
+Record pre-existing failures before migration and require the final run to add
+none. Build artifacts are not proof of usable modal behavior; perform the manual
+interaction checks on device or simulator.
+
+## When to share Widgets between apps
+
+Extract or copy a Widget into another app only when:
+
+- its API is stable and contains no business rules;
+- localized strings and callbacks are supplied by the host;
+- appearance depends on a documented semantic-token contract;
+- platform and minimum Titanium/Alloy versions are declared;
+- lifecycle and accessibility tests travel with it;
+- at least two apps need the same behavior, or one app has a clear portability
+  requirement.
+
+Do not extract merely because a view appeared three times. Extract because the
+boundary is independently understandable, testable, and maintainable.
+

package/skills/ti-expert/references/feedback-surfaces.md

@@ -0,0 +1,140 @@
+# Feedback surfaces and app-owned UI
+
+Use this guide before choosing a Titanium proxy or drawing a component. The
+surface follows the meaning of the event: style comes afterwards.
+
+## Contents
+
+- [Decision sequence](#decision-sequence)
+- [Feedback scale](#feedback-scale)
+- [App-owned versus system-owned](#app-owned-versus-system-owned)
+- [What to standardize next](#what-to-standardize-next)
+- [Phone, tablet, and accessibility](#phone-tablet-and-accessibility)
+- [References](#references)
+
+## Decision sequence
+
+Classify the event in this order:
+
+1. **Owner**: does the app own the interaction, or does the operating system?
+2. **Blocking**: can the person continue safely without acknowledging it?
+3. **Recovery**: is the action reversible or is data at risk?
+4. **Location**: does the message belong to a field, a screen, or the whole app?
+5. **Persistence**: is it transient, persistent until state changes, or modal?
+6. **Choice shape**: is there one acknowledgement, a binary decision, or a list
+   of related actions?
+
+Do not begin with "which native dialog can display this string?" That turns
+different meanings into the same interruption and makes the app feel visually
+inconsistent.
+
+## Feedback scale
+
+| Situation | Preferred surface | Why |
+| --- | --- | --- |
+| Ordinary success or confirmation | Snackbar | Visible without interrupting the task |
+| Undoable action | Snackbar with one Undo action | Keeps recovery close to the event |
+| Non-blocking warning | Warning Snackbar | Calls attention without forcing acknowledgement |
+| Invalid value in one field | Inline validation next to that field | Preserves context and identifies the fix |
+| Form-wide recoverable validation | Inline summary; Snackbar only if no single field owns it | Avoids a modal loop |
+| Persistent connectivity, sync, or account state | Banner or inline notice | Remains visible while the condition remains true |
+| Blocking error or required acknowledgement | Dialog | The task cannot continue safely |
+| Uncommon irreversible action | Destructive confirmation Dialog | Provides a safe escape before data loss |
+| Several actions related to the current context | Bottom Sheet | Presents a compact choice without pretending it is an error |
+| Long, searchable, or multi-select options | Bottom Sheet, sheet, or dedicated screen with `ListView` | A dialog is too constrained |
+| Multi-step task or complex form | Sheet or dedicated screen | The interaction has its own workflow |
+| No content yet | Empty State inside the screen | This is screen state, not transient feedback |
+| Initial or blocking work | Loading/Progress state in context | Communicates progress without inventing a message |
+
+Reserve Dialogs for critical information. Do not use them merely because they
+are easy to create. If an action is common and undoable, prefer immediate
+execution plus Undo over confirmation.
+
+### Snackbar versus Toast
+
+For app-owned foreground feedback, standardize on Snackbar. It supports the
+app's semantic colors, accessibility, safe-area positioning, duration policy,
+and one optional recovery action. Do not maintain both a custom Toast and a
+Snackbar for the same job.
+
+A platform Toast can remain only when the operating system owns the behavior or
+when a documented platform fallback is necessary. It is not the default design
+surface.
+
+### Banner versus Snackbar
+
+- Use Snackbar when the event has happened and the message can disappear.
+- Use Banner or inline notice while an ongoing condition remains relevant.
+- Never keep a Snackbar indefinitely to simulate persistent screen state.
+
+### Bottom Sheet versus Dialog
+
+- Use Bottom Sheet for related choices: sorting, exporting, selecting a category,
+  or choosing an action for an item.
+- Use Dialog for acknowledgement or a consequential confirm/cancel decision.
+- Move long prose, structured data, search, or complex input into a sheet or
+  dedicated screen.
+
+## App-owned versus system-owned
+
+Recreate and brand a surface only when the app owns its content and behavior.
+Keep the platform UI when the system owns trust, permissions, identity, files,
+or another protected workflow.
+
+| Keep native/system-owned | May be app-owned and styled |
+| --- | --- |
+| Permission prompts | Success, warning, and error feedback |
+| File and document pickers | Destructive confirmations |
+| Share sheets and activity views | Contextual action lists |
+| Date/time pickers when the platform interaction is desired | Category and app-data selectors |
+| Camera and media authorization UI | Loading, empty, and error states |
+| Biometric authentication prompt | Banners and inline validation |
+| Keyboard, autofill, purchases, notifications, and OS settings | App-specific onboarding or education |
+
+An app may explain why a system surface is about to appear, but it must not
+imitate the trusted system prompt. Use the official Titanium API or native module
+for the system-owned part.
+
+Cancellation is often a normal system outcome. Do not turn every cancellation
+into an error, a "Cancelled" message, or an unsupported success claim. Document
+silence explicitly at the call site when it is meaningful.
+
+## What to standardize next
+
+After Snackbar, Dialog, and Bottom Sheet, the highest-value shared patterns are:
+
+1. **Banner / Inline Notice** for persistent app state.
+2. **Loading / Progress wrapper** that uses the native activity indicator but
+   standardizes placement, text, blocking behavior, and cleanup.
+3. **Empty / Error State** for consistent screen-level recovery.
+4. **Field Validation** for message placement, focus, accessibility, and colors.
+
+Standardize buttons, cards, badges, chips, skeletons, and coach marks only when
+real product repetition exposes a stable contract. A visual resemblance alone
+does not justify a Widget.
+
+## Phone, tablet, and accessibility
+
+- On phones, present contextual choices from the bottom and keep touch targets
+  reachable.
+- On tablets and large screens, use a centered, width-limited action surface or
+  a platform-appropriate anchored presentation; do not stretch phone geometry
+  edge to edge.
+- Respect safe areas, bottom navigation, orientation, split screen, text scaling,
+  and localized strings.
+- Announce transient feedback appropriately and move accessibility focus into a
+  modal surface when it opens.
+- While a modal is active, prevent interaction with and accessibility traversal
+  into the underlying content. Restore the exact previous state on close.
+- Back, backdrop, Cancel, and destructive actions must have predictable semantics
+  and must never execute callbacks more than once.
+
+## References
+
+- [Titanium Alloy Widgets](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Widgets.html)
+- [Apple Human Interface Guidelines: Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
+- [Apple Human Interface Guidelines: Modality](https://developer.apple.com/design/human-interface-guidelines/modality)
+- [Material Design 3: Snackbar](https://m3.material.io/components/snackbar/overview)
+- [Material Design 3: Dialogs](https://m3.material.io/components/dialogs/overview)
+- [Material Design 3: Bottom sheets](https://m3.material.io/components/bottom-sheets/overview)
+

package/skills/ti-expert/references/feedback-widget-contracts.md

@@ -0,0 +1,213 @@
+# Contracts for feedback Widgets
+
+Use these contracts for app-owned Snackbar, Dialog, and Bottom Sheet surfaces in
+Alloy. Namespaces and visual tokens belong to each app; behavior stays stable.
+
+## Contents
+
+- [Boundary and registration](#boundary-and-registration)
+- [Snackbar](#snackbar)
+- [Dialog](#dialog)
+- [Bottom Sheet](#bottom-sheet)
+- [Shared lifecycle contract](#shared-lifecycle-contract)
+- [PurgeTSS integration](#purgetss-integration)
+- [Widget, Require, state, or native UI](#widget-require-state-or-native-ui)
+
+## Boundary and registration
+
+Implement each surface as an independent Alloy Widget under `app/widgets/`.
+Each Widget owns its XML, controller, optional styles, assets, state, listeners,
+timers, and `widget.json`. Keep them independent from any third-party component
+library — including TiKit, the Alloy/PurgeTSS component set. A feedback surface
+must not require one to work, and must not be folded into one: its value comes
+from being installable and testable on its own.
+
+Register every Widget in `app/config.json`:
+
+```json
+{
+  "dependencies": {
+    "com.example.ui.bottomsheet": "1.0.0",
+    "com.example.ui.dialog": "1.0.0",
+    "com.example.ui.snackbar": "1.0.0"
+  }
+}
+```
+
+Use the app's reverse-domain namespace. The dependency key must match the `id`
+in that Widget's `widget.json`.
+
+Declare Widgets in XML, normally as the last visual children of the owning
+window so overlays render above screen content:
+
+```xml
+<Widget id="snackbar" src="com.example.ui.snackbar" />
+<Widget id="dialog" src="com.example.ui.dialog" />
+<Widget id="bottomSheet" src="com.example.ui.bottomsheet" />
+```
+
+Build the stable proxy tree in XML. JavaScript may update properties and supply
+`ListView` data; it must not reconstruct the complete surface imperatively.
+
+## Snackbar
+
+```javascript
+$.snackbar.show({
+  message,
+  tone: 'neutral', // neutral | success | warning | error
+  duration: 4500,
+  actionTitle,
+  onAction,
+  onDismiss
+})
+
+$.snackbar.dismiss()
+$.snackbar.destroy()
+```
+
+Contract:
+
+- A new message replaces the visible message and restarts the timer.
+- Default `duration` is 4500 ms; `duration: 0` remains visible until an action,
+  `dismiss()`, replacement, or destruction.
+- Allow at most one text action, such as Undo.
+- Invoke `onAction` once, then close the Snackbar.
+- Invoke `onDismiss` once with the reason `timeout`, `action`, `replaced`,
+  `programmatic`, or `destroy`.
+- Clear the old timer before replacement and on every close path.
+- Position above bottom navigation and inside the current safe area.
+- Queueing Snackbars is not the default. The newest relevant message wins.
+
+## Dialog
+
+```javascript
+$.dialog.attach(window)
+
+$.dialog.show({
+  title,
+  message,
+  tone: 'neutral', // neutral | warning | error
+  confirmTitle,
+  cancelTitle,
+  destructive: false,
+  onConfirm,
+  onCancel
+})
+
+$.dialog.dismiss('programmatic')
+$.dialog.destroy()
+```
+
+Contract:
+
+- Without `cancelTitle`, present an acknowledgement. With it, present a
+  confirmation.
+- Enqueue additional `show()` calls FIFO. Never stack two Dialogs visually.
+- Disable both buttons on the first accepted tap.
+- Invoke `onConfirm` or `onCancel` at most once; never both.
+- Cancel button, Android Back, or allowed backdrop dismissal invokes `onCancel`.
+  Android Back closes an acknowledgement as its single dismissal action.
+- A destructive confirmation must not close from a backdrop tap.
+- `dismiss('programmatic')` closes without treating the operation as a user
+  confirmation or cancellation.
+- `destroy()` clears the active request and queue without running business
+  callbacks.
+- Use platform-familiar safe/cancel ordering and a distinct destructive role;
+  do not hard-code one platform's button order for both.
+
+## Bottom Sheet
+
+```javascript
+$.bottomSheet.attach(window)
+
+$.bottomSheet.show({
+  title,
+  message,
+  items: [{
+    id,
+    title,
+    subtitle,
+    icon,
+    tone: 'neutral',
+    enabled: true
+  }],
+  selectedId,
+  onSelect,
+  onCancel
+})
+
+$.bottomSheet.dismiss('cancel')
+$.bottomSheet.destroy()
+```
+
+Contract:
+
+- Render items with a fixed `ListView` template and data objects. Support long
+  lists, disabled rows, optional subtitles/icons, and a selected marker.
+- Enqueue additional `show()` calls FIFO. Never stack sheets.
+- Accept the first enabled selection only, invoke `onSelect(item)` once, and
+  close.
+- Backdrop, Android Back, Cancel, or `dismiss('cancel')` invokes `onCancel` once.
+- Other programmatic dismissal and `destroy()` do not imply cancellation and do
+  not execute business callbacks.
+- Present from the bottom on phones. On tablets and large screens, use a centered,
+  width-limited action surface. Reserve `anchor` for a future anchored variant;
+  do not expose behavior that is not implemented.
+
+## Shared lifecycle contract
+
+- Prefer one instance of each needed Widget per window. Add a global coordinator
+  only after real cross-window requirements exist.
+- Call `attach(window)` after the host window/controller exists. Call `destroy()`
+  from the host's close cleanup.
+- Make `destroy()` idempotent. Remove listeners, clear timers, cancel pending
+  animation callbacks, clear queues, and release callback references.
+- Guard every asynchronous completion with the current presentation generation
+  so a stale timer or animation cannot dismiss a newer request.
+- Consume backdrop events and prevent them from bubbling to underlying controls.
+- Save the host's previous accessibility state, exclude underlying content while
+  modal, move focus to the surface, and restore the saved state on close.
+- Keep localized copy outside the Widget. Pass strings and business callbacks in
+  the public API.
+- Keep business logic out of the Widget. It reports a choice; the host performs
+  domain work.
+- Verify every callback path for exactly-once behavior: action, confirm, cancel,
+  Back, backdrop, timeout, replacement, programmatic dismissal, and destruction.
+
+## PurgeTSS integration
+
+When `purgetss/` or `purgetss/config.cjs` exists, load the `purgetss` skill before
+writing styles. `ti-expert` decides the component boundary; `purgetss` decides
+the verified utilities and configuration.
+
+Apply these architectural rules:
+
+- Set PurgeTSS `options.widgets` to `true` so Widget XML is scanned.
+- Express stable anatomy and utility classes in Widget XML.
+- Use semantic color names for surfaces, text, borders, accent, overlay, success,
+  warning, and error. Let Titanium resolve light/dark variants.
+- Do not edit generated `app/styles/app.tss`.
+- Use `widget.tss` only for properties that have no verified utility or that are
+  inherently specific to the Widget.
+- Declare animations as XML `Animation` proxies using `purgetss.ui`. Use explicit
+  `open()` and `close()` calls instead of toggle behavior.
+- After generation, inspect the final `app.tss` section for unused or unsupported
+  classes and resolve every new entry.
+
+Do not copy class inventories into this skill and do not guess Tailwind-like
+names. The installed PurgeTSS skill remains the source of truth.
+
+## Widget, Require, state, or native UI
+
+| Choose | When |
+| --- | --- |
+| Alloy Widget | Self-contained public API, state/lifecycle ownership, portable boundary, or reuse across apps/screens |
+| `<Require>` controller | App-specific view/controller composition that shares the host's domain and lifecycle |
+| Screen state in XML | Loading, empty, content, or error presentation belongs only to that screen |
+| TSS or PurgeTSS utilities | Repeated visual treatment has no behavior, state, or lifecycle |
+| Native/system UI | The operating system owns permissions, trust, files, sharing, identity, purchases, or another protected flow |
+
+Usage count is evidence, not a threshold. A component can deserve a Widget on
+its first use if it has a stable portable API and non-trivial lifecycle; three
+similar labels still do not deserve one.
+

package/skills/ti-expert/references/migration-patterns.md

@@ -4,7 +4,8 @@
 ## Contents
 
 - [Assessment checklist](#assessment-checklist)
-- [Phase 1: TSS organization](#phase-1-tss-organization)
+- [Phase 1: styling-system organization](#phase-1-styling-system-organization)
+- [Phase 1B: feedback surfaces](#phase-1b-feedback-surfaces)
 - [Phase 2: service layer extraction](#phase-2-service-layer-extraction)
 - [Phase 3: event system migration](#phase-3-event-system-migration)
 - [Phase 4: navigation service](#phase-4-navigation-service)
@@ -21,24 +22,36 @@ Before migrating, evaluate the current codebase:
 
 | Area        | Signs of Legacy Code                               | Target State                                  |
 | ----------- | -------------------------------------------------- | --------------------------------------------- |
-| Styling     | Inline attributes, scattered styles                | Organized TSS files (per-controller + global) |
+| Styling     | Inline attributes, scattered styles                | PurgeTSS utilities when detected; otherwise organized Alloy TSS |
 | Controllers | 200+ lines, API calls, business logic              | Thin orchestrators (<100 lines)               |
 | Events      | `Ti.App.fireEvent` everywhere                      | Backbone.Events or StateStore                 |
 | Navigation  | Direct `Alloy.createController().getView().open()` | Navigation service                            |
 | Data        | Scattered `Ti.App.Properties`, no collections      | Centralized state + Collections               |
 
-## Phase 1: TSS organization
+## Phase 1: styling-system organization
 
-**Goal**: Migrate from inline styling and scattered styles to well-organized TSS files.
+**Goal**: Migrate from inline and scattered styling into the styling system the
+project actually uses.
+
+### Step 0: detect PurgeTSS
+
+Check for `purgetss/` or `purgetss/config.cjs` before editing styles.
+
+- **PurgeTSS detected:** invoke the `purgetss` skill, use verified utilities and
+  semantic colors, configure reusable rules in `config.cjs`, and never edit the
+  generated `app/styles/app.tss`.
+- **No PurgeTSS:** use standard per-controller TSS and a manually maintained
+  `app/styles/app.tss` for genuinely global selectors.
+
+Do not migrate a PurgeTSS application back into manual TSS by following a generic
+Alloy example.
 
 ### Step 1: audit existing styles
 
-Find all inline attributes and consolidate into TSS files:
+Find inline attributes and classify them for the detected styling system:
 ```bash
 # Find inline styling in XML views
-grep -r 'backgroundColor=' app/views/
-grep -r 'font=' app/views/
-grep -r 'color=' app/views/
+rg -n 'backgroundColor=|font=|color=' app/views/
 ```
 
 ### Step 2: move inline attributes to TSS
@@ -51,7 +64,7 @@ grep -r 'color=' app/views/
 ```
 
 ```xml
-<!-- AFTER: Clean XML + TSS file -->
+<!-- AFTER in standard Alloy: clean XML + TSS file -->
 <View id="header">
   <Label id="title" text="L('welcome')" />
 </View>
@@ -63,9 +76,11 @@ grep -r 'color=' app/views/
 "#title": { color: "#333", font: { fontSize: 18, fontWeight: "bold" } }
 ```
 
-### Step 3: organize TSS structure
+### Step 3: organize standard Alloy TSS
+
+This step applies only when PurgeTSS is not present.
 
-1. Use `app.tss` for global styles (shared across all views)
+1. Use `app.tss` for genuinely global styles shared across views
 2. Use per-controller TSS files for view-specific styles
 3. Use class selectors for reusable style patterns:
 ```tss
@@ -74,6 +89,18 @@ grep -r 'color=' app/views/
 ".btn-primary": { backgroundColor: '#2563eb', color: '#fff', height: 44, borderRadius: 8 }
 ```
 
+In either styling path, replace hard-coded visual colors with semantic roles as
+part of the migration. See [Theming and Dark Mode](theming.md).
+
+## Phase 1B: feedback surfaces
+
+Inventory native alerts, option dialogs, Toasts, and local overlays. Classify
+each occurrence before replacing it, then migrate one window at a time. Preserve
+system-owned pickers, permission prompts, sharing, and biometric UI.
+
+Use [Feedback Migration](feedback-migration.md) for the sequence, deliberate
+silence rules, and verification contract.
+
 ## Phase 2: service layer extraction
 
 **Goal**: Move business logic from controllers to services.
@@ -280,11 +307,12 @@ const { user } = appStore.getState()
 
 Recommended sequence to minimize risk:
 
-1. **TSS Organization** - Visual only, no logic changes
-2. **Service Layer** - Extract logic without changing behavior
-3. **Navigation Service** - Centralize with cleanup
-4. **Event System** - Replace Ti.App events
-5. **State Management** - Last, as it touches everything
+1. **Styling-system organization** - Establish semantic tokens and the correct PurgeTSS/Alloy path
+2. **Feedback surfaces** - Migrate one window without changing domain outcomes
+3. **Service Layer** - Extract logic without changing behavior
+4. **Navigation Service** - Centralize with cleanup
+5. **Event System** - Replace Ti.App events
+6. **State Management** - Last, as it touches everything
 
 ## Rollback strategy
 
@@ -293,16 +321,10 @@ For each phase:
 1. **Create a branch** before starting
 2. **Migrate one feature** completely
 3. **Test thoroughly** before moving to next feature
-4. **Keep legacy code** commented until stable
+4. **Delete the replaced implementation** after the vertical slice passes
 
-```javascript
-// Temporary: Keep both during migration
-// Legacy:
-// Ti.App.fireEvent('user:updated', data)
-
-// New:
-Alloy.Events.trigger('user:updated', data)
-```
+Use version control for rollback. Do not keep commented legacy implementations:
+they conceal duplicate listeners, stale callbacks, and incomplete migrations.
 
 ## Common migration pitfalls