@hubspot/cms-component-library 0.3.7 → 0.3.9

package/components/componentLibrary/Button/llm.txt

@@ -37,7 +37,7 @@ Button/
 **Base Props (shared by both types):**
 ```tsx
 {
-  variant?: 'primary' | 'secondary' | 'tertiary';  // Visual style variant
+  variant?: 'primaryButton' | 'secondaryButton' | 'tertiaryButton' | 'accentButton';  // Visual style variant (connected to theme settings)
   className?: string;                               // Additional CSS classes
   style?: React.CSSProperties;                      // Inline styles
   children?: React.ReactNode;                       // Button text/content
@@ -108,7 +108,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="link"
-  variant="primary"
+  variant="primaryButton"
   href="https://www.hubspot.com"
   target="_self"
 >
@@ -121,7 +121,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="link"
-  variant="primary"
+  variant="primaryButton"
   href="https://www.hubspot.com"
   target="_blank"
   rel="noopener noreferrer"
@@ -135,7 +135,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="button"
-  variant="primary"
+  variant="primaryButton"
   onClick={handleClick}
   showIcon={true}
   iconFieldPath="icon"
@@ -152,7 +152,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="link"
-  variant="secondary"
+  variant="secondaryButton"
   href="/back"
   showIcon={true}
   iconFieldPath="icon"
@@ -170,7 +170,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="button"
-  variant="primary"
+  variant="primaryButton"
   disabled={true}
   onClick={handleClick}
 >
@@ -183,7 +183,7 @@ import { Island } from '@hubspot/cms-components'
 ```tsx
 <Button
   buttonType="link"
-  variant="primary"
+  variant="primaryButton"
   href="/custom"
   className="custom-button-class"
   style={{ maxWidth: '300px' }}
@@ -240,7 +240,7 @@ Configurable props for variant and icon position:
 <Button.StyleFields
   buttonVariantLabel="Button variant"
   buttonVariantName="buttonVariant"
-  buttonVariantDefault="primary"
+  buttonVariantDefault={{ variant_name: 'primaryButton' }}
   buttonIconPositionLabel="Icon position"
   buttonIconPositionName="buttonIconPosition"
   buttonIconPositionDefault="right"
@@ -248,7 +248,7 @@ Configurable props for variant and icon position:
 ```
 
 **Fields:**
-- `buttonVariant`: ChoiceField for selecting visual style (primary, secondary, tertiary)
+- `buttonVariant`: VariantSelectionField connected to theme settings (primaryButton, secondaryButton, tertiaryButton, accentButton)
 - `buttonIconPosition`: ChoiceField for selecting icon placement (left, right). This field has a hardcoded visibility rule — it is only shown when the icon toggle is enabled (`iconComponentShowIcon === true`), which corresponds to the `BooleanField` id hardcoded in `Icon.ContentFields`.
 
 ### Module Usage Example
@@ -276,57 +276,44 @@ export default function CTAModule({ fieldValues }) {
 
 ## Styling
 
-### CSS Variables
-
-The Button component uses CSS variables for theming and customization:
-
-**Base Styles:**
-- `--hscl-button-gap`: Space between text and icon (default: 8px)
-- `--hscl-button-backgroundColor`: Background color
-- `--hscl-button-color`: Text color
-- `--hscl-button-paddingBlock`: Vertical padding
-- `--hscl-button-paddingInline`: Horizontal padding
-- `--hscl-button-borderRadius`: Border radius
-- `--hscl-button-borderWidth`: Border width
-- `--hscl-button-borderColor`: Border color
-- `--hscl-button-fontSize`: Font size
-- `--hscl-button-fontWeight`: Font weight
-
-**Hover States:**
-- `--hscl-button-backgroundColor-hover`: Hover background color
-- `--hscl-button-color-hover`: Hover text color
-- `--hscl-button-borderWidth-hover`: Hover border width
-- `--hscl-button-borderColor-hover`: Hover border color
-
-**Focus States:**
-- `--hscl-button-backgroundColor-focus`: Focus background color
-- `--hscl-button-color-focus`: Focus text color
-- `--hscl-button-borderWidth-focus`: Focus border width
-- `--hscl-button-borderColor-focus`: Focus border color
-- `--hscl-button-outlineWidth-focus`: Focus outline width
-- `--hscl-button-outlineColor-focus`: Focus outline color
-- `--hscl-button-outlineOffset-focus`: Focus outline offset
-
-**Icon:**
-- `--hscl-button-icon-fill`: Icon fill color
-
-### Custom Styling Example
+### Theme CSS Variables
 
-```tsx
-<Button
-  buttonType="button"
-  variant="primary"
-  style={{
-    '--hscl-button-backgroundColor': '#FF7A59',
-    '--hscl-button-color': '#FFFFFF',
-    '--hscl-button-paddingBlock': '12px',
-    '--hscl-button-paddingInline': '24px',
-    '--hscl-button-borderRadius': '8px',
-  }}
->
-  Custom Colors
-</Button>
-```
+The Button component is themed via `--hs-button-*` CSS variables, which are provided by the theme settings variant system (scoped via the variant prop and `data-buttons-variant` attribute).
+
+**Base Styles (from theme):**
+- `--hs-button-backgroundColor`: Background color
+- `--hs-button-color`: Text color
+- `--hs-button-borderRadius`: Border radius
+- `--hs-button-border`: Border shorthand
+- `--hs-button-fontSize`: Font size
+- `--hs-button-fontFamily`: Font family
+- `--hs-button-fontStyle`: Font style
+- `--hs-button-fontWeight`: Font weight
+- `--hs-button-textDecoration`: Text decoration
+
+**Hover States (from theme):**
+- `--hs-button-backgroundColor-hover`: Hover background (falls back to base)
+- `--hs-button-color-hover`: Hover text color (falls back to base)
+- `--hs-button-border-hover`: Hover border (falls back to base)
+
+**Focus States (from theme):**
+- `--hs-button-backgroundColor-focus`: Focus background (falls back to base)
+- `--hs-button-color-focus`: Focus text color (falls back to base)
+- `--hs-button-border-focus`: Focus border (falls back to base)
+
+**Active States (from theme):**
+- `--hs-button-backgroundColor-active`: Active background (falls back to base)
+- `--hs-button-color-active`: Active text color (falls back to base)
+- `--hs-button-border-active`: Active border (falls back to base)
+
+### Hardcoded Layout Values
+
+The following properties use fixed values and are not configurable via CSS variables:
+
+- **Gap:** 8px (space between text and icon)
+- **Padding:** 12px vertical, 24px horizontal
+- **Focus outline:** 2px solid currentColor, offset 2px
+- **Icon fill:** currentColor
 
 ## Accessibility
 
@@ -359,7 +346,7 @@ The Button component follows accessibility best practices:
 - **Icon purpose**: Use `SEMANTIC` when the icon adds meaning, `DECORATIVE` when it's purely visual
 - **Disabled state**: Only use with `buttonType="button"`, not applicable to links
 - **CSS Variables**: Override design tokens using CSS variables rather than hardcoding values
-- **Variant system**: Currently variants are passed as props but full theming implementation is pending
+- **Variant system**: Variants are connected to theme settings via `VariantSelectionField` and `data-variant-name` attribute. CSS variables are scoped automatically by the ContentUILib variant system.
 
 ## Common Patterns
 
@@ -368,7 +355,7 @@ The Button component follows accessibility best practices:
 ```tsx
 <Button
   buttonType="link"
-  variant="primary"
+  variant="primaryButton"
   href="/signup"
   showIcon={true}
   iconFieldPath="icon"
@@ -383,7 +370,7 @@ The Button component follows accessibility best practices:
 ```tsx
 <Button
   buttonType="button"
-  variant="primary"
+  variant="primaryButton"
   onClick={handleSubmit}
   disabled={isSubmitting}
 >
@@ -396,7 +383,7 @@ The Button component follows accessibility best practices:
 ```tsx
 <Button
   buttonType="link"
-  variant="secondary"
+  variant="secondaryButton"
   href="/dashboard"
   showIcon={true}
   iconFieldPath="icon"
@@ -411,7 +398,7 @@ The Button component follows accessibility best practices:
 ```tsx
 <Button
   buttonType="link"
-  variant="tertiary"
+  variant="tertiaryButton"
   href="https://docs.hubspot.com"
   target="_blank"
   rel="noopener noreferrer"

package/components/componentLibrary/Button/stories/Button.AsButton.stories.tsx

@@ -26,7 +26,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    variant: 'primary',
+    variant: 'primaryButton',
     children: 'Click me',
     onClick: () => alert('Button clicked!'),
   },
@@ -34,7 +34,7 @@ export const Default: Story = {
 
 export const WithIcon: Story = {
   args: {
-    variant: 'primary',
+    variant: 'primaryButton',
     children: 'Click me',
     onClick: () => alert('Button clicked!'),
     showIcon: true,

package/components/componentLibrary/Button/stories/Button.AsLink.stories.tsx

@@ -26,7 +26,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    variant: 'primary',
+    variant: 'primaryButton',
     children: 'Click me',
     href: 'https://www.hubspot.com',
   },
@@ -34,7 +34,7 @@ export const Default: Story = {
 
 export const WithIcon: Story = {
   args: {
-    variant: 'primary',
+    variant: 'primaryButton',
     children: 'Click me',
     href: 'https://www.hubspot.com',
     showIcon: true,

package/components/componentLibrary/Button/stories/ButtonDecorator.module.scss

@@ -1,25 +1,21 @@
 .buttonContainer {
-  padding: '20px';
-  --hscl-button-gap: 8px;
-  --hscl-button-backgroundColor: #0066cc;
-  --hscl-button-color: #ffffff;
-  --hscl-button-paddingBlock: 10px;
-  --hscl-button-paddingInline: 20px;
-  --hscl-button-borderRadius: 4px;
-  --hscl-button-borderWidth: 1px;
-  --hscl-button-borderColor: transparent;
-  --hscl-button-fontSize: 14px;
-  --hscl-button-fontWeight: 500;
-  --hscl-button-backgroundColor-hover: #0052a3;
-  --hscl-button-color-hover: #ffffff;
-  --hscl-button-borderWidth-hover: 1px;
-  --hscl-button-borderColor-hover: transparent;
-  --hscl-button-backgroundColor-focus: #0066cc;
-  --hscl-button-color-focus: #ffffff;
-  --hscl-button-borderWidth-focus: 1px;
-  --hscl-button-borderColor-focus: transparent;
-  --hscl-button-outlineWidth-focus: 2px;
-  --hscl-button-outlineColor-focus: #0066cc;
-  --hscl-button-outlineOffset-focus: 2px;
-  --hscl-button-icon-fill: currentColor;
+  padding: 20px;
+  --hs-button-backgroundColor: #0066cc;
+  --hs-button-color: #ffffff;
+  --hs-button-borderRadius: 4px;
+  --hs-button-border: 1px solid transparent;
+  --hs-button-fontSize: 14px;
+  --hs-button-fontFamily: inherit;
+  --hs-button-fontStyle: normal;
+  --hs-button-fontWeight: 500;
+  --hs-button-textDecoration: none;
+  --hs-button-backgroundColor-hover: #0052a3;
+  --hs-button-color-hover: #ffffff;
+  --hs-button-border-hover: 1px solid transparent;
+  --hs-button-backgroundColor-focus: #0066cc;
+  --hs-button-color-focus: #ffffff;
+  --hs-button-border-focus: 1px solid transparent;
+  --hs-button-backgroundColor-active: #004080;
+  --hs-button-color-active: #ffffff;
+  --hs-button-border-active: 1px solid transparent;
 }

package/components/componentLibrary/Button/types.ts

@@ -8,7 +8,7 @@ export type IconPositionHorizontal = 'left' | 'right';
 
 // Base props shared by all variants
 export type BaseButtonProps = {
-  variant?: 'primary' | 'secondary' | 'tertiary'; // !todo: not used atm but keeping for when we need to add variant system.
+  variant?: 'primaryButton' | 'secondaryButton' | 'tertiaryButton' | 'accentButton';
   className?: string;
   style?: React.CSSProperties;
   children?: React.ReactNode;
@@ -57,7 +57,7 @@ export type ContentFieldsProps = Omit<
 export type StyleFieldsProps = {
   buttonVariantLabel?: string;
   buttonVariantName?: string;
-  buttonVariantDefault?: string;
+  buttonVariantDefault?: { variant_name: string };
   buttonIconPositionLabel?: string;
   buttonIconPositionName?: string;
   buttonIconPositionDefault?: IconPositionHorizontal;

package/components/componentLibrary/Card/StyleFields.tsx

@@ -1,22 +1,17 @@
-import { ChoiceField } from '@hubspot/cms-components/fields';
+import { VariantSelectionField } from '@hubspot/cms-components/fields';
 import { StyleFieldsProps } from './types.js';
 
 const StyleFields = ({
-  variantLabel = 'Card Variant',
-  variantName = 'variant',
-  variantDefault = 'elevated',
+  cardVariantLabel = 'Card variant',
+  cardVariantName = 'cardVariant',
+  cardVariantDefault = { variantName: 'cardStyle1' },
 }: StyleFieldsProps) => {
   return (
-    <ChoiceField
-      label={variantLabel}
-      name={variantName}
-      required={true}
-      choices={[
-        ['elevated', 'Elevated (with shadow)'],
-        ['outlined', 'Outlined (with border)'],
-        ['filled', 'Filled (solid background)'],
-      ]}
-      default={variantDefault}
+    <VariantSelectionField
+      label={cardVariantLabel}
+      name={cardVariantName}
+      variantDefinitionName="card"
+      default={cardVariantDefault}
     />
   );
 };

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

@@ -2,13 +2,13 @@
   display: flex;
   flex-direction: column;
   box-sizing: border-box;
-  padding: var(--hscl-card-padding, 24px);
-  border-radius: var(--hscl-card-borderRadius, 8px);
-  background-color: var(--hscl-card-backgroundColor, #ffffff);
-  box-shadow: var(--hscl-card-boxShadow, none);
-  border: var(--hscl-card-border, none);
+  padding: 24px;
+  border-radius: var(--hs-card-borderRadius, 8px);
+  background-color: var(--hs-card-backgroundColor, #ffffff);
+  color: var(--hs-card-color, inherit);
+  border: var(--hs-card-border, none);
 
-  &:hover {
-    box-shadow: var(--hscl-card-boxShadow-hover, var(--hscl-card-boxShadow, none));
+  h1,h2,h3,h4,h5,h6,p,span {
+    color: inherit;
   }
 }

package/components/componentLibrary/Card/index.tsx

@@ -1,30 +1,25 @@
 import styles from './index.module.scss';
 import cx from '../utils/classname.js';
-import type { CSSVariables } from '../utils/types.js';
 import { CardProps } from './types.js';
 import StyleFields from './StyleFields.js';
 
 const CardComponent = ({
-  variant = 'elevated',
+  variant = 'cardStyle1',
   as: Component = 'div',
-  borderRadius = 8,
   className = '',
   style = {},
   children,
   ...rest
 }: CardProps) => {
-  const variantClass = styles[`hscl-card-${variant}`]; // !todo: not used atm but keeping for when we need to add variant system.
-
-  const defaultClasses = cx(styles.card, variantClass);
-  const combinedClasses = cx(defaultClasses, className);
-
-  const cssVariables: CSSVariables = {
-    '--hscl-card-borderRadius': `${borderRadius}px`,
-    ...style,
-  };
+  const combinedClasses = cx(styles.card, className);
 
   return (
-    <Component className={combinedClasses} style={cssVariables} {...rest}>
+    <Component
+      className={combinedClasses}
+      style={style}
+      data-card-variant={variant}
+      {...rest}
+    >
       {children}
     </Component>
   );

package/components/componentLibrary/Card/llm.txt

@@ -1,6 +1,6 @@
 # Card Component
 
-A flexible, polymorphic container component that provides a consistent visual structure for grouping related content with customizable variants and styling.
+A flexible, polymorphic container component that provides a consistent visual structure for grouping related content with theme variant styling.
 
 ## Import path
 ```tsx
@@ -9,7 +9,7 @@ import Card from '@hubspot/cms-component-library/Card';
 
 ## Purpose
 
-The Card component provides a reusable container for grouping related content in HubSpot CMS projects. It solves the challenge of maintaining visual consistency across content sections while supporting different elevation styles (shadows, borders, or filled backgrounds). Use it when you need to visually separate and organize content into distinct sections with flexible styling.
+The Card component provides a reusable container for grouping related content in HubSpot CMS projects. It uses the theme variant system (via `data-card-variant` attribute) to apply visual styles like background color, text color, border radius, and borders. Use it when you need to visually separate and organize content into distinct sections with theme-consistent styling.
 
 ## Component Structure
 
@@ -17,29 +17,28 @@ The Card component provides a reusable container for grouping related content in
 Card/
 ├── index.tsx                    # Main component with render logic
 ├── types.ts                     # TypeScript type definitions
-├── StyleFields.tsx              # HubSpot field definitions for styling
-├── index.module.scss            # CSS module with design tokens
+├── StyleFields.tsx              # HubSpot field definitions for styling (VariantSelectionField)
+├── index.module.scss            # CSS module consuming theme variant CSS variables
 └── stories/
     ├── Card.stories.tsx         # Storybook examples
     ├── CardDecorator.tsx        # Storybook decorator
-    └── CardDecorator.module.css # Decorator styles
+    └── CardDecorator.module.scss # Decorator styles with variant variable definitions
 ```
 
 ## Components
 
 ### Card (Main Component)
 
-**Purpose:** Polymorphic container component that renders as a `<div>`, `<article>`, or `<section>` element with configurable visual variants.
+**Purpose:** Polymorphic container component that renders as a `<div>`, `<article>`, or `<section>` element with theme variant styling applied via the `data-card-variant` attribute.
 
 **Props:**
 ```tsx
 {
-  variant?: 'elevated' | 'outlined' | 'filled';   // Visual style variant (default: 'elevated')
+  variant?: 'cardStyle1' | 'cardStyle2' | 'cardStyle3' | 'cardStyle4';  // Theme variant (default: 'cardStyle1')
   as?: 'div' | 'article' | 'section';             // HTML element to render (default: 'div')
-  borderRadius?: number;                          // Border radius in pixels (default: 8)
   children?: React.ReactNode;                     // Card content
   className?: string;                             // Additional CSS classes
-  style?: React.CSSProperties;                    // Inline styles with CSS variables
+  style?: React.CSSProperties;                    // Inline styles
 }
 ```
 
@@ -59,7 +58,7 @@ import Card from '@hubspot/cms-component-library/Card';
 ### Semantic Article Card
 
 ```tsx
-<Card as="article" variant="filled">
+<Card as="article" variant="cardStyle3">
   <h3>Blog Post Title</h3>
   <p>Article content goes here...</p>
 </Card>
@@ -84,25 +83,11 @@ const features = [
 </div>
 ```
 
-### Card with Rich Content
-
-```tsx
-<Card variant="outlined">
-  <h3>Product Features</h3>
-  <ul>
-    <li>Real-time collaboration</li>
-    <li>Advanced security</li>
-    <li>Custom integrations</li>
-  </ul>
-  <button>Learn More</button>
-</Card>
-```
-
 ## HubSpot CMS Integration
 
 ### Field Definitions
 
-The Card component provides field definitions for styling configuration in HubSpot CMS modules.
+The Card component uses `VariantSelectionField` from `@hubspot/cms-components/fields` to allow theme variant selection in the CMS editor.
 
 #### StyleFields.tsx
 
@@ -110,14 +95,14 @@ Configurable props for customizing field labels, names, and defaults:
 
 ```tsx
 <Card.StyleFields
-  variantLabel="Card variant"
-  variantName="variant"
-  variantDefault="elevated"
+  cardVariantLabel="Card variant"
+  cardVariantName="cardVariant"
+  cardVariantDefault={{ variant_name: 'cardStyle1' }}
 />
 ```
 
 **Fields:**
-- `variant`: ChoiceField for selecting visual style (elevated, outlined, filled)
+- `cardVariant`: VariantSelectionField for selecting theme variant (variantDefinitionName: "card")
 
 ### Module Usage Example
 
@@ -127,7 +112,7 @@ import Card from '@hubspot/cms-component-library/Card';
 export default function FeatureCardModule({ fieldValues }) {
   return (
     <Card
-      variant={fieldValues.variant}
+      variant={fieldValues.cardVariant.variant_name}
       as="article"
     >
       <h3>{fieldValues.title}</h3>
@@ -147,19 +132,13 @@ FeatureCardModule.fields = (
 
 ## Styling
 
-### CSS Variables
-
-The Card component uses CSS variables for theming and customization:
+### Theme Variant CSS Variables (provided by the variant system via `data-card-variant`)
 
-**Base Styles:**
-- `--hscl-card-padding`: Internal padding (default: 24px)
-- `--hscl-card-borderRadius`: Border radius (default: 8px)
-- `--hscl-card-backgroundColor`: Background color (default: #ffffff)
-- `--hscl-card-boxShadow`: Box shadow (default: none)
-- `--hscl-card-border`: Border style (default: none)
+- `--hs-card-borderRadius`: Border radius
+- `--hs-card-backgroundColor`: Background color
+- `--hs-card-color`: Text color
+- `--hs-card-border`: Border style
 
-**Hover States:**
-- `--hscl-card-boxShadow-hover`: Hover box shadow (inherits from base if not set)
 
 ## Accessibility
 
@@ -167,13 +146,13 @@ The Card component follows accessibility best practices:
 
 - **Semantic HTML**: Use the `as` prop to render appropriate semantic elements (`article` for blog posts, `section` for page sections, `div` for generic containers)
 - **Content Structure**: Ensure proper heading hierarchy within card content (e.g., if cards are in an h2 section, use h3 for card titles)
-- **Color Contrast**: Default styles meet WCAG AA contrast requirements; verify custom colors maintain sufficient contrast
+- **Color Contrast**: Theme variants should meet WCAG AA contrast requirements; verify custom colors maintain sufficient contrast
 - **Focus Management**: Cards themselves are not interactive, but ensure interactive elements within cards (buttons, links) have proper focus styles
 
 ## Best Practices
 
 - **Choose semantic elements**: Use `as="article"` for self-contained content, `as="section"` for thematic groupings, and `as="div"` (default) for generic containers
-- **Border radius via theme settings**: Border radius is controlled by card shape settings in theme settings/variants, not an element-level field. Use the `borderRadius` prop only for programmatic overrides.
+- **Border radius via theme variants**: Border radius is controlled by the variant system, not a direct prop.
 - **Override CSS variables**: Customize appearance using CSS variables rather than overriding class styles
 - **Grid layouts**: Use CSS Grid or Flexbox for card layouts rather than relying on card margins
 - **Content flexibility**: Cards are content-agnostic containers; structure internal content using appropriate semantic elements