Alexa Styles and Resources (v1.1.0)

(This is not the most recent version of the alexa-styles package. Use the Other Versions option to see the documentation for the most recent version of the alexa-styles package)

Use the Alexa styles package to create a consistent presentation across different devices. This package provides a collection of named resources and styles designed to work well on different device types.

For details about defining your own resources and styles, see APL Resources and APL Styles.

Import the Alexa styles package

To use the Alexa styles package, and have access to all of its values, add the alexa-styles package to the import array in your document. The latest version of the alexa-styles package is 1.6.0.

Example of the imports section of a document:

Copied to clipboard.

{
  "import": [
    {
      "name": "alexa-styles",
      "version": "1.6.0"
    }
  ]
}

Color resources

The Alexa color resources define a set of colors. Use the "@" resource syntax to use these values on the color property of an APL component, for example:

{
    "type": "Text",
    "color": "@colorText"
},
{
    "type": "Frame",
    "backgroundColor": "@colorBackground",
    "borderColor": "@colorRed800"
}

Basic color resources

These resources define a set of color names. Many of these colors are also used within the UI color resources shown below.

Resource Name Default

colorBlack

#000000

colorBlackTVSafe

#0F0F0F

colorBlue800

#232F3E

colorGray100

#FAFAFA

colorGray200

#EBEDED

colorGray300

#D6DBDB

colorGray400

#ABB8B8

colorGray500

#879496

colorGray600

#6B7878

colorGray700

#383D3D

colorGray800

#1E2222

colorGreen800

#34581B

colorOrange800

#652718

colorPurple800

#3E3F68

colorRed800

#65151E

colorSalmon800

#652E2C

colorTeal800

#0A655E

colorWhite

#FFFFFF

colorWhiteTVSafe

#F0F0F0

colorYellow800

#986300

UI element color resources

These resources define colors recommended for specific APL document elements, such as text and backgrounds. Note that some of these use the colors defined in Basic color resources.

The Default value is used for most viewports. The TV value is used for viewports that match the tvLandscapeXLarge viewport profile.

Resource Name Description Default TV

colorAccent

Use to draw attention to a UI component.

#00C9FF

Default

colorBackground

Use for a basic background color.

@colorBlue800

Default

colorBackgroundOverlay

Color to use as an overlay over an image, to make text shown on top of the image easier to read.

@colorBlack

@colorBlackTVSafe

colorBackgroundReversed

Use for a basic background color.

colorGray200

Default

colorComponent

The primary color for a component in its default state. For example, the default color of a button.

@colorGray100

#DADADA

colorComponentReversed

The primary color for a component in its default state. For example, the default color of a button.

@colorGray800

Default

colorText

Default color for text elements.

@colorGray100

#DADADA

colorTextDisabled

Use for any disabled text, whether primary or secondary text.

@colorGray100

#DADADA

colorTextDisabledReversed

Used for any disabled text, when displayed over elements with dramatically different color value than the background

@colorGray800

Default

colorTextReversed

Use when standard text elements are displayed over elements with dramatically different color value than the background.

@colorGray800

Default

colorTextSecondary

Use to deemphasize metadata text.

@colorWhite

@colorWhiteTVSafe

colorTextSecondaryReversed

Use for metadata text which appears over elements with dramatically different color values than the background.

@colorGray800

Default

Opacity resources

The opacity resources define numerical values you can use to set the opacity property of a Component. Use the "@" resource syntax to use these values on the property, for example:

{
  "type": "Text",
  "text": "This text should appear disabled.",
  "opacity": "@opacityDisabled"
}
Resource Name Description Value

opacityDisabled

Fade the component to appear disabled.

0.3

opacityBackgroundOverlay

Fade the component enough to make text shown on top of the component more readable. This level of opacity is often used with background images.

0.6

Text resources

The text resources define values you can use to set properties on the Text and EditText components. Use the "@" resource syntax to set text properties to these values, for example:

{
    "type": "Text",
    "fontFamily": "@fontFamilyRomanSans",
    "fontWeight": "@fontWeightBold",
    "fontSize": "@fontSizeMedium",
    "lineHeight": "@lineHeightExpanded",
    "letterSpacing": "@letterSpacingNormal"
}

Font family

Use these string resources to set the fontFamily property of the APL Text and APL EditText components.

Resource Name Description Value

fontFamilyRomanSans

Includes sans serifs used for English and English-like languages that are written in Latin, Greek, and Cyrillic scripts.

Amazon Ember Display

fontFamilyRomanSerif

Includes serifs used for English and English-like languages that are written in Latin, Greek, and Cyrillic scripts.

Bookerly

fontFamilyCompact

Includes Chinese, Japanese, and Korean languages that are written in script languages where additional spacing may be needed for larger glyphs.

Noto Sans CJK

Font weight

Use these string resources to set the fontWeight property of the APL Text and APL EditText components.

Resource Name Description Value

fontWeightLight

Use for most smaller text and any longer text.

300

fontWeightRegular

Use for karaoke text and text set at sizes below 18dp.

400

fontWeightMedium

Use for label text for titles.

500

fontWeightBold

Use to create contrast and to highlight a number or part of a phrase.

700

fontWeightHeavy

Use to create extreme contrast.

900

Font size

Use these dimension resources to set the fontSize property of the APL Text and APL EditText components. These resources are responsive, so they adjust in size based on the viewport of the user's device. The numerical values shown here are in dp.

The Default value is used for most viewports. The Hub (small) value is used for viewports that match the hubRoundSmall or hubLandscapeSmall viewport profiles. The TV is used for viewports that match the tvLandscapeXLarge viewport profile.

Resource Name Description Default Hub (small) TV

fontSize5XLarge

Use for quick, glanceable text, such as acronyms or large numbers to show time or day of the week.

148

106

96

fontSize4XLarge

Slightly smaller display size to use for quick, glanceable text, such as acronyms or large numbers to show time or day of the week.

112

80

64

fontSize3XLarge

Use when displaying a small amount of text, such as list items or inline titles that need to be read at a distance.

92

66

48

fontSize2XLarge

Slightly smaller display size to use when displaying a small amount of text, such as list items or inline titles that need to be read at a distance.

74

53

32

fontSizeXLarge

48

48

24

fontSizeLarge

Use for text that is shown alongside text set in display sizes, such as a brief description to go alongside a movie title.

40

40

20

fontSizeMedium

Use for long-form content, such as a synopsis of a book.

32

32

16

fontSizeSmall

Use to accompany titles, such as a displaying additional metadata about a movie time.

28

28

14

fontSizeXSmall

Use for navigation, page, and section headers, such as flight information in a header.

24

24

12

Line height

Use these number resources to set the lineHeight property of the APL Text component. These resources are responsive, so they adjust in size based on the viewport of the user's device.

The Default value is used for most viewports. The Hub (small) value is used for viewports that match the hubRoundSmall or hubLandscapeSmall viewport profiles. The TV is used for viewports that match the tvLandscapeXLarge viewport profile.

Resource Name Default Hub (small) TV

lineHeightNormal

1.25

1.25

1.25

lineHeightMedium

1.285

1.285

1.285

lineHeightLarge

1.3

1.3

1.3

lineHeightXLarge

1.333

1.333

1.333

lineHeightXXLarge

1.375

1.375

1.375

lineHeightTextStyleDisplay1

1.162

1.132

1.1667

lineHeightTextStyleDisplay2

1.117

1.15

1.125

lineHeightTextStyleDisplay3

1.173

1.151

1.166

lineHeightTextStyleDisplay4

1.297

1.207

@lineHeightNormal

lineHeightTextStyleKaraoke

1.297

1.207

@lineHeightXXLarge

Letter spacing

Use these number resources to set the letterSpacing property of the APL Text component. These values increase or decrease the space between characters.

Resource Name Description Value

letterSpacingNormal

No extra space between characters.

0

letterSpacingCondensed

Decreases the space between characters.

0.8

letterSpacingExpanded

Increases the space between characters.

2

Spacing resources

The spacing resources define dimension values you can use to set padding and spacing properties. Use the "@" resource syntax to set:

The dimensions are expressed in dp.

For example:

{
    "type": "Container",
    "paddingLeft": "@spacingMedium",
    "paddingRight": "@spacingMedium"
}

The Default value is used for most viewports. The Hub (large) value is used for viewports that match the hubLandscapeLarge viewport profile. The TV is used for viewports that match the tvLandscapeXLarge viewport profile.

Resource Name Default Hub (large) TV

marginHorizontal

64

80

48

spacing3XSmall

8

default

4

spacing2XSmall

12

default

6

spacingXSmall

16

default

8

spacingSmall

24

default

12

spacingMedium

32

default

16

spacingLarge

48

default

24

spacingXLarge

56

default

28

spacing2XLarge

64

default

32

spacing3XLarge

72

default

36

Border radius resources

The border radius resources define dimension values you can use to set the borderRadius property. Use the "@" resource syntax to use these values on the borderRadius property of these components:

This lets you clip the corners of the image or frame. For example:

{
    "type": "Image",
    "borderRadius": "@shapeRoundedRect"
}

The Default value is used for most viewports. The TV is used for viewports that match the tvLandscapeXLarge viewport profile.

Resource Name Description Default TV

shapeRoundedRect

Round the corners of the image.

8dp

6dp

shapeCircle

Clip the image to a circle. This is set to the full viewport width to ensure that the value is a large enough number to clip the image to a circle.

100vw

default

Text styles

Use the Alexa text styles to set the style property of the APL Text component. These styles combine multiple text attributes such as color, fontFamily, fontSize, and other attributes. These styles are defined to be responsive, so they work well across different devices.

Although other components also have a style property, these styles specifically control Text component properties, so it only makes sense to use them with the Text component.

To assign a style to a Text component, assign the style name to the component's style property, for example:

{
    "type": "Text",
    "style": "textStyleDisplay4",
    "text": "This text is using textStyleDisplay4."
}

The alexa-styles package defines a base style (textStyleDisplayBase) that sets all of the following Text properties:

{
  "color": "@colorText",
  "fontFamily": "@fontFamilyRomanSans",
  "fontStyle": "normal",
  "lineHeight": "@lineHeightNormal",
  "letterSpacing": "@letterSpacingNormal",
  "opacity": 1
}

All remaining styles build off of this base.

Style Name Description

textStyleDisplayBase

Base text style, extended by the other styles.

textStyleDisplay1

Use for glanceable text, such as acronyms, or large numbers to show time or day-of-the-week.

textStyleDisplay1Alt

Use to create contrast with textStyleDisplay1.

textStyleDisplay2

Smaller than textStyleDisplay1. Use for glanceable text, such as acronyms, or large numbers to show time or day-of-the-week.

textStyleDisplay2Alt

Use to create contrast with textStyleDisplay2.

textStyleDisplay3

Use to display a small amount of text, such as list items to be read at a distance.

textStyleDisplay3Alt

Use to create contrast with textStyleDisplay3.

textStyleDisplay4

Smaller than textStyleDisplay3. Use to display a small amount of text, such as list items to be read at a distance.

textStyleDisplay4Alt

Use to create contrast with textStyleDisplay4.

textStyleDisplay5

Use for text that is shown alongside an item, such as a brief description or synopsis of a movie.

textStyleDisplay5Alt

Use to create contrast with textStyleDisplay5.

textStyleDisplay6

Use for headline text in paragraph or body copy.

textStyleDisplay6Alt

Use to create contrast with textStyleDisplay6.

textStyleKaraoke

Use to highlight text in a karaoke experience.

textStyleBody

Use for long-form content, such as the synopsis of a book.

textStyleBodyAlt

Use to create contrast with textStyleBody.

textStyleHint

Use for hint text or action hint text.

textStyleCallout

Use for text that plays a supporting role, such as a grid view of images that each have a title.

textStyleCalloutAlt

Use to create contrast with textStyleCallout.

textStyleActionHint

Used for button text that indicates that the button can be selected with the user's voice.

textStyleTitle

Use for buttons and actionable touch controls.

textStyleMetadata

Use to accompany textStyleCallout titles, such as a displaying additional metadata about a movie time.

textStyleMetadataAlt

Use to create contrast with textStyleMetadata.

textStyleCaption

Use for optional UI elements, such as time passed in a progress bar.
Was this page helpful?

Last updated: Nov 28, 2023