Tasarım aracı playbook’u

Sayfa, chrome ve bileşenleri MCP/API ile düzenlemek için token-verimli döngü.

Doğrulama döngüsü

get_* ile mode=summary kullanarak blok id/type/propsKeys görün. propsKeys kayıtlı üst düzey anahtarlardır; grup adları ve shell dahildir.
save_* ops ile yama yapın (blockId + prop path ile set/insert/remove/move). Tam content yerine ops tercih edin. Tasarım şeması menüsündeki iç içe yolları kullanın: typography.fontSize, action.url, shell.visibility.showOnBreakpoints, shell.anchor.anchorId, shell.box.sizeByBreakpoint.
Slim güncelleme yanıtları changedBlockIds, contentLocale ve hasWarnings döner—tam belgeyi değil.
hasWarnings true ise ayrıntı için get_design_warnings çağırın (şema, layout prop'ları ve routePageId; DOM taşması yok — onu screen_capture_page bildirir).
Tek alt ağaç için blockId ile get_*, veya yalnızca gerektiğinde tam get.
Yalnızca get_docs yüzey kataloglarındaki tipleri ekleyin. Mevcut JSON’da bilinmeyen bir tip görmek onu kopyalama tarifi değildir. Düz anahtarlar yine açılır; sonraki kayıt iç içe şekli yazar.

Yeniden tasarım istekleri

Kullanıcı bir şeyi güncellemeyi, iyileştirmeyi veya yeniden tasarlamayı istediğinde bunu yapısal bir iş olarak ele alın: sayfayı okuyun, ardından iki ila dört somut iyileştirme belirleyin ve aynı turda uygulayın. Renk ve boşluklara geçmeden önce bölüm sırasını değiştirin, bölüm ve blok ekleyin veya kaldırın, başlıkları ve metni düzeltin. Her adım için izin istemeyin; makul varsayılanı seçin, değişikliğin tamamını uygulayın ve sonunda ne değiştiğini en fazla üç sonraki adımla birlikte anlatın. En fazla bir engelleyici soru sorun ve seçenekleri iletinin sonunda toplayın.

Block-id ops

Ops şekli: set {blockId, path, value}, insert {parentBlockId, slot?, index, block}, remove {blockId}, move {blockId, parentBlockId, slot?, index}. Bir kayıt op alanını atlayabilir: block + parentBlockId insert, path set olarak okunur. Kök props için blockId "root" (veya root. ile başlayan path). Ya content ya ops—ikisi birden değil. Hatalar: design.block_not_found, design.block_id_ambiguous, design.op_bad_path, design.ops_or_content, design.json_parse. set value ve insert block, metin {, [ veya tırnak ile başlıyorsa JSON olarak ayrıştırılır. {{bind:…}}, {{var:…}} veya {{icon:…}} jetonu metin olarak saklanır. Tırnaklı bir JSON metni jetona açılır. JSON olmayan diğer { veya [ metinleri ops[n].value üzerinde design.json_parse verir.

Yazımlar: birleştirme mi değiştirme mi

content seyrek bir birleştirmedir, asla değiştirme değildir. Verilmeyen anahtarlar kalır, null bir anahtarı siler, blok listeleri id ile eşleşir: listedeki blok yerinde birleşir, listede olmayan kalır, yeni id sona eklenir ve { id, props: null } bir bloğu kaldırır.

İç içe blok listeleri de aynı şekilde birleşir; yani { content: [{ id: 'section', content: [yeniBlok] }] } yeniBloku o bölümün çocuklarına ekler, onları değiştirmez. Bir slotun çocuklarını değiştirmek için o yol için ops set gönderin (dizi ile set diziyi değiştirir) ya da önce her çocuğu { id, props: null } ile kaldırın.

ops set nesne değeriyle saklanan nesneye birleşir; diziler ve skalerler onu değiştirir. Tek bir değer kastediyorsanız tüm props nesnesi göndermek yerine typography.size gibi noktalı yolu kullanın.

Blok id'leri bir belgede tekil olmalıdır. İki blokta kullanılan bir id'ye op göndermek design.block_id_ambiguous ile her yolu bildirir; get_design_warnings de design.warning.duplicate_block_id üretir. Diff veya arama çıktısındaki id-1/id-2 sonekleri yalnızca tekrarlanan id'leri okumak için ayırır; saklanan id değildirler, op'a asla göndermeyin.

Değerler, birimler ve dekorasyon

Metin değil JSON türleri gönderin: typography.size, shell.spacing.* ve tüm …ByBreakpoint haritaları için sayı; …enabled bayrakları için boolean. Bir alanın kod örneği bir değeri gösterir, kopyalanacak metni değil — fontSize: 48 sayı 48 demektir.

Breakpoint haritaları sitenin kendi breakpoint id'leriyle anahtarlanır (get_theme ve section=layout). Id tam eşleşmelidir: desktop, breakpoint-1024 yerine geçmez. columnsByBreakpoint içinde "2" gibi sayısal bir metin yine render edilir, ama sayı yazın.

shell.box (sizeByBreakpoint dahil), boşluk, arka plan, kenarlık, gölge, efektler ve hareket yalnızca shell.customizeEnabled true iken render edilir. Aksi halde değerler saklanır ama yok sayılır ve get_design_warnings design.warning.box_size_ignored_without_customize üretir.

Formlar ve arama (dataRequests)

design/shared-concepts/data-requests okuyun.
root.props.variables tanımlayın.
root.props.dataRequests ekleyin (op list|get|create|update; args içinde {{var:id}}; boş değişken filtresi whenEmpty no-filter veya no-results; select döndürülecek her alanı listeler (boşsa hiçbiri dönmez) ve category.name gibi noktalı olabilir; include { as, from, via, filters, sortBy, sortDirection, limit, include, rerun } ve derinlik 3; yalnızca include içinde kullanılan değişken, rerun request değilse o include’u yeniden çeker; resultWrites images[].size dahil sonuçları yazar, distinct, sortBy, sortDirection, orderFrom ve defaultVariableId alabilir).
VariableInputBlock + Button action runRequest|runMutation + requestName; runRequest isteğe bağlı include takma adı alır.
Liste UI: resultWrites sonrası VariableArrayTemplateBlock — arrayBinding {{var:hits}} (veya {{var:items}}), slot {{var:item.<fieldKey>}}. Beden seçici itemFilter ile {{var:size}} süzer. Include satırlarını requests.<name>.results.<as> ile eşleyin.
mode=detailed istekleri ve include bağımlılıklarını listeler; istemci filtreleri clientDependencies olur. get_design_warnings uydurma anahtarları yakalar.
list|detail|form için save_component_preset tercih edin. Ürün detayı tek get, ileri category yolları ve ters section/image include kullanır. ComponentBlock ile gömün. Liste select { field, format: html|excerpt, maxChars }, { field, format: date, style, pattern } veya { field, format: number, minimumFractionDigits, maximumFractionDigits, currency }. currency, TRY gibi bir ISO 4217 kodudur ve içerik yerel ayarında biçimlenir. order.price gibi noktalı alanlar aynı nesneyi kullanır. {{bind:…}} bu biçimli metni basar. currency yanındaki hazır para simgesi simgeyi yineler. args.page / args.offset listeyi sayfalar (offset kazanır). Doğrudan yükleme ?page= değerini uygular. {{bind:requests.<name>.total}}, .hasMore ve .page bağlayın veya resultWrites source total, hasMore ya da page ile kopyalayın. URL sayfası {{bind:query.page}} üzerinde kalır. Button requestNextPage ve requestPrevPage bu sorguyu yazar. VariableInputBlock labelGap etiket boşluğunu px olarak ayarlar. İlgili listeler overlaps, valueFromRoute, excludeRouteEntry ve fallback kullanır. SlotSlider arrayBinding ilk slaydı satır başına tekrarlar.

Kesme noktaları ve düzen

get_theme ve save_theme section=layout: maxContentWidthPx ve breakpoints. Blok props genelde breakpoint id ile anahtarlanır; breakpoint değişince bu haritaları kontrol edin. Mobil nav için ModalBlock + butonları tercih edin.

Düzeni şekle göre seçin, alışkanlığa göre değil:

Dikey/yatay yığın — FlexListBlock. Yön her breakpoint'te varsayılan row'dur; layout.flexDirectionByBreakpoint değerini açıkça ayarlayın: yığın için { mobile: "column", desktop: "column" }, duyarlı bölünme için { mobile: "column", desktop: "row" }. Birden çok çocuğu olan ve yönü olmayan FlexListBlock tek satır olur ve metni kırpar.
Izgara veya kart satırı — GridListBlock: columnsByBreakpoint, columnGapByBreakpoint, rowGapByBreakpoint ve isteğe bağlı columnSpanByChildId. Bir kart, sütun yönlü FlexListBlock'u saran tek bir GridListBlock hücresidir.
Tekrarlanan veri — VariableArrayTemplateBlock: arrayBinding ve columnsByBreakpoint; tek hücreli grid içine almayın.

Grid anahtarları (columnsByBreakpoint, gap/align haritaları, *SpanByChildId) FlexListBlock prop'u değildir. Saklanır ama yok sayılır; bu bir renderer hatası gibi görünür ve get_design_warnings design.warning.prop_not_supported_by_block üretir.

Uyarı kodları

get_design_warnings ve kayıt yanıtındaki warningCodes kaydedilen belge üzerinde statik kontrollerdir.

filter-variable-unset — bir istek filtresi {{var:q}} okuyor ve q'yu hiçbir şey ayarlayamıyor. Değişkene varsayılan verin, resultWrites ile doldurun veya bir VariableInputBlock/buton variableUpdates bağlayın.
design.warning.box_size_ignored_without_customize — boyut saklanmış ama shell.customizeEnabled true değil.
design.warning.duplicate_block_id — iki blok aynı id'yi kullanıyor; o id ile düzenlemeden önce birini yeniden adlandırın veya kaldırın.
design.warning.result_write_bad_source — results.name gibi bir resultWrites kaynağı hiçbir şey okumaz; tek satır için results.0.name, liste için results[].name kullanın.
unknown-variable, unused-variable, unknown-query — bir jeton var olmayan değişken/isteğe işaret ediyor ya da bir değişken hiç kullanılmıyor.
design.warning.prop_not_supported_by_block — prop başka bir blok tipine aittir; burada saklanır ama yok sayılır. Mesajın adlandırdığı bloğu veya o bloğun desteklediği prop'u kullanın.
design.warning.flex_list_implicit_row — birden çok çocuğu olan FlexListBlock'ta flexDirectionByBreakpoint yok; her breakpoint'te satır olarak render edilir. Yığın için { mobile: "column", desktop: "column" }, satırı korumak için { mobile: "row", desktop: "row" } ayarlayın.

Görsel kontroller

screen_capture_page görüntüyle birlikte servedRevision, viewport ve layout.issues döner. Düzen kontrolü render edilen DOM'u ölçer: viewport dışında kalan blok, kendi taşmasıyla kırpılan içerik veya ebeveyninden taşan doğrudan çocuk. Raporlamadan önce listedeki her sorunu düzeltin.

Temiz liste tasarımın iyi olduğunu kanıtlamaz: boşluk, renk, eksik görsel ve hiyerarşi için görüntüye yine bakın. get_design_warnings kaydedilen belge üzerinde statiktir ve DOM taşmasını göremez; DOM kontrolü ekran görüntüsünün düzen kontrolüdür.

Önbellek zamanlaması

Chrome, sayfa veya bileşen kaydı, kaydı işleyen web sürecindeki public rotayı yeniden doğrular; sonraki istek yeni revizyonu render eder.

Public HTML beklenmesi gereken bir önbellek değildir. Proxy her yanıta X-Hoc-Version (sayfa head revizyonu) ve X-Hoc-Chrome-* (header/footer revizyonları) damgası vurur. screen_capture_page bunları servedRevision ve chrome olarak döner: servedRevision'ı kaydın döndürdüğü revisionId ile karşılaştırın. Farklıysa görüntü kayıt tamamlanmadan alınmıştır; eski önbellek varsaymak yerine yeniden yakalayın.

Çok örnekli bir kurulumda veya CDN arkasında başka bir süreç kendi önbelleği dolana kadar önceki render'ı sunabilir. Duvar saatine değil revizyon başlığına güvenin.

Çapa / taslak

Çapa kimliği ve anahtarı shell.anchor.anchorId ve shell.anchor.anchorKey altında durur. Summary propsKeys, shell nesnesi varsa shell listeler. Hedefli yamalar için çapayı blockId ile eşleştirin. DOM id kuralları bu çapa alanlarını izler.