Div on image layout JSON to SwiftUI: safe, native overlays for hero media, badges, and callouts
AI and frontend devs use “div on image” layouts everywhere: hero cards with labels, product tiles with badges, video thumbnails with overlays. If you’re…

AI and frontend devs use “div on image” layouts everywhere: hero cards with labels, product tiles with badges, video thumbnails with overlays. If you’re building native iOS, the key is to treat these as structured, layered layouts (not just “text on an image”) and map them into safe SwiftUI ZStack / overlay compositions — ideally from a validated, server-driven JSON spec.
This guide explains:
- What a div on image layout JSON really looks like
- How to convert HTML overlays to SwiftUI ZStack safely
- How an Uzori-style pipeline lets an LLM propose hero image overlays, badges, and callouts that are validated server-side before they hit the device
We’ll stay concrete, with JSON shapes, SwiftUI snippets, and a realistic validation flow.
What “div on image” layouts really are (beyond “text on a picture”)
In web UI, a div on image layout is really a layered box model:
- A base container establishes the frame (
position: relative) - An image fills that frame (
object-fit: cover) - Overlay layers (badges, callouts, buttons) use
position: absoluteandz-index - Hit-testing and semantics are tuned with
pointer-eventsand ARIA roles
A minimal overlay div on image HTML might look like:
<div class="card" role="img" aria-label="Limited-time roaming offer">
<img src="hero.jpg" class="media" />
<div class="badge badge--top-right">New</div>
<div class="callout callout--bottom-left">
<h3>Europe roaming</h3>
<p>From $9 / day</p>
</div>
</div>
The important part: visually simple cards hide real complexity:
- Layering rules: which elements are above/below, what can overlap
- Hit-testing: which layers respond to clicks/taps, which are purely decorative
- Accessibility: one combined label vs multiple separate nodes
If you just treat this as “an image and some labels,” you lose structure, semantics, and safety when you port it to native.
Div on image layout JSON: a web-style mental model
LLM and SDUI systems rarely ship raw HTML/CSS. They ship structured JSON describing a tree of components.
A typical div on image layout JSON might look like this:
{
"type": "card",
"role": "imageComposition",
"accessibilityLabel": "Limited-time roaming offer",
"layout": "relative",
"children": [
{
"type": "image",
"src": "https://cdn.example.com/hero/roaming-eu.jpg",
"fit": "cover",
"aspectRatio": 1.6
},
{
"type": "badge",
"anchor": "topRight",
"zIndex": 2,
"text": "New"
},
{
"type": "callout",
"anchor": "bottomLeft",
"zIndex": 3,
"title": "Europe roaming",
"subtitle": "From $9 / day"
}
]
}
This describes a media base layer (type: image) plus overlay layers (badge, callout).
Key ideas:
- The card is a single semantic unit (
role: imageComposition) with one accessibility label. - Each child is a typed element, not arbitrary HTML:
image,badge,callout. - Anchors (
topRight,bottomLeft) describe overlay positioning relative to the base frame. zIndexdefines stacking order.
This is the shape you want your LLM to produce and your SwiftUI app to consume — with validation in between.
From div on image to SwiftUI: ZStack and overlay basics
To convert HTML overlays to SwiftUI ZStack, you map the same conceptual layers into native primitives.
SwiftUI gives you two main tools:
ZStack– stacks children along the Z-axis, like CSS stacking contextsoverlay(_:alignment:)– overlays a view atop another while preserving base layout
A basic hero image with overlay badge and callout in SwiftUI:
struct HeroCardView: View {
let title: String
let subtitle: String
let badgeText: String
let imageName: String
var body: some View {
ZStack(alignment: .bottomLeading) {
Image(imageName)
.resizable()
.scaledToFill() // CSS object-fit: cover
.clipped() // crop to frame
// Scrim layer to improve text contrast
LinearGradient(
colors: [.clear, .black.opacity(0.55)],
startPoint: .center,
endPoint: .bottom
)
.allowsHitTesting(false) // decorative only
VStack(alignment: .leading, spacing: 8) {
HStack {
Spacer()
Text(badgeText)
.padding(.horizontal, 10)
.padding(.vertical, 6)
.background(.black.opacity(0.7))
.clipShape(Capsule())
}
Text(title)
.font(.headline)
.foregroundStyle(.white)
Text(subtitle)
.font(.subheadline)
.foregroundStyle(.white.opacity(0.85))
}
.padding(16)
}
.clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
.accessibilityElement(children: .ignore)
.accessibilityLabel("\(title). \(subtitle)")
}
}
This is the SwiftUI version of “div on image”: base media, scrim, overlays, and one combined accessibility element.
Mapping core CSS concepts to SwiftUI
object-fit: cover→scaledToFill()position: relative→ the baseZStackcontainerposition: absolute; top/right/bottom/left→alignment+ padding in SwiftUIz-index→ order of children inZStackpointer-events: none→.allowsHitTesting(false)role="img"and consolidated label →.accessibilityElement(children: .ignore)+.accessibilityLabel(...)
Once you see it as layers, the mapping becomes mechanical.
Safe native overlays: SwiftUI hit-testing and accessibility
“Div on image” layouts can be unsafe if overlays intercept taps or confuse accessibility.
To build safe native overlays in SwiftUI, pay attention to:
Hit-testing
Use allowsHitTesting(_:) to ensure decorative layers don’t block interaction:
LinearGradient(...)
.allowsHitTesting(false)
Common cases:
- Scrims and shading layers → always
.allowsHitTesting(false) - Non-interactive decorative badges →
.allowsHitTesting(false)so the card handles taps - Transparent layout helpers → also non-interactive
Accessibility
SwiftUI’s accessibility APIs give you fine-grained control:
- Use
.accessibilityElement(children: .combine)when overlays conceptually belong together. - Use
.accessibilityElement(children: .ignore)and setaccessibilityLabelmanually for complex compositions. - Hide decorative images with
.accessibilityHidden(true)orImage(decorative:).
For a hero card, a good pattern is:
ZStack { ... }
.accessibilityElement(children: .ignore)
.accessibilityLabel("Limited-time roaming offer, from nine dollars per day")
This is the SwiftUI equivalent of an ARIA role="img" with a single label.
DivKit vs Uzori: why JSON-first matters
If you’re coming from server-driven UI iOS frameworks like DivKit, the pattern here will feel familiar.
DivKit models UI as JSON trees rendered natively:
- Backend sends a tree of
text,image, andcontainernodes div-containercan lay out children vertically, horizontally, or as overlaysdiv-image-backgrounddefines remote images, alignment, and scaling- Templates and enums keep payloads small and safe
Their playground demo shows a sample render with 11 components in about 115 ms, and DivKit reports 5 years of use in production Yandex apps — a good proof that JSON-first, server-driven layouts are mature.
Uzori takes a similar stance, but tuned specifically for LLM to native iOS UI streaming SDK scenarios:
- The LLM emits Uzori SDK SwiftUI JSON instead of HTML
- The backend validates that JSON against a schema
- The iOS app renders it as fully native SwiftUI
Where DivKit generalizes server-driven UI, Uzori leans heavily into generative UI — letting AI compose the layout within a strict, safe schema.
Uzori-style JSON for hero images, badges, and callouts
To make “LLM generated hero image overlay” safe and predictable, Uzori-style setups constrain what the model can emit.
A plausible schema for a hero card might look like this (simplified for clarity):
{
"type": "heroCard",
"id": "string",
"image": {
"src": "uri",
"contentMode": "fill | fit",
"aspectRatio": 1.6,
"decorative": false
},
"badge": {
"text": "string",
"anchor": "topRight | topLeft",
"style": "primary | subtle"
},
"callout": {
"title": "string",
"subtitle": "string",
"anchor": "bottomLeft | bottomRight",
"layout": "compact | spacious"
},
"action": {
"type": "navigate",
"target": "planDetails",
"parameters": {
"planId": "string"
}
},
"accessibility": {
"label": "string",
"hint": "string"
}
}
Notice what’s not here:
- No arbitrary CSS
- No direct coordinate-based positioning
- No uncontrolled URLs or actions
Instead, the LLM chooses from finite enums (anchor, style, layout) and structured fields.
Secure server-side validation for generated UI
Structured JSON is only safe if you validate it before sending it to the device.
A robust validate UI JSON server-side pipeline typically looks like this:
- LLM generation
- The LLM receives user intent and backend metadata (e.g., OpenAPI)
- It produces a candidate screen spec: a tree of typed components like
heroCard,productList,form
- JSON Schema validation
- The server validates the spec against JSON Schema / OpenAPI 3.1
- This enforces required fields, enums, number ranges, array lengths
- Business rule validation
- Allowed image hosts only
- Text-length limits to prevent layout blow-ups
- Allowed actions and parameters
- Required accessibility labels for non-decorative media
- Semantic checks
- No overlapping tappable regions with conflicting actions
- No nested tappables that violate platform guidelines
- Minimum tap area for primary controls
- Correction or rejection
- The server can patch minor issues (e.g. truncate text, default anchors)
- Or reject and ask the LLM for a revised spec
Only after this pipeline passes does the device receive the payload and render it with SwiftUI.
Industry-wide, this kind of constrained output + schema validation + fallback behavior is becoming the norm for generative UI. Thesys’s 2025 Generative UI report highlights that structured outputs improve usability, and their own tooling claims 67% fewer tokens and 3x faster renders versus free-form text workflows — a reminder that structure helps both safety and performance.
Mapping Uzori JSON to SwiftUI: practical conversion patterns
Let’s walk through how you might generate SwiftUI from JSON for a hero card.
Assume you’ve validated a heroCard node like the one above.
Step 1: Decode JSON to a typed model
struct HeroCardSpec: Decodable {
struct ImageSpec: Decodable {
let src: URL
let contentMode: ContentMode
let aspectRatio: CGFloat
let decorative: Bool
}
struct BadgeSpec: Decodable {
let text: String
let anchor: Anchor
let style: Style
}
struct CalloutSpec: Decodable {
let title: String
let subtitle: String
let anchor: Anchor
let layout: Layout
}
let id: String
let image: ImageSpec
let badge: BadgeSpec?
let callout: CalloutSpec
let accessibility: AccessibilitySpec
}
Step 2: Render with a reusable SwiftUI component
struct GeneratedHeroCard: View {
let spec: HeroCardSpec
var body: some View {
ZStack {
RemoteImage(url: spec.image.src)
.aspectRatio(spec.image.aspectRatio, contentMode: mapContentMode(spec.image.contentMode))
.clipped()
if let badge = spec.badge {
badgeView(badge)
}
calloutView(spec.callout)
}
.clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
.accessibilityElement(children: .ignore)
.accessibilityLabel(spec.accessibility.label)
.accessibilityHint(spec.accessibility.hint)
}
@ViewBuilder
private func badgeView(_ badge: HeroCardSpec.BadgeSpec) -> some View {
Text(badge.text)
.padding(.horizontal, 10)
.padding(.vertical, 6)
.background(badgeBackgroundStyle(badge.style))
.clipShape(Capsule())
.frame(maxWidth: .infinity, alignment: badge.anchor == .topRight ? .topTrailing : .topLeading)
.padding(12)
.allowsHitTesting(false)
}
@ViewBuilder
private func calloutView(_ callout: HeroCardSpec.CalloutSpec) -> some View {
VStack(alignment: .leading, spacing: 4) {
Text(callout.title)
.font(.headline)
.foregroundStyle(.white)
Text(callout.subtitle)
.font(.subheadline)
.foregroundStyle(.white.opacity(0.85))
}
.padding(16)
.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottomLeading)
}
}
This is the core LLM to native iOS UI streaming SDK pattern:
- The LLM never touches Swift or SwiftUI directly.
- It emits typed JSON.
- Your server validates the JSON and enforces rules.
- Your client maps JSON to reusable SwiftUI components.
Any new overlay-heavy layout (div images, div video thumbnails, div text banners) is just another schema + renderer pair.
Example: LLM-generated roaming plan hero flow
Imagine you’re building an AI concierge for roaming protection in an iOS app.
User flow
- User types: “I’m traveling to Germany and Spain next week, what roaming plan should I pick?”
- The assistant calls your backend’s pricing APIs and gets plan options.
- The LLM proposes hero image callouts LLM generated for each plan:
- Hero image of a map or cityscape
- Badge: “Best value”, “New”, or “Limited offer”
- Callout: title, price, and key benefit
JSON spec (simplified)
{
"type": "screen",
"children": [
{
"type": "heroCard",
"id": "plan-eu-weekly",
"image": {
"src": "https://media.example.com/roaming/eu-city.jpg",
"contentMode": "fill",
"aspectRatio": 1.6,
"decorative": false
},
"badge": {
"text": "Best value",
"anchor": "topRight",
"style": "primary"
},
"callout": {
"title": "EU Weekly Pass",
"subtitle": "$9 / day, capped at $40",
"anchor": "bottomLeft",
"layout": "compact"
},
"action": {
"type": "navigate",
"target": "planDetails",
"parameters": { "planId": "eu-weekly" }
},
"accessibility": {
"label": "EU Weekly Pass, nine dollars per day, capped at forty dollars",
"hint": "Double tap to view details"
}
}
]
}
Validation checks
Server-side, you might enforce:
image.srchost is in an allowlistbadge.styleis one ofprimary | subtlecallout.titleis under 80 characterscallout.subtitleis under 120 charactersaccessibility.labelis present for non-decorative imagesaction.targetis one of known routes
With this in place, your safe native overlays SwiftUI rendering becomes predictable and robust.
How Uzori fits this pattern
Uzori is designed exactly for this intersection of generative UI and server-driven UI for iOS.
With a single-screen SwiftUI integration, the Uzori iOS SDK lets you:
- Send user requests and backend API metadata (e.g., OpenAPI)
- Receive SwiftUI-ready JSON describing hero cards, product explorers, and configuration flows
- Stream those screens into your app with native components and navigation
The key design principles are:
- Native first – everything renders as SwiftUI, not web views
- Structure over chaos – no arbitrary remote code, only schema-constrained JSON
- AI as interface – the AI orchestrates screens and flows, not just text
If you want to experiment with div-on-image style layouts driven by AI — but keep them fully native and safe — Uzori gives you an out-of-the-box pipeline you can attach to your app. You can learn more and request access at uzori.ai.
FAQ: div on image layouts and SwiftUI
1. How do I overlay badges on images in SwiftUI?
Use ZStack or overlay with alignment and padding.
Image("product")
.resizable()
.scaledToFill()
.overlay(alignment: .topTrailing) {
Text("New")
.padding(.horizontal, 8)
.padding(.vertical, 4)
.background(.black.opacity(0.7))
.clipShape(Capsule())
.padding(8)
}
This is the canonical how to overlay badges on images SwiftUI snippet.
2. How do I convert complex HTML overlays to SwiftUI ZStack?
Treat the HTML as structure, not markup:
- Parse or regenerate it into div on image layout JSON (typed nodes).
- Map each type (
image,badge,callout) to a SwiftUI view. - Use
ZStackandoverlaywith alignment and padding to position overlays. - Mirror CSS
object-fit: coverwithscaledToFill(). - Use
.allowsHitTesting(false)and accessibility APIs to keep it safe.
You rarely need to run HTML directly; JSON + SwiftUI is more robust.
3. How do I keep LLM-generated overlays safe?
Follow a validate UI JSON server-side pattern:
- Constrain output with JSON Schema / OpenAPI
- Validate and normalize texts, actions, and URLs
- Enforce allowed enums for layout and style
- Reject or correct specs that don’t pass
- Render only validated specs on-device
This keeps the AI in a bounded, typed sandbox.
4. Can I reuse this approach for div video and div text banners?
Yes.
The same pattern applies to div video thumbnails, div text banners, and other overlay-heavy components:
- Represent them as typed JSON nodes (
videoCard,banner) - Define safe enums for anchors, styles, and actions
- Render with SwiftUI layouts (
ZStack,overlay,VStack,HStack)
All the safety and accessibility best practices carry over.
5. How do I stream generative UI into a running iOS app?
You need three pieces:
- A backend that orchestrates LLM calls and validates UI JSON
- A typed SDUI schema for components (hero cards, lists, forms)
- A client SDK that maps JSON to SwiftUI views and handles streaming updates
Uzori’s iOS SDK packages these pieces specifically for SwiftUI, so the “div on image” mental model becomes a first-class, native layout pattern instead of an HTML artifact.