Cloudscape Design System Components

Cloudscape components require the following environments:

Frameworks

• React 16.8+
• Jest 25+

Browsers

• Desktop: Latest 3 major versions of Google Chrome, Mozilla Firefox, and Microsoft Edge.
• macOS: Latest 3 minor versions of Apple Safari.

Note: Mobile browsers and Microsoft Internet Explorer are not supported. All viewport sizes across supported desktop browsers are supported.

When a table cell contains interactive elements like text inputs or radio groups, they may conflict with grid navigation keyboard inputs. To resolve this, you must make cell elements conditionally interactive (e.g., activated by Enter or F2).

To suppress grid navigation and allow the element to capture keyboard input, wrap the interactive content in a container with role="dialog" or use the grid navigation API to suppress behaviors.

<td>
  <div role="dialog">
    <input value="editable cell value" />
    <button>save</button>
    <button>discard</button>
  </div>
</td>

When styling components, avoid hardcoded values like specific colors, spacing, or font sizes. Instead, use design tokens and custom CSS properties to ensure consistency across different themes and modes.

To support Right-to-Left (RTL) layouts, use CSS logical properties instead of physical properties:

• Use inline-start / inline-end instead of left / right.
• Use block-start / block-end instead of top / bottom.
• Use inline-size instead of width.
• Use block-size instead of height.

Install the project dependencies using npm.

npm install

Use the following npm scripts to run different test suites. The scripts automatically handle environment variables like TZ=UTC and NODE_OPTIONS=--experimental-vm-modules, as well as the dev server lifecycle for integration and motion tests.

npm test               # all tests
npm run test:unit      # unit tests
npm run test:integ     # integration tests (starts dev server automatically)
npm run test:motion    # motion tests (starts dev server automatically)
npm run test:a11y      # accessibility tests

Snapshot tests guard artifacts like API definitions and design tokens. Before updating snapshots, you must run a full build to ensure documenter docs are generated.

To update unit test snapshots:

TZ=UTC npx jest -u -c jest.unit.config.js src/__tests__/

If design tokens have changed, you must also update integration test snapshots:

NODE_OPTIONS=--experimental-vm-modules npx jest -u -c jest.integ.config.js src/__integ__/

npm run build

# Update unit test snapshots
TZ=UTC npx jest -u -c jest.unit.config.js src/__tests__/

# Update integration test snapshots (if design tokens changed)
NODE_OPTIONS=--experimental-vm-modules npx jest -u -c jest.integ.config.js src/__integ__/

To add a new @i18n string, follow these steps:

1. Add the English source string and a translator note to the AWS-UI-Components-I18n package (at i18n/<component>/en.json).
2. Run npm run build in that package.
3. Copy the generated output/ files into this repository's src/i18n/ (specifically messages/all.<locale>.json bundles and messages-types.ts).
4. Ensure the message key path (e.g., i18nStrings.sortDropdown.sortAscending) matches the interface used by useInternalI18n.

When component APIs or design tokens change, you must update snapshots. Before updating, run a full build using npm run build to ensure documenter docs are generated. Use the -u flag with Jest to perform the update.

# Unit snapshots
TZ=UTC npx jest -u -c jest.unit.config.js src/__tests__/snapshot-tests

# Integ snapshots (requires dev server running via `npm start`)
NODE_OPTIONS=--experimental-vm-modules npx jest -u -c jest.integ.config.js src/__integ__/

# Snapshots inside components (e.g. when custom-css-properties.js changes)
TZ=UTC npx jest -u -c jest.unit.config.js src/

To ensure proper documentation and type referencing, do not define union types inline within an interface. Instead, define them as named type aliases within the component's namespace and reference them using the component's namespace prefix.

Example pattern: Instead of variant?: 'primary' | 'secondary', use variant?: ButtonProps.Variant where Variant is a named type alias.

When CSS logical properties are insufficient for direction-aware logic, use the following tools:

• In SCSS: Use the with-direction mixin.
• In TypeScript: Use the direction detection and logical geometry helpers provided by @cloudscape-design/component-toolkit/internal. These helpers should be used to replace physical DOM property checks.