Overview

@amazon-devices/kepler-a11y-settings-interface-turbo provides accessibility settings APIs and UI scaling hooks for Kepler applications.

Getting Started

Installation

In the package.json file, add the @amazon-devices/kepler-a11y-settings-interface-turbo package as a dependency: From the command line, run the following:

npm install @amazon-devices/kepler-a11y-settings-interface-turbo

Or, you can manually edit the package.json file as shown:

"dependencies": {
  ...
  "@amazon-devices/kepler-a11y-settings-interface-turbo": "~1.0.0", // or latest major version
  ...
}

Then run npm install.

Usage

Settings Getters, Setters, and Listeners

Reading Settings

Use the KeplerA11ySettingsInterface to query current accessibility settings. All getter methods return Promises.

import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';

// Get current settings (getter methods return Promises)
KeplerA11ySettingsInterface.isScreenReaderEnabled().then(isEnabled => {
  console.log('Screen reader enabled:', isEnabled);
});

KeplerA11ySettingsInterface.getUiScaleSetting().then(scale => {
  console.log('Current UI scale:', scale);
});

KeplerA11ySettingsInterface.getColorCorrectionMode().then(mode => {
  console.log('Color correction mode:', mode);
});

KeplerA11ySettingsInterface.getCaptionPreferences().then(captionPrefs => {
  console.log('Current caption preferences:', captionPrefs);
});

Listening for Changes

Add listeners to respond to accessibility setting changes. Listener registration and removal methods are asynchronous and return Promises:

import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';

// Listen for screen reader state changes
const handleScreenReaderChange = (enabled: boolean) => {
  console.log(`Screen reader ${enabled ? 'enabled' : 'disabled'}`);
  // Respond to screen reader state
};

const success = await KeplerA11ySettingsInterface.addScreenReaderStateListener(handleScreenReaderChange);
if (!success) {
  console.warn('Failed to register screen reader listener');
}

// Remember to remove listeners when component unmounts
await KeplerA11ySettingsInterface.removeScreenReaderStateListener();

Writing Settings (System Apps Only)

Setter methods require the com.amazon.devconf.privilege.accessibility.write permission, which is reserved for system applications. Third-party apps are not eligible to declare this permission.

import KeplerA11ySettingsInterface, { CaptioningProps } from '@amazon-devices/kepler-a11y-settings-interface-turbo';

await KeplerA11ySettingsInterface.setScreenReaderEnabled(true);
await KeplerA11ySettingsInterface.setUiScaleSetting(3);
await KeplerA11ySettingsInterface.setColorCorrectionMode('deuteranomaly');

const newPrefs: CaptioningProps = {
  textSize: 'large',
  textColor: 'white',
  textFont: 'sans_serif',
  textEdgeStyle: 'drop_shadowed',
  textOpacity: 'percent_100'
};

await KeplerA11ySettingsInterface.setCaptionPreferences(newPrefs);

UI Scale Setting Hooks

React Hooks for Dynamic Scaling

Use the provided hooks to create responsive UI that automatically adapts to scale setting changes. These hooks are necessary where UI sizes are defined, in the case that the associated UI element should scale. If you are using UI elements that have already wrapped underlying predefined sizes with these hooks, you simply need to wrap your App definition in the UiScaleSettingContextProvider. Application developers are responsible for ensuring that their app gracefully handles changes in size to the onboarded UI elements. For example, an application developer may need to ensure that a container is scrollable, or text component has overflow behavior defined, even if these properties were unnecessary at the default scale.

import React from 'react';
import { View, StyleSheet } from 'react-native';
import { 
  UiScaleSettingContextProvider, 
  useScaledSize, 
  useScalingMultiplier,
  useUiScaleSetting 
} from '@amazon-devices/kepler-a11y-settings-interface-turbo';

const CONTENT_WIDTH_DEFAULT_BASE = 144;
const CONTENT_HEIGHT_DEFAULT_BASE = 80;
const LOGO_DEFAULT_WIDTH = 57;
const LOGO_DEFAULT_HEIGHT = 24;

const styles = StyleSheet.create({
  viewStyle: {
    marginLeft: 8,
    alignItems: 'center',
    zIndex: 0,
  },
  text: {
    fontSize: 14,
    color: '#666',
    fontFamily: 'sans-serif',
  },
});

const App = () => {
  // Get scaled dimensions that automatically update when scale setting changes
  const contentWidthDefault = useScaledSize(CONTENT_WIDTH_DEFAULT_BASE, { 
    itemType: 'medium_upscale' 
  });
  const contentHeightDefault = useScaledSize(CONTENT_HEIGHT_DEFAULT_BASE, { 
    itemType: 'medium_upscale' 
  });
  
  // Get scaling multiplier for related dimensions
  const assetScalingMultiplier = useScalingMultiplier(LOGO_DEFAULT_WIDTH, { 
    itemType: 'image' 
  });

  // Memoize the style sheet so it only updates when the contentWidthDefault or
  // contentHeightDefault change via the useScaledSize hook.
  const viewStyle = React.useMemo(
    () => ({
      ...styles.viewStyle,
      width: contentWidthDefault,
      height: contentHeightDefault,
    }),
    [contentWidthDefault, contentHeightDefault],
  );

  // Memoize the style sheet so it only updates when the assetScalingMultiplier
  // changes via the useScalingMultiplier hook.
  const assetStyle = React.useMemo(
    () => ({
      width: LOGO_DEFAULT_WIDTH * assetScalingMultiplier,
      height: LOGO_DEFAULT_HEIGHT * assetScalingMultiplier,
      marginRight: 12,
    }),
    [assetScalingMultiplier],
  );

  // Get current scale factor to display below
  const currentScale = useUiScaleSetting();

  return (
    <View style={viewStyle}>
      <Image style={assetStyle} source={logoSource} />
      <Text style={styles.text}>Current scale: {currentScale}</Text>
    </View>
  );
};

// Wrap your app with the provider.  This will cause all UI elements utilizing
// the useScaledSize and useScalingMultiplier hooks to respond dynamically to
// UiScaleSetting setting changes, even if the UI element is imported from another
// library.
const AppWithProvider = () => (
  <UiScaleSettingContextProvider>
    <App />
  </UiScaleSettingContextProvider>
);

export default AppWithProvider;

Scaling Types

The library supports different scaling behaviors for various UI elements:

'low_upscale' - Large items that scale minimally (e.g., cards)
'medium_upscale' - Standard UI elements with moderate scaling
'large_upscale' - Small elements that need significant scaling (e.g., buttons)
'low_downscale' - Whitespace that reduces at higher scales
'large_downscale' - Large padding that reduces dramatically
'text' - Text elements with corresponding line height scaling
'image' - Images and visual assets

Advanced Scaling Options

Control scaling limits with optional parameters:

const scaledWidth = useScaledSize(100, {
  itemType: 'medium_upscale',
  maxSize: 200,  // Never exceed 200 units
  minSize: 50    // Never go below 50 units
});

Density Independent Pixels (DIP)

The scaling APIs (useScaledSize, useScalingMultiplier, getScaledSize, getScalingMultiplier) support both Density Independent Pixel (DIP) and physical pixel inputs, depending on whether the consuming application has enabled the PLATFORM_DENSITY_INDEPENDENT_PIXEL runtime feature flag in its react-native.config.js.

DIP enabled (PLATFORM_DENSITY_INDEPENDENT_PIXEL: true): Size values passed to the scaling APIs are expected to be in density-independent pixels.
DIP not enabled: Size values are expected to be in physical pixels.

API Reference

Classes

KeplerA11ySettingsInterface

Interfaces

CaptioningProps — Captioning properties to describe captioning preferences.
KeplerA11ySettingsInterfaceTurbo
ScalingProps — Scaling properties to describe an item that will be scaled.

Type Aliases

CaptionColor — Color values for captioning.
CaptionEdgeStyle — Edge style values for captioning.
CaptionFont — Font values for captioning.
CaptionOpacity — Opacity values for captioning.
CaptionTextSize — Text size values for captioning.
ColorCorrectionMode — Color correction modes for addressing color vision deficiencies.
ItemScalingType — Types of items that can be scaled. Different types of objects scale at different rates.
TimeoutMultiplier — Timeout multiplier values for adjusting timeout durations.
UiScaleSetting — This enum defines scale settings for applications and UI frameworks

Functions

UiScaleSettingContextProvider — Provider component that supplies UI scale setting context to child components
useScaledSize — Hook to retrieve the UI scaled size value based on original size and scaling properties.
useScalingMultiplier — Hook to retrieve the UI scaling multiplier value based on original size and scaling properties.
useUiScaleSetting — Hook to access the current UI scale setting.
useUiScaleSettingLoading — Hook to check whether we’re still fetching the UI scale setting.

Variables

SCALING_PROP_IMAGE_TYPE — Convenience ScalingProps object for image scaling when maxSize/minSize are not needed
SCALING_PROP_LARGE_DOWNSCALE_TYPE — Convenience ScalingProps object for large downscale items when maxSize/minSize are not needed
SCALING_PROP_LARGE_UPSCALE_TYPE — Convenience ScalingProps object for large upscale items when maxSize/minSize are not needed
SCALING_PROP_LOW_DOWNSCALE_TYPE — Convenience ScalingProps object for low downscale items when maxSize/minSize are not needed
SCALING_PROP_LOW_UPSCALE_TYPE — Convenience ScalingProps object for low upscale items when maxSize/minSize are not needed
SCALING_PROP_MEDIUM_UPSCALE_TYPE — Convenience ScalingProps object for medium upscale items when maxSize/minSize are not needed
SCALING_PROP_TEXT_TYPE — Convenience ScalingProps object for text scaling when maxSize/minSize are not needed
UiScaleSettingMode — Mapping from public-facing level name to numerical UiScaleSetting value

​Overview

​Getting Started

​Installation

​Usage

​Settings Getters, Setters, and Listeners

​Reading Settings

​Listening for Changes

​Writing Settings (System Apps Only)

​UI Scale Setting Hooks

​React Hooks for Dynamic Scaling

​Scaling Types

​Advanced Scaling Options

​Density Independent Pixels (DIP)

​API Reference

​Classes

​Interfaces

​Type Aliases

​Functions

​Variables