@redocly/theme 0.69.0-next.1 → 0.69.0-next.11

package/src/core/styles/global.ts

@@ -20,7 +20,7 @@ import { checkbox } from '@redocly/theme/icons/CheckboxIcon/variables';
 import { admonition } from '@redocly/theme/components/Admonition/variables';
 import { footer } from '@redocly/theme/components/Footer/variables';
 import { button } from '@redocly/theme/components/Button/variables';
-import { aiAssistantButton, connectMCPButton } from '@redocly/theme/components/Buttons/variables';
+import { aiAssistantButton } from '@redocly/theme/components/Buttons/variables';
 import { navbar } from '@redocly/theme/components/Navbar/variables';
 import { search } from '@redocly/theme/components/Search/variables';
 import { menu, mobileMenu } from '@redocly/theme/components/Menu/variables';
@@ -454,18 +454,24 @@ const borders = css`
 
   --border-color-primary: var(--color-warm-grey-3); // Raised dividers
   --border-color-secondary: var(--color-warm-grey-2); // Default dividers, borders
-  --border-color-invers: var(--color-warm-grey-10);
+  --border-color-inverse: var(--color-warm-grey-10);
+  --border-color-invers: var(--border-color-inverse, var(--color-warm-grey-10)); // Deprecated: use --border-color-inverse
 
   /**
      * @tokens Border Radius
      * @presenter BorderRadius
      */
 
+  --border-radius-none: 0;
   --border-radius: 4px;
   --border-radius-md: calc(var(--border-radius) * 1.5);
   --border-radius-lg: calc(var(--border-radius) * 2);
   --border-radius-xl: calc(var(--border-radius) * 3);
   --border-radius-xxl: calc(var(--border-radius) * 4);
+  --border-radius-xxxl: calc(var(--border-radius) * 6);
+  --border-radius-full: 999px;
+
+  // @tokens End
 `;
 
 const headingsTypography = css`
@@ -824,7 +830,7 @@ const badges = css`
 
   --badge-text-color: var(--text-color-inverse); // @presenter Color
   --badge-bg-color: var(--color-purple-6); // @presenter Color
-  --badge-border-radius: var(--border-radius); // @presenter BorderRadius
+  --badge-border-radius: var(--border-radius-md); // @presenter BorderRadius
 
   /**
     * @tokens Deprecated Badge
@@ -832,7 +838,7 @@ const badges = css`
 
   --badge-deprecated-text-color: var(--color-warm-grey-1); // @presenter Color
   --badge-deprecated-bg-color: var(--color-warning-base); // @presenter Color
-  --badge-deprecated-border-radius: var(--border-radius); // @presenter BorderRadius
+  --badge-deprecated-border-radius: var(--border-radius-md); // @presenter BorderRadius
 
    /**
     * @tokens Webhook Badge
@@ -840,7 +846,7 @@ const badges = css`
 
   --badge-webhook-text-color: var(--color-warm-grey-1); // @presenter Color
   --badge-webhook-bg-color: var(--color-purple-7); // @presenter Color
-  --badge-webhook-border-radius: var(--border-radius); // @presenter BorderRadius
+  --badge-webhook-border-radius: var(--border-radius-md); // @presenter BorderRadius
 
   /**
     * @tokens Audience Badge
@@ -1048,11 +1054,6 @@ const pages = css`
   --page-mcp-405-margin-vertical-mobile: var(--spacing-xxl);
   --page-mcp-405-margin-horizontal-mobile: 1rem;
 
-  --page-mcp-405-status-text-color: var(--text-color-helper);
-  --page-mcp-405-status-font-size: var(--font-size-lg); // @presenter FontSize
-  --page-mcp-405-status-line-height: var(--line-height-lg); // @presenter LineHeight
-  --page-mcp-405-status-font-weight: var(--font-weight-semibold); // @presenter FontWeight
-
   --page-mcp-405-title-text-color: var(--text-color-primary);
   --page-mcp-405-title-font-size: 42px; // @presenter FontSize
   --page-mcp-405-title-font-weight: var(--font-weight-bold); // @presenter FontWeight
@@ -1067,6 +1068,11 @@ const pages = css`
   --page-mcp-405-description-font-size-mobile: var(--font-size-lg);
   --page-mcp-405-description-line-height-mobile: var(--line-height-lg);
 
+  --page-mcp-405-snippets-font-size: var(--font-size-base); // @presenter FontSize
+  --page-mcp-405-snippets-line-height: var(--line-height-base); // @presenter LineHeight
+  --page-mcp-405-snippets-hint-text-color: var(--text-color-secondary);
+  --page-mcp-405-snippets-code-padding-right: var(--spacing-xxl);
+
    // @tokens End
 
   /**
@@ -1264,7 +1270,7 @@ const tree = css`
 
     *::-webkit-scrollbar-thumb {
         background-color: var(--color-warm-grey-2);
-        border-radius: var(--border-radius);
+        border-radius: var(--border-radius-full);
     }
 
     *::-webkit-scrollbar-thumb:hover {
@@ -1332,7 +1338,6 @@ export const styles = css<{ palette?: string }>`
     ${breadcrumbs}
     ${button}
     ${aiAssistantButton}
-    ${connectMCPButton}
     ${cards}
     ${catalog}
     ${catalogClassic}

package/src/core/styles/palette.ts

@@ -244,4 +244,6 @@ function brandPaletteLight(palette: string | undefined): RuleSet<object> {
  */
 export const activeBrandPaletteLight = css<{ palette?: string }>`
   ${({ palette }) => brandPaletteLight(palette)}
+
+  // @tokens End
 `;

package/src/core/types/button-group.ts

@@ -0,0 +1,2 @@
+export type ButtonGroupVariant = 'primary' | 'secondary' | 'outlined';
+export type ButtonGroupSize = 'small' | 'medium' | 'large';

package/src/core/types/catalog.ts

@@ -212,10 +212,8 @@ export type BffCatalogEntityList = BffCatalogList<BffCatalogEntity>;
 export type BffCatalogRelatedEntityList = BffCatalogList<BffCatalogRelatedEntity>;
 
 export type Page = {
-  endCursor: string | null;
-  startCursor: string | null;
-  hasNextPage: boolean;
-  hasPrevPage: boolean;
+  nextPage: string | null;
+  previousPage: string | null;
   limit: number;
   total: number;
 };

package/src/core/types/common.ts

@@ -1,5 +1,8 @@
+import type React from 'react';
 import { DEFAULT_COLOR_MODES } from '../constants';
 
 export type Plural<T extends string> = `${T}s`;
 
 export type ColorMode = (typeof DEFAULT_COLOR_MODES)[keyof typeof DEFAULT_COLOR_MODES];
+
+export type RenderableChildren<Context> = React.ReactNode | ((context: Context) => React.ReactNode);

package/src/core/types/hooks.ts

@@ -143,6 +143,7 @@ export type ThemeHooks = {
     docs: {
       enabled: boolean;
       name?: string;
+      publicEndpoint?: boolean;
     };
   };
   useSidebarItems: (activeVersion?: Version | null) => {

package/src/core/types/index.ts

@@ -22,3 +22,4 @@ export type * from './segmented';
 export type * from './tooltip';
 export type * from './toast';
 export type * from './link';
+export type * from './button-group';

package/src/core/types/l10n.ts

@@ -134,8 +134,28 @@ export type TranslationKey =
   | 'page.forbidden.description'
   | 'page.notFound.title'
   | 'page.notFound.description'
+  | 'page.apiNotFound.title'
+  | 'page.apiNotFound.description'
+  | 'page.apiNotFound.hint'
+  | 'page.apiNotFound.backButton'
   | 'page.mcpNotAllowed.title'
   | 'page.mcpNotAllowed.description'
+  | 'page.mcpNotAllowed.publicNote'
+  | 'page.mcpNotAllowed.publicEndpointHint'
+  | 'page.mcpNotAllowed.mainEndpointHint'
+  | 'page.mcpNotAllowed.snippets.terminal.hint'
+  | 'page.mcpNotAllowed.snippets.claudeCode.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.instruction'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.headline'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.instruction'
+  | 'page.mcpNotAllowed.snippets.codexCli.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.hint'
+  | 'page.mcpNotAllowed.snippets.json.hint'
+  | 'page.mcpNotAllowed.tabs.claude'
+  | 'page.mcpNotAllowed.tabs.chatgpt'
+  | 'page.mcpNotAllowed.tabs.json'
   | 'page.lastUpdated.timeago'
   | 'page.lastUpdated.on'
   | 'catalog.filters.placeholder'
@@ -271,8 +291,14 @@ export type TranslationKey =
   | 'page.actions.connectMcp.cursorDescription'
   | 'page.actions.connectMcp.vscode'
   | 'page.actions.connectMcp.vscodeDescription'
+  | 'page.actions.connectMcp.claudeCode'
+  | 'page.actions.connectMcp.claudeCodeDescription'
+  | 'page.actions.connectMcp.codex'
+  | 'page.actions.connectMcp.codexDescription'
   | 'page.actions.connectMcp.copyConfig'
   | 'page.actions.connectMcp.copyConfigDescription'
+  | 'page.actions.connectMcp.moreOptions'
+  | 'page.actions.moreActions'
   | 'openapi.download.description.title'
   | 'openapi.info.title'
   | 'openapi.info.contact.url'
@@ -280,6 +306,7 @@ export type TranslationKey =
   | 'openapi.info.license'
   | 'openapi.info.termsOfService'
   | 'openapi.info.metadata.title'
+  | 'graphql.info.metadata.title'
   | 'openapi.key'
   | 'openapi.value'
   | 'openapi.enum'
@@ -369,6 +396,8 @@ export type TranslationKey =
   | 'openapi.mcp.inputExample'
   | 'openapi.mcp.outputSchema'
   | 'openapi.mcp.outputExample'
+  | 'openapi.mcp.exampleTitle'
+  | 'openapi.mcp.argumentsExample'
   | 'asyncapi.download.description.title'
   | 'asyncapi.info.title'
   | 'asyncapi.info.contact.url'
@@ -449,7 +478,6 @@ export type TranslationKey =
   | 'graphql.sample'
   | 'graphql.referenced'
   | 'graphql.content.fragment'
-  | 'button.copy.tooltipText'
   | 'button.download.tooltipText'
   | 'button.externalLink.tooltipText'
   | 'button.email.tooltipText'

package/src/core/types/mcp.ts

@@ -1,6 +1,6 @@
 export type MCPClientType = 'cursor' | 'vscode';
 
-export type MCPOption = 'cursor' | 'vscode' | 'copy';
+export type MCPOption = 'cursor' | 'vscode' | 'claude-code' | 'codex' | 'copy';
 
 export type McpConnectionParams = {
   serverName: string;

package/src/core/utils/RenderWithLink.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+
+import type { JSX } from 'react';
+
+// Splits a translated sentence on <link>...</link> markers and renders the
+// marked phrase as an anchor, so each locale keeps its own word order.
+export function renderWithLink(text: string, href: string): JSX.Element {
+  const [before, label, after] = text.split(/<link>|<\/link>/);
+  if (label === undefined) {
+    return <>{text}</>;
+  }
+  return (
+    <>
+      {before}
+      <a href={href}>{label}</a>
+      {after}
+    </>
+  );
+}

package/src/core/utils/index.ts

@@ -48,3 +48,4 @@ export * from './get-auto-dismiss-duration';
 export * from './tooltip-placement';
 export * from './telemetry/get-base-data-attributes';
 export * from './telemetry/generate-before-after-context';
+export * from './RenderWithLink';

package/src/core/utils/mcp.ts

@@ -32,3 +32,42 @@ export function generateMCPDeepLink(
       return generateCursorMCPDeepLink(config);
   }
 }
+
+// Server names can contain spaces (e.g. "Docs MCP server") which break bare CLI
+// arguments, so commands use a slugified form while JSON configs keep the raw name.
+export function slugifyMcpServerName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Claude Desktop's config file only launches stdio commands, so remote servers
+// connect through the mcp-remote bridge.
+export function generateClaudeDesktopConfig(config: McpConnectionParams): string {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [slugifyMcpServerName(config.serverName)]: {
+          command: 'npx',
+          args: ['-y', 'mcp-remote', config.url],
+        },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+export function generateClaudeCodeCommand(config: McpConnectionParams): string {
+  return `claude mcp add --transport http ${slugifyMcpServerName(config.serverName)} ${config.url}`;
+}
+
+export function generateCodexCommand(config: McpConnectionParams): string {
+  return `codex mcp add ${slugifyMcpServerName(config.serverName)} --url ${config.url}`;
+}
+
+// Pasted into an AI assistant (Claude Code, Codex) so it installs the server itself.
+export function generateMcpInstallPrompt(config: McpConnectionParams): string {
+  return `Add the MCP server "${slugifyMcpServerName(config.serverName)}" with URL ${config.url} (streamable HTTP transport) to my MCP configuration, then verify it is connected.`;
+}

package/src/icons/CodexIcon/CodexIcon.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" {...props}>
+    <path d="M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.073zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.8956zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997z" />
+  </svg>
+);
+
+export const CodexIcon = styled(Icon).attrs({
+  'data-component-name': 'icons/CodexIcon/CodexIcon',
+})`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/icons/LinkIcon/LinkIcon.tsx

@@ -15,7 +15,7 @@ const Icon = (props: IconProps) => (
     {...props}
   >
     <path
-      d="M0 4C0 1.79086 1.79086 0 4 0H16C18.2091 0 20 1.79086 20 4V16C20 18.2091 18.2091 20 16 20H4C1.79086 20 0 18.2091 0 16V4Z"
+      d="M0 6C0 2.68629 2.68629 0 6 0H14C17.3137 0 20 2.68629 20 6V14C20 17.3137 17.3137 20 14 20H6C2.68629 20 0 17.3137 0 14V6Z"
       fill="var(--layer-color)"
     />
     <path

package/src/index.ts

@@ -15,6 +15,8 @@ export * from '@redocly/theme/components/Badge/Badge';
 export * from '@redocly/theme/components/Dropdown/Dropdown';
 export * from '@redocly/theme/components/Dropdown/DropdownMenu';
 export * from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+export * from '@redocly/theme/components/Dropdown/DropdownMenuItemContent';
+export * from '@redocly/theme/components/SplitButton/SplitButton';
 export * from '@redocly/theme/components/Loaders/Loading';
 export * from '@redocly/theme/components/LoadMore/LoadMore';
 export * from '@redocly/theme/components/Link/Link';

package/src/layouts/McpNotAllowed.tsx

@@ -3,28 +3,61 @@ import styled from 'styled-components';
 
 import type { JSX } from 'react';
 
-import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { useThemeHooks, useMCPConfig } from '@redocly/theme/core/hooks';
+import { renderWithLink } from '@redocly/theme/core/utils';
 import { ConnectMCPButton } from '@redocly/theme/components/Buttons/ConnectMCPButton';
+import { McpConnectionTabs } from '@redocly/theme/components/MCP/McpConnectionTabs';
 
 export default function McpNotAllowed(): JSX.Element {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
+  const { isPublicEndpointPage, alternateServerUrl } = useMCPConfig();
 
   return (
     <NotAllowedWrapper data-component-name="layouts/McpNotAllowed">
-      <StatusText>405</StatusText>
       <Title data-translation-key="page.mcpNotAllowed.title">
-        {translate('page.mcpNotAllowed.title', 'Method not allowed')}
+        {translate('page.mcpNotAllowed.title', 'Connect to the MCP server')}
       </Title>
       <Description data-translation-key="page.mcpNotAllowed.description">
         {translate(
           'page.mcpNotAllowed.description',
-          'To use this MCP server, register it in your MCP Client (for example: VS Code, Cursor, or Claude Code).',
+          'To use this MCP server, register it in your MCP client (for example: VS Code, Cursor, or Claude Code).',
         )}
       </Description>
+      {isPublicEndpointPage && (
+        <Description data-translation-key="page.mcpNotAllowed.publicNote">
+          {translate(
+            'page.mcpNotAllowed.publicNote',
+            'This endpoint serves publicly available content only and requires no login.',
+          )}
+        </Description>
+      )}
+      {isPublicEndpointPage && alternateServerUrl && (
+        <Description data-translation-key="page.mcpNotAllowed.mainEndpointHint">
+          {renderWithLink(
+            translate(
+              'page.mcpNotAllowed.mainEndpointHint',
+              'To access content available to your account, use the <link>main MCP endpoint</link>.',
+            ),
+            alternateServerUrl,
+          )}
+        </Description>
+      )}
+      {!isPublicEndpointPage && alternateServerUrl && (
+        <Description data-translation-key="page.mcpNotAllowed.publicEndpointHint">
+          {renderWithLink(
+            translate(
+              'page.mcpNotAllowed.publicEndpointHint',
+              'To connect anonymously without an account, use the <link>public endpoint</link>.',
+            ),
+            alternateServerUrl,
+          )}
+        </Description>
+      )}
       <ButtonWrapper>
         <ConnectMCPButton alignment="start" />
       </ButtonWrapper>
+      <McpConnectionTabs />
     </NotAllowedWrapper>
   );
 }
@@ -44,13 +77,6 @@ const NotAllowedWrapper = styled.div`
   }
 `;
 
-const StatusText = styled.div`
-  color: var(--page-mcp-405-status-text-color);
-  font-size: var(--page-mcp-405-status-font-size);
-  line-height: var(--page-mcp-405-status-line-height);
-  font-weight: var(--page-mcp-405-status-font-weight);
-`;
-
 const Title = styled.div`
   font-size: var(--page-mcp-405-title-font-size);
   line-height: var(--page-mcp-405-title-line-height);

package/src/markdoc/components/Accordion/Accordion.tsx

@@ -1,10 +1,11 @@
-import React from 'react';
+import React, { useContext } from 'react';
 import styled, { keyframes } from 'styled-components';
 
 import type { JSX, PropsWithChildren } from 'react';
 
 import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
 import { ACCORDION_COMPONENT_NAME } from '@redocly/theme/core/constants';
+import { AccordionGroupContext } from '@redocly/theme/core/contexts';
 
 export type AccordionProps = {
   title: string;
@@ -22,10 +23,13 @@ export function Accordion({
   'data-source': dataSource,
   'data-hash': dataHash,
 }: PropsWithChildren<AccordionProps>): JSX.Element {
+  const groupName = useContext(AccordionGroupContext);
+
   return (
     <AccordionWrapper
       className={className}
       open={expanded}
+      name={groupName ?? undefined}
       data-component-name={ACCORDION_COMPONENT_NAME}
       data-source={dataSource}
       data-hash={dataHash}
@@ -37,7 +41,9 @@ export function Accordion({
         />
         {title}
       </AccordionSummary>
-      <AccordionBody>{children}</AccordionBody>
+      <AccordionBody>
+        <AccordionGroupContext.Provider value={null}>{children}</AccordionGroupContext.Provider>
+      </AccordionBody>
     </AccordionWrapper>
   );
 }

package/src/markdoc/components/Accordion/AccordionGroup.tsx

@@ -1,24 +1,31 @@
-import React from 'react';
+import React, { useId } from 'react';
 import styled from 'styled-components';
 
 import type { JSX, PropsWithChildren } from 'react';
 
 import { ACCORDION_GROUP_COMPONENT_NAME, ACCORDION_SELECTOR } from '@redocly/theme/core/constants';
+import { AccordionGroupContext } from '@redocly/theme/core/contexts';
 
 export type AccordionGroupProps = {
+  singleExpanded?: boolean;
   className?: string;
 };
 
 export function AccordionGroup({
+  singleExpanded = false,
   className,
   children,
 }: PropsWithChildren<AccordionGroupProps>): JSX.Element {
+  const groupName = useId();
+
   return (
     <AccordionGroupWrapper
       className={className}
       data-component-name={ACCORDION_GROUP_COMPONENT_NAME}
     >
-      {children}
+      <AccordionGroupContext.Provider value={singleExpanded ? groupName : null}>
+        {children}
+      </AccordionGroupContext.Provider>
     </AccordionGroupWrapper>
   );
 }

package/src/markdoc/components/Cards/Card.tsx

@@ -2,8 +2,10 @@ import React from 'react';
 import styled from 'styled-components';
 
 import { ChevronRightIcon } from '@redocly/theme/icons/ChevronRightIcon/ChevronRightIcon';
+import { ArrowUpRightIcon } from '@redocly/theme/icons/ArrowUpRightIcon/ArrowUpRightIcon';
 import { CardImage } from '@redocly/theme/markdoc/components/Cards/CardImage';
 import { CardIcon, CardIconWrapper } from '@redocly/theme/markdoc/components/Cards/CardIcon';
+import { CardBadge } from '@redocly/theme/markdoc/components/Cards/CardBadge';
 import { Link } from '@redocly/theme/components/Link/Link';
 
 export type CardProps = React.PropsWithChildren<{
@@ -17,8 +19,15 @@ export type CardProps = React.PropsWithChildren<{
   layout?: 'horizontal' | 'vertical' | 'combined';
   variant?: 'filled' | 'outlined' | 'elevated' | 'ghost';
   iconVariant?: 'filled' | 'ghost';
+  iconColor?: string;
   align?: 'start' | 'center' | 'end';
   to?: string;
+  linkIcon?: 'chevron' | 'arrow';
+  cta?: React.ReactNode;
+  badge?: string;
+  badgeColor?: string;
+  badgeIcon?: string;
+  badgeIconRawContent?: string;
 }>;
 
 export function Card({
@@ -32,8 +41,15 @@ export function Card({
   variant = 'filled',
   lineClamp,
   iconVariant = 'filled',
+  iconColor,
   align = 'start',
   to,
+  cta,
+  linkIcon,
+  badge,
+  badgeColor,
+  badgeIcon,
+  badgeIconRawContent,
   children,
 }: CardProps) {
   const titleNoSpaces = title?.replace(/\s+/g, '-').toLowerCase();
@@ -66,14 +82,30 @@ export function Card({
               src={icon}
               rawContent={iconRawContent}
               position={iconPosition}
+              color={iconColor}
             />
           )}
           <ContentWrapper>
-            <Title id={cardTitleId} $isCardLink={!!to} $justifyContent={justifyContent}>
-              {title}
-              {variant == 'ghost' && !!to && <CardLinkIcon />}
-            </Title>
+            <TitleWrapper id={cardTitleId} $isCardLink={!!to} $justifyContent={justifyContent}>
+              <Title>
+                {title}
+                {!!to && !!linkIcon && (
+                  <CardLinkIcon as={linkIcon === 'arrow' ? ArrowUpRightIcon : undefined} />
+                )}
+              </Title>
+              {!!badge && (
+                <CardBadge color={badgeColor} icon={badgeIcon} iconRawContent={badgeIconRawContent}>
+                  {badge}
+                </CardBadge>
+              )}
+            </TitleWrapper>
             <Body $lineClamp={lineClamp}>{children}</Body>
+            {!!to && !!cta && (
+              <Cta $justifyContent={justifyContent}>
+                <CtaText> {cta} </CtaText>
+                <CtaIcon />
+              </Cta>
+            )}
           </ContentWrapper>
         </CardContentWrapper>
       </>
@@ -105,25 +137,28 @@ const ContentWrapper = styled.div`
   width: 100%;
 `;
 
-const Title = styled.h3<{ $isCardLink: boolean; $justifyContent: string }>`
-  margin: var(--card-title-margin);
-  font-weight: var(--card-title-font-weight);
+const TitleWrapper = styled.div<{ $isCardLink: boolean; $justifyContent: string }>`
   color: var(--card-title-text-color);
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
+  row-gap: var(--card-title-row-gap);
   justify-content: ${({ $justifyContent }) => $justifyContent};
   width: 100%;
 `;
 
+const Title = styled.h3`
+  margin: var(--card-title-margin);
+  font-weight: var(--card-title-font-weight);
+`;
+
+// The `as` prop selects the icon; the chevron is the default target.
 const CardLinkIcon = styled(ChevronRightIcon)`
   width: var(--card-link-icon-width);
   height: var(--card-link-icon-height);
-  color: var(--card-link-icon-color);
+  color: var(--icon-color-secondary);
   margin-left: var(--spacing-xxs);
-  opacity: 0;
-  transition:
-    opacity 0.3s,
-    transform 0.3s;
+  margin-top: calc(var(--spacing-xxs) / 2);
 `;
 
 const Body = styled.div<{ $lineClamp?: number }>`
@@ -149,6 +184,29 @@ const Body = styled.div<{ $lineClamp?: number }>`
   }
 `;
 
+const Cta = styled.div<{ $justifyContent: string }>`
+  display: flex;
+  gap: var(--card-cta-gap);
+  align-items: center;
+  margin-top: var(--card-cta-margin-top);
+  color: var(--card-cta-text-color);
+  font-size: var(--card-cta-font-size);
+  justify-content: ${({ $justifyContent }) => $justifyContent};
+    
+  && > * {
+    cursor: pointer;
+  }  
+`;
+
+const CtaText = styled.span`
+  font-weight: var(--card-cta-font-weight);
+`;
+
+const CtaIcon = styled(ChevronRightIcon)`
+  width: var(--card-cta-icon-width);
+  height: var(--card-cta-icon-height);
+`;
+
 const CardWrapper = styled.div.attrs<{
   $variant: string;
   $isCardLink: boolean;
@@ -185,6 +243,13 @@ const CardWrapper = styled.div.attrs<{
       height: 100%;
       object-fit: cover;
     `}
+  } 
+    
+  &:hover,
+  &:focus-within {
+    ${Cta} {
+      color: var(--card-link-icon-color);
+    }
   }
 
   &.card-link {
@@ -203,8 +268,8 @@ const CardWrapper = styled.div.attrs<{
         background-color: var(--card-icon-bg-color-hover);
       }
 
-      svg {
-        opacity: 1;
+      ${CardLinkIcon} {
+        color: var(--card-link-icon-color);
       }
     }
   }