From bfd7debf274e02efbaf6f407fce9fedfa7ae008b Mon Sep 17 00:00:00 2001
From: Jessica Kuelz <15003460+jkuelz@users.noreply.github.com>
Date: Sun, 26 Jul 2026 17:06:00 -0700
Subject: [PATCH 1/5] feat: support end-positioned expand icon in expandable
 section

Add internal __expandIconPosition ('start' | 'end', default 'start') to
InternalExpandableSection. When 'end', the expand caret is DOM-reordered
to the inline-end (preserving focus order for accessibility) across all
variants; the outside-header caret (container and default-with-actions)
renders as an accessible button. Default 'start' behavior is unchanged
and there is no public API change (internal __-prefixed prop).

Groundwork for the side-navigation icon layout. Note: the navigation
variant now wraps its header text in a span (styled only in the end
layout), a minor DOM change for that side-nav-only variant.
---
 .../__tests__/expandable-section.test.tsx     | 270 ++++++++++++++++++
 .../expandable-section-header.tsx             | 190 +++++++++---
 src/expandable-section/internal.tsx           |   8 +
 src/expandable-section/styles.scss            |  96 +++++++
 4 files changed, 532 insertions(+), 32 deletions(-)

diff --git a/src/expandable-section/__tests__/expandable-section.test.tsx b/src/expandable-section/__tests__/expandable-section.test.tsx
index 06a20b7f65..502cd1f0c6 100644
--- a/src/expandable-section/__tests__/expandable-section.test.tsx
+++ b/src/expandable-section/__tests__/expandable-section.test.tsx
@@ -8,10 +8,13 @@ import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
 import '../../__a11y__/to-validate-a11y';
 import Button from '../../../lib/components/button';
 import ExpandableSection, { ExpandableSectionProps } from '../../../lib/components/expandable-section';
+import InternalExpandableSection from '../../../lib/components/expandable-section/internal';
 import Header from '../../../lib/components/header';
 import Link from '../../../lib/components/link';
 import createWrapper, { ExpandableSectionWrapper } from '../../../lib/components/test-utils/dom';
 
+import styles from '../../../lib/components/expandable-section/styles.selectors.js';
+
 jest.mock('@cloudscape-design/component-toolkit/internal', () => ({
   ...jest.requireActual('@cloudscape-design/component-toolkit/internal'),
   warnOnce: jest.fn(),
@@ -509,3 +512,270 @@ describe('headerText', () => {
     });
   }
 });
+
+describe('__expandIconPosition', () => {
+  function renderInternalExpandableSection(
+    props: Partial<Parameters<typeof InternalExpandableSection>[0]> = {}
+  ): ExpandableSectionWrapper {
+    const { container } = render(<InternalExpandableSection headerText="Header" {...props} />);
+    return createWrapper(container).findExpandableSection()!;
+  }
+
+  describe('default behavior (start position)', () => {
+    test('icon renders before header text for default variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'default' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      const children = Array.from(expandButton.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
+      expect(iconIndex).toBeLessThan(textIndex);
+    });
+
+    test('icon renders before header text for footer variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      const children = Array.from(expandButton.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
+      expect(iconIndex).toBeLessThan(textIndex);
+    });
+
+    test('icon renders before header content for navigation variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'navigation' });
+      const header = wrapper.findHeader().getElement();
+      const children = Array.from(header.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      // Icon should be the first child (index 0)
+      expect(iconIndex).toBe(0);
+    });
+
+    test('does not apply icon-end modifier classes when position is start', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'start' });
+      const icon = wrapper.findExpandIcon().getElement();
+      expect(icon.classList.contains(styles['icon-container-end'])).toBe(false);
+    });
+  });
+
+  describe('end position', () => {
+    test('icon renders after header text for footer variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      const children = Array.from(expandButton.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
+      expect(iconIndex).toBeGreaterThan(textIndex);
+    });
+
+    test('icon renders after header text for default variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'default', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      const children = Array.from(expandButton.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
+      expect(iconIndex).toBeGreaterThan(textIndex);
+    });
+
+    test('icon renders after header content for navigation variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
+      const header = wrapper.findHeader().getElement();
+      const children = Array.from(header.children);
+      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
+      // Icon should be the last child
+      expect(iconIndex).toBe(children.length - 1);
+    });
+
+    test('icon renders after header text for container variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'container', __expandIconPosition: 'end' });
+      // For container variant, icon is rendered outside InternalHeader
+      const icon = wrapper.findExpandIcon().getElement();
+      expect(icon.classList.contains(styles['icon-container-end'])).toBe(true);
+    });
+
+    test('applies icon-container-end modifier class for footer variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
+      const icon = wrapper.findExpandIcon().getElement();
+      expect(icon.classList.contains(styles['icon-container-end'])).toBe(true);
+    });
+
+    test('applies header-icon-end modifier class for navigation variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
+      const header = wrapper.findHeader().getElement();
+      expect(header.classList.contains(styles['header-icon-end'])).toBe(true);
+    });
+
+    test('applies header-button-icon-end modifier class for footer variant', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      expect(expandButton.classList.contains(styles['header-button-icon-end'])).toBe(true);
+    });
+
+    test('icon renders outside header actions for default variant with headerActions', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'default',
+        __expandIconPosition: 'end',
+        headerActions: <button>Action</button>,
+      });
+      // The icon should be rendered outside the header-content wrapper,
+      // as a direct child of the header-icon-end wrapper — matching the container variant pattern.
+      const header = wrapper.findHeader().getElement();
+      const headerContent = header.querySelector(`.${styles['header-content']}`);
+      expect(headerContent).toBeTruthy();
+      const icon = wrapper.findExpandIcon().getElement();
+      // Icon should be a sibling of the header-content wrapper, not nested inside it.
+      expect(icon.parentElement).toBe(headerContent!.parentElement);
+      expect(icon.previousElementSibling).not.toBe(null);
+    });
+  });
+
+  describe('expand/collapse functionality with end position', () => {
+    test('navigation variant toggles aria-expanded on click', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
+      wrapper.findExpandButton().click();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    test('footer variant toggles aria-expanded on click', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
+      wrapper.findExpandButton().click();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    test('default variant toggles aria-expanded on click', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'default', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
+      wrapper.findExpandButton().click();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    test('container variant toggles aria-expanded on click', () => {
+      const wrapper = renderInternalExpandableSection({ variant: 'container', __expandIconPosition: 'end' });
+      const expandButton = wrapper.findExpandButton().getElement();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
+      wrapper.findExpandButton().click();
+      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    test('content is shown when expanded with end position', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'footer',
+        __expandIconPosition: 'end',
+        defaultExpanded: true,
+        children: 'Expanded content',
+      });
+      const expandedContent = wrapper.findExpandedContent()?.getElement();
+      expect(expandedContent).toHaveTextContent('Expanded content');
+    });
+  });
+
+  describe('outside icon button (end position with renderIconOutsideHeader)', () => {
+    test('container variant renders outside caret as a button with aria-expanded', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'container',
+        __expandIconPosition: 'end',
+        headerText: 'Header',
+      });
+      const iconButton = wrapper.findExpandIcon().getElement();
+      expect(iconButton.tagName).toBe('BUTTON');
+      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
+      expect(iconButton).toHaveAttribute('aria-controls');
+    });
+
+    test('default variant with headerActions renders outside caret as a button with aria-expanded', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'default',
+        __expandIconPosition: 'end',
+        headerText: 'Header',
+        headerActions: <button>Action</button>,
+      });
+      const iconButton = wrapper.findExpandIcon().getElement();
+      expect(iconButton.tagName).toBe('BUTTON');
+      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
+      expect(iconButton).toHaveAttribute('aria-controls');
+    });
+
+    test('clicking the outside caret button toggles expansion for container variant', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'container',
+        __expandIconPosition: 'end',
+        headerText: 'Header',
+        children: 'Content',
+      });
+      const iconButton = wrapper.findExpandIcon().getElement();
+      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
+      iconButton.click();
+      expect(iconButton).toHaveAttribute('aria-expanded', 'true');
+      expect(wrapper.findExpandedContent()?.getElement()).toHaveTextContent('Content');
+    });
+
+    test('clicking the outside caret button toggles expansion for default with actions', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'default',
+        __expandIconPosition: 'end',
+        headerText: 'Header',
+        headerActions: <button>Action</button>,
+        children: 'Content',
+      });
+      const iconButton = wrapper.findExpandIcon().getElement();
+      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
+      iconButton.click();
+      expect(iconButton).toHaveAttribute('aria-expanded', 'true');
+      expect(wrapper.findExpandedContent()?.getElement()).toHaveTextContent('Content');
+    });
+
+    test('container without actions: clicking caret toggles exactly once (no double-toggle)', () => {
+      const onChange = jest.fn();
+      const { container } = render(
+        <InternalExpandableSection
+          variant="container"
+          __expandIconPosition="end"
+          headerText="Header"
+          onChange={onChange}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const iconButton = wrapper.findExpandIcon().getElement();
+      iconButton.click();
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ detail: { expanded: true } }));
+    });
+
+    test('outside caret button has aria-controls matching content region id', () => {
+      const wrapper = renderInternalExpandableSection({
+        variant: 'container',
+        __expandIconPosition: 'end',
+        headerText: 'Header',
+        children: 'Content',
+        defaultExpanded: true,
+      });
+      const iconButton = wrapper.findExpandIcon().getElement();
+      const contentRegion = wrapper.findContent().getElement();
+      expect(iconButton.getAttribute('aria-controls')).toBe(contentRegion.getAttribute('id'));
+    });
+
+    test('keyboard Enter on outside caret button toggles expansion', () => {
+      const onChange = jest.fn();
+      const { container } = render(
+        <InternalExpandableSection
+          variant="container"
+          __expandIconPosition="end"
+          headerText="Header"
+          onChange={onChange}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const iconButton = wrapper.findExpandIcon().getElement();
+      // Native button handles Enter/Space natively, triggering click
+      iconButton.click();
+      expect(onChange).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/src/expandable-section/expandable-section-header.tsx b/src/expandable-section/expandable-section-header.tsx
index 2d8192d0a2..85700248f7 100644
--- a/src/expandable-section/expandable-section-header.tsx
+++ b/src/expandable-section/expandable-section-header.tsx
@@ -27,6 +27,54 @@ import styles from './styles.css.js';
 
 const componentName = 'ExpandableSection';
 
+interface ExpandIconButtonProps {
+  icon: JSX.Element;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaControls: string;
+  expanded: boolean;
+  onClick: MouseEventHandler;
+  stopPropagation?: boolean;
+  className?: string;
+}
+
+/**
+ * Standalone expand/collapse caret button used when the icon renders OUTSIDE
+ * the main clickable header area (navigation variant) or outside the headerButton
+ * (end-position with actions/container). This is always an independent interactive
+ * element with its own ARIA attributes.
+ */
+const ExpandIconButton = ({
+  icon,
+  ariaLabel,
+  ariaLabelledBy,
+  ariaControls,
+  expanded,
+  onClick,
+  stopPropagation,
+  className,
+}: ExpandIconButtonProps) => (
+  <button
+    className={clsx(styles['icon-container'], styles['expand-button'], className)}
+    type="button"
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledBy}
+    aria-controls={ariaControls}
+    aria-expanded={expanded}
+    onClick={
+      stopPropagation
+        ? event => {
+            event.stopPropagation();
+            onClick(event);
+          }
+        : onClick
+    }
+    {...getExpandActionAnalyticsMetadataAttribute(expanded)}
+  >
+    {icon}
+  </button>
+);
+
 interface ExpandableDefaultHeaderProps {
   id: string;
   descriptionId?: string;
@@ -40,6 +88,7 @@ interface ExpandableDefaultHeaderProps {
   onClick: MouseEventHandler;
   icon: JSX.Element;
   variant: InternalVariant;
+  expandIconPosition?: 'start' | 'end';
 }
 
 interface ExpandableNavigationHeaderProps extends Omit<ExpandableDefaultHeaderProps, 'onKeyUp' | 'onKeyDown'> {
@@ -125,22 +174,40 @@ const ExpandableNavigationHeader = ({
   expanded,
   children,
   icon,
+  expandIconPosition = 'start',
 }: ExpandableNavigationHeaderProps) => {
+  const expandButton = (
+    <ExpandIconButton
+      icon={icon}
+      ariaLabelledBy={ariaLabelledBy}
+      ariaLabel={ariaLabel}
+      ariaControls={ariaControls}
+      expanded={expanded}
+      onClick={onClick}
+      className={expandIconPosition === 'end' ? styles['icon-container-end'] : undefined}
+    />
+  );
   return (
-    <div id={id} className={clsx(className, styles['click-target'], analyticsSelectors['header-label'])}>
-      <button
-        className={clsx(styles['icon-container'], styles['expand-button'])}
-        aria-labelledby={ariaLabelledBy}
-        aria-label={ariaLabel}
-        aria-controls={ariaControls}
-        aria-expanded={expanded}
-        type="button"
-        onClick={onClick}
-        {...getExpandActionAnalyticsMetadataAttribute(expanded)}
-      >
-        {icon}
-      </button>
-      {children}
+    <div
+      id={id}
+      className={clsx(
+        className,
+        styles['click-target'],
+        analyticsSelectors['header-label'],
+        expandIconPosition === 'end' && styles['header-icon-end']
+      )}
+    >
+      {expandIconPosition === 'end' ? (
+        <>
+          {children}
+          {expandButton}
+        </>
+      ) : (
+        <>
+          {expandButton}
+          {children}
+        </>
+      )}
     </div>
   );
 };
@@ -163,6 +230,7 @@ const ExpandableHeaderTextWrapper = ({
   headingTagOverride,
   onKeyUp,
   onKeyDown,
+  expandIconPosition = 'start',
 }: ExpandableHeaderTextWrapperProps) => {
   const isContainer = variant === 'container';
   const HeadingTag = headingTagOverride || 'div';
@@ -175,6 +243,11 @@ const ExpandableHeaderTextWrapper = ({
     </span>
   );
   const listeners = { onClick, onKeyDown, onKeyUp };
+  const iconAtEnd = expandIconPosition === 'end';
+  // For the variants that allow actions, when end placement is active, the icon is rendered outside the
+  // InternalHeader so it appears at the inline-end of the wrapper, past any header actions.
+  // Other variants render the icon at the end of the headerButton itself.
+  const renderIconOutsideHeader = iconAtEnd && (isContainer || !!actions);
 
   // If interactive elements are present, constrain the clickable area to only the icon and the header text
   // to prevent nesting interactive elements.
@@ -185,11 +258,49 @@ const ExpandableHeaderTextWrapper = ({
   const headingTagListeners = !headerButtonListeners && !isContainer && description ? listeners : undefined;
   // For all other cases, make the entire header clickable for backwards compatibility.
   const wrapperListeners = !headerButtonListeners && !headingTagListeners ? listeners : undefined;
+
+  // Standalone caret button — used when the icon is rendered OUTSIDE the headerButton
+  // (end-position with container or actions). Must be its own <button> for accessibility.
+  const expandButton = (
+    <ExpandIconButton
+      icon={icon}
+      ariaLabel={ariaLabel}
+      ariaLabelledBy={!ariaLabel ? id : undefined}
+      ariaControls={ariaControls}
+      expanded={expanded}
+      onClick={onClick}
+      stopPropagation={true}
+      className={clsx(styles[`icon-container-${variant}`], styles['icon-container-end'])}
+    />
+  );
+
+  // Decorative inline icon — used when the caret is INSIDE the headerButton
+  // (which itself is the interactive element). A nested <button> would be illegal.
+  const expandIcon = (
+    <span
+      className={clsx(
+        styles['icon-container'],
+        styles[`icon-container-${variant}`],
+        iconAtEnd && styles['icon-container-end']
+      )}
+    >
+      {icon}
+    </span>
+  );
+
+  const outsideIcon = renderIconOutsideHeader ? expandButton : null;
+
+  const textElement = (
+    <span id={id} className={clsx(styles['header-text'], analyticsSelectors['header-label'])}>
+      {children}
+    </span>
+  );
   const headerButton = (
     <span
       className={clsx(
         styles['expand-button'],
         isContainer ? styles['header-container-button'] : styles['header-button'],
+        iconAtEnd && styles['header-button-icon-end'],
         headerButtonListeners && styles['click-target']
       )}
       role="button"
@@ -202,34 +313,46 @@ const ExpandableHeaderTextWrapper = ({
       {...headerButtonListeners}
       {...(headerButtonListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
     >
-      <span className={clsx(styles['icon-container'], styles[`icon-container-${variant}`])}>{icon}</span>
-      <span id={id} className={clsx(styles['header-text'], analyticsSelectors['header-label'])}>
-        {children}
-      </span>
+      {renderIconOutsideHeader ? (
+        textElement
+      ) : iconAtEnd ? (
+        <>
+          {textElement}
+          {expandIcon}
+        </>
+      ) : (
+        <>
+          {expandIcon}
+          {textElement}
+        </>
+      )}
     </span>
   );
 
   return (
     <div
-      className={clsx(className, wrapperListeners && styles['click-target'])}
+      className={clsx(className, wrapperListeners && styles['click-target'], iconAtEnd && styles['header-icon-end'])}
       {...wrapperListeners}
       {...(wrapperListeners ? getExpandActionAnalyticsMetadataAttribute(expanded) : {})}
     >
       {isContainer ? (
-        <InternalHeader
-          variant="h2"
-          description={description}
-          counter={headerCounter}
-          info={headerInfo}
-          actions={actions}
-          headingTagOverride={headingTagOverride}
-          __inExpandableSection={true}
-        >
-          {headerButton}
-        </InternalHeader>
+        <>
+          <InternalHeader
+            variant="h2"
+            description={description}
+            counter={headerCounter}
+            info={headerInfo}
+            actions={actions}
+            headingTagOverride={headingTagOverride}
+            __inExpandableSection={true}
+          >
+            {headerButton}
+          </InternalHeader>
+          {outsideIcon}
+        </>
       ) : (
         <>
-          <div className={clsx(actions && styles['header-actions-wrapper'])}>
+          <div className={clsx(styles['header-content'], actions && styles['header-actions-wrapper'])}>
             <HeadingTag
               className={clsx(styles['header-wrapper'], headingTagListeners && styles['click-target'])}
               {...headingTagListeners}
@@ -240,6 +363,7 @@ const ExpandableHeaderTextWrapper = ({
             {actions}
           </div>
           {description && <HeaderDescription variantOverride="h3">{description}</HeaderDescription>}
+          {outsideIcon}
         </>
       )}
     </div>
@@ -265,6 +389,7 @@ export const ExpandableSectionHeader = ({
   onKeyUp,
   onKeyDown,
   onClick,
+  expandIconPosition,
 }: ExpandableSectionHeaderProps) => {
   const alwaysShowDivider = variantRequiresActionsDivider(variant) && headerActions;
   const icon = (
@@ -282,6 +407,7 @@ export const ExpandableSectionHeader = ({
     ariaLabel: ariaLabel,
     onClick: onClick,
     variant,
+    expandIconPosition,
   };
 
   if ((headerCounter || headerInfo) && !variantSupportsInfoLink(variant) && isDevelopment) {
@@ -311,7 +437,7 @@ export const ExpandableSectionHeader = ({
         ariaLabelledBy={ariaLabelledBy}
         {...defaultHeaderProps}
       >
-        {headerText ?? header}
+        <span className={styles['header-navigation-content']}>{headerText ?? header}</span>
       </ExpandableNavigationHeader>
     );
   }
diff --git a/src/expandable-section/internal.tsx b/src/expandable-section/internal.tsx
index 2f17df540d..8d5705fbf3 100644
--- a/src/expandable-section/internal.tsx
+++ b/src/expandable-section/internal.tsx
@@ -25,6 +25,12 @@ export type InternalExpandableSectionProps = Omit<ExpandableSectionProps, 'varia
   InternalBaseComponentProps & {
     variant?: InternalVariant;
     __injectAnalyticsComponentMetadata?: boolean;
+    /**
+     * Controls placement of the expand/collapse icon relative to the header content.
+     * Defaults to 'start'. When set to 'end', the icon is rendered after the header
+     * content and pushed to the inline-end of a full-width header.
+     */
+    __expandIconPosition?: 'start' | 'end';
   };
 
 export default function InternalExpandableSection({
@@ -44,6 +50,7 @@ export default function InternalExpandableSection({
   headerAriaLabel,
   __internalRootRef,
   __injectAnalyticsComponentMetadata,
+  __expandIconPosition = 'start',
   ...props
 }: InternalExpandableSectionProps) {
   const ref = useRef<HTMLDivElement>(null);
@@ -122,6 +129,7 @@ export default function InternalExpandableSection({
           headerInfo={headerInfo}
           headerActions={headerActions}
           headingTagOverride={headingTagOverride}
+          expandIconPosition={__expandIconPosition}
           {...triggerProps}
         />
       }
diff --git a/src/expandable-section/styles.scss b/src/expandable-section/styles.scss
index f0923f16b3..360d25cbde 100644
--- a/src/expandable-section/styles.scss
+++ b/src/expandable-section/styles.scss
@@ -198,6 +198,8 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
     flex-direction: row;
     justify-content: space-between;
     align-items: center;
+    flex: 1;
+    min-inline-size: 0;
   }
 
   &-button,
@@ -302,3 +304,97 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
     color: awsui.$color-text-expandable-section-hover;
   }
 }
+
+// When the expand/collapse icon is rendered at the end of the header.
+// For non-container variants the icon is rendered at the end of the headerButton
+// (taking the full width of the header). For the container variant the icon is
+// rendered as a sibling of the InternalHeader so it appears past any actions.
+.header-icon-end {
+  &.wrapper-default,
+  &.wrapper-inline,
+  &.wrapper-footer,
+  &.wrapper-compact {
+    padding-inline-start: 0;
+  }
+
+  &.wrapper-navigation {
+    justify-content: space-between;
+  }
+
+  &.wrapper-container,
+  &.wrapper-default {
+    display: flex;
+    align-items: flex-start;
+    column-gap: awsui.$space-m;
+  }
+
+  &.wrapper-container {
+    &:not(.header-deprecated) {
+      padding-inline-start: container.$header-padding-horizontal;
+    }
+  }
+}
+
+.header-button-icon-end {
+  margin-inline-start: 0;
+  column-gap: awsui.$space-xs;
+  justify-content: space-between;
+
+  // For non-container variants the icon lives inside this button, so it
+  // needs to be a full-width flex row to push the icon to the inline-end.
+  // The container variant renders the icon outside InternalHeader, so
+  // making this element a block-level flex container with 100% width would
+  // force the title to consume all available space and push the info slot
+  // (rendered as a sibling inside InternalHeader) to a new line.
+  &:not(.header-container-button) {
+    display: flex;
+    inline-size: 100%;
+
+    > .header-text {
+      flex: 1;
+      min-inline-size: 0;
+    }
+  }
+}
+
+.icon-container-end {
+  margin-inline-start: auto;
+  margin-inline-end: 0;
+  flex-shrink: 0;
+
+  // Reset native <button> chrome for the outside caret in end-icon-position.
+  // The navigation variant already has its own reset via .header-navigation > .icon-container
+  // so this is harmless-but-redundant for that path, and necessary for default/container.
+  border-block: none;
+  border-inline: none;
+  background: none;
+  padding-block: 0;
+  padding-inline: 0;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+
+  // In the end layout the icon is a flex child governed by the parent's
+  // align-items: flex-start. Reset the inset-block-start offsets that the
+  // start layout uses (they assume relative positioning within text flow)
+  // so the icon aligns with the first line of header text via flex.
+  @include theming.one-theme-only {
+    &:not(.icon-container-container) {
+      inset-block-start: $icon-offset-block;
+    }
+    > .icon {
+      inset-block-start: 0;
+    }
+  }
+}
+
+// Semantic wrapper around HeadingTag + actions in non-container variants
+.header-icon-end > .header-content {
+  flex: 1;
+  min-inline-size: 0;
+}
+
+.header-icon-end > .header-navigation-content {
+  flex: 1;
+  min-inline-size: 0;
+}

From 87995cfc52cb5ac2f64402b1e7568d7a81f96a39 Mon Sep 17 00:00:00 2001
From: Jessica Kuelz <15003460+jkuelz@users.noreply.github.com>
Date: Tue, 28 Jul 2026 11:41:56 -0700
Subject: [PATCH 2/5] feat: Add automatic icon layout to collapsible side
 navigation

 When any nav item has an icon, SideNavigation switches to an icon layout: the expand caret moves to the inline-end, item spacing widens, and rows get a full-width hover background. Consumes the existing withIcons signal and threads the internal __expandIconPosition to the Section and ExpandableLinkGroup expandable headers.

Also fixes ExpandableSection's  to remove content padding for all variants (previously only , despite other variants having default content padding) and corrects its docs. Adds a colorBackgroundSideNavigationItemIconHover design token.
---
 pages/side-navigation/collapsed.page.tsx      | 37 +++++++-
 .../__snapshots__/themes.test.ts.snap         |  8 ++
 .../__snapshots__/documenter.test.ts.snap     |  2 +-
 .../__tests__/expandable-section.test.tsx     | 19 +++++
 src/expandable-section/interfaces.ts          |  2 +-
 src/expandable-section/internal.tsx           | 22 ++++-
 src/expandable-section/styles.scss            | 37 ++++++++
 src/side-navigation/parts.tsx                 |  8 ++
 src/side-navigation/styles.scss               | 85 ++++++++++++++-----
 style-dictionary/one-theme/colors.ts          |  4 +
 style-dictionary/one-theme/typography.ts      |  3 -
 style-dictionary/utils/token-names.ts         |  1 +
 style-dictionary/visual-refresh/colors.ts     |  1 +
 13 files changed, 197 insertions(+), 32 deletions(-)

diff --git a/pages/side-navigation/collapsed.page.tsx b/pages/side-navigation/collapsed.page.tsx
index eb01e7eb6f..7d35fe90d0 100644
--- a/pages/side-navigation/collapsed.page.tsx
+++ b/pages/side-navigation/collapsed.page.tsx
@@ -14,14 +14,45 @@ const items: SideNavigationProps.Item[] = [
   { type: 'link', text: 'Settings', href: '#/settings', icon: <Icon name="settings" /> },
   {
     type: 'section',
-    text: 'Resources',
+    text: 'Section',
     items: [
       { type: 'link', text: 'Announcements', href: '#/announcements', icon: <Icon name="announcement" /> },
       { type: 'link', text: 'Team', href: '#/team', icon: <Icon name="group" /> },
       { type: 'link', text: 'Networking', href: '#/networking', icon: <Icon name="share" /> },
     ],
   },
+  { type: 'divider' },
+  {
+    type: 'link-group',
+    text: 'Link group',
+    href: '#/',
+    items: [
+      { type: 'link', text: 'Announcements', href: '#/announcements3', icon: <Icon name="announcement" /> },
+      { type: 'link', text: 'Team', href: '#/team3', icon: <Icon name="group" /> },
+      { type: 'link', text: 'Networking', href: '#/networking3', icon: <Icon name="share" /> },
+    ],
+  },
+  {
+    type: 'expandable-link-group',
+    text: 'Expandable link group',
+    href: '#/projects',
+    icon: <Icon name="folder" />,
+    items: [
+      { type: 'link', text: 'Project 1', href: '#/projects/1' },
+      { type: 'link', text: 'Project 2', href: '#/projects/2' },
+      { type: 'link', text: 'Project 3', href: '#/projects/3' },
+    ],
+  },
   { type: 'link', text: 'Documentation', href: '#/docs', external: true },
+  {
+    type: 'section-group',
+    title: 'Section group',
+    items: [
+      { type: 'link', text: 'Announcements', href: '#/announcements2', icon: <Icon name="announcement" /> },
+      { type: 'link', text: 'Team', href: '#/team2', icon: <Icon name="group" /> },
+      { type: 'link', text: 'Networking', href: '#/networking2', icon: <Icon name="share" /> },
+    ],
+  },
 ];
 
 const COLLAPSED_WIDTH = 52;
@@ -49,7 +80,7 @@ export default function SideNavigationCollapsedPage() {
   }
 
   return (
-    <div style={{ display: 'flex', blockSize: '100vh', overflow: 'hidden' }}>
+    <div style={{ display: 'flex', blockSize: '100vh', overflow: 'auto' }}>
       {/* Nav panel */}
       <nav
         id="side-navigation-panel"
@@ -64,7 +95,7 @@ export default function SideNavigationCollapsedPage() {
           flexDirection: 'column',
         }}
       >
-        <div style={{ inlineSize: collapsed ? 'auto' : EXPANDED_WIDTH, boxSizing: 'border-box' }}>
+        <div style={{ inlineSize: collapsed ? 'auto' : EXPANDED_WIDTH, boxSizing: 'border-box', overflow: 'auto' }}>
           {/* Toggle button at top */}
           <div
             style={{
diff --git a/src/__integ__/__snapshots__/themes.test.ts.snap b/src/__integ__/__snapshots__/themes.test.ts.snap
index 30b658079c..f19634ea03 100644
--- a/src/__integ__/__snapshots__/themes.test.ts.snap
+++ b/src/__integ__/__snapshots__/themes.test.ts.snap
@@ -182,6 +182,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "compact" 1`] =
   "color-background-segment-wrapper": "#ffffff",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#0073bb",
+  "color-background-side-navigation-item-icon-hover": "#f1faff",
   "color-background-skeleton": "#eaeded",
   "color-background-skeleton-wave": "#f6f6f9",
   "color-background-slider-handle-active": "#0a4a74",
@@ -1164,6 +1165,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "dark" 1`] = `
   "color-background-segment-wrapper": "#2a2e33",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#00a1c9",
+  "color-background-side-navigation-item-icon-hover": "#414750",
   "color-background-skeleton": "#2a2e33",
   "color-background-skeleton-wave": "#414750",
   "color-background-slider-handle-active": "#44b9d6",
@@ -2146,6 +2148,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "light" 1`] = `
   "color-background-segment-wrapper": "#ffffff",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#0073bb",
+  "color-background-side-navigation-item-icon-hover": "#f1faff",
   "color-background-skeleton": "#eaeded",
   "color-background-skeleton-wave": "#f6f6f9",
   "color-background-slider-handle-active": "#0a4a74",
@@ -3128,6 +3131,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "reduced-motion"
   "color-background-segment-wrapper": "#ffffff",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#0073bb",
+  "color-background-side-navigation-item-icon-hover": "#f1faff",
   "color-background-skeleton": "#eaeded",
   "color-background-skeleton-wave": "#f6f6f9",
   "color-background-slider-handle-active": "#0a4a74",
@@ -4110,6 +4114,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "visual-refresh"
   "color-background-segment-wrapper": "#ffffff",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#006ce0",
+  "color-background-side-navigation-item-icon-hover": "#f0fbff",
   "color-background-skeleton": "#ebebf0",
   "color-background-skeleton-wave": "#f6f6f9",
   "color-background-slider-handle-active": "#004a9e",
@@ -5092,6 +5097,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "visual-refresh-
   "color-background-segment-wrapper": "#ffffff",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#006ce0",
+  "color-background-side-navigation-item-icon-hover": "#f0fbff",
   "color-background-skeleton": "#ebebf0",
   "color-background-skeleton-wave": "#f6f6f9",
   "color-background-slider-handle-active": "#004a9e",
@@ -6074,6 +6080,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "visual-refresh-
   "color-background-segment-wrapper": "#0f141a",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#42b4ff",
+  "color-background-side-navigation-item-icon-hover": "#333843",
   "color-background-skeleton": "#232b37",
   "color-background-skeleton-wave": "#333843",
   "color-background-slider-handle-active": "#75cfff",
@@ -7056,6 +7063,7 @@ exports[`CSS Custom Properties match previous snapshot for mode "visual-refresh-
   "color-background-segment-wrapper": "#161d26",
   "color-background-side-navigation-item-active": "transparent",
   "color-background-side-navigation-item-active-collapsed": "#42b4ff",
+  "color-background-side-navigation-item-icon-hover": "#333843",
   "color-background-skeleton": "#232b37",
   "color-background-skeleton-wave": "#333843",
   "color-background-slider-handle-active": "#75cfff",
diff --git a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
index e872e9fbab..9c7cb08fa9 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
@@ -13440,7 +13440,7 @@ manner even if you provide a value for this property.",
       "type": "boolean",
     },
     {
-      "description": "Determines whether the content section's default padding is removed. This default padding is only present for the \`container\` variant.",
+      "description": "Determines whether the default padding around the content section is removed.",
       "name": "disableContentPaddings",
       "optional": true,
       "type": "boolean",
diff --git a/src/expandable-section/__tests__/expandable-section.test.tsx b/src/expandable-section/__tests__/expandable-section.test.tsx
index 502cd1f0c6..0ec354aa33 100644
--- a/src/expandable-section/__tests__/expandable-section.test.tsx
+++ b/src/expandable-section/__tests__/expandable-section.test.tsx
@@ -672,6 +672,25 @@ describe('__expandIconPosition', () => {
     });
   });
 
+  describe('disableContentPaddings', () => {
+    test('applies disable-content-paddings class when disableContentPaddings is true', () => {
+      const wrapper = renderExpandableSection({
+        disableContentPaddings: true,
+        defaultExpanded: true,
+        children: 'Content',
+      });
+      expect(wrapper.findContent().getElement()).toHaveClass(styles['disable-content-paddings']);
+    });
+
+    test('does not apply disable-content-paddings class by default', () => {
+      const wrapper = renderExpandableSection({
+        defaultExpanded: true,
+        children: 'Content',
+      });
+      expect(wrapper.findContent().getElement()).not.toHaveClass(styles['disable-content-paddings']);
+    });
+  });
+
   describe('outside icon button (end position with renderIconOutsideHeader)', () => {
     test('container variant renders outside caret as a button with aria-expanded', () => {
       const wrapper = renderInternalExpandableSection({
diff --git a/src/expandable-section/interfaces.ts b/src/expandable-section/interfaces.ts
index 00e700d654..3cf470c3ae 100644
--- a/src/expandable-section/interfaces.ts
+++ b/src/expandable-section/interfaces.ts
@@ -51,7 +51,7 @@ export interface ExpandableSectionProps extends BaseComponentProps {
   variant?: ExpandableSectionProps.Variant;
 
   /**
-   * Determines whether the content section's default padding is removed. This default padding is only present for the `container` variant.
+   * Determines whether the default padding around the content section is removed.
    */
   disableContentPaddings?: boolean;
 
diff --git a/src/expandable-section/internal.tsx b/src/expandable-section/internal.tsx
index 8d5705fbf3..92f36921b4 100644
--- a/src/expandable-section/internal.tsx
+++ b/src/expandable-section/internal.tsx
@@ -31,6 +31,13 @@ export type InternalExpandableSectionProps = Omit<ExpandableSectionProps, 'varia
      * content and pushed to the inline-end of a full-width header.
      */
     __expandIconPosition?: 'start' | 'end';
+    /**
+     * Removes default padding from the header wrapper and content wrapper.
+     * Used by side-navigation to zero out expandable-section's own padding so the
+     * parent can control spacing directly, eliminating brittle cross-component
+     * positional selectors.
+     */
+    __disableHeaderPaddings?: boolean;
   };
 
 export default function InternalExpandableSection({
@@ -51,6 +58,7 @@ export default function InternalExpandableSection({
   __internalRootRef,
   __injectAnalyticsComponentMetadata,
   __expandIconPosition = 'start',
+  __disableHeaderPaddings = false,
   ...props
 }: InternalExpandableSectionProps) {
   const ref = useRef<HTMLDivElement>(null);
@@ -119,7 +127,12 @@ export default function InternalExpandableSection({
         <ExpandableSectionHeader
           id={triggerControlId}
           descriptionId={descriptionId}
-          className={clsx(styles.header, styles[`header-${baseVariant}`], screenReaderTextClass)}
+          className={clsx(
+            styles.header,
+            styles[`header-${baseVariant}`],
+            screenReaderTextClass,
+            __disableHeaderPaddings && styles['disable-header-paddings']
+          )}
           variant={baseVariant}
           expanded={!!expanded}
           header={header}
@@ -139,7 +152,12 @@ export default function InternalExpandableSection({
         <div
           id={controlId}
           ref={ref}
-          className={clsx(styles.content, styles[`content-${baseVariant}`], expanded && styles['content-expanded'])}
+          className={clsx(
+            styles.content,
+            styles[`content-${baseVariant}`],
+            expanded && styles['content-expanded'],
+            disableContentPaddings && styles['disable-content-paddings']
+          )}
           role="group"
           aria-label={triggerProps.ariaLabel}
           aria-labelledby={triggerProps.ariaLabelledBy}
diff --git a/src/expandable-section/styles.scss b/src/expandable-section/styles.scss
index 360d25cbde..48e3e90964 100644
--- a/src/expandable-section/styles.scss
+++ b/src/expandable-section/styles.scss
@@ -287,6 +287,20 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
   }
 }
 
+// Internal-only class: zeros header wrapper padding when __disableHeaderPaddings is set.
+// Allows parent components to control spacing without brittle positional selectors.
+.disable-header-paddings {
+  padding-block: 0;
+  padding-inline: 0;
+}
+
+// Internal-only class: zeros content wrapper padding when the disableContentPaddings prop is set.
+// Paired with disable-header-paddings for consistent zero-padding on both wrapper divs.
+.disable-content-paddings {
+  padding-block: 0;
+  padding-inline: 0;
+}
+
 .focusable {
   &:focus {
     outline: none;
@@ -319,6 +333,8 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
 
   &.wrapper-navigation {
     justify-content: space-between;
+    align-items: flex-start;
+    column-gap: awsui.$space-xs;
   }
 
   &.wrapper-container,
@@ -374,11 +390,23 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
   font: inherit;
   color: inherit;
 
+  // Align the navigation end-layout caret to the first line of header text.
+  // The header link has padding-block equal to (item-height - line-height) / 2
+  // (set by side-navigation). Mirror that on the caret so it sits at the same
+  // vertical position as the first text line — identical to the start layout.
+  .header-icon-end.wrapper-navigation > & {
+    padding-block-start: calc((#{awsui.$size-side-navigation-item-height} - #{awsui.$line-height-body-m}) / 2);
+  }
+
   // In the end layout the icon is a flex child governed by the parent's
   // align-items: flex-start. Reset the inset-block-start offsets that the
   // start layout uses (they assume relative positioning within text flow)
   // so the icon aligns with the first line of header text via flex.
   @include theming.one-theme-only {
+    // Override the base .icon-container one-theme rule that re-introduces
+    // margin-inline-end via the margin-inline shorthand (equal specificity,
+    // later source order wins).
+    margin-inline-end: 0;
     &:not(.icon-container-container) {
       inset-block-start: $icon-offset-block;
     }
@@ -398,3 +426,12 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
   flex: 1;
   min-inline-size: 0;
 }
+
+// Navigation variant, start icon: align the expand caret to the first line of text
+// when header paddings are disabled (side-navigation use case).
+// Mirrors the end-icon alignment at .icon-container-end (same formula).
+.disable-header-paddings.wrapper-navigation:not(.header-icon-end) > .icon-container {
+  display: grid;
+  align-items: flex-start;
+  padding-block: calc((#{awsui.$size-side-navigation-item-height} - #{awsui.$line-height-body-m}) / 2);
+}
diff --git a/src/side-navigation/parts.tsx b/src/side-navigation/parts.tsx
index 87a84446c0..7f579f5c2a 100644
--- a/src/side-navigation/parts.tsx
+++ b/src/side-navigation/parts.tsx
@@ -393,6 +393,7 @@ export function NavigationItemsList({
               className={clsx(styles.list, styles[`list-variant-${variant}`], {
                 [styles['list-variant-root--first']]: list.listVariant === 'root' && index === 0,
                 [styles['list-variant-root--collapsed']]: list.listVariant === 'root' && collapsed,
+                [styles['list--with-icons']]: withIcons,
               })}
             >
               {list.element}
@@ -620,12 +621,15 @@ function Section({
       variant="footer"
       expanded={expanded}
       onChange={onExpandedChange}
+      disableContentPaddings={true}
       className={clsx(
         styles.section,
         isInSectionGroup && styles['section--no-ident'],
+        withIcons && styles['section--expand-icon-end'],
         isVisualRefresh && styles.refresh
       )}
       headerText={<span className={styles['section-header']}>{definition.text}</span>}
+      __expandIconPosition={withIcons ? 'end' : 'start'}
     >
       <NavigationItemsList
         variant="section"
@@ -812,11 +816,15 @@ function ExpandableLinkGroup({
       className={clsx(
         styles['expandable-link-group'],
         variant === 'section-group' && styles['expandable-link-group--no-ident'],
+        withIcons && styles['expandable-link-group--expand-icon-end'],
         definition.href === activeHref && styles['expandable-link-group--active']
       )}
       variant="navigation"
       expanded={userExpanded ?? expanded}
       onChange={onExpandedChange}
+      disableContentPaddings={true}
+      __disableHeaderPaddings={true}
+      __expandIconPosition={withIcons ? 'end' : 'start'}
       headerText={
         <Link
           definition={{ type: 'link', href: definition.href, text: definition.text, icon: definition.icon }}
diff --git a/src/side-navigation/styles.scss b/src/side-navigation/styles.scss
index 423bccc5d7..508d1e92c4 100644
--- a/src/side-navigation/styles.scss
+++ b/src/side-navigation/styles.scss
@@ -19,7 +19,7 @@ $item-padding-inline: awsui.$space-xs;
 $item-indent: calc(awsui.$size-icon-normal + #{$item-icon-text-gap} - #{$item-padding-inline});
 $expandable-icon-negative-margin: awsui.$space-l;
 
-@mixin item-radius($radius: awsui.$border-radius-item) {
+@mixin item-radius($radius: awsui.$border-radius-side-navigation-item) {
   border-start-start-radius: $radius;
   border-start-end-radius: $radius;
   border-end-start-radius: $radius;
@@ -122,14 +122,27 @@ $expandable-icon-negative-margin: awsui.$space-l;
     padding-inline-start: 0;
     padding-inline-end: 0;
   }
+
+  &.list--with-icons:not(.list-variant-root--collapsed) {
+    padding-inline-start: calc(#{awsui.$space-panel-side-right} - #{$item-padding-inline});
+  }
 }
 
 .list-variant-expandable-link-group {
   padding-inline-start: calc(#{$item-indent} + #{$expandable-icon-negative-margin});
+
+  &.list--with-icons {
+    padding-inline-start: $item-indent;
+  }
 }
 
 .list-variant-section {
   padding-inline-start: calc(#{$expandable-icon-negative-margin} - #{$item-padding-inline});
+
+  &.list--with-icons {
+    padding-inline-start: 0;
+    margin-inline-start: calc(-1 * #{awsui.$space-xs});
+  }
 }
 
 .list-variant-link-group {
@@ -206,31 +219,16 @@ $expandable-icon-negative-margin: awsui.$space-l;
 .expandable-link-group {
   margin-inline-start: calc(-1 * #{$expandable-icon-negative-margin});
 
-  // HACK: Remove padding from section header and content to rely on margin collapsing rules.
-  // Hits the two direct <div> children of the ExpandableSection root: the header
-  // (.wrapper-footer / .header-footer) and the content (.content-footer).
-  /* stylelint-disable-next-line selector-max-type */
-  & > div {
-    padding-block: 0;
-    padding-inline: 0;
-  }
-
-  // Hits the header's first child only — the .icon-container inside the
-  // ExpandableSection header — to vertically align the icon with the text.
-  // Must NOT match the content div's first child (our <ul>); turning the <ul>
-  // into a grid container breaks sibling margin collapse on the .list-item children.
-  /* stylelint-disable-next-line selector-max-type */
-  & > div:first-child > :first-child {
-    display: grid;
-    align-items: flex-start;
-    padding-block: $item-padding-block;
+  &--no-ident {
+    margin-inline-start: 0;
   }
 
-  &--no-ident {
+  &--expand-icon-end {
     margin-inline-start: 0;
   }
 }
 
+// Targets the ExpandableSection header wrapper (first child div of the component root).
 .expandable-link-group > div:first-child {
   @include item-radius;
   display: flex;
@@ -239,6 +237,7 @@ $expandable-icon-negative-margin: awsui.$space-l;
   box-sizing: content-box;
 }
 
+// Targets the ExpandableSection header wrapper (first child div of the component root).
 .expandable-link-group--active > div:first-child {
   background-color: awsui.$color-background-side-navigation-item-active;
 }
@@ -264,7 +263,6 @@ $expandable-icon-negative-margin: awsui.$space-l;
 // Section groups
 // ==========================================================================
 .section-group {
-  @include styles.font-heading-m;
   margin-block: calc(#{awsui.$space-scaled-xs} - #{awsui.$border-divider-section-width});
   margin-inline: 0;
 
@@ -291,7 +289,7 @@ $expandable-icon-negative-margin: awsui.$space-l;
   padding-inline: $item-padding-inline;
   margin-inline: calc(-1 * #{$item-padding-inline});
   align-items: flex-start;
-  @include item-radius(awsui.$border-radius-side-navigation-item);
+  @include item-radius;
   font-weight: styles.$font-weight-normal;
   -webkit-font-smoothing: auto;
   -moz-osx-font-smoothing: auto;
@@ -385,3 +383,46 @@ $expandable-icon-negative-margin: awsui.$space-l;
     }
   }
 }
+
+// ==========================================================================
+// Icon-layout hover states
+// When icons are present, nav rows show a full-width hover background
+// connecting the item text/icon to the end-positioned caret.
+// ==========================================================================
+
+// Shared hover background for icon-layout rows (expanded with-icons AND collapsed rail).
+@mixin icon-layout-hover-background {
+  background-color: awsui.$color-background-side-navigation-item-icon-hover;
+}
+
+// --- Expanded icon layout (gated by .list--with-icons) ---
+.list--with-icons {
+  // Plain links: hover background.
+  > .list-item > .link:hover {
+    @include icon-layout-hover-background;
+  }
+
+  // Expandable-link-group header: hover background.
+  > .list-item > .expandable-link-group > div:first-child:hover {
+    @include icon-layout-hover-background;
+  }
+
+  // Section (footer-variant expandable) header: full-width hover geometry + background.
+  // :first-child targets the ExpandableSection header wrapper (positional cross-component coupling).
+  > .list-item > .section > :first-child {
+    @include item-radius;
+    display: flex;
+    padding-inline: $item-padding-inline;
+    margin-inline: calc(-1 * #{$item-padding-inline});
+    box-sizing: content-box;
+
+    &:hover {
+      @include icon-layout-hover-background;
+    }
+  }
+}
+
+// --- Collapsed rail items (always have icons; gated by collapsed classes) ---
+.link--collapsed:not(.link-active):hover {
+  @include icon-layout-hover-background;
+}
diff --git a/style-dictionary/one-theme/colors.ts b/style-dictionary/one-theme/colors.ts
index c56cb27c86..d05732ef82 100644
--- a/style-dictionary/one-theme/colors.ts
+++ b/style-dictionary/one-theme/colors.ts
@@ -192,6 +192,10 @@ const tokens: StyleDictionary.ColorsDictionary = {
   colorTextSideNavigationItemDefault: { light: '{colorTextBodyDefault}', dark: '{colorTextBodyDefault}' },
   colorBackgroundSideNavigationItemActive: { light: 'transparent', dark: 'transparent' },
   colorBackgroundSideNavigationItemActiveCollapsed: { light: '{colorPrimary500}', dark: '{colorPrimary500}' },
+  colorBackgroundSideNavigationItemIconHover: {
+    light: '{colorPrimary50}',
+    dark: '{colorBackgroundStatusIndicatorInfo}',
+  },
 
   // ── Dropzone ──────────────────────────────────────────────────────────────
   colorDropzoneBackgroundDefault: { light: '{colorWhite}', dark: '{colorNeutral850}' },
diff --git a/style-dictionary/one-theme/typography.ts b/style-dictionary/one-theme/typography.ts
index 3a07054e04..20fd6bb77f 100644
--- a/style-dictionary/one-theme/typography.ts
+++ b/style-dictionary/one-theme/typography.ts
@@ -31,9 +31,6 @@ const tokens: StyleDictionary.TypographyDictionary = {
   lineHeightHeadingXs: '20px',
   fontWeightHeadingXs: '500',
 
-  fontSideNavigationSectionHeaderSize: '14px',
-  fontSideNavigationSectionHeaderWeight: '500',
-
   fontWeightDisplayL: '500',
   fontWeightDisplayXl: '400',
 
diff --git a/style-dictionary/utils/token-names.ts b/style-dictionary/utils/token-names.ts
index c8c87850ea..a8f47b0c37 100644
--- a/style-dictionary/utils/token-names.ts
+++ b/style-dictionary/utils/token-names.ts
@@ -581,6 +581,7 @@ export type ColorsTokenName =
   | 'colorBackgroundItemSelected'
   | 'colorBackgroundSideNavigationItemActive'
   | 'colorBackgroundSideNavigationItemActiveCollapsed'
+  | 'colorBackgroundSideNavigationItemIconHover'
   | 'colorBackgroundLayoutMain'
   | 'colorBackgroundLayoutAiDrawer'
   | 'colorBackgroundDrawer'
diff --git a/style-dictionary/visual-refresh/colors.ts b/style-dictionary/visual-refresh/colors.ts
index 8e12282a2f..ab221457ce 100644
--- a/style-dictionary/visual-refresh/colors.ts
+++ b/style-dictionary/visual-refresh/colors.ts
@@ -64,6 +64,7 @@ const tokens: StyleDictionary.ColorsDictionary = {
   colorBackgroundItemSelected: { light: '{colorPrimary50}', dark: '{colorPrimary1000}' },
   colorBackgroundSideNavigationItemActive: 'transparent',
   colorBackgroundSideNavigationItemActiveCollapsed: '{colorBackgroundControlChecked}',
+  colorBackgroundSideNavigationItemIconHover: { light: '{colorPrimary50}', dark: '{colorNeutral700}' },
   colorBackgroundLayoutMain: { light: '{colorWhite}', dark: '{colorNeutral850}' },
   colorBackgroundLayoutAiDrawer: '{colorNeutral850}',
   colorBackgroundDrawer: '{colorBackgroundLayoutPanelContent}',

From 5246fb37c3a3e8e947fcd9da676e0b170cca2a18 Mon Sep 17 00:00:00 2001
From: Jessica Kuelz <15003460+jkuelz@users.noreply.github.com>
Date: Tue, 28 Jul 2026 20:03:37 -0700
Subject: [PATCH 3/5] test: Fix code coverage

---
 src/expandable-section/expandable-section-header.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/expandable-section/expandable-section-header.tsx b/src/expandable-section/expandable-section-header.tsx
index 85700248f7..c1b6508541 100644
--- a/src/expandable-section/expandable-section-header.tsx
+++ b/src/expandable-section/expandable-section-header.tsx
@@ -88,7 +88,7 @@ interface ExpandableDefaultHeaderProps {
   onClick: MouseEventHandler;
   icon: JSX.Element;
   variant: InternalVariant;
-  expandIconPosition?: 'start' | 'end';
+  expandIconPosition: 'start' | 'end';
 }
 
 interface ExpandableNavigationHeaderProps extends Omit<ExpandableDefaultHeaderProps, 'onKeyUp' | 'onKeyDown'> {
@@ -174,7 +174,7 @@ const ExpandableNavigationHeader = ({
   expanded,
   children,
   icon,
-  expandIconPosition = 'start',
+  expandIconPosition,
 }: ExpandableNavigationHeaderProps) => {
   const expandButton = (
     <ExpandIconButton
@@ -230,7 +230,7 @@ const ExpandableHeaderTextWrapper = ({
   headingTagOverride,
   onKeyUp,
   onKeyDown,
-  expandIconPosition = 'start',
+  expandIconPosition,
 }: ExpandableHeaderTextWrapperProps) => {
   const isContainer = variant === 'container';
   const HeadingTag = headingTagOverride || 'div';

From feadac4db2503554fb8e529e392ea3e168b44f11 Mon Sep 17 00:00:00 2001
From: Jessica Kuelz <15003460+jkuelz@users.noreply.github.com>
Date: Tue, 28 Jul 2026 22:02:17 -0700
Subject: [PATCH 4/5] fix: Collapsed active hover state

---
 src/side-navigation/styles.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/side-navigation/styles.scss b/src/side-navigation/styles.scss
index 508d1e92c4..247885e8d4 100644
--- a/src/side-navigation/styles.scss
+++ b/src/side-navigation/styles.scss
@@ -397,8 +397,8 @@ $expandable-icon-negative-margin: awsui.$space-l;
 
 // --- Expanded icon layout (gated by .list--with-icons) ---
 .list--with-icons {
-  // Plain links: hover background.
-  > .list-item > .link:hover {
+  // Plain links: hover background (exclude active collapsed links to preserve their active background).
+  > .list-item > .link:not(.link-active.link--collapsed):hover {
     @include icon-layout-hover-background;
   }
 

From 48e999674adf97b2f281f20433d646a6bec84662 Mon Sep 17 00:00:00 2001
From: Jessica Kuelz <15003460+jkuelz@users.noreply.github.com>
Date: Fri, 31 Jul 2026 03:59:29 -0700
Subject: [PATCH 5/5] chore: Address comments

---
 .../expandable-section/permutations.page.tsx  |  30 +-
 pages/expandable-section/test.page.tsx        |  24 ++
 .../__integ__/expandable-section.test.ts      | 140 +++++++++
 .../__tests__/expandable-section.test.tsx     | 274 ++++++++++--------
 .../expandable-section-header.tsx             |  53 ++--
 src/expandable-section/styles.scss            |   9 +
 src/side-navigation/styles.scss               |   5 +-
 7 files changed, 386 insertions(+), 149 deletions(-)

diff --git a/pages/expandable-section/permutations.page.tsx b/pages/expandable-section/permutations.page.tsx
index 7ffc5519f2..e2a50acf23 100644
--- a/pages/expandable-section/permutations.page.tsx
+++ b/pages/expandable-section/permutations.page.tsx
@@ -5,7 +5,10 @@ import React from 'react';
 import Button from '~components/button';
 import Container from '~components/container';
 import ExpandableSection, { ExpandableSectionProps } from '~components/expandable-section';
+import InternalExpandableSection from '~components/expandable-section/internal';
 import Header from '~components/header';
+import SpaceBetween from '~components/space-between';
+import StatusIndicator from '~components/status-indicator';
 import Table from '~components/table';
 
 import createPermutations from '../utils/permutations';
@@ -158,7 +161,24 @@ const permutations = createPermutations<ExpandableSectionProps>([
     children: ['Sample content'],
   },
 ]);
-/* eslint-enable react/jsx-key */
+
+const endIconPermutations = createPermutations<ExpandableSectionProps>([
+  {
+    variant: ['default', 'footer', 'navigation', 'container'],
+    headerText: [
+      'Short Header',
+      'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
+    ],
+    headerActions: [
+      undefined,
+      <SpaceBetween direction="horizontal" size="xs" alignItems="center">
+        <Button variant="inline-link">Action</Button>
+        <Button>Another action</Button>
+        <StatusIndicator>Information</StatusIndicator>
+      </SpaceBetween>,
+    ],
+  },
+]);
 
 export default function ExpandableSectionPermutations() {
   return (
@@ -166,6 +186,14 @@ export default function ExpandableSectionPermutations() {
       <h1>Expandable Section permutations</h1>
       <ScreenshotArea disableAnimations={true}>
         <PermutationsView permutations={permutations} render={permutation => <ExpandableSection {...permutation} />} />
+        <PermutationsView
+          permutations={endIconPermutations}
+          render={permutation => (
+            <InternalExpandableSection {...permutation} defaultExpanded={true} __expandIconPosition="end">
+              Variant {permutation.variant} section content
+            </InternalExpandableSection>
+          )}
+        />
       </ScreenshotArea>
     </>
   );
diff --git a/pages/expandable-section/test.page.tsx b/pages/expandable-section/test.page.tsx
index 4ad5b58040..fb7b90c481 100644
--- a/pages/expandable-section/test.page.tsx
+++ b/pages/expandable-section/test.page.tsx
@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import React from 'react';
 
+import Button from '~components/button';
 import ExpandableSection from '~components/expandable-section';
+import InternalExpandableSection from '~components/expandable-section/internal';
 
 export default function ExpandableSectionTestPage() {
   return (
@@ -15,6 +17,28 @@ export default function ExpandableSectionTestPage() {
         After you enable your S3 bucket for static website hosting, web browsers can access your content through the
         Amazon S3 website endpoint for the bucket.
       </ExpandableSection>
+
+      <div data-testid="end-position-single-row">
+        <InternalExpandableSection
+          variant="default"
+          headerText="End position section"
+          __expandIconPosition="end"
+          headerActions={<Button>Action</Button>}
+        >
+          Content of the end-position expandable section used for keyboard toggle and focus tests.
+        </InternalExpandableSection>
+      </div>
+
+      <div data-testid="end-position-wrapping-header">
+        <InternalExpandableSection
+          variant="default"
+          headerText="This is a long wrapping header text that is intentionally verbose and extended to ensure it wraps to multiple lines when rendered in the test viewport used by integration tests"
+          __expandIconPosition="end"
+          headerActions={<Button>Action</Button>}
+        >
+          Content of the wrapping-header end-position expandable section used for the below-caret click test.
+        </InternalExpandableSection>
+      </div>
     </article>
   );
 }
diff --git a/src/expandable-section/__integ__/expandable-section.test.ts b/src/expandable-section/__integ__/expandable-section.test.ts
index 6ea2b608b5..057a3c4ac6 100644
--- a/src/expandable-section/__integ__/expandable-section.test.ts
+++ b/src/expandable-section/__integ__/expandable-section.test.ts
@@ -5,6 +5,8 @@ import useBrowser from '@cloudscape-design/browser-test-tools/use-browser';
 
 import createWrapper from '../../../lib/components/test-utils/selectors';
 
+import styles from '../../../lib/components/expandable-section/styles.selectors.js';
+
 const focusTargetSelector = '#focus-target';
 
 const expandableSectionWrapper = createWrapper().findExpandableSection();
@@ -37,3 +39,141 @@ describe('Expandable Section', () => {
     })
   );
 });
+
+// --- End-position integration tests ---
+// These sections use headerActions to trigger the OUTSIDE caret button path
+// (renderIconOutsideHeader = iconAtEnd && (isContainer || !!actions)).
+// The outside <button> with .icon-container-end is the element exercised by the #9 fixes:
+// stopPropagation on keydown/keyup, focus ring, and align-self:stretch clickable area.
+
+const endSingleRowWrapper = createWrapper().find('[data-testid="end-position-single-row"]').findExpandableSection();
+const endWrappingWrapper = createWrapper().find('[data-testid="end-position-wrapping-header"]').findExpandableSection();
+
+// The outside caret button: a native <button> with class .icon-container-end, rendered separately
+// from the headerButton when actions are present. This is the element that receives the #9 fixes.
+const endCaretButtonSelector = endSingleRowWrapper
+  .findHeader()
+  .find(`button.${styles['icon-container-end']}`)
+  .toSelector();
+const wrappingCaretButtonSelector = endWrappingWrapper
+  .findHeader()
+  .find(`button.${styles['icon-container-end']}`)
+  .toSelector();
+
+class EndPositionPage extends BasePageObject {
+  hasOutline(selector: string) {
+    return this.browser.execute(selector => {
+      const element = document.querySelector(selector);
+      return !!element && getComputedStyle(element).outline.includes('2px');
+    }, selector);
+  }
+
+  async clickAtPosition(x: number, y: number) {
+    await this.browser.performActions([
+      {
+        type: 'pointer',
+        id: 'mouse',
+        parameters: { pointerType: 'mouse' },
+        actions: [
+          { type: 'pointerMove', duration: 0, x, y },
+          { type: 'pointerDown', button: 0 },
+          { type: 'pointerUp', button: 0 },
+        ],
+      },
+    ]);
+  }
+}
+
+const setupEndPositionTest = (testFn: (page: EndPositionPage) => Promise<void>) => {
+  return useBrowser(async browser => {
+    const page = new EndPositionPage(browser);
+    await browser.url('#/light/expandable-section/test');
+    await page.waitForVisible(endSingleRowWrapper.toSelector());
+    await testFn(page);
+  });
+};
+
+describe('Expandable Section - end icon position', () => {
+  test(
+    'Enter toggles an end-position section exactly once',
+    setupEndPositionTest(async page => {
+      await page.click(focusTargetSelector);
+
+      // Tab order from #focus-target:
+      // 1. First section headerButton ("Static website hosting")
+      // 2. End-position section headerButton (text-only, since caret is outside)
+      // 3. Action <Button> inside headerActions
+      // 4. Outside caret <button> (ExpandIconButton)
+      await page.keys(['Tab', 'Tab', 'Tab', 'Tab']);
+      await expect(page.isFocused(endCaretButtonSelector)).resolves.toBe(true);
+
+      // Press Enter — should expand (single toggle, not open+close due to stopPropagation fix)
+      await page.keys(['Enter']);
+      await expect(page.isExisting(endSingleRowWrapper.findExpandedContent().toSelector())).resolves.toBe(true);
+
+      // Press Enter again — should collapse
+      await page.keys(['Enter']);
+      await expect(page.isExisting(endSingleRowWrapper.findExpandedContent().toSelector())).resolves.toBe(false);
+    })
+  );
+
+  test(
+    'Space toggles an end-position section exactly once',
+    setupEndPositionTest(async page => {
+      await page.click(focusTargetSelector);
+
+      // Tab to the outside caret button (4 stops from #focus-target)
+      await page.keys(['Tab', 'Tab', 'Tab', 'Tab']);
+      await expect(page.isFocused(endCaretButtonSelector)).resolves.toBe(true);
+
+      // Press Space — should expand (single toggle, not open+close due to stopPropagation fix)
+      await page.keys(['Space']);
+      await expect(page.isExisting(endSingleRowWrapper.findExpandedContent().toSelector())).resolves.toBe(true);
+
+      // Press Space again — should collapse
+      await page.keys(['Space']);
+      await expect(page.isExisting(endSingleRowWrapper.findExpandedContent().toSelector())).resolves.toBe(false);
+    })
+  );
+
+  test(
+    'end-position caret button shows a focus ring when focused',
+    setupEndPositionTest(async page => {
+      await page.click(focusTargetSelector);
+
+      // Tab to the outside caret button
+      await page.keys(['Tab', 'Tab', 'Tab', 'Tab']);
+      await expect(page.isFocused(endCaretButtonSelector)).resolves.toBe(true);
+
+      // Verify focus ring (2px outline) is visible on the caret button
+      // This exercises the @include focus-highlight(2px) rule on .icon-container-end
+      await expect(page.hasOutline(endCaretButtonSelector)).resolves.toBe(true);
+    })
+  );
+
+  test(
+    'clicking below the caret on a wrapped end-position header toggles the section',
+    setupEndPositionTest(async page => {
+      // WHY HEADER-RELATIVE: Computing the click from the caret button's own bbox is vacuous —
+      // the point always lands inside the button regardless of align-self:stretch. Instead we
+      // derive y from the HEADER's full height (the tall wrapped row) and x from the caret's
+      // horizontal center. With align-self:stretch the caret button fills the header height,
+      // so (caret-x, header-bottom) is INSIDE the button → toggles. Without stretch, the
+      // caret button is only glyph-tall at the top and restrictClickableArea (actions present)
+      // makes the header wrapper dead space → no toggle. This genuinely exercises the fix.
+      const headerSelector = endWrappingWrapper.findHeader().toSelector();
+      const caretBox = await page.getBoundingBox(wrappingCaretButtonSelector);
+      const headerBox = await page.getBoundingBox(headerSelector);
+
+      // x = horizontal center of the caret button (at the header's inline-end)
+      const x = Math.round(caretBox.left + caretBox.width / 2);
+      // y = near the bottom of the tall wrapped header, well below the small caret glyph
+      const y = Math.round(headerBox.top + headerBox.height - 5);
+
+      await page.clickAtPosition(x, y);
+
+      // Should expand — the stretched caret button covers this point
+      await expect(page.isExisting(endWrappingWrapper.findExpandedContent().toSelector())).resolves.toBe(true);
+    })
+  );
+});
diff --git a/src/expandable-section/__tests__/expandable-section.test.tsx b/src/expandable-section/__tests__/expandable-section.test.tsx
index 0ec354aa33..751611d859 100644
--- a/src/expandable-section/__tests__/expandable-section.test.tsx
+++ b/src/expandable-section/__tests__/expandable-section.test.tsx
@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import React from 'react';
-import { render } from '@testing-library/react';
+import { fireEvent, render } from '@testing-library/react';
 
 import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
 
@@ -262,18 +262,20 @@ describe('Expandable Section', () => {
         });
       }
     });
-    test('aria-expanded=false when collapsed', () => {
-      const wrapper = renderExpandableSection();
-      const header = wrapper.findHeader().getElement();
-      expect(header).toHaveAttribute('aria-expanded', 'false');
-    });
-    test('aria-expanded=true when expanded', () => {
-      const wrapper = renderExpandableSection({
-        defaultExpanded: true,
-      });
-      const header = wrapper.findHeader().getElement();
-      expect(header).toHaveAttribute('aria-expanded', 'true');
-    });
+    test.each<ExpandableSectionProps.Variant>(['default', 'footer', 'navigation', 'container', 'stacked', 'inline'])(
+      '%s variant has aria-expanded=false when collapsed',
+      variant => {
+        const wrapper = renderExpandableSection({ variant, headerText: 'Header' });
+        expect(wrapper.findExpandButton().getElement()).toHaveAttribute('aria-expanded', 'false');
+      }
+    );
+    test.each<ExpandableSectionProps.Variant>(['default', 'footer', 'navigation', 'container', 'stacked', 'inline'])(
+      '%s variant has aria-expanded=true when expanded',
+      variant => {
+        const wrapper = renderExpandableSection({ variant, headerText: 'Header', defaultExpanded: true });
+        expect(wrapper.findExpandButton().getElement()).toHaveAttribute('aria-expanded', 'true');
+      }
+    );
 
     test('can assign a different label to the header', () => {
       const wrapper = renderExpandableSection({
@@ -455,23 +457,6 @@ describe('headerText', () => {
         const contentId = expandedContent?.getAttribute('id');
         expect(headerButton).toHaveAttribute('aria-controls', contentId);
       });
-      test('aria-expanded=false when collapsed', () => {
-        const wrapper = renderExpandableSection({
-          variant,
-          headerText: 'Header component',
-        });
-        const headerButton = wrapper.findHeader().find('[role="button"]')!.getElement();
-        expect(headerButton).toHaveAttribute('aria-expanded', 'false');
-      });
-      test('aria-expanded=true when expanded', () => {
-        const wrapper = renderExpandableSection({
-          variant,
-          headerText: 'Header component',
-          defaultExpanded: true,
-        });
-        const headerButton = wrapper.findHeader().find('[role="button"]')!.getElement();
-        expect(headerButton).toHaveAttribute('aria-expanded', 'true');
-      });
       test('set headerAriaLabel assigns an aria-label to the header, and no aria-labelledby will be set', () => {
         const wrapper = renderExpandableSection({
           variant,
@@ -522,17 +507,8 @@ describe('__expandIconPosition', () => {
   }
 
   describe('default behavior (start position)', () => {
-    test('icon renders before header text for default variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'default' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      const children = Array.from(expandButton.children);
-      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
-      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
-      expect(iconIndex).toBeLessThan(textIndex);
-    });
-
-    test('icon renders before header text for footer variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer' });
+    test.each(['default', 'footer'] as const)('icon renders before header text for %s variant', variant => {
+      const wrapper = renderInternalExpandableSection({ variant });
       const expandButton = wrapper.findExpandButton().getElement();
       const children = Array.from(expandButton.children);
       const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
@@ -548,26 +524,11 @@ describe('__expandIconPosition', () => {
       // Icon should be the first child (index 0)
       expect(iconIndex).toBe(0);
     });
-
-    test('does not apply icon-end modifier classes when position is start', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'start' });
-      const icon = wrapper.findExpandIcon().getElement();
-      expect(icon.classList.contains(styles['icon-container-end'])).toBe(false);
-    });
   });
 
   describe('end position', () => {
-    test('icon renders after header text for footer variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      const children = Array.from(expandButton.children);
-      const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
-      const textIndex = children.findIndex(el => el.classList.contains(styles['header-text']));
-      expect(iconIndex).toBeGreaterThan(textIndex);
-    });
-
-    test('icon renders after header text for default variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'default', __expandIconPosition: 'end' });
+    test.each(['footer', 'default'] as const)('icon renders after header text for %s variant', variant => {
+      const wrapper = renderInternalExpandableSection({ variant, __expandIconPosition: 'end' });
       const expandButton = wrapper.findExpandButton().getElement();
       const children = Array.from(expandButton.children);
       const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
@@ -578,35 +539,24 @@ describe('__expandIconPosition', () => {
     test('icon renders after header content for navigation variant', () => {
       const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
       const header = wrapper.findHeader().getElement();
+      // Header wrapper should have the icon-end modifier
+      expect(header.classList.contains(styles['header-icon-end'])).toBe(true);
+      // Icon should be the last child
       const children = Array.from(header.children);
       const iconIndex = children.findIndex(el => el.classList.contains(styles['icon-container']));
-      // Icon should be the last child
       expect(iconIndex).toBe(children.length - 1);
     });
 
-    test('icon renders after header text for container variant', () => {
+    test('container variant positions caret outside header wrapper (as separate sibling element)', () => {
       const wrapper = renderInternalExpandableSection({ variant: 'container', __expandIconPosition: 'end' });
-      // For container variant, icon is rendered outside InternalHeader
       const icon = wrapper.findExpandIcon().getElement();
-      expect(icon.classList.contains(styles['icon-container-end'])).toBe(true);
-    });
-
-    test('applies icon-container-end modifier class for footer variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
-      const icon = wrapper.findExpandIcon().getElement();
-      expect(icon.classList.contains(styles['icon-container-end'])).toBe(true);
-    });
-
-    test('applies header-icon-end modifier class for navigation variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
-      const header = wrapper.findHeader().getElement();
-      expect(header.classList.contains(styles['header-icon-end'])).toBe(true);
-    });
-
-    test('applies header-button-icon-end modifier class for footer variant', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
       const expandButton = wrapper.findExpandButton().getElement();
-      expect(expandButton.classList.contains(styles['header-button-icon-end'])).toBe(true);
+      // Icon should NOT be a descendant of the expand-button wrapper
+      expect(expandButton.contains(icon)).toBe(false);
+      // Icon is a sibling of the internal header content, both inside the same header row
+      const headerRow = wrapper.findHeader().getElement();
+      expect(headerRow.contains(icon)).toBe(true);
+      expect(headerRow.contains(expandButton)).toBe(true);
     });
 
     test('icon renders outside header actions for default variant with headerActions', () => {
@@ -628,37 +578,16 @@ describe('__expandIconPosition', () => {
   });
 
   describe('expand/collapse functionality with end position', () => {
-    test('navigation variant toggles aria-expanded on click', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'navigation', __expandIconPosition: 'end' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
-      wrapper.findExpandButton().click();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
-    });
-
-    test('footer variant toggles aria-expanded on click', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'footer', __expandIconPosition: 'end' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
-      wrapper.findExpandButton().click();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
-    });
-
-    test('default variant toggles aria-expanded on click', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'default', __expandIconPosition: 'end' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
-      wrapper.findExpandButton().click();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
-    });
-
-    test('container variant toggles aria-expanded on click', () => {
-      const wrapper = renderInternalExpandableSection({ variant: 'container', __expandIconPosition: 'end' });
-      const expandButton = wrapper.findExpandButton().getElement();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'false');
-      wrapper.findExpandButton().click();
-      expect(expandButton).toHaveAttribute('aria-expanded', 'true');
-    });
+    test.each(['navigation', 'footer', 'default', 'container'] as const)(
+      '%s variant toggles aria-expanded on click',
+      variant => {
+        const wrapper = renderInternalExpandableSection({ variant, __expandIconPosition: 'end' });
+        const expandButton = wrapper.findExpandButton().getElement();
+        expect(expandButton).toHaveAttribute('aria-expanded', 'false');
+        wrapper.findExpandButton().click();
+        expect(expandButton).toHaveAttribute('aria-expanded', 'true');
+      }
+    );
 
     test('content is shown when expanded with end position', () => {
       const wrapper = renderInternalExpandableSection({
@@ -692,29 +621,27 @@ describe('__expandIconPosition', () => {
   });
 
   describe('outside icon button (end position with renderIconOutsideHeader)', () => {
-    test('container variant renders outside caret as a button with aria-expanded', () => {
+    test('container variant caret is a native button element so it is keyboard-focusable without role hacks', () => {
       const wrapper = renderInternalExpandableSection({
         variant: 'container',
         __expandIconPosition: 'end',
         headerText: 'Header',
       });
-      const iconButton = wrapper.findExpandIcon().getElement();
-      expect(iconButton.tagName).toBe('BUTTON');
-      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
-      expect(iconButton).toHaveAttribute('aria-controls');
+      const caret = wrapper.findExpandIcon().getElement();
+      // Native <button> is automatically keyboard-focusable and announced as "button" by AT
+      expect(caret.tagName).toBe('BUTTON');
     });
 
-    test('default variant with headerActions renders outside caret as a button with aria-expanded', () => {
+    test('default variant with actions renders caret as a native button for independent keyboard access', () => {
       const wrapper = renderInternalExpandableSection({
         variant: 'default',
         __expandIconPosition: 'end',
         headerText: 'Header',
         headerActions: <button>Action</button>,
       });
-      const iconButton = wrapper.findExpandIcon().getElement();
-      expect(iconButton.tagName).toBe('BUTTON');
-      expect(iconButton).toHaveAttribute('aria-expanded', 'false');
-      expect(iconButton).toHaveAttribute('aria-controls');
+      const caret = wrapper.findExpandIcon().getElement();
+      // Native <button> is automatically keyboard-focusable and announced as "button" by AT
+      expect(caret.tagName).toBe('BUTTON');
     });
 
     test('clicking the outside caret button toggles expansion for container variant', () => {
@@ -778,7 +705,7 @@ describe('__expandIconPosition', () => {
       expect(iconButton.getAttribute('aria-controls')).toBe(contentRegion.getAttribute('id'));
     });
 
-    test('keyboard Enter on outside caret button toggles expansion', () => {
+    test('keyboard Enter on outside caret button toggles exactly once (no double-toggle)', () => {
       const onChange = jest.fn();
       const { container } = render(
         <InternalExpandableSection
@@ -792,9 +719,110 @@ describe('__expandIconPosition', () => {
       );
       const wrapper = createWrapper(container).findExpandableSection()!;
       const iconButton = wrapper.findExpandIcon().getElement();
-      // Native button handles Enter/Space natively, triggering click
-      iconButton.click();
+
+      // Simulate keyboard Enter: keyDown → keyUp → browser-synthesized click
+      // keyCode is required because the wrapper's onKeyUp handler checks event.keyCode
+      fireEvent.keyDown(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.keyUp(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.click(iconButton);
+
+      // Should toggle exactly once (expanded = true)
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ detail: { expanded: true } }));
+    });
+
+    test('keyboard Space on outside caret button toggles exactly once (no double-toggle)', () => {
+      const onChange = jest.fn();
+      const { container } = render(
+        <InternalExpandableSection
+          variant="container"
+          __expandIconPosition="end"
+          headerText="Header"
+          onChange={onChange}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const iconButton = wrapper.findExpandIcon().getElement();
+
+      // Simulate keyboard Space: keyDown → keyUp → browser-synthesized click
+      // keyCode is required because the wrapper's onKeyUp handler checks event.keyCode
+      fireEvent.keyDown(iconButton, { key: ' ', keyCode: 32 });
+      fireEvent.keyUp(iconButton, { key: ' ', keyCode: 32 });
+      fireEvent.click(iconButton);
+
+      // Should toggle exactly once (expanded = true)
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ detail: { expanded: true } }));
+    });
+
+    test('keyboard toggle then toggle again results in closed state', () => {
+      const onChange = jest.fn();
+      const { container } = render(
+        <InternalExpandableSection
+          variant="container"
+          __expandIconPosition="end"
+          headerText="Header"
+          onChange={onChange}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const iconButton = wrapper.findExpandIcon().getElement();
+
+      // First toggle: expand
+      fireEvent.keyDown(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.keyUp(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.click(iconButton);
       expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ detail: { expanded: true } }));
+
+      // Second toggle: collapse
+      fireEvent.keyDown(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.keyUp(iconButton, { key: 'Enter', keyCode: 13 });
+      fireEvent.click(iconButton);
+      expect(onChange).toHaveBeenCalledTimes(2);
+      expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ detail: { expanded: false } }));
+    });
+  });
+
+  describe('tab order for link-group with expand icon position', () => {
+    test('start position: caret button precedes link in tab order', () => {
+      const { container } = render(
+        <InternalExpandableSection
+          variant="navigation"
+          __expandIconPosition="start"
+          headerText={<a href="/link">Link</a>}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const header = wrapper.findHeader().getElement();
+      const focusableElements = Array.from(header.querySelectorAll('button, a[href], [role="button"][tabindex="0"]'));
+      const tags = focusableElements.map(el => el.tagName);
+      // Start position: caret (BUTTON) first, then the link (A)
+      expect(tags).toEqual(['BUTTON', 'A']);
+    });
+
+    test('end position: link precedes caret button in tab order', () => {
+      const { container } = render(
+        <InternalExpandableSection
+          variant="navigation"
+          __expandIconPosition="end"
+          headerText={<a href="/link">Link</a>}
+        >
+          Content
+        </InternalExpandableSection>
+      );
+      const wrapper = createWrapper(container).findExpandableSection()!;
+      const header = wrapper.findHeader().getElement();
+      const focusableElements = Array.from(header.querySelectorAll('button, a[href], [role="button"][tabindex="0"]'));
+      const tags = focusableElements.map(el => el.tagName);
+      // End position: link (A) first, then the caret (BUTTON)
+      expect(tags).toEqual(['A', 'BUTTON']);
     });
   });
 });
diff --git a/src/expandable-section/expandable-section-header.tsx b/src/expandable-section/expandable-section-header.tsx
index c1b6508541..c14266309c 100644
--- a/src/expandable-section/expandable-section-header.tsx
+++ b/src/expandable-section/expandable-section-header.tsx
@@ -53,27 +53,38 @@ const ExpandIconButton = ({
   onClick,
   stopPropagation,
   className,
-}: ExpandIconButtonProps) => (
-  <button
-    className={clsx(styles['icon-container'], styles['expand-button'], className)}
-    type="button"
-    aria-label={ariaLabel}
-    aria-labelledby={ariaLabelledBy}
-    aria-controls={ariaControls}
-    aria-expanded={expanded}
-    onClick={
-      stopPropagation
-        ? event => {
-            event.stopPropagation();
-            onClick(event);
-          }
-        : onClick
-    }
-    {...getExpandActionAnalyticsMetadataAttribute(expanded)}
-  >
-    {icon}
-  </button>
-);
+}: ExpandIconButtonProps) => {
+  const stopKeyPropagation = stopPropagation
+    ? (event: React.KeyboardEvent) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.stopPropagation();
+        }
+      }
+    : undefined;
+  return (
+    <button
+      className={clsx(styles['icon-container'], styles['expand-button'], className)}
+      type="button"
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-controls={ariaControls}
+      aria-expanded={expanded}
+      onClick={
+        stopPropagation
+          ? event => {
+              event.stopPropagation();
+              onClick(event);
+            }
+          : onClick
+      }
+      onKeyUp={stopKeyPropagation}
+      onKeyDown={stopKeyPropagation}
+      {...getExpandActionAnalyticsMetadataAttribute(expanded)}
+    >
+      {icon}
+    </button>
+  );
+};
 
 interface ExpandableDefaultHeaderProps {
   id: string;
diff --git a/src/expandable-section/styles.scss b/src/expandable-section/styles.scss
index 48e3e90964..9ea3c929eb 100644
--- a/src/expandable-section/styles.scss
+++ b/src/expandable-section/styles.scss
@@ -378,6 +378,11 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
   margin-inline-end: 0;
   flex-shrink: 0;
 
+  // Stretch the button to fill the parent's block-size so the entire caret
+  // column is clickable/hoverable, matching start-position behavior.
+  align-self: stretch;
+  align-items: flex-start;
+
   // Reset native <button> chrome for the outside caret in end-icon-position.
   // The navigation variant already has its own reset via .header-navigation > .icon-container
   // so this is harmless-but-redundant for that path, and necessary for default/container.
@@ -390,6 +395,10 @@ $icon-total-space-medium: calc(#{$icon-width-medium} + #{$icon-margin-left} + #{
   font: inherit;
   color: inherit;
 
+  @include focus-visible.when-visible {
+    @include styles.focus-highlight(2px);
+  }
+
   // Align the navigation end-layout caret to the first line of header text.
   // The header link has padding-block equal to (item-height - line-height) / 2
   // (set by side-navigation). Mirror that on the caret so it sits at the same
diff --git a/src/side-navigation/styles.scss b/src/side-navigation/styles.scss
index 247885e8d4..eaf11cf8d7 100644
--- a/src/side-navigation/styles.scss
+++ b/src/side-navigation/styles.scss
@@ -219,10 +219,7 @@ $expandable-icon-negative-margin: awsui.$space-l;
 .expandable-link-group {
   margin-inline-start: calc(-1 * #{$expandable-icon-negative-margin});
 
-  &--no-ident {
-    margin-inline-start: 0;
-  }
-
+  &--no-ident,
   &--expand-icon-end {
     margin-inline-start: 0;
   }