AI Ajanlarına Ekranı Anlatmak: Jetpack Compose Semantics Tasarımı Pratik Rehberi

AI Ajanlarına Ekranı Anlatmak: Jetpack Compose Semantics Tasarımı Pratik Rehberi

Giriş

Jetpack Compose'daki AI ajanlarının ve test otomasyon araçlarının "bu buton ne yapar" sorusunu doğru anlaması için Semantics'in uygun tasarımı kritik öneme sahiptir.

Compose dahili olarak bir "Semantics Tree" barındırır; bu ağaç erişilebilirlik, UI testleri ve otomatik işlem AI'larının (Appium/UIAutomator/MCP vb.) referans aldığı anlamsal yapı olarak işlev görür. Web'deki ARIA ve DOM'a karşılık gelir.

Semantics'in Temel Özellikleri

contentDescription

Yalnızca ikon içeren butonlara anlam vermek için en temel özellik.

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "Sil"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

AI ve erişilebilirlik tarafı bunu "Sil butonu · tıklanabilir · Button rolü" olarak algılar.

role

Özel UI bileşenine UI türünü açıkça belirtir. Sıradan Box(clickable) "tıklanabilir bir şey" olurken role eklemek Button, Switch, Checkbox, Tab gibi anlamları netleştirir.

Modifier.semantics {
    role = Role.Button
}

stateDescription

UI'ın mevcut durumunu AI'a iletir.

Modifier.semantics {
    stateDescription =
        if (subscribed) "Abone olundu"
        else "Abone olunmadı"
}

testTag

MCP, Appium ve otomatik UI ajanları için en önemli tanımlayıcı. Koordinat, OCR veya metin değişikliğine bağlı olmayan kararlı tanımlama sağlar.

Modifier.testTag("login_button")

UIAutomator Entegrasyonu İçin Ayar

Compose doğrudan View hiyerarşisi oluşturmadığından UIAutomator testTag'ı göremeyebilir. Kök bileşene şunun eklenmesiyle çözülür:

Scaffold(
    modifier = Modifier.semantics {
        testTagsAsResourceId = true
    }
)

testTag resource-id olarak tanınır ve UIAutomator'dan doğrudan alınabilir hale gelir.

AI'ın En Kolay Anlayacağı Uygulama Kalıbı

En iyi pratik, birden fazla özelliği birleştirmektir.

Button(
    onClick = login,
    modifier = Modifier
        .testTag("login_button")
        .semantics {
            contentDescription = "Giriş Yap"
            role = Role.Button
        }
) {
    Text("Giriş Yap")
}

Karmaşık UI'ı Tek Bir Anlama Toplamak

İkon, metin ve Badge gibi karmaşık yapıyı AI'a tek buton olarak göstermek için clearAndSetSemantics kullanılır.

Modifier.clearAndSetSemantics {
    contentDescription = "Ürünü sepete ekle"
    role = Role.Button
}

İçerideki iç içe yapı ve ikon grupları görmezden gelinerek yalnızca anlam AI'a aktarılabilir.

Semantics Tasarımıyla Neler Yapılabilir

Otomasyonun Kararlılaştırılması

testTag sayesinde koordinat veya OCR olmadan kararlı işlem mümkün hale gelir. UI yeniden tasarlandıktan sonra bile testTag aynı kaldığı sürece otomasyon bozulmaz. Çok dilli destek de güçlenir.

Token Miktarının Azaltılması

Yalnızca ekran görüntüsüne bağlı kalındığında görüntü analizi çok sayıda token gerektirir; ancak Semantics Tree ile hafif yapılandırılmış veri olarak işlenebilir.

[
  {"type": "Button", "label": "Giriş Yap"},
  {"type": "TextField", "label": "E-posta"},
  {"type": "TextField", "label": "Şifre"}
]

Uzun süreli otomatik işlemlerde ve büyük çaplı ekran analizlerinde özellikle etkili olup context overflow'u önlemeye de katkı sağlar.

AI'ın Durum Kavraması

stateDescription sayesinde AI ekranın mevcut durumunu tahmin edip "şu anda duraklatılmış, o zaman oynat butonuna basayım" gibi kararlar verebilir. Ekranı bir durum makinesi olarak anlamasını sağlar.

MCP Entegrasyonunda Yapılandırılmış Analiz

Semantics Tree'yi MCP Server aracılığıyla alıp LLM Agent'a aktarmak, tüm ekranın anlam kavramasını, sonraki işlem adaylarının tahminini ve durum geçişi analizini mümkün kılar.

Compose UI → Semantics Tree → MCP Server → LLM Agent

Semantics Özelliklerinin Kullanım Özeti

Özet

Compose "görünüm" ile "anlam"ı birbirinden ayırabilir. Semantics tasarımının özü, insan için UI'ı ve AI için anlam yapısını bağımsız olarak tasarlayabilmekte yatar.

AI ajanları, MCP, UIAutomator ve otomatik E2E testlerini kullanacaksanız, her bileşen için şu standardizasyon yüksek yatırım getirisi sağlar:

Modifier
    .testTag(...)
    .semantics {
        contentDescription = ...
        role = ...
    }

Renk, konum ve boyut yerine "bu ne butonu · basılınca ne olur · şu an ne durumda" bilgisini Semantics aracılığıyla iletmek — AI'a dayanıklı UI tasarımının özü budur.