# Customizing an Amazon Q Business web experience
Customizing a web experience

Creating an Amazon Q Business application environment automatically creates a web experience with a shareable URL. Amazon Q offers customization options for your web experience, allowing you to align the interface with your organization's branding and user needs. This guide will walk you through the process of customizing text elements, visual themes, and some accessibility features, helping you create a more suited experience for your users.

**Note**  
As of Oct 31, 2024, once you have created a new Amazon Q Business application environment, the default web experience will allow users to interact directly with the LLM to get answers from its general knowledge or uploaded file content, even if the Admin has not yet connected any enterprise data sources.  
For existing application environments, the *Allow direct access to LLM* setting will remain as previously configured. For new application environments, the *Allow direct access to LLM* setting will be enabled by default, though Admins can still disable this if desired.

You can customize a web experience by using either the AWS Management Console or the Amazon Q API. These customizations persist even in *Amazon Q embedded*. You can perform these customizations using either the AWS Management Console or the Amazon Q API (available via the AWS SDK, REST API, and AWS CLI).

If you use the API, customizing your Amazon Q Business can involve a combination of the following API operations.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateApplication.html) – Creates an Amazon Q application environment.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateWebExperience.html) – Creates an Amazon Q web experience.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetWebExperience.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetWebExperience.html) – Gets the properties of the web experience that you set up.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateWebExperience.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateWebExperience.html) – Updates the properties of an existing Amazon Q web experience.
+ [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListWebExperiences.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_ListWebExperiences.html) – Lists Amazon Q web experiences.

**Topics**
+ [

## Customization overview
](#customization-web-experience-iam-overview)
+ [

# Customizing text elements
](customizing-web-experience-text-elements.md)
+ [

# Customizing visual themes
](customizing-web-experience-themes.md)
+ [

# Reference materials for customizing the visual theme
](customizing-web-experience-themes-reference-materials.md)

## Customization overview
Overview

Creating an Amazon Q Business application environment automatically generates a web experience with a shareable URL. Before sharing this URL, you can customize various elements:
+ Title and subtitle
+ Welcome message
+ Sample prompts
+ Logo and favicon
+ Colors and fonts

# Customizing text elements
Text Elements

This topic shows how to customize text elements using the AWS Management Console and the AWS CLI.

**Note**  
When using the console, you can preview changes in real-time as you customize your web experience.

**Topics**
+ [

## Using the AWS Management Console
](#customizing-web-experience-text-elements-using-aws-management-console)
+ [

## Using the AWS CLI
](#customizing-web-experience-text-elements-using-aws-cli)

## Using the AWS Management Console
Console

The following procedure shows how to update text elements using the console.

1. Sign in to the AWS Management Console and find the Amazon Q Business console.

1. From the Amazon Q Business **Applications** page, select *your application*, then choose **Customize web experience**.

1. In the **Customize web experience** section, choose **Customize web experience** from the right navigation panel.

1. Choose **Text** and enter the following information:
   + **Title**: A title for your web experience (visible to end users).
   + **Subtitle** (optional): Additional information for end users.
   + **Welcome message**: An optional message for end users (consider mentioning data sources and application capabilities).
   + **Display sample prompts**: Enable or disable the display of [sample prompts](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/quick-prompts.html) for the end user's conversation start screen.

1. Choose **Save**.

## Using the AWS CLI
CLI

The following code snippet shows how to customize text elements using the AWS CLI.

```
aws qbusiness update-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--title optional-title \
--subtitle optional-subtitle \ 
--welcome-message optional-welcome-message \
--sample-prompts-control-mode ENABLED
```

# Customizing visual themes
Visual Themes

This topic shows how to customize the visual theme using the Amazon Q Business console and the AWS CLI.

**Note**  
The console only supports accessing customization artifacts stored in Amazon S3 but the Amazon Q Business API supports accessing artifacts in both S3 and other data sources.
Your web customization artifacts must be of one of the following supported content types.  
Custom logo and favicons — `image/svg+xml`, `image/x-icon`, and `image/png`. Logo files must be 1 MB or smaller.
Custom fonts — `font/ttf`, `font/otf`, `font/woff`, and `font/woff2`.

**Topics**
+ [

## Prerequisites for accessing your customization artifacts stored in Amazon S3
](#customizing-web-experience-themes-requirements)
+ [

## Using the AWS Management Console
](#customizing-visual-themes-using-aws-management-console)
+ [

## Using the AWS CLI
](#customizing-web-experience-themes-using-aws-cli)

## Prerequisites for accessing your customization artifacts stored in Amazon S3
Prerequisites

1. All S3 URIs for files to read and folders to store must be located in the same AWS Region as the application environment of the web experience.

1. You can use public or private Amazon S3 buckets to save and store your web experience customization.
   + 

**Prerequisites for public S3 buckets**
     + Ensure all S3 URIs for files to read and folders to store are publicly accessible. For managing access to your S3 files, see [Access Control in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-management.html).
     + Configure CORS to allow console and web app access to resources. For more information, see [Configuring cross-origin resource sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html).
   + **Prerequisites for private S3 buckets**

     To allow Amazon Q Business to access web customization artifacts from your private S3 buckets, you must do the following:
     + Disable [access control lists (ACLs)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html). For more information, see [Setting Object Ownership on an existing bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-ownership-existing-bucket.html).
     + If your Amazon S3 bucket is encrypted using AWS KMS Key instead of Amazon S3 managed key, a similar resource policy to the sample bucket policy below must be added to AWS KMS key.

------
#### [ JSON ]

****  

       ```
       {
           "Version":"2012-10-17",		 	 	 
           "Statement": [{
               "Sid": "PolicyForAmazonQWebAccessForWebExperienceArtifacts",
               "Effect": "Allow",
               "Principal": {
                   "Service": "application.qbusiness.amazonaws.com"
               },
               "Action": ["kms:Decrypt"],
               "Resource": ["arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"]
           }]
       }
       ```

------
     + Create a bucket policy in your private bucket.
**Note**  
 The value of "`aws:Referer"` cannot contain `"https://"` or end with `"/"`.   
**Example policy for giving Amazon Q Business access to your web experience artifacts**  

------
#### [ JSON ]

****  

     ```
     {
          "Version":"2012-10-17",		 	 	 
          "Statement": [
              {
                  "Sid": "PolicyForAmazonQWebAccessForWebExperienceArtifacts",
                  "Effect": "Allow",
                  "Principal": {
                      "Service": "application.qbusiness.amazonaws.com"
                  },
                  "Action": [
                      "s3:GetObject"
                  ],
                  "Resource": [
                      "arn:aws:s3:::amzn-s3-demo-bucket/web-experience-object-key",
                      "arn:aws:s3:::amzn-s3-demo-bucket/web-experience-object-key-2"
                  ],
                  "Condition":{
                      "StringLike":{
                          "aws:Referer":[
                              "web-experience-domain-without-https"
                          ]
                      },
                      "Bool": {
                          "aws:SecureTransport": "true"
                      } 
                  }
              }
          ]
      }
     ```

------

## Using the AWS Management Console
Console

The following procedure shows how to customize visual themes using the console.

1. Sign in to the AWS Management Console and find the Amazon Q Business console.

1. From the Amazon Q Business **Applications** page, select *your application*, then choose **Customize web experience**.

1. In the **Customize web experience** section, choose **Customize web experience** from the right navigation panel and choose **Theme**.

1. Choose either **Managed theming** (for direct input of colors and assets) or **Custom theming** (for using your own CSS).

   1. For **Managed theming**:
      + Enter colors for background, and primary title.
      + Provide the S3 URI for the logo file. Logo files must be 1 MB or smaller.

   1. For **Custom theming**:
      + Enter your CSS snippet in the editor.

1. Enter the S3 URI to store your customization.

1. Choose **Save**.

## Using the AWS CLI
CLI

The following code snippet shows how to customize visual themes using the AWS CLI.

```
aws qbusiness update-web-experience \
--application-id application-id \
--web-experience-id web-experience-id \
--customization-configuration {"customCSSUrl":"custom css url","logoUrl":"logo url","fontUrl":"font url","faviconUrl":"favicon url"}
```

# Reference materials for customizing the visual theme
Reference Materials

**Topics**
+ [

## Color considerations for accessibility
](#customizing-web-experience-themes-color-format)
+ [

## Choosing Color Values for Your Theme
](#reference-materials-color-values)
+ [

## Supported Root CSS Variables
](#customizing-web-experience-themes-reference-materials-supported-css-variables)
+ [

## Example
](#customizing-web-experience-themes-examples)

## Color considerations for accessibility
Accessibility

When customizing your Amazon Q web experience, it's crucial to prioritize accessibility. Ensure sufficient contrast is there between the text and background colors. Use tools like the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your color choices meet Web Content Accessibility Guidelines (WCAG) 2.x standards.

For comprehensive accessibility guidelines, refer to the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG21/).

## Choosing Color Values for Your Theme
Color Values

Amazon Q supports the following color value formats:
+ Hexadecimal colors (with and without transparency)
+ RGB and RGBA colors
+ HSL and HSLA colors
+ Predefined/Cross-browser color names

**Note**  
Amazon Q Business doesn't support `currentcolor`. For a comprehensive list of supported CSS color values, see [W3Schools CSS Colors](https://www.w3schools.com/cssref/css_colors_legal.php)

## Supported Root CSS Variables
CSS Variables

Only the following root CSS variables are supported:

```
--black
--white
--foreground
--primary
--primary-foreground
--secondary
--secondary-foreground
--card
--card-foreground
--popover
--popover-foreground
--tooltip
--tooltip-foreground
--muted
--muted-foreground
--accent
--accent-foreground
--info
--info-foreground
--success
--success-foreground
--warning
--warning-foreground
--error
--error-foreground
--destructive
--destructive-foreground
--border
--input
--ring
--radius

--background
--qbusiness-webexperience-title-color
--qbusiness-webexperience-font-typeface
--qbusiness-webexperience-chat-user-background-color
--qbusiness-webexperience-chat-user-text-color
--qbusiness-webexperience-chat-agent-background-color
--qbusiness-webexperience-chat-agent-text-color
--qbusiness-webexperience-chat-logo-visibility
--qbusiness-webexperience-logo-url
--qbusiness-webexperience-font-url
--qbusiness-webexperience-favicon-url
```

## Example
Example

### CSS
CSS

The following is an example of a valid CSS file setting the visual theme for Amazon Q Business.

```
:root {
  --background: #FFFFFF;
  --qbusinesness-webexperience-title-color: #9013FE;
  --qbusiness-webexperience-font-typeface: Custom Font;
  --qbusiness-webexperience-chat-user-background-color: #7ED321;
  --qbusiness-webexperience-chat-user-text-color: #344054;
  --qbusiness-webexperience-chat-agent-background-color: #FFFFFF;
  --qbusiness-webexperience-chat-agent-text-color: #344054;
  --qbusiness-webexperience-chat-logo-visibility: hidden;
  --qbusiness-webexperience-logo-url: "https://<bucket_name>.s3.<region>.amazonaws.com/<logo_name>.png";
  --qbusiness-webexperience-font-url: "https://<bucket_name>.s3.<region>.amazonaws.com/<font_name>.ttf";
  --qbusiness-webexperience-favicon-url: "https://<bucket_name>.s3.<region>.amazonaws.com/<favicon_name>.ico";
}
```