diff --git a/.stylelintrc b/.stylelintrc
index a0819dac1a..0fc8715ddf 100644
--- a/.stylelintrc
+++ b/.stylelintrc
@@ -4,7 +4,7 @@
"stylelint-prettier/recommended"
],
"rules": {
- "custom-property-pattern": "^(?!.+)",
+ "custom-property-pattern": "^awsui-(internal-)?style-",
"scss/comment-no-empty": null,
"scss/operator-no-newline-after": null,
"selector-pseudo-class-no-unknown": [
diff --git a/pages/styling/custom-panel.scss b/pages/styling/custom-panel.scss
new file mode 100644
index 0000000000..648f26c38d
--- /dev/null
+++ b/pages/styling/custom-panel.scss
@@ -0,0 +1,41 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+
+@use '@cloudscape-design/component-toolkit/internal/style-api' as style-api;
+
+// Illustrates a shared token group.
+$surface: (color-text, color-background, color-border, border-width, border-radius);
+
+// Creates panel props by combining shared and component-specific tokens.
+$props: style-api.combine($surface, (color-text-secondary));
+$tokens: style-api.resolve($props, carrier);
+
+@include style-api.register($props);
+
+.panel {
+ @include style-api.carriers($props);
+ box-sizing: border-box;
+ max-inline-size: 360px;
+ background: var(#{style-api.read($tokens, color-background)}, #fcf2f4);
+ border-block: var(#{style-api.read($tokens, border-width)}, 1px) solid
+ var(#{style-api.read($tokens, color-border)}, #ff8da1);
+ border-inline: var(#{style-api.read($tokens, border-width)}, 1px) solid
+ var(#{style-api.read($tokens, color-border)}, #ff8da1);
+ border-start-start-radius: var(#{style-api.read($tokens, border-radius)}, 8px);
+ border-start-end-radius: var(#{style-api.read($tokens, border-radius)}, 8px);
+ border-end-start-radius: var(#{style-api.read($tokens, border-radius)}, 8px);
+ border-end-end-radius: var(#{style-api.read($tokens, border-radius)}, 8px);
+ padding-block: 16px;
+ padding-inline: 16px;
+}
+// Descendant elements can read tokens because of the carrier re-anchoring inside panel.
+.title {
+ color: var(#{style-api.read($tokens, color-text)}, #16191f);
+ font-weight: 700;
+}
+.body {
+ margin-block-start: 8px;
+ color: var(#{style-api.read($tokens, color-text-secondary)}, #5f6b7a);
+}
diff --git a/pages/styling/custom-panel.tsx b/pages/styling/custom-panel.tsx
new file mode 100644
index 0000000000..db357f162f
--- /dev/null
+++ b/pages/styling/custom-panel.tsx
@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import clsx from 'clsx';
+
+import styles from './custom-panel.scss';
+
+export interface CustomPanelProps {
+ title: React.ReactNode;
+ className?: string;
+ children?: React.ReactNode;
+}
+
+// A simple custom component that uses --awsui-style-* tokens with a carrier layer, thus allowing nested
+// elements to inherit them.
+export function CustomPanel({ title, className, children }: CustomPanelProps) {
+ return (
+
+ );
+}
diff --git a/pages/styling/custom-pill.scss b/pages/styling/custom-pill.scss
new file mode 100644
index 0000000000..93fbf7e9a4
--- /dev/null
+++ b/pages/styling/custom-pill.scss
@@ -0,0 +1,25 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+
+@use '@cloudscape-design/component-toolkit/internal/style-api' as style-api;
+
+$props: (color-background, color-border, color-text, border-radius);
+$tokens: style-api.resolve($props, public);
+
+@include style-api.register($props);
+
+.pill {
+ box-sizing: border-box;
+ background: var(#{style-api.read($tokens, color-background)}, #c2185b);
+ color: var(#{style-api.read($tokens, color-text)}, #ffffff);
+ border-block: 1px solid var(#{style-api.read($tokens, color-border)}, #c2185b);
+ border-inline: 1px solid var(#{style-api.read($tokens, color-border)}, #c2185b);
+ border-start-start-radius: var(#{style-api.read($tokens, border-radius)}, 12px);
+ border-start-end-radius: var(#{style-api.read($tokens, border-radius)}, 12px);
+ border-end-start-radius: var(#{style-api.read($tokens, border-radius)}, 12px);
+ border-end-end-radius: var(#{style-api.read($tokens, border-radius)}, 12px);
+ padding-block: 4px;
+ padding-inline: 8px;
+}
diff --git a/pages/styling/custom-pill.tsx b/pages/styling/custom-pill.tsx
new file mode 100644
index 0000000000..cec05bd1b4
--- /dev/null
+++ b/pages/styling/custom-pill.tsx
@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import clsx from 'clsx';
+
+import styles from './custom-pill.scss';
+
+export interface CustomPillProps {
+ className?: string;
+ children?: React.ReactNode;
+}
+
+// A simple custom component that uses --awsui-style-* tokens directly (no inheritance and carrier tokens needed).
+export function CustomPill({ className, children }: CustomPillProps) {
+ return {children}
;
+}
diff --git a/pages/styling/style-api-tools.page.tsx b/pages/styling/style-api-tools.page.tsx
new file mode 100644
index 0000000000..9450f2abaf
--- /dev/null
+++ b/pages/styling/style-api-tools.page.tsx
@@ -0,0 +1,47 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import { Box, SpaceBetween } from '~components';
+
+import { SimplePage } from '../app/templates';
+import { CustomPanel } from './custom-panel';
+import { CustomPill } from './custom-pill';
+
+import overrides from './style-overrides.scss';
+
+export default function StyleApiToolsPage() {
+ return (
+
+ Applies style-api tools to a set of custom components, which are then themed via{' '}
+ --awsui-style-* tokens.
+
+ }
+ screenshotArea={{}}
+ >
+
+
Examples
+
+ Without carrier tokens — no token inheritance needed
+
+ Default
+ Themed
+
+
+ With carrier tokens — style tokens read by descendant elements
+
+ Default style (no overrides).
+
+
+ Themed via --awsui-style-* on the root; the title and body colors resolve through carriers.
+ Default style (no overrides).
+
+
+
+
+
+ );
+}
diff --git a/pages/styling/style-overrides.scss b/pages/styling/style-overrides.scss
new file mode 100644
index 0000000000..266958e7b1
--- /dev/null
+++ b/pages/styling/style-overrides.scss
@@ -0,0 +1,24 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+
+@use '~design-tokens' as tokens;
+
+// Consumer style overrides. These can use any values: raw, var(...), light-dark(...), or design tokens.
+
+.panel {
+ --awsui-style-color-background: #{tokens.$color-background-status-info};
+ --awsui-style-color-text: #{tokens.$color-text-status-info};
+ --awsui-style-color-text-secondary: #{tokens.$color-text-body-secondary};
+ --awsui-style-color-border: #{tokens.$color-border-status-info};
+ --awsui-style-border-width: 2px;
+ --awsui-style-border-radius: 4px;
+}
+
+.pill {
+ --awsui-style-color-background: #{tokens.$color-background-status-info};
+ --awsui-style-color-text: #{tokens.$color-text-status-info};
+ --awsui-style-color-border: #{tokens.$color-border-status-info};
+ --awsui-style-border-radius: 4px;
+}