chore: Style api v2 tools test pages

.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": [

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);
+}

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 (
+    <div className={clsx(styles.panel, className)}>
+      <div className={styles.title}>{title}</div>
+      <div className={styles.body}>{children}</div>
+    </div>
+  );
+}

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;
+}

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 <div className={clsx(styles.pill, className)}>{children}</div>;
+}

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 (
+    <SimplePage
+      title="Style API v2: tools"
+      subtitle={
+        <Box variant="span">
+          Applies style-api tools to a set of custom components, which are then themed via{' '}
+          <Box variant="awsui-inline-code">--awsui-style-*</Box> tokens.
+        </Box>
+      }
+      screenshotArea={{}}
+    >
+      <div>
+        <h2>Examples</h2>
+
+        <h3>Without carrier tokens — no token inheritance needed</h3>
+        <SpaceBetween size="s" direction="horizontal">
+          <CustomPill>Default</CustomPill>
+          <CustomPill className={overrides.pill}>Themed</CustomPill>
+        </SpaceBetween>
+
+        <h3>With carrier tokens — style tokens read by descendant elements</h3>
+        <SpaceBetween size="s" direction="horizontal">
+          <CustomPanel title="Default">Default style (no overrides).</CustomPanel>
+          <CustomPanel className={overrides.panel} title="Themed">
+            <SpaceBetween size="s">
+              <span>Themed via --awsui-style-* on the root; the title and body colors resolve through carriers.</span>
+              <CustomPanel title="Default">Default style (no overrides).</CustomPanel>
+            </SpaceBetween>
+          </CustomPanel>
+        </SpaceBetween>
+      </div>
+    </SimplePage>
+  );
+}

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;
+}