Brand Concierge Style Guide (iOS)

This document provides a reference for styling properties supported by the AEPBrandConcierge framework. Themes are configured using JSON files that follow a web-compatible CSS variable format.

Overview

The theme configuration is loaded from a JSON file using ConciergeThemeLoader.load(from:in:). The framework supports CSS-like variable names (prefixed with --) that are mapped to native Swift properties.

Loading a Theme

// Load from app bundle
let theme = ConciergeThemeLoader.load(from: "theme-default", in: .main)

// Use default theme
let defaultTheme = ConciergeThemeLoader.default()

Applying a Theme

Apply the theme using the .conciergeTheme() view modifier on your wrapped content:

import SwiftUI
import AEPBrandConcierge

struct ContentView: View {
    @State private var theme: ConciergeTheme = ConciergeThemeLoader.default()
    
    var body: some View {
        Concierge.wrap(
            // Your app content here
            Text("Hello, World!"),
            surfaces: ["my-surface"]
        )
        .conciergeTheme(theme)  // Apply theme to the wrapper
        .onAppear {
            // Load custom theme from JSON file
            if let loadedTheme = ConciergeThemeLoader.load(from: "my-theme", in: .main) {
                theme = loadedTheme
            }
        }
    }
}

Important: The .conciergeTheme() modifier must be applied to the result of Concierge.wrap() so the theme is available to both the wrapper and the chat overlay.

JSON Structure

The theme JSON file contains these top-level keys:

Value Formats

Understanding the value formats used throughout this document.

Colors

Colors are specified as hex strings:

"--color-primary": "#EB1000"
"--message-user-background": "#EBEEFF"
"--input-box-shadow": "0 2px 8px 0 #00000014"

Supported formats:

• #RRGGBB - 6 digit hex
• #RRGGBBAA - 8 digit hex with alpha

Dimensions

Dimensions use CSS pixel units:

{
  "--input-height-mobile": "52px",
  "--input-border-radius-mobile": "12px",
  "--message-max-width": "100%"
}

On iOS, prefer the *-mobile token names; --input-height and --input-border-radius without the suffix are not supported (see Unsupported CSS Variables).

Padding

Padding follows CSS shorthand syntax:

"--message-padding": "8px 16px"

Formats:

• 8px - All sides
• 8px 16px - Vertical, horizontal
• 8px 16px 4px - Top, horizontal, bottom
• 8px 16px 4px 2px - Top, right, bottom, left

Shadows

Shadows use CSS box-shadow syntax:

"--input-box-shadow": "0 2px 8px 0 #00000014"
"--multimodal-card-box-shadow": "none"

Format: offsetX offsetY blurRadius spreadRadius color

Font Weights

Font weights use CSS numeric or named values:

Text Alignment

Metadata

Theme identification information.

Example

{
  "metadata": {
    "brandName": "Concierge Demo",
    "version": "1.0.0",
    "language": "en-US",
    "namespace": "brand-concierge"
  }
}

Behavior

Feature toggles and interaction configuration.

Multimodal Carousel

Input

Chat

Product Card

Welcome Card

Prompt Suggestions

Feedback

Note: The notes field is only available in "modal" display mode, gated by components.feedback.positiveNotesEnabled / negativeNotesEnabled.

Citations

Privacy Notice

Example

{
  "behavior": {
    "multimodalCarousel": {
      "cardClickAction": "openLink",
      "carouselStyle": "paged"
    },
    "input": {
      "enableVoiceInput": true,
      "disableMultiline": false,
      "showAiChatIcon": null,
      "sendButtonStyle": "default",
      "silenceThreshold": 0.02,
      "silenceDuration": 2
    },
    "chat": {
      "messageAlignment": "left",
      "messageWidth": "100%",
      "userMessageBubbleStyle": "default"
    },
    "productCard": {
      "cardStyle": "productDetail",
      "cardsAlignment": "center"
    },
    "welcomeCard": {
      "closeButtonAlignment": "end",
      "promptFullWidth": true,
      "promptMaxLines": 3,
      "contentAlignment": "top"
    },
    "promptSuggestions": {
      "itemMaxLines": 1,
      "showHeader": false,
      "alignToMessage": false
    },
    "feedback": {
      "displayMode": "modal",
      "thumbsPlacement": "inline",
      "showCloseButton": null,
      "showCancelButton": null
    },
    "citations": {
      "showLinkIcon": false
    },
    "privacyNotice": {
      "title": "Privacy Notice",
      "text": "Privacy notice text."
    }
  }
}

Disclaimer

Legal disclaimer text with embedded links.

Example

{
  "disclaimer": {
    "text": "AI responses may be inaccurate. Check answers and sources. {Terms}",
    "links": [
      {
        "text": "Terms",
        "url": "https://www.adobe.com/legal/licenses-terms/adobe-gen-ai-user-guidelines.html"
      }
    ]
  }
}

Text (Copy)

Localized UI strings using dot-notation keys.

✅ Content Recommendations

While there are no strict requirements for character limits in many of these text fields, it is strongly recommended that the values be tested on target device(s) prior to deployment, ensuring the UI renders as desired.

Header

Tip: To hide the header subtitle, set text["header.subtitle"] to "". The subtitle is automatically hidden when its text is blank.

Welcome Screen

Input

Cards & Carousel

System Messages

Feedback Dialog

Sources & Feedback

Prompt Suggestions

Example

{
  "text": {
    "welcome.heading": "Welcome to Brand Concierge!",
    "welcome.subheading": "I'm your personal guide to help you explore.",
    "input.placeholder": "How can I help?",
    "error.network": "I'm sorry, I'm having trouble connecting."
  }
}

Arrays

List-based configuration for examples and feedback options.

Welcome Examples

You shouldn't have more than four items in your welcome examples.

Always test your values on device to ensure the UI looks as desired.

Feedback Options

You shouldn't have more than five options available for feedback.

Always test your values on device to ensure the UI looks as desired.

Example

{
  "arrays": {
    "welcome.examples": [
      {
        "text": "I'd like to explore templates to see what I can create.",
        "image": "https://example.com/template.png",
        "backgroundColor": "#F5F5F5"
      }
    ],
    "feedback.positive.options": [
      "Helpful and relevant recommendations",
      "Clear and easy to understand",
      "Other"
    ],
    "feedback.negative.options": [
      "Didn't understand my request",
      "Unhelpful or irrelevant information",
      "Other"
    ]
  }
}

Assets

Icon and image asset configuration.

Bundling local icons

Asset catalog (recommended): Add the image to an .xcassets file in the host app and use the image set name as the value. This supports @1x/@2x/@3x scale variants and dark mode variants automatically.

Loose bundle file: Add the image file directly to the app target so it is copied to the bundle root, then use the filename without its extension as the value.

Remote URLs must resolve to a supported raster format (PNG, JPEG, WebP, HEIC/HEIF, GIF, TIFF, BMP). SVG is not supported for remote or local icons.

Example

{
  "assets": {
    "icons": {
      "company": "company-logo"
    }
  }
}

Theme Tokens

Visual styling using CSS-like variable names. All properties in the theme object use the --property-name format.

Typography

Colors - Primary

Colors - Surface

Colors - Messages

Colors - Buttons

Colors - Input

Colors - Input Icons

Colors - Welcome Prompts

Colors - Prompt Suggestions

Colors - Citations

Colors - Feedback

Colors - Product Card

Colors - CTA Button

Colors - Disclaimer

Colors - Thinking Animation

Layout - Input

Layout - Messages

Layout - Chat

Layout - Cards & Carousel

Layout - Buttons

Layout - Feedback

Layout - Citations

Layout - Disclaimer

Layout - Product Card

Layout - CTA Button

Layout - Welcome Screen Order

Layout - Header

Layout - Welcome Screen

Layout - Thinking Animation

Complete Example

{
  "metadata": {
    "brandName": "Concierge Demo",
    "version": "1.0.0",
    "language": "en-US",
    "namespace": "brand-concierge"
  },
  "behavior": {
    "multimodalCarousel": {
      "cardClickAction": "openLink",
      "carouselStyle": "paged"
    },
    "input": {
      "enableVoiceInput": true,
      "disableMultiline": false,
      "showAiChatIcon": null,
      "sendButtonStyle": "default",
      "silenceThreshold": 0.02,
      "silenceDuration": 2
    },
    "chat": {
      "messageAlignment": "left",
      "messageWidth": "100%",
      "userMessageBubbleStyle": "default"
    },
    "productCard": {
      "cardStyle": "productDetail",
      "cardsAlignment": "center"
    },
    "welcomeCard": {
      "closeButtonAlignment": "end",
      "promptFullWidth": true,
      "promptMaxLines": 3,
      "contentAlignment": "top"
    },
    "promptSuggestions": {
      "itemMaxLines": 1,
      "showHeader": false,
      "alignToMessage": false
    },
    "feedback": {
      "displayMode": "modal",
      "thumbsPlacement": "inline",
      "showCloseButton": null,
      "showCancelButton": null
    },
    "citations": {
      "showLinkIcon": false
    },
    "privacyNotice": {
      "title": "Privacy Notice",
      "text": "Privacy notice text."
    }
  },
  "disclaimer": {
    "text": "AI responses may be inaccurate. Check answers and sources. {Terms}",
    "links": [
      {
        "text": "Terms",
        "url": "https://www.adobe.com/legal/licenses-terms/adobe-gen-ai-user-guidelines.html"
      }
    ]
  },
  "text": {
    "welcome.heading": "Welcome to Brand Concierge!",
    "welcome.subheading": "I'm your personal guide to help you explore.",
    "input.placeholder": "How can I help?",
    "input.messageInput.aria": "Message input",
    "input.send.aria": "Send message",
    "feedback.dialog.title.positive": "Your feedback is appreciated",
    "feedback.dialog.submit": "Submit",
    "feedback.dialog.cancel": "Cancel",
    "header.title": "",
    "header.subtitle": "",
    "sourcesLabel": "Sources",
    "feedbackHelpfulLabel": "Was this helpful?",
    "suggestions.header": "Suggestions"
  },
  "arrays": {
    "welcome.examples": [
      {
        "text": "I'd like to explore templates to see what I can create.",
        "image": "https://example.com/template.png",
        "backgroundColor": "#F5F5F5"
      }
    ],
    "feedback.positive.options": [
      "Helpful and relevant recommendations",
      "Clear and easy to understand",
      "Other"
    ],
    "feedback.negative.options": [
      "Didn't understand my request",
      "Unhelpful or irrelevant information",
      "Other"
    ]
  },
  "assets": {
    "icons": {
      "company": ""
    }
  },
  "theme": {
    "--welcome-input-order": "3",
    "--welcome-cards-order": "2",
    "--font-family": "",
    "--color-primary": "#EB1000",
    "--color-text": "#131313",
    "--line-height-body": "1.75",
    "--main-container-background": "#FFFFFF",
    "--main-container-bottom-background": "#FFFFFF",
    "--message-blocker-background": "#FFFFFF",
    "--input-height-mobile": "52px",
    "--input-border-radius-mobile": "12px",
    "--input-background": "#FFFFFF",
    "--input-outline-color": null,
    "--input-outline-width": "2px",
    "--input-focus-outline-width": "2px",
    "--input-focus-outline-color": "#4B75FF",
    "--input-font-size": "16px",
    "--input-text-color": "#292929",
    "--input-button-height": "32px",
    "--input-button-width": "32px",
    "--input-button-border-radius": "8px",
    "--input-box-shadow": "0 2px 8px 0 #00000014",
    "--submit-button-fill-color": "#FFFFFF",
    "--submit-button-fill-color-disabled": "#C6C6C6",
    "--color-button-submit": "#292929",
    "--button-disabled-background": "#FFFFFF",
    "--button-primary-background": "#3B63FB",
    "--button-primary-text": "#FFFFFF",
    "--button-secondary-border": "#2C2C2C",
    "--button-secondary-text": "#2C2C2C",
    "--button-height-s": "30px",
    "--disclaimer-color": "#4B4B4B",
    "--disclaimer-font-size": "12px",
    "--disclaimer-font-weight": "400",
    "--message-user-background": "#EBEEFF",
    "--message-user-text": "#292929",
    "--message-concierge-background": "#F5F5F5",
    "--message-concierge-text": "#292929",
    "--message-concierge-link-color": "#274DEA",
    "--message-border-radius": "10px",
    "--message-padding": "8px 16px",
    "--message-max-width": "100%",
    "--chat-interface-max-width": "768px",
    "--chat-history-padding": "16px",
    "--chat-history-padding-top-expanded": "0",
    "--chat-history-bottom-padding": "0",
    "--message-blocker-height": "105px",
    "--border-radius-card": "16px",
    "--multimodal-card-box-shadow": "none",
    "--feedback-container-gap": "4px",
    "--feedback-icon-btn-background": "#FFFFFF",
    "--feedback-icon-btn-size-desktop": "32px",
    "--feedback-sheet-background-color": "#FFFFFF",
    "--feedback-title-text-color": "#131313",
    "--feedback-question-text-color": "#424242",
    "--feedback-options-text-color": "#131313",
    "--feedback-checkbox-border-color": "#131313",
    "--feedback-drag-handle-color": "#CCCCCC",
    "--feedback-submit-button-fill-color": "#006554",
    "--feedback-submit-button-text-color": "#FFFFFF",
    "--feedback-submit-button-border-radius": "10px",
    "--feedback-submit-button-font-weight": "600",
    "--feedback-cancel-button-fill-color": "#006554",
    "--feedback-cancel-button-text-color": "#006554",
    "--feedback-cancel-button-border-color": "#006554",
    "--feedback-cancel-button-border-width": "1px",
    "--feedback-cancel-button-border-radius": "10px",
    "--feedback-cancel-button-font-weight": "600",
    "--feedback-checkbox-border-radius": "6px",
    "--feedback-title-font-size": "22px",
    "--citations-text-font-weight": "700",
    "--citations-desktop-button-font-size": "12px",
    "--product-card-background-color": "#FFFFFF",
    "--product-card-title-color": "#292929",
    "--product-card-title-font-size": "14px",
    "--product-card-title-font-weight": "700",
    "--product-card-subtitle-color": "#292929",
    "--product-card-subtitle-font-size": "12px",
    "--product-card-subtitle-font-weight": "400",
    "--product-card-price-color": "#292929",
    "--product-card-price-font-size": "16px",
    "--product-card-price-font-weight": "300",
    "--product-card-was-price-color": "#6E6E6E",
    "--product-card-was-price-text-prefix": "was ",
    "--product-card-was-price-font-size": "12px",
    "--product-card-was-price-font-weight": "400",
    "--product-card-badge-text-color": "#FFFFFF",
    "--product-card-badge-background-color": "#000000",
    "--product-card-badge-font-size": "12px",
    "--product-card-badge-font-weight": "600",
    "--product-card-outline-color": "#00000000",
    "--product-card-width": "200px",
    "--product-card-height": "300px",
    "--product-card-text-spacing": "8px",
    "--product-card-text-top-padding": "20px",
    "--product-card-text-bottom-padding": "12px",
    "--product-card-text-horizontal-padding": "12px",
    "--product-card-carousel-spacing": "12px",
    "--product-card-carousel-horizontal-padding": "4px",
    "--cta-button-background-color": "#EDEDED",
    "--cta-button-text-color": "#191F1C",
    "--cta-button-icon-color": "#161313",
    "--cta-button-border-radius": "99px",
    "--cta-button-horizontal-padding": "16px",
    "--cta-button-vertical-padding": "12px",
    "--cta-button-font-size": "14px",
    "--cta-button-font-weight": "400",
    "--cta-button-icon-size": "16px",
    "--header-title-font-size": "18px",
    "--input-send-icon-color": "",
    "--input-send-arrow-icon-color": "",
    "--input-send-arrow-background-color": "",
    "--input-mic-icon-color": "",
    "--input-mic-recording-icon-color": "",
    "--color-container": "#F0F0F0",
    "--suggestion-background-color": "#F0F0F0",
    "--suggestion-text-color": "#131313",
    "--suggestion-item-border-radius": "10px",
    "--welcome-prompt-background-color": "",
    "--welcome-prompt-text-color": "",
    "--welcome-title-font-size": "22px",
    "--welcome-text-align": "left",
    "--welcome-content-padding": "0px",
    "--welcome-prompt-image-size": "90px",
    "--welcome-prompt-spacing": "8px",
    "--welcome-title-bottom-spacing": "10px",
    "--welcome-prompts-top-spacing": "8px",
    "--welcome-prompt-padding": "0px",
    "--welcome-prompt-corner-radius": "16px"
  }
}

Implementation Status

This section documents which properties are fully implemented, partially implemented, or not yet implemented in the iOS framework.

Legend

Metadata

Behavior

Disclaimer

Text (Copy)

Arrays

Assets

Theme Tokens - Typography

Theme Tokens - Colors

Theme Tokens - Colors (CTA Button)

Theme Tokens - Colors (Product Card)

Theme Tokens - Layout

Unsupported CSS Variables

The following CSS variables appear in web theme configurations but are not supported on iOS: