Styles, layout and visual system

Principle

Keep component identity separate from appearance. Prefer a small component vocabulary plus composable styles/modifiers.

{
  "id": "run",
  "type": "Button",
  "props": { "text": "Run" },
  "style": {
    "padding": 16,
    "font": "headline",
    "glass": true,
    "glassInteractive": true
  }
}

Implemented v1 style surface

• padding
• frame (width/height/min/max/alignment)
• font
• fontWeight
• buttonStyle (plain, bordered; default remains the Host's prominent/native action style)
• foregroundStyle
• background
• cornerRadius
• opacity
• blur
• shadow
• offset
• scale
• rotation
• overlay
• clipShape
• disabled
• hidden
• animation
• transition
• glass
• glassInteractive

Container-specific values such as spacing, grid columns and ScrollView axes may live in props where they define component behavior rather than decoration.

Native-first appearance

Style values should map to SwiftUI semantics. Apsule should not invent CSS as an intermediate visual model. This keeps output consistent with iOS and allows native Liquid Glass, typography, controls, animations and accessibility behavior to remain available.

Theme tokens

Prefer semantic/theme references for repeated visual choices. The Host now loads theme.json and resolves $path.to.token strings used by supported style values:

{
  "style": {
    "padding": "$spacing.md",
    "cornerRadius": "$radius.card",
    "typography": "$typography.title"
  }
}

The future Windows Builder should expose both direct values and theme-token selection. Reusable definitions in components/*.json are also expanded by the Host; invocation props are exposed to descendants under the props scope.

Builder implications

The schema must support:

• visual selection by stable node ID;
• drag/drop reparenting;
• property editing without rewriting unrelated nodes;
• component extraction;
• token-based global restyling;
• preview-only device frames and mock state;
• round-trip JSON edits made by AI without losing Builder metadata.