Tabs redesign (#3274)

* remove index files

* change tab styles

* add glider and scroll indicators

* add small padding to tabs

* update tests

* fix scroll indicator color

* fix scroll indicator color

* Mark component as stable

* add mobile screenshots

* add internal components to storybook

* add description for the stretched prop

* update documentation

* lint

* fix stretched tabs overflow styles

* update styles on resize

* fix tablist border width

* replace scrollIntoView with scrollLeft

* default initialSelectedIndex to 0 if given value is invalid

* make glider animation a progressive enhancement

* improve initialisation of selected id

* improve glider styles

Author: sirineJ

.changeset/hip-phones-sleep.md

@@ -0,0 +1,5 @@
+---
+"@sumup-oss/circuit-ui": minor
+---
+
+Updated the styles of the Tabs component to align with the updated design system guidelines.

packages/circuit-ui/components/Tabs/Tabs.mdx

@@ -1,30 +1,73 @@
-import { Meta, Status, Props, Story } from '../../../../.storybook/components';
+import { Meta, Status, Props, Story } from "../../../../.storybook/components";
 
-import * as Stories from './Tabs.stories';
+import * as Stories from "./Tabs.stories";
 
 <Meta of={Stories} />
 
 # Tabs
 
-<Status variant="under-review">
-  Does not handle content overflow on mobile. Unclear use case compared to
-  subnavigation.
-</Status>
+<Status variant="stable" />
+
+The Tabs component allows users to navigate between different views or sections of content within the same context.
 
 <Story of={Stories.Base} />
 
 <Props />
 
-## Variations
+## When to use it
+
+### Group related content
+
+Tabs help optimize space by organizing large amounts of content into easily scannable sections, reducing cognitive load for users. They provide simple navigation between related sections that don’t require side-by-side comparison.
+
+Examples include:
+
+- Switching between subsets of the same data: Active Orders | Completed Orders | Cancelled Orders
+
+- Breaking a long process into steps: Personal Info | Delivery Details | Payment Details | Review
+
+### Navigation
+
+Use tabs to navigate between a set of related pages within a larger website or application. For example, in a user profile section:
+
+Overview | Posts | Comments | Settings
 
-If you need more control on the tabs, you can build you own tabs list instead of passing an array of items to the `Tabs` component. This can be useful to style any of the components individually.
+## How to use it
+
+### Use the Tabs component directly
+
+You can use the Tabs component out of the box to create a tabbed view by providing an array of tab items. Each tab should include:
+
+- a unique id
+- a clear, concise label
+- the content to display when the tab is active
+
+### Use subcomponents independently
+
+If you need finer control over your layout, you can use the `Tab`, `TabList`, and `TabPanel` components independently. This gives you flexibility to customize the structure and behavior of your tabs while still relying on the core functionality provided by Tabs.
+
+⚠️ When doing so, you are responsible for ensuring accessibility and managing state correctly.
+
+- Using Tab:
+  - Provide a unique `id` for each tab.
+  - Add an `aria-controls` attribute that points to the id of its corresponding panel.
+  - Implement keyboard navigation (e.g., arrow keys, Home/End) to support keyboard users.
+- Using TabPanel:
+  - Assign a unique id to each panel.
+  - Ensure this id matches the `aria-controls` value of its corresponding tab.
+  - Set `aria-labelledby` to reference the id of the associated tab.
 
 <Story of={Stories.ControlledState} />
 
-## With links
+### With links
+
+Tabs render as buttons by default. In navigation contexts, you can pass a `href` prop to render them as links.
+Avoid using external links, as this can create an inconsistent user experience across tabs.
 
 <Story of={Stories.Links} />
 
-## When to use it
+### Stretched
+
+Set the `stretched` prop to true to make all tabs expand and share the available space evenly.
 
-## Usage guidelines
+<Story of={Stories.Stretched} />

packages/circuit-ui/components/Tabs/Tabs.spec.tsx

@@ -13,16 +13,19 @@
  * limitations under the License.
  */
 
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
 
 import { axe, render, screen, userEvent } from '../../util/test-utils.js';
 
-import { TabPanel } from './components/TabPanel/index.js';
-import { TabList } from './components/TabList/index.js';
-import { Tab } from './components/Tab/index.js';
+import { TabPanel } from './components/TabPanel/TabPanel.js';
+import { TabList } from './components/TabList/TabList.js';
+import { Tab } from './components/Tab/Tab.js';
 import { Tabs } from './Tabs.js';
 
 describe('Tabs', () => {
+  beforeAll(() => {
+    HTMLElement.prototype.scrollIntoView = vi.fn();
+  });
   it('should switch panels on tab click', async () => {
     render(
       <Tabs

packages/circuit-ui/components/Tabs/Tabs.stories.tsx

@@ -19,10 +19,13 @@ import { ArrowLeft, ExternalLink } from '@sumup-oss/icons';
 import { Body } from '../Body/index.js';
 import { Headline } from '../Headline/index.js';
 import { Button } from '../Button/index.js';
+import { modes } from '../../../../.storybook/modes.js';
 
 import type { TabsProps } from './Tabs.js';
-
-import { Tabs, TabList, TabPanel, Tab } from './index.js';
+import { Tabs } from './Tabs.js';
+import { TabList } from './components/TabList/TabList.js';
+import { TabPanel } from './components/TabPanel/TabPanel.js';
+import { Tab } from './components/Tab/Tab.js';
 
 export default {
   title: 'Navigation/Tabs',
@@ -31,6 +34,12 @@ export default {
   tags: ['status:under-review'],
   parameters: {
     layout: 'fullscreen',
+    chromatic: {
+      modes: {
+        mobile: modes.smallMobile,
+        desktop: modes.desktop,
+      },
+    },
   },
 };
 
@@ -85,6 +94,16 @@ const tabs = [
     tab: 'Tab 4',
     panel: <ContentWithInteractiveElements index={4} />,
   },
+  {
+    id: 'five',
+    tab: 'Tab 5',
+    panel: <ContentWithInteractiveElements index={5} />,
+  },
+  {
+    id: 'six',
+    tab: 'Tab 6',
+    panel: <ContentWithInteractiveElements index={6} />,
+  },
 ];
 
 export const Base = (args: TabsProps) => <Tabs {...args} />;
@@ -94,18 +113,20 @@ Base.args = {
   stretched: false,
 };
 
+export const Stretched = (args: TabsProps) => <Tabs {...args} />;
+
+Stretched.args = {
+  items: tabs,
+  stretched: true,
+};
+
 export const Links = () => (
   <TabList>
     <Tab selected>Home</Tab>
-    <Tab href="https://github.com/sumup-oss/circuit-ui" target="_blank">
-      GitHub
-    </Tab>
-    <Tab
-      href="https://www.npmjs.com/package/@sumup-oss/circuit-ui"
-      target="_blank"
-    >
-      NPM
+    <Tab href="#posts" target="">
+      Posts
     </Tab>
+    <Tab href="#reviews">Reviews</Tab>
   </TabList>
 );
 

packages/circuit-ui/components/Tabs/Tabs.tsx

@@ -23,9 +23,9 @@ import {
   isArrowDown,
 } from '../../util/key-codes.js';
 
-import { TabList, type TabListProps } from './components/TabList/index.js';
-import { Tab } from './components/Tab/index.js';
-import { TabPanel } from './components/TabPanel/index.js';
+import { TabList, type TabListProps } from './components/TabList/TabList.js';
+import { Tab } from './components/Tab/Tab.js';
+import { TabPanel } from './components/TabPanel/TabPanel.js';
 
 export interface TabsProps extends TabListProps {
   /**
@@ -45,7 +45,9 @@ export interface TabsProps extends TabListProps {
 }
 
 export function Tabs({ items, initialSelectedIndex = 0, ...props }: TabsProps) {
-  const [selectedId, setSelectedId] = useState(items[initialSelectedIndex]?.id);
+  const [selectedId, setSelectedId] = useState(
+    items[initialSelectedIndex]?.id ?? items[0]?.id,
+  );
 
   const handleTabKeyDown = (event: KeyboardEvent) => {
     const selectedIndex = items.findIndex((item) => item.id === selectedId);

packages/circuit-ui/components/Tabs/components/Tab/Tab.module.css

@@ -1,24 +1,29 @@
 .base {
+  --selected-tab-pseudo-content: "";
+
   float: left;
   display: flex;
   flex-direction: column;
   align-items: center;
   justify-content: center;
-  height: 100%;
-  padding: var(--cui-spacings-kilo) var(--cui-spacings-tera);
-  font-size: var(--cui-body-m-font-size);
-  line-height: var(--cui-body-m-line-height);
+  padding: 0 var(--cui-spacings-bit);
+  margin: var(--cui-spacings-kilo) 0;
+  font-size: var(--cui-body-s-font-size);
+  font-weight: var(--cui-font-weight-semibold);
+  line-height: var(--cui-body-s-line-height);
   color: var(--cui-fg-subtle);
   white-space: nowrap;
   text-decoration: none;
   cursor: pointer;
   outline: none;
   background-color: var(--cui-bg-normal);
   border: none;
+  border-radius: var(--cui-border-radius-bit);
+  transition: color var(--cui-transitions-default);
 }
 
 .base:hover {
-  background-color: var(--cui-bg-normal-hovered);
+  color: var(--cui-fg-normal-hovered);
 }
 
 .base:focus {
@@ -35,7 +40,7 @@
 }
 
 .base:active {
-  background-color: var(--cui-bg-normal-pressed);
+  color: var(--cui-fg-normal);
 }
 
 .base[aria-selected="true"] {
@@ -47,11 +52,15 @@
 .base[aria-selected="true"]::after {
   position: absolute;
   right: 0;
-  bottom: 0;
+  bottom: calc(
+    -1 * calc(var(--cui-spacings-kilo) - var(--cui-border-width-kilo))
+  );
   left: 0;
   z-index: var(--cui-z-index-absolute);
-  width: 100%;
-  height: var(--cui-spacings-bit);
-  content: " ";
-  background: var(--cui-border-accent);
+  height: 3px;
+  content: var(--selected-tab-pseudo-content);
+  background-color: var(--cui-border-accent);
+  border-top-left-radius: var(--cui-border-radius-byte);
+  border-top-right-radius: var(--cui-border-radius-byte);
+  transition: all var(--cui-transitions-default);
 }

packages/circuit-ui/components/Tabs/components/Tab/index.ts renamed to packages/circuit-ui/components/Tabs/components/Tab/Tab.stories.tsx

@@ -1,5 +1,5 @@
 /**
- * Copyright 2019, SumUp Ltd.
+ * Copyright 2025, SumUp Ltd.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -13,6 +13,23 @@
  * limitations under the License.
  */
 
-export { Tab } from './Tab.js';
+import { Tab } from './Tab.js';
 
-export type { TabProps } from './Tab.js';
+export default {
+  title: 'Navigation/Tabs/Tab',
+  component: Tab,
+  tags: ['status:internal'],
+  parameters: {
+    chromatic: {
+      disableSnapshot: true,
+    },
+  },
+};
+
+export const Base = () => (
+  <div>
+    <Tab>Button</Tab>
+    <Tab href="#link">Link</Tab>
+    <Tab selected>Selected</Tab>
+  </div>
+);

packages/circuit-ui/components/Tabs/components/Tab/Tab.tsx

@@ -27,17 +27,16 @@ import { clsx } from '../../../../styles/clsx.js';
 
 import classes from './Tab.module.css';
 
-interface BaseProps {
-  /**
-   * Triggers selected styles of the component
-   */
-  selected?: boolean;
-}
-
 type LinkElProps = AnchorHTMLAttributes<HTMLAnchorElement>;
 type ButtonElProps = ButtonHTMLAttributes<HTMLButtonElement>;
 
-export type TabProps = BaseProps & LinkElProps & ButtonElProps;
+export type TabProps = LinkElProps &
+  ButtonElProps & {
+    /**
+     * Triggers selected styles of the component
+     */
+    selected?: boolean;
+  };
 
 const tabIndex = (selected: boolean) => (selected ? undefined : -1);