AI Agents dünyasında katı bir Screen / Content kuralı, bir design system ve preview’lar ile tutarlı UI tasarımları, UI mimarisi nasıl geliştiririz? Agent (Claude) ve ona görmeyi sağlayacak o komut: android preview render
Claude Code’a bir UI tasarım örneği vermiyorum. Sadece birkaç cümleyle ekranı tarif ediyorum. Ve ekran hazır hem de tasarım sistemimize uygun!
$ prompt — bana bir bildirimler ekranı oluştur. kullanıcının henüz bildirimi yoksa boş durum göster. mesaj ve ikon olsun.
Claude Code — Derleme temiz. Şimdi önizlemeleri render edip bakıyorum.
Birkaç dakika sonra elimde bir ViewModel, bir ekran, yeni component’ler (eğer yoksa) ve o ekranın her durumu ve component’ler için bir preview oluyor. Agent geliştirmeyi henüz bana teslim etmeden bu preview’leri görüntüye çevirip gördüğü sorunları düzeltmiş oluyor. Biz de Android Studio’ya girmeden bile yorumlayabiliyor oluyoruz.
Aslında parçaların birçoğu yeni değil: stateless composable’lar, preview’lar ve bir design system.
Sorun: “Derleniyor” ile “doğru görünüyor” aynı şey değil
Bir agent derlenen bir Compose kodu ile “iş tamamlandı” diyebilir. Peki gerçekten tamamlandı mı? Tasarım sisteminize ne kadar uydu? Agent, kafasına göre buton oluşturabilir. Ana renklerinizden sapabilir.
Bunu yakalamanın yolu, Android Studio’ya girmek, emülatörü başlatmak ve uygulamayı manuel test etmek. Ama bu hem yavaş hem de bizim AI’dan beklediğimiz hızla uyuşmuyor. Agent ise bunu cihaz olmadan yapamıyor. Agent bir emülatör açıp adb ile ekran görüntüsü alabilir, kontroller sağlayabilir ancak buradaki sorun da yine yavaşlık.
Bu yüzden uygulamayı çalıştırmadan hem benim hem de agent tarafından kontrol edilebilmesini ve her ekranın aynı küçük parça kümesinden kurulmasını istedim.
Beni buraya dört şey getirdi:
- Screen / Content ayrımı
- Preview’ları neye göre kontrol edeceğimiz: design system
- Agent preview’ları nasıl kontrol edecek:
android preview render(Android CLI ile) - Agent’ın uyması gereken kurallar:
CLAUDE.md
Screen / Content ayrımı
Screen, ekranın genel yapısını tanımlar. ViewModel’i bilir, state’i toplar ve event’leri iletir. Content burada barınır.
@Composable
fun NotificationsScreen(
onBack: () -> Unit,
onNotificationClick: (NotificationUiModel) -> Unit,
viewModel: NotificationsViewModel = hiltViewModel()
) {
val uiState by viewModel.uiState.collectAsStateWithLifecycle()
NotificationsContent(
uiState = uiState,
onBack = onBack,
onNotificationClick = { notification ->
viewModel.markAsRead(notification.id)
onNotificationClick(notification)
},
onMarkAllAsRead = viewModel::markAllAsRead
)
}
Content ise stateless bir composable’dır. Sadece düz bir UI state alır. Dolayısıyla kolayca farklı durumlarını preview’da gözlemleyebiliriz:
@Composable
fun NotificationsContent(
uiState: NotificationsUiState,
onBack: () -> Unit,
onNotificationClick: (NotificationUiModel) -> Unit,
onMarkAllAsRead: () -> Unit,
modifier: Modifier = Modifier,
) {
Column(modifier = modifier.fillMaxSize()) {
AppToolbar(
title = stringResource(R.string.notifications_title),
navigationIcon = {
AppIconButton(
onClick = onBack,
contentDescription = stringResource(R.string.content_desc_back),
// ... tam hali verilmemiştir.
Aslında bir yandan da state hoisting uygulamış oluyoruz. Preview’lara kattığı şey: oluşabilecek her durumu preview’da görebilecek olmamız.
@Composable
private fun NotificationsPreview(uiState: NotificationsUiState) {
MyCustomTheme {
NotificationsContent(
uiState = uiState,
onBack = {},
onNotificationClick = {},
onMarkAllAsRead = {}
)
}
}
@Preview(name = "Notifications · loaded", heightDp = 900)
@Composable
private fun NotificationsLoadedPreview() {
NotificationsPreview(NotificationsUiState(notifications = NotificationsSampleData.notifications()))
}
@Preview(name = "Notifications · empty", heightDp = 640)
@Composable
private fun NotificationsEmptyPreview() {
NotificationsPreview(NotificationsUiState())
}
Bu ayrımın ikinci ve daha katı nedeni de var. Preview renderer, hiltViewModel() çağıran bir composable’ın preview’ını render edemiyor. Örneğin NotificationsContent yerine NotificationsScreen’i çağırırsak şöyle bir hata ile karşılaşacağız:
Error rendering NotificationsLoadedPreview: Expected an activity context for creating a HiltViewModelFactory but instead found: com.android.layoutlib.bridge.android.BridgeContext@6e0b5316
java.lang.IllegalStateException: Expected an activity context for creating a HiltViewModelFactory but instead found: com.android.layoutlib.bridge.android.BridgeContext@6e0b5316 at
...
Her state için bir preview
Agent’a vereceğimiz kural “bir preview ekle” değil, “ekranın oluşturabileceği her durum için bir preview ekle” olmalı. Bu da zamanla bizi ve agent’ı farklı oluşabilecek durumları tasarlamaya zorluyor. Bu iyi bir yan etki oldu benim için. Production’a çıkmadan oluşabilecek durumları görmek, öncesinde preview oluştururken tespit etmek demek bu!
- Yükleniyor durumu
- Boş durum
- Hata durumu (response hataları, tekrar dene durumları)
- Başarılı durum (verinin dolduğu durum)
Design system: Preview’ları neye göre kontrol ediyoruz?
Preview ile biz “neye benzediğini” cevaplarız. Peki nasıl doğrulayacağız? Cevap: Design system.
Token’lar, ana bileşenler, uygulama renkleri, tipografi…
- Renkler, tipografi, tema token’ları üzerinden okunmalı.
- Token’larla kurulmuş core bileşenler: Primary/secondary butonlar, kartlar, ikon butonları, bottom sheet’ler, chip’ler…
Design system’i referansa dönüştüren kural: Asla feature kodunda ham değerler kullanma. Bu kural agent’ı design system’i kullanmaya zorluyor.
Bununla birlikte agent geliştirirken de doğrularken de design system’den sonuna kadar faydalanmış oluyor.
Agent’a görmeyi öğretmek: android preview render
Daha önce preview’lara bakan bendim. Agent bunları görmüyordu. Görmeden teslim ediyordu. “Derleme başarılı” diyerek onaylıyordu. Peki çıktı ne kadar doğruydu? Android Studio’yu açıp preview’ı render edip kendim kontrol ediyordum. UI’da bir kayma, eksik varsa bildiriyordum, düzenlemesini istiyordum. Bu yavaş bir döngü oluyordu. Artık Agent, Android CLI içindeki android preview render komutunu çalıştırıp PNG preview çıktısını alıyor, kontrol döngüsüne katıyor. Bir bozukluk varsa düzeltene kadar devam ediyor. Ve sonunda daha doğru sonuçlar ve daha az hata elde etmiş oluyoruz.


Peki android preview nedir? 2 komutumuz var:
android preview list: Projedeki preview composable’ların listesini çıktı olarak verir.
com.example.notifications.NotificationsScreenKt.NotificationsEmptyPreview
com.example.notifications.NotificationsScreenKt.NotificationsLoadedPreview
android preview render: Preview composable fonksiyonunu render eder ve çıktı olarak PNG verir.
- Belirli bir preview’ı render etmek için:
android preview render --fqn=com.example.notifications.NotificationsScreenKt.NotificationsLoadedPreview - Uygulamanızda product flavor’lar varsa varyantı belirtmeniz gerekecektir:
android preview render :app@devDebug
Agent’ı yönlendirmek: CLAUDE.md
Agent’ı yönlendirebilmek, en az hata ile geliştirmeyi yapabilmesi için kurallar dosyamız olan CLAUDE.md dosyasını yapılandırmamız gerekir. Her oturumda bunu okuyarak uygulama mimarisi, design system, preview yapısı hakkında bilgisi olacak ve bu dosyadaki kurallara uyum sağlayacak.
Örnek bir CLAUDE.md dosyası:
## Design System
Dark-only UI built from three core colors (background, primary orange, white text)
plus neutral steps between them. Tokens live in `ui/theme/`, reusable components
in `core/ui/composable/`.
**Golden rules** (apply to every new or edited screen/component):
- Read every design value from `MyCustomTheme.colors / typography / shapes / spacing`.
- Never write raw `Color(0x…)`, `RoundedCornerShape(…)`, `fontSize` / `fontWeight`
literals in feature or component code. If a needed value is missing, add a token first.
- Use `MyCustomTheme.spacing.*` for padding and gaps when the value is on the scale.
Off-scale values stay as plain `dp` and are not added to the scale.
- Prefer an existing component over building a new one. A new reusable piece goes in
`core/ui/composable/<group>/` with a `@Preview`, and is added to the gallery.
**Colors**
| Group | Tokens |
|----------|-----------------------------------------------------|
| Surfaces | background, surfaceLow, surface, card, surfaceHigh |
| Primary | primary, onPrimary, primaryContainer, ... |
| Text | onSurface, onSurfaceVariant, textMuted |
Usage: depth comes from surface steps plus a 1dp outline, never drop shadows.
Orange marks the single next action and the current selection; avoid two competing
orange buttons on one screen. White on primary is only 3.2:1 contrast, so labels on
orange fills are 17sp bold or larger.
**Components**
| Component | Use for |
|-----------------------------------|---------------------------------------------------|
| PrimaryButton, SecondaryButton | Full-width actions (one primary per screen) |
| AppIconButton + style | Round icon buttons; Glass style over photos |
| ListCard, ListDivider, MenuRow | Grouped rows in one card (settings, lists) |
| LoadErrorState | A screen whose *first* load failed; later refresh |
| | failures use the info bar instead |
Ve preview’ları bir doğrulama adımına çeviren kısım:
**Previewing**: every screen is a thin `XScreen` (ViewModel, state collection) plus a
stateless `XContent` (UI state + lambdas) with one preview per state (loading, empty,
first-load error, loaded).
**Check UI work yourself, without a device**: after adding or changing a screen,
component or preview, render the affected previews and look at every PNG before
handing the work over:
`android preview render :app --component-tree -o <scratch dir> --fqn=<Preview FQN>`
The renderer is layoutlib: no DI, network or device APIs, so previews
must target `XContent`, never a composable that calls `hiltViewModel()`, and a preview
may be at most 3000dp tall.
Bu dosyayı yazarken öğrendiğim birkaç şey:
- Sadece kuralı yazmak yetmez, nedenini de yazmalıyız. Agent kuralı ve nedenini yorumlayarak benzer durumlarda kural olmasa da karar vererek doğru sonuçlar çıkaracaktır.
- Üzerinde tartıştığımız uç durumları yazmalıyız. “İlk yükleme başarısız → tam ekran hata durumu; yenileme başarısız → bilgi bar’ı” dosyada tek bir satır. O satır yokken her yeni ekranda bunu tekrar söylemek zorunda kalıyordum.
- Dosyayı güncel kalacak hale getirmeliyiz. Yeni component + preview eklendiğinde bununla birlikte
CLAUDE.mddosyasının da güncellenerek agent’ın da sonraki oturumlarda yeni eklenenleri unutmamasını sağlarız. - Okunabilecek kadar kısa tutmalıyız. Her oturumda agent bu dosyayı okuyarak context’ine yüklüyor. Her satırın da bir maliyeti var.
Uçtan uca döngü
Hepsini bir araya koyunca bir ekran oluşturmak şöyle görünüyor:
- Agent’a ekranı, özelliklerini tarif ediyorum. Kullanıcı ne yapabiliyor, hangi durumları var.
- Agent (Claude),
CLAUDE.md’yi okuyarak component’leri, token’ları kontrol ederek ekranı çizmeye başlar. - Ekranın durumlarına göre preview composable fonksiyonlar oluşturulur.
- Agent (Claude),
android preview renderkomutunu çalıştırır ve render edilen preview’ları design system bilgisiyle birlikte kontrolden geçirir. - Agent işi teslim ettikten sonra ancak o zaman kontrole geçiyorum. Preview + cihazdan uygulamayı çalıştırarak testleri yapıyorum.
Sınırlar
Preview’lar bir cihaz değildir. Bu yüzden yakalayamadıkları durumlar bulunuyor.
- Servisten veya veritabanından gelen gerçek veriler
- Navigasyon, back stack, konfigürasyon değişiklikleri, süreç ölümleri
- Donanımsal özellikler (kamera, sensörler vb.)
- Widget’lar
Bu durumları uygulamayı çalıştırıp emülatör veya gerçek cihazdan test etmemiz gerekir.
Çıkarımlar
- Her ekranı ince bir Screen ve stateless bir Content’e böl. Her durumu preview’da görülebilir kılan şey bu ve bir preview renderer’ının çizebildiği tek parça da o.
- Ekran başına bir preview değil, durum başına bir preview iste. Bu, durumların tasarlanmasını zorunlu kılar.
- Agent’a kapalı bir kelime dağarcığı ver: token’lar ve bileşenler, ham değer yok. Tutarlılık kibarca rica etmekten değil, kısıtlardan gelir.
- Agent’ın kendi preview’larını
android preview renderile render etmesine izin ver ve ona işi teslim etmeden önce hem görüntüye hem de component tree’ye bakmasını söyle. - Kuralları nedenleriyle birlikte yaz, her gözden geçirmede tekrarlayacağın kararları kaydet ve dosyayı olabildiğince kısa tut.
Kodu yazan ve pikselleri kontrol eden agent. Neye benzemesi gerektiği konusunda ise preview’larda anlaşıyoruz.