ttb-skill-swiftui

name	ttb-skill-swiftui
description	SwiftUI full-stack development for TTBaseUIKit apps. Use for SwiftUI/SUIBaseView/TTBaseSUI screens, reusable SwiftUI views, list/grid screens, SwiftUI ViewModels, and native SwiftUI fallback when TTBaseSUI has no equivalent. Supports English and Vietnamese user prompts. iOS 14+.
version	2.4.0
date_updated	2026-05-30
risk	safe
source	internal
loadLevel	domain
tags	["swiftui","ttbasesui","suibaseview","navigation","viewmodel","native-fallback","routing","multilingual"]

ttb-skill-swiftui

SwiftUI development skill set for TTBaseUIKit apps.

Primary rule: use TTBaseSUI whenever an equivalent component exists. Use native SwiftUI only as a documented fallback.

Mandatory Preflight Execution Gate

Before this skill generates code, refactors, migrates, modifies files, creates architecture, updates UI/navigation, changes dependencies, updates workflows, or changes business logic, run the shared gate:

• ttb-skill-shared/fragments/ttb-preflight-execution-gate.frag.md
• ttb-skill-shared/fragments/ttb-cross-functional-analysis-gate.frag.md for feature updates, new features, and bug fixes
• ttb-skill-shared/templates/ttb-clarification-survey.md when confidence is below threshold

Required phase order: Requirement Analysis -> Context Validation -> Ambiguity Detection -> Missing Information Detection -> Survey / Clarification -> Confidence Evaluation -> Execution Approval.

Execution thresholds:

Confidence	Action
90-100	Execute directly and state key assumptions
70-89	Execute only with documented low-risk assumptions
<70	Do not execute; ask a concise survey first

Cap confidence at 69 when target module, architecture direction, UIKit/SwiftUI choice, navigation behavior, API/business logic, localization format, state management, dependency info, or ownership is unclear. Parse English, Vietnamese, mixed-language, diacritic-free Vietnamese, and light typos before scoring.

For feature updates, new feature development, and bug fixes, analyze as Product Owner, Business Analyst, UX/UI Designer, Solution Architect, Senior Developer, and QA. Compare options across business value, architecture, UI/UX, performance, scalability, maintainability, security, testing, and operations; ask at least 5 value-expansion questions after analysis. If requirements are ambiguous/incomplete, ask at least 6 clarification questions before design/development.

Trigger Scope

Use this skill when the user asks for any of these artifacts:

Artifact	Route	Examples
SwiftUI screen	/ttb-sui-screen	screen, page, flow, detail, settings, profile
SwiftUI list/grid screen	/ttb-sui-list	list, grid, collection, carousel, searchable list
Reusable TTBaseSUI view	/ttb-sui-view	card, row, header, badge, empty state, custom cell
SwiftUI ViewModel	/ttb-sui-viewmodel	ObservableObject, @Published state, loading/error state
Native SwiftUI screen fallback	/ttb-native-screen	custom chart, advanced gesture, custom animation, layout not covered by TTBaseSUI
Native SwiftUI view fallback	/ttb-native-view	bespoke visual component not covered by TTBaseSUI

Do not use this skill for UIKit-only requests. Route UIKit/ViewController/cell/API/coordinator tasks to the UIKit skill.

Multilingual Prompt Support

Treat English and Vietnamese prompts as equivalent intent signals. Keep generated code, comments, documentation, and final implementation notes in English unless the user explicitly asks for Vietnamese output.

Common aliases:

• English: SwiftUI screen, build SwiftUI, TTBaseSUI view, SUIBaseView, SwiftUI list, grid screen, SwiftUI ViewModel, native SwiftUI, custom SwiftUI component.
• Vietnamese: tạo màn hình SwiftUI, tao man hinh SwiftUI, danh sách SwiftUI, danh sach SwiftUI, tạo view SwiftUI, tao view SwiftUI, điều hướng SwiftUI, dieu huong SwiftUI, tạo ViewModel SwiftUI, tao ViewModel SwiftUI.

Routing Contract

input:
  required: [artifact_type, feature_name, visual_or_text_requirements]
  optional:
    - navigation_flow
    - data_source_or_api_contract
    - empty_loading_error_states
    - localization_keys
    - image_reference_or_mockup
    - ttbase_sui_component_availability
output:
  artifacts:
    - suibaseview_screen_or_reusable_view
    - ttbase_sui_components
    - native_swiftui_fallback_when_needed
    - swiftui_viewmodel_when_needed
    - verification_report
  completion_gate: "SUIBaseView + TTBaseNavigationLink when navigating + iOS 14 compatibility + build verification"
confidence:
  auto_route: ">= 0.78 for SwiftUI, TTBaseSUI, SUIBaseView, SwiftUI list/view/screen/viewmodel intents"
  clarify: "0.55-0.77 when the user says screen/view but does not specify UIKit or SwiftUI"
fallback:
  default: "Prefer TTBaseSUI. Use native SwiftUI only when TTBaseSUI has no equivalent and document the missing component."

Workflow

1. Classify the requested artifact and choose exactly one route from the trigger table.
2. Extract requirements from text, screenshots, mockups, or existing code. Preserve visual hierarchy, spacing, states, copy intent, and navigation behavior.
3. Inspect the local codebase for existing patterns, token names, localization style, target folders, and project registration requirements.
4. Prefer TTBaseSUI components. If falling back to native SwiftUI, name the missing TTBaseSUI equivalent in the implementation notes.
5. Implement with iOS 14-compatible SwiftUI and TTBaseUIKit tokens.
6. Add or update localization keys when the project uses localization.
7. Register new files in the Xcode project when needed.
8. Run build verification and fix issues until BUILD SUCCEEDED, with a maximum of three fix attempts before reporting blockers.

Image and Description Fidelity

When the user provides an image, screenshot, or detailed visual description:

• Identify all visible regions before coding: navigation bar, primary content, actions, lists/cards, empty/loading/error states, overlays, and bottom controls.
• Match layout order, alignment, approximate spacing, typography hierarchy, color roles, icon intent, and component states using TTBaseUIKit tokens.
• Do not invent unrelated sections or marketing copy.
• If information is missing, infer conservative defaults from nearby project patterns and clearly state the assumption.
• Validate that generated screens still satisfy accessibility, dynamic text resilience, and iOS 14 API constraints.

Core SwiftUI Rules

1. iOS 14+ only: no NavigationStack, .task, #Preview, .foregroundStyle, .scrollIndicators, @Observable, or iOS 15+ APIs without @available.
2. Every full SwiftUI screen uses SUIBaseView.
3. Navigation between SwiftUI screens uses TTBaseNavigationLink.
4. Use TTBaseSUI* components before native SwiftUI primitives.
5. Use TTView, TTSize, and TTFont tokens instead of hardcoded colors, spacing, and font sizes.
6. User-visible strings go through the project localization helper, usually XText("key") or the existing local convention.
7. Owned ViewModels use @StateObject; injected ViewModels use @ObservedObject.
8. ViewModels are @MainActor ObservableObject with @Published state and no UIKit/SwiftUI imports.
9. Use [weak self] in escaping closures.
10. Extract subviews when body grows beyond roughly 40 lines.
11. Use PreviewProvider, not #Preview.

Required Screen Pattern

import SwiftUI
import TTBaseUIKit

struct ProductListScreen: View {

    @StateObject private var vm = ProductListViewModel()

    var body: some View {
        SUIBaseView(
            backType: .SWIFTUI,
            title: XText("App.ProductList.Nav.Title"),
            type: .DEFAULT,
            isHiddenTabbar: true,
            backAction: {}
        ) {
            TTBaseSUIVStack(alignment: .center, spacing: TTSize.P_XS, bg: TTView.viewBgColor.toColor()) {
                headerSection
                contentSection
            }
        }
        .onAppear { vm.fetchData() }
    }
}

Required Navigation Pattern

TTBaseNavigationLink(destination: {
    ProductDetailScreen(product: product)
}, label: {
    ProductCardView(product: product)
        .pAll(TTSize.P_CONS_DEF)
        .bg(byDef: TTView.viewBgCellColor.toColor())
        .corner(byDef: TTSize.CORNER_PANEL)
        .baseShadow()
}, isAnimation: true)

Place TTBaseNavigationLink inside the relevant scroll, stack, list, grid, or card row. Use closure-based destination and label parameters, pass isAnimation: true explicitly for normal navigation, and use isAnimation: false only when required by performance or UX.

TTBaseSUI Component Preference

Use these families before native SwiftUI:

• Text: TTBaseSUIText
• Buttons: TTBaseSUIButton
• Stacks: TTBaseSUIVStack, TTBaseSUIHStack, TTBaseSUIZStack
• Scroll/list/grid: TTBaseSUIScroll, TTBaseSUILazyVStack, TTBaseSUILazyHStack, TTBaseSUILazyVGrid, TTBaseEqualHeightGridView, TTBaseSUIList
• Images: TTBaseSUIImage, TTBaseSUICircleImage, TTBaseSUIAsyncImage when project deployment supports it
• Forms: TTBaseSUITextField, TTBaseSUIToggle, TTBaseSUISlider
• Containers: TTBaseSUIView, TTBaseSUIGroup, dividers, spacers, tab views

Preferred card modifier chain:

.pAll(TTSize.P_CONS_DEF)
.bg(byDef: TTView.viewBgCellColor.toColor())
.corner(byDef: TTSize.CORNER_PANEL)
.baseShadow()

Command Prompt Files

Load only the route-specific prompt file that matches the task:

File	Use when
ttb-skill-sui-screen.prompt.md	Build a TTBaseSUI screen with SUIBaseView and navigation
ttb-skill-sui-view.prompt.md	Build a reusable TTBaseSUI component
ttb-skill-sui-list.prompt.md	Build a TTBaseSUI list/grid/carousel screen
ttb-skill-sui-viewmodel.prompt.md	Build a SwiftUI ViewModel
ttb-skill-native-screen.prompt.md	Build a native SwiftUI screen fallback
ttb-skill-native-view.prompt.md	Build a native SwiftUI reusable view fallback

Verification

After implementation:

1. Ensure every new Swift file is part of the Xcode target.
2. Run the project verification command used by the repository, preferably xcodebuild or the shared ttb-verify.sh script when present.
3. Check for iOS 14 API compatibility and TTBaseUIKit token compliance.
4. Complete only when the build succeeds, or report exact blocking errors after three failed repair attempts.

Anti-Patterns

• Building full SwiftUI screens without SUIBaseView.
• Using native SwiftUI components when a TTBaseSUI equivalent exists.
• Navigating between screens without TTBaseNavigationLink.
• Hardcoding colors, sizes, or user-visible strings.
• Adding iOS 15+ APIs without availability guards.
• Creating unrelated UI not present in the input image or description.
• Leaving generated files unregistered in the Xcode project.

---

Version: 2.3.0 | Date: 2026-05-22