@hubspot/cms-component-library 0.3.9 → 0.3.11

package/components/componentLibrary/Button/index.module.scss

@@ -29,10 +29,10 @@
   }
 
   &:focus-visible {
-    background-color: var(--hs-button-backgroundColor-focus, var(--hs-button-backgroundColor));
-    color: var(--hs-button-color-focus, var(--hs-button-color));
-    border: var(--hs-button-border-focus, var(--hs-button-border));
-    outline: 2px solid;
+    background-color: var(--hs-button-backgroundColor-hover, var(--hs-button-backgroundColor));
+    color: var(--hs-button-color-hover, var(--hs-button-color));
+    border: var(--hs-button-border-hover, var(--hs-button-border));
+    outline: 2px solid Highlight;
     outline-offset: 2px;
   }
 

package/components/componentLibrary/Button/index.tsx

@@ -22,7 +22,7 @@ const ButtonComponent = ({
   const sharedProps = {
     className: defaultClasses,
     style: style,
-    'data-buttons-variant': variant,
+    'data-button-variant': variant,
   };
 
   const RenderWithIcon = ({

package/components/componentLibrary/Card/StyleFields.tsx

@@ -4,7 +4,7 @@ import { StyleFieldsProps } from './types.js';
 const StyleFields = ({
   cardVariantLabel = 'Card variant',
   cardVariantName = 'cardVariant',
-  cardVariantDefault = { variantName: 'cardStyle1' },
+  cardVariantDefault = { variant_name: 'card1' },
 }: StyleFieldsProps) => {
   return (
     <VariantSelectionField

package/components/componentLibrary/Card/index.tsx

@@ -4,7 +4,7 @@ import { CardProps } from './types.js';
 import StyleFields from './StyleFields.js';
 
 const CardComponent = ({
-  variant = 'cardStyle1',
+  variant = 'card1',
   as: Component = 'div',
   className = '',
   style = {},

package/components/componentLibrary/Card/llm.txt

@@ -34,7 +34,7 @@ Card/
 **Props:**
 ```tsx
 {
-  variant?: 'cardStyle1' | 'cardStyle2' | 'cardStyle3' | 'cardStyle4';  // Theme variant (default: 'cardStyle1')
+  variant?: 'card1' | 'card2' | 'card3' | 'card4';  // Theme variant (default: 'card1')
   as?: 'div' | 'article' | 'section';             // HTML element to render (default: 'div')
   children?: React.ReactNode;                     // Card content
   className?: string;                             // Additional CSS classes
@@ -58,7 +58,7 @@ import Card from '@hubspot/cms-component-library/Card';
 ### Semantic Article Card
 
 ```tsx
-<Card as="article" variant="cardStyle3">
+<Card as="article" variant="card3">
   <h3>Blog Post Title</h3>
   <p>Article content goes here...</p>
 </Card>
@@ -97,7 +97,7 @@ Configurable props for customizing field labels, names, and defaults:
 <Card.StyleFields
   cardVariantLabel="Card variant"
   cardVariantName="cardVariant"
-  cardVariantDefault={{ variant_name: 'cardStyle1' }}
+  cardVariantDefault={{ variant_name: 'card1' }}
 />
 ```
 

package/components/componentLibrary/Card/stories/Card.stories.tsx

@@ -43,7 +43,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    variant: 'cardStyle1',
+    variant: 'card1',
   },
   render: args => (
     <Card {...args}>
@@ -60,7 +60,7 @@ export const Variants: Story = {
     <SBContainer flex direction="column" gap="large">
       <SBContainer addBackground>
         <h4>Card Style 1 (Light)</h4>
-        <Card variant="cardStyle1">
+        <Card variant="card1">
           <CardHeading>Card Style 1</CardHeading>
           <CardDivider />
           <CardContent>Light background with dark text.</CardContent>
@@ -69,7 +69,7 @@ export const Variants: Story = {
 
       <SBContainer addBackground>
         <h4>Card Style 2 (Subtle)</h4>
-        <Card variant="cardStyle2">
+        <Card variant="card2">
           <CardHeading>Card Style 2</CardHeading>
           <CardDivider />
           <CardContent>Subtle background with dark text.</CardContent>
@@ -78,7 +78,7 @@ export const Variants: Story = {
 
       <SBContainer addBackground>
         <h4>Card Style 3 (Dark)</h4>
-        <Card variant="cardStyle3">
+        <Card variant="card3">
           <CardHeading>Card Style 3</CardHeading>
           <CardDivider />
           <CardContent>Dark background with light text.</CardContent>
@@ -87,7 +87,7 @@ export const Variants: Story = {
 
       <SBContainer addBackground>
         <h4>Card Style 4 (Darker)</h4>
-        <Card variant="cardStyle4">
+        <Card variant="card4">
           <CardHeading>Card Style 4</CardHeading>
           <CardDivider />
           <CardContent>Darker background with light text.</CardContent>

package/components/componentLibrary/Card/stories/CardDecorator.module.scss

@@ -1,27 +1,27 @@
 .cardContainer {
   /* card Variant Styles */
-  :global([data-card-variant='cardStyle1']) {
+  :global([data-card-variant='card1']) {
     --hs-card-borderRadius: 10px;
     --hs-card-backgroundColor: rgb(255, 255, 255);
     --hs-card-color: rgb(28, 28, 31);
     --hs-card-border: 1px solid #e0e0e0;
   }
 
-  :global([data-card-variant='cardStyle2']) {
+  :global([data-card-variant='card2']) {
     --hs-card-borderRadius: 10px;
     --hs-card-backgroundColor: rgb(249, 249, 249);
     --hs-card-color: rgb(28, 28, 31);
     --hs-card-border: 1px solid #e0e0e0;
   }
 
-  :global([data-card-variant='cardStyle3']) {
+  :global([data-card-variant='card3']) {
     --hs-card-borderRadius: 10px;
     --hs-card-backgroundColor: rgb(28, 28, 31);
     --hs-card-color: rgb(255,255,255);
     --hs-card-border: 1px solid #e0e0e0;
   }
 
-  :global([data-card-variant='cardStyle4']) {
+  :global([data-card-variant='card4']) {
     --hs-card-borderRadius: 10px;
     --hs-card-backgroundColor: rgb(36, 36, 36);
     --hs-card-color: rgb(255,255,255);

package/components/componentLibrary/Card/types.ts

@@ -1,8 +1,8 @@
 export type CardVariant =
-  | 'cardStyle1'
-  | 'cardStyle2'
-  | 'cardStyle3'
-  | 'cardStyle4';
+  | 'card1'
+  | 'card2'
+  | 'card3'
+  | 'card4';
 
 export type CardAs = 'div' | 'article' | 'section';
 

package/components/componentLibrary/Form/StyleFields.tsx

@@ -4,7 +4,7 @@ import { StyleFieldsProps } from './types.js';
 const StyleFields = ({
   formVariantLabel = 'Form variant',
   formVariantName = 'formVariant',
-  formVariantDefault = { variant_name: 'primaryForm' },
+  formVariantDefault = { variant_name: 'form1' },
 }: StyleFieldsProps) => {
   return (
     <VariantSelectionField

package/components/componentLibrary/Form/llm.txt

@@ -123,7 +123,7 @@ Configurable props for variant selection:
 <Form.StyleFields
   formVariantLabel="Form variant"
   formVariantName="formVariant"
-  formVariantDefault={{ variant_name: 'primaryForm' }}
+  formVariantDefault={{ variant_name: 'form1' }}
 />
 ```
 
@@ -135,7 +135,7 @@ Configurable props for variant selection:
 {
   formVariantLabel?: string;                     // Label shown in the editor (default: "Form variant")
   formVariantName?: string;                      // Field name (default: "formVariant")
-  formVariantDefault?: { variant_name: string }; // Default variant (default: { variant_name: 'primaryForm' })
+  formVariantDefault?: { variant_name: string }; // Default variant (default: { variant_name: 'form1' })
 }
 ```
 

package/components/componentLibrary/Link/StyleFields.tsx

@@ -1,25 +1,18 @@
-import { ChoiceField } from '@hubspot/cms-components/fields';
+import { VariantSelectionField } from '@hubspot/cms-components/fields';
 import { StyleFieldsProps } from './types.js';
 
-// !todo: may not need later, but keeping for now in case we have variant system for links
 const StyleFields = ({
-  linkVariantLabel = 'Link variant',
-  linkVariantName = 'linkVariant',
-  linkVariantDefault = 'primary',
+  variantLabel = 'Link variant',
+  variantName = 'linkVariant',
+  variantDefault = { variant_name: 'primaryLink' },
 }: StyleFieldsProps) => {
   return (
-    <>
-      <ChoiceField
-        label={linkVariantLabel}
-        name={linkVariantName}
-        choices={[
-          ['primary', 'Primary'],
-          ['secondary', 'Secondary'],
-          ['tertiary', 'Tertiary'],
-        ]}
-        default={linkVariantDefault}
-      />
-    </>
+    <VariantSelectionField
+      label={variantLabel}
+      name={variantName}
+      variantDefinitionName="link"
+      default={variantDefault}
+    />
   );
 };
 

package/components/componentLibrary/Link/index.module.scss

@@ -1,21 +1,23 @@
 .link {
-  display: var(--hscl-link-display, inline-block);
-  color: var(--hscl-link-color);
-  text-decoration: var(--hscl-link-textDecoration, underline);
+  display: inline-block;
+  color: var(--hs-link-color);
+  text-decoration: var(--hs-link-textDecoration);
   cursor: pointer;
 
   &:hover {
-    color: var(--hscl-link-color-hover);
-    text-decoration: var(--hscl-link-textDecoration-hover, underline);
+    color: var(--hs-link-color-hover);
+    text-decoration: var(--hs-link-textDecoration-hover);
   }
 
   &:focus-visible {
-    outline: var(--hscl-link-outlineWidth-focus, 2px) solid var(--hscl-link-outlineColor-focus, currentColor);
-    outline-offset: var(--hscl-link-outlineOffset-focus, 2px);
+    color: var(--hs-link-color-hover);
+    text-decoration: var(--hs-link-textDecoration-hover);
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 
   &:active {
-    color: var(--hscl-link-color-active, var(--hscl-link-color));
-    text-decoration: var(--hscl-link-textDecoration-active, var(--hscl-link-textDecoration, underline));
+    color: var(--hs-link-color-active, var(--hs-link-color));
+    text-decoration: var(--hs-link-textDecoration-active, var(--hs-link-textDecoration));
   }
 }

package/components/componentLibrary/Link/index.tsx

@@ -2,7 +2,6 @@ import styles from './index.module.scss';
 import ContentFields from './ContentFields.js';
 import StyleFields from './StyleFields.js';
 import cx from '../utils/classname.js';
-import type { CSSVariables } from '../utils/types.js';
 import { LinkProps, BaseLinkProps, LinkHTMLProps } from './types.js';
 import {
   getLinkRel,
@@ -32,7 +31,7 @@ const getLinkValues = (props: Omit<LinkProps, keyof BaseLinkProps>) => {
 };
 
 const LinkComponent = ({
-  variant = 'primary',
+  variant = 'primaryLink',
   className = '',
   style = {},
   children,
@@ -43,18 +42,14 @@ const LinkComponent = ({
   const defaultClasses = styles.link;
   const combinedClasses = cx(defaultClasses, className);
 
-  const cssVariables: CSSVariables = {
-    '--hscl-link-color': `var(--hscl-link-color-${variant})`,
-    '--hscl-link-color-hover': `var(--hscl-link-color-hover-${variant})`,
-  };
-
   return (
     <a
       className={combinedClasses}
-      style={{ ...cssVariables, ...style }}
+      style={style}
       href={href}
       target={target}
       rel={rel}
+      data-link-variant={variant}
       {...anchorProps}
     >
       {children}

package/components/componentLibrary/Link/llm.txt

@@ -58,9 +58,9 @@ Pass a `linkField` prop containing HubSpot link field data. The component automa
     open_in_new_tab?: boolean;                       // Open in new tab
     no_follow?: boolean;                             // Add nofollow rel
   };
-  variant?: 'primary' | 'secondary' | 'tertiary';    // Visual style variant (default: 'primary')
+  variant?: 'primaryLink' | 'secondaryLink';         // Visual style variant (default: 'primaryLink')
   className?: string;                                // Additional CSS classes
-  style?: React.CSSProperties;                       // Inline styles (including CSS variables)
+  style?: React.CSSProperties;                       // Inline styles
   children?: React.ReactNode;                        // Link text/content
 }
 ```
@@ -74,9 +74,9 @@ Pass individual `href`, `target`, and `rel` props directly.
   href: string;                                      // Link destination URL (required)
   target?: '_self' | '_blank' | '_parent' | '_top';  // Link target behavior
   rel?: string;                                      // Link relationship (e.g., 'noopener noreferrer')
-  variant?: 'primary' | 'secondary' | 'tertiary';    // Visual style variant (default: 'primary')
+  variant?: 'primaryLink' | 'secondaryLink';         // Visual style variant (default: 'primaryLink')
   className?: string;                                // Additional CSS classes
-  style?: React.CSSProperties;                       // Inline styles (including CSS variables)
+  style?: React.CSSProperties;                       // Inline styles
   children?: React.ReactNode;                        // Link text/content
 }
 ```
@@ -107,21 +107,7 @@ export default function MyModule({ fieldValues }) {
 ```tsx
 <Link
   linkField={fieldValues.link}
-  variant="secondary"
->
-  Visit HubSpot
-</Link>
-```
-
-#### Field-based Link with Style Override
-
-```tsx
-<Link
-  linkField={fieldValues.link}
-  style={{
-    '--hscl-link-textDecoration': 'none',
-    '--hscl-link-textDecoration-hover': 'underline',
-  }}
+  variant="secondaryLink"
 >
   Visit HubSpot
 </Link>
@@ -163,17 +149,13 @@ import Link from '@hubspot/cms-component-library/Link';
 ### Using Variants
 
 ```tsx
-<Link href="https://www.hubspot.com" variant="primary">
+<Link href="https://www.hubspot.com" variant="primaryLink">
   Primary Link
 </Link>
 
-<Link href="https://www.hubspot.com" variant="secondary">
+<Link href="https://www.hubspot.com" variant="secondaryLink">
   Secondary Link
 </Link>
-
-<Link href="https://www.hubspot.com" variant="tertiary">
-  Tertiary Link
-</Link>
 ```
 
 ## HubSpot CMS Integration
@@ -220,12 +202,12 @@ The Link component provides field definitions for easy integration with HubSpot
 <Link.StyleFields
   variantLabel="Link style"
   variantName="linkVariant"
-  variantDefault="primary"
+  variantDefault={{ variant_name: 'primaryLink' }}
 />
 ```
 
 **Fields:**
-- `linkVariant`: Choice field for variant selection (primary, secondary, tertiary)
+- `linkVariant`: VariantSelectionField for theme variant selection (primaryLink, secondaryLink)
 
 ### Module Usage Example
 
@@ -238,7 +220,7 @@ export default function NavigationModule({ fieldValues }) {
   return (
     <Link
       linkField={fieldValues.link}
-      variant={fieldValues.linkVariant}
+      variant={fieldValues.style.linkVariant?.variantName}
     >
       {fieldValues.linkText}
     </Link>
@@ -255,7 +237,7 @@ export default function NavigationModule({ fieldValues }) {
       href="https://www.hubspot.com"
       target="_blank"
       rel="nofollow"
-      variant="primary"
+      variant="primaryLink"
     >
       Go to HubSpot
     </Link>
@@ -269,69 +251,32 @@ Note: The field-based approach is simpler and less error-prone.
 
 ### Variants
 
-The Link component supports three visual style variants through the `variant` prop:
+The Link component supports two visual style variants through the `variant` prop:
 
-- **primary** (default): Default link styling using `--hscl-link-color-primary` and `--hscl-link-color-hover-primary`
-- **secondary**: Alternative styling using `--hscl-link-color-secondary` and `--hscl-link-color-hover-secondary`
-- **tertiary**: Third alternative using `--hscl-link-color-tertiary` and `--hscl-link-color-hover-tertiary`
+- **primaryLink** (default): Default link styling
+- **secondaryLink**: Alternative link styling
 
-The component internally sets:
-```tsx
-style={{
-  '--hscl-link-color': `var(--hscl-link-color-${variant})`,
-  '--hscl-link-color-hover': `var(--hscl-link-color-hover-${variant})`,
-}}
-```
+The component renders a `data-link-variant` attribute on the `<a>` element. The theme provides CSS variables scoped to `[data-link-variant]` selectors.
 
-### CSS Variables
+### CSS Variables (Theme-provided)
 
-The Link component uses CSS variables for theming and customization:
+The theme provides these CSS variables via `[data-link-variant]` selectors:
 
 **Base Styles:**
-- `--hscl-link-display`: Display property (default: inline-block)
-- `--hscl-link-color`: Text color (set by variant, no fallback)
-- `--hscl-link-textDecoration`: Text decoration (default: underline)
+- `--hs-link-color`: Text color
+- `--hs-link-textDecoration`: Text decoration
 
 **Hover States:**
-- `--hscl-link-color-hover`: Hover text color (set by variant, no fallback)
-- `--hscl-link-textDecoration-hover`: Hover text decoration (default: underline)
-
-**Variant-specific Variables (must be defined globally):**
-- `--hscl-link-color-primary`: Primary variant text color
-- `--hscl-link-color-hover-primary`: Primary variant hover text color
-- `--hscl-link-color-secondary`: Secondary variant text color
-- `--hscl-link-color-hover-secondary`: Secondary variant hover text color
-- `--hscl-link-color-tertiary`: Tertiary variant text color
-- `--hscl-link-color-hover-tertiary`: Tertiary variant hover text color
-
-### Custom Styling Examples
+- `--hs-link-color-hover`: Hover text color
+- `--hs-link-textDecoration-hover`: Hover text decoration
 
-#### Override Text Decoration
+**Active States:**
+- `--hs-link-color-active`: Active text color (falls back to `--hs-link-color`)
+- `--hs-link-textDecoration-active`: Active text decoration (falls back to `--hs-link-textDecoration`)
 
-```tsx
-<Link
-  href="https://www.hubspot.com"
-  style={{
-    '--hscl-link-textDecoration': 'none',
-    '--hscl-link-textDecoration-hover': 'underline',
-  }}
->
-  Hover for underline
-</Link>
-```
-
-#### Override Display
-
-```tsx
-<Link
-  href="https://www.hubspot.com"
-  style={{
-    '--hscl-link-display': 'block',
-  }}
->
-  Block-level Link
-</Link>
-```
+**Hardcoded Styles (not theme-configurable):**
+- `display: inline-block`
+- Focus outline: `2px solid currentColor` with `2px` offset
 
 ## Accessibility
 
@@ -349,9 +294,8 @@ The Link component follows accessibility best practices:
 
 - **Use linkField prop when available**: If you have HubSpot field data, use the `linkField` prop instead of manually extracting href/target/rel
 - **Do NOT mix approaches**: TypeScript will prevent you from using both `linkField` and `href` props together
-- **Use variants for consistency**: Choose the appropriate variant (primary/secondary/tertiary) rather than overriding colors directly
+- **Use variants for consistency**: Choose the appropriate variant (primaryLink/secondaryLink) rather than overriding colors directly
 - **Security**: The component automatically adds `rel="noopener noreferrer"` when target is `_blank`
-- **CSS Variables**: Override design tokens using CSS variables for advanced customization
 - **Minimal styling**: Keep link styling simple; use Button component for prominent CTAs
 
 ## Common Patterns
@@ -359,7 +303,7 @@ The Link component follows accessibility best practices:
 ### Navigation Menu Item
 
 ```tsx
-<Link href="/dashboard" variant="secondary">
+<Link href="/dashboard" variant="secondaryLink">
   Dashboard
 </Link>
 ```

package/components/componentLibrary/Link/stories/Link.stories.tsx

@@ -4,12 +4,6 @@ import { LinkProps } from '../types.js';
 import { withLinkStyles } from './LinkDecorator.js';
 import { SBContainer, SBFocusWrapper } from '@sb-utils';
 import { SBCard } from '@sb-utils/SBCard.js';
-import type { CSSVariables } from '../../utils/types.js';
-
-const removeUnderlineStyle: CSSVariables = {
-  '--hscl-link-textDecoration': 'none',
-  '--hscl-link-textDecoration-hover': 'none',
-};
 
 const meta: Meta<LinkProps> = {
   title: 'Component Library/Link',
@@ -34,7 +28,7 @@ export const Default: Story = {
     href: 'https://www.hubspot.com',
     target: '_blank',
     rel: 'noopener noreferrer',
-    variant: 'primary',
+    variant: 'primaryLink',
     className: 'test-class',
   },
 };
@@ -90,7 +84,7 @@ export const InContext: Story = {
           gap="medium"
           style={{ flexWrap: 'wrap' }}
         >
-          <Link href="https://www.hubspot.com" style={removeUnderlineStyle}>
+          <Link href="https://www.hubspot.com">
             <SBCard
               title="Clickable Card"
               description="The entire card is wrapped in a link, making it clickable."
@@ -143,7 +137,6 @@ export const InContext: Story = {
               <Link
                 key={key}
                 href={`/image/${key}`}
-                style={removeUnderlineStyle}
               >
                 <div
                   style={{
@@ -179,7 +172,7 @@ export const InteractionStates: Story = {
       <SBContainer addBackground>
         <h4>Hover State</h4>
         <p>Hover over the link to see the hover effect</p>
-        <Link href="https://www.hubspot.com" variant="primary">
+        <Link href="https://www.hubspot.com" variant="primaryLink">
           Hover me
         </Link>
       </SBContainer>
@@ -192,7 +185,7 @@ export const InteractionStates: Story = {
           to show how it looks.
         </p>
         <SBFocusWrapper>
-          <Link href="https://www.hubspot.com" variant="primary">
+          <Link href="https://www.hubspot.com" variant="primaryLink">
             Focused link
           </Link>
         </SBFocusWrapper>

package/components/componentLibrary/Link/stories/LinkDecorator.module.scss

@@ -0,0 +1,15 @@
+.linkContainer {
+  [data-link-variant='primaryLink'] {
+    --hs-link-color: #0066cc;
+    --hs-link-textDecoration: none;
+    --hs-link-color-hover: #0052a3;
+    --hs-link-textDecoration-hover: underline;
+  }
+
+  [data-link-variant='secondaryLink'] {
+    --hs-link-color: #516f90;
+    --hs-link-textDecoration: none;
+    --hs-link-color-hover: #33475b;
+    --hs-link-textDecoration-hover: underline;
+  }
+}

package/components/componentLibrary/Link/stories/LinkDecorator.tsx

@@ -1,17 +1,8 @@
 import type { Decorator } from '@storybook/react';
-import type { CSSVariables } from '../../utils/types.js';
-
-const defaultLinkStyles: CSSVariables = {
-  '--hscl-link-color-primary': '#0066cc',
-  '--hscl-link-color-secondary': '#516f90',
-  '--hscl-link-color-tertiary': '#7c98b6',
-  '--hscl-link-color-hover-primary': '#0052a3',
-  '--hscl-link-color-hover-secondary': '#33475b',
-  '--hscl-link-color-hover-tertiary': '#516f90',
-};
+import styles from './LinkDecorator.module.scss';
 
 export const withLinkStyles: Decorator = Story => (
-  <div style={defaultLinkStyles}>
+  <div className={styles.linkContainer}>
     <Story />
   </div>
 );

package/components/componentLibrary/Link/types.ts

@@ -1,8 +1,10 @@
 import { LinkFieldDefaults, Visibility } from '@hubspot/cms-components/fields';
 import { LinkFieldValue } from '../utils/linkField.js';
 
+export type LinkVariant = 'primaryLink' | 'secondaryLink';
+
 export type BaseLinkProps = {
-  variant?: 'primary' | 'secondary' | 'tertiary';
+  variant?: LinkVariant;
   className?: string;
   style?: React.CSSProperties;
   children?: React.ReactNode;
@@ -42,7 +44,7 @@ export type ContentFieldsProps<TLinkName extends string = 'link'> = {
 );
 
 export type StyleFieldsProps = {
-  linkVariantLabel?: string;
-  linkVariantName?: string;
-  linkVariantDefault?: string;
+  variantLabel?: string;
+  variantName?: string;
+  variantDefault?: { variant_name: LinkVariant };
 };

package/components/componentLibrary/_patterns/css-patterns.md

@@ -136,8 +136,11 @@ render: () => {
     property: var(--hscl-componentName-property-hover);
   }
 
-  &:focus {
-    property: var(--hscl-componentName-property-focus);
+  // Focus-visible reuses hover styles + browser default outline
+  &:focus-visible {
+    property: var(--hscl-componentName-property-hover);
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 
   &:disabled {
@@ -186,9 +189,11 @@ Use `&` for pseudo-classes and nested selectors:
     background-color: var(--hscl-button-backgroundColor-hover);
   }
 
-  &:focus {
-    outline: var(--hscl-button-outlineWidth-focus) solid
-             var(--hscl-button-outlineColor-focus);
+  &:focus-visible {
+    background-color: var(--hscl-button-backgroundColor-hover);
+    color: var(--hscl-button-color-hover);
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 
   &:disabled {
@@ -244,9 +249,11 @@ Use `&` for pseudo-classes and nested selectors:
     background-color: var(--hscl-button-backgroundColor-hover);
   }
 
-  &:focus {
-    outline: var(--hscl-button-outlineWidth-focus) solid
-             var(--hscl-button-outlineColor-focus);
+  &:focus-visible {
+    background-color: var(--hscl-button-backgroundColor-hover);
+    color: var(--hscl-button-color-hover);
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 
   &:disabled {
@@ -286,10 +293,12 @@ All interactive components should style **hover, focus, active** states:
     color: var(--hscl-button-color-hover, var(--hscl-button-color));
   }
 
-  // Focus-visible - keyboard navigation only (not mouse clicks)
+  // Focus-visible - reuses hover styles + browser default outline
   &:focus-visible {
-    outline: var(--hscl-button-outlineWidth-focus, 2px) solid var(--hscl-button-outlineColor-focus, currentColor);
-    outline-offset: var(--hscl-button-outlineOffset-focus, 2px);
+    background-color: var(--hscl-button-backgroundColor-hover, var(--hscl-button-backgroundColor));
+    color: var(--hscl-button-color-hover, var(--hscl-button-color));
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 
   // Active - pressed/clicked state
@@ -322,11 +331,17 @@ All interactive components should style **hover, focus, active** states:
    background-color: var(--hscl-button-backgroundColor-hover);
    ```
 
-3. **Use `currentColor` for focus outlines**
-   - Adapts to component's text color automatically
-   - Ensures sufficient contrast in most cases
+3. **Reuse hover styles for focus, rely on browser default outline**
+   - Focus-visible should apply the same visual treatment as hover (background, color, border)
+   - Use `outline: 2px solid initial` for the browser's default focus ring color
+   - No need for separate focus-specific CSS variables
    ```scss
-   outline: var(--hscl-button-outlineColor-focus, currentColor);
+   &:focus-visible {
+     background-color: var(--hscl-button-backgroundColor-hover, var(--hscl-button-backgroundColor));
+     color: var(--hscl-button-color-hover, var(--hscl-button-color));
+     outline: 2px solid Highlight;
+     outline-offset: 2px;
+   }
    ```
 
 4. **Respect reduced motion preferences**
@@ -360,8 +375,10 @@ See these components for implementation examples:
     property: var(--hscl-componentName-property-hover);
   }
 
-  &:focus {
-    property: var(--hscl-componentName-property-focus);
+  &:focus-visible {
+    property: var(--hscl-componentName-property-hover);
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {