@hubspot/cms-component-library 0.3.8 → 0.3.9

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

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

@@ -43,8 +43,7 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
   args: {
-    variant: 'elevated',
-    borderRadius: 8,
+    variant: 'cardStyle1',
   },
   render: args => (
     <Card {...args}>
@@ -55,34 +54,43 @@ export const Default: Story = {
   ),
 };
 
-export const BorderRadius: Story = {
-  name: 'Border Radius Options',
+export const Variants: Story = {
+  name: 'Card Variants',
   render: () => (
     <SBContainer flex direction="column" gap="large">
       <SBContainer addBackground>
-        <h4>No Radius (0px)</h4>
-        <Card borderRadius={0}>
-          <CardHeading>Sharp Corners</CardHeading>
+        <h4>Card Style 1 (Light)</h4>
+        <Card variant="cardStyle1">
+          <CardHeading>Card Style 1</CardHeading>
           <CardDivider />
-          <CardContent>This card has no border radius.</CardContent>
+          <CardContent>Light background with dark text.</CardContent>
         </Card>
       </SBContainer>
 
       <SBContainer addBackground>
-        <h4>Default Radius (8px)</h4>
-        <Card borderRadius={8}>
-          <CardHeading>Default Corners</CardHeading>
+        <h4>Card Style 2 (Subtle)</h4>
+        <Card variant="cardStyle2">
+          <CardHeading>Card Style 2</CardHeading>
           <CardDivider />
-          <CardContent>This card has the default border radius.</CardContent>
+          <CardContent>Subtle background with dark text.</CardContent>
         </Card>
       </SBContainer>
 
       <SBContainer addBackground>
-        <h4>Large Radius (16px)</h4>
-        <Card borderRadius={16}>
-          <CardHeading>Large Corners</CardHeading>
+        <h4>Card Style 3 (Dark)</h4>
+        <Card variant="cardStyle3">
+          <CardHeading>Card Style 3</CardHeading>
           <CardDivider />
-          <CardContent>This card has large rounded corners.</CardContent>
+          <CardContent>Dark background with light text.</CardContent>
+        </Card>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Card Style 4 (Darker)</h4>
+        <Card variant="cardStyle4">
+          <CardHeading>Card Style 4</CardHeading>
+          <CardDivider />
+          <CardContent>Darker background with light text.</CardContent>
         </Card>
       </SBContainer>
     </SBContainer>
@@ -141,7 +149,7 @@ export const ComplexContent: Story = {
     <SBContainer flex direction="column" gap="large">
       <SBContainer addBackground>
         <h4>Card with Rich Content</h4>
-        <Card borderRadius={12}>
+        <Card>
           <CardHeading>Product Launch Announcement</CardHeading>
           <CardDivider />
           <div style={{ margin: 0 }}>
@@ -163,7 +171,7 @@ export const ComplexContent: Story = {
 
       <SBContainer addBackground>
         <h4>Card with Multiple Elements</h4>
-        <Card borderRadius={8}>
+        <Card>
           <CardHeading>Multi-Section Card</CardHeading>
           <CardDivider />
           <div style={{ margin: 0 }}>
@@ -223,7 +231,7 @@ export const InteractionStates: Story = {
           Card wrapped in a link becomes clickable and shows hover/focus states
         </p>
         <a href="https://www.hubspot.com" style={{ textDecoration: 'none' }}>
-          <Card borderRadius={8}>
+          <Card>
             <CardHeading>Clickable Feature Card</CardHeading>
             <CardDivider />
             <CardContent>
@@ -243,7 +251,7 @@ export const InteractionStates: Story = {
         </p>
         <SBFocusWrapper>
           <a href="https://www.hubspot.com" style={{ textDecoration: 'none' }}>
-            <Card borderRadius={8}>
+            <Card>
               <CardHeading>Focused Card</CardHeading>
               <CardDivider />
               <CardContent>

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

@@ -1,7 +1,30 @@
 .cardContainer {
-  /* Base container for stories */
-  /* Default elevated variant always applied */
-  --hscl-card-backgroundColor: #ffffff;
-  --hscl-card-boxShadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  --hscl-card-boxShadow-hover: 0 4px 16px rgba(0, 0, 0, 0.15);
+  /* card Variant Styles */
+  :global([data-card-variant='cardStyle1']) {
+    --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']) {
+    --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']) {
+    --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']) {
+    --hs-card-borderRadius: 10px;
+    --hs-card-backgroundColor: rgb(36, 36, 36);
+    --hs-card-color: rgb(255,255,255);
+    --hs-card-border: 1px solid #e0e0e0;
+  }
 }

package/components/componentLibrary/Card/types.ts

@@ -1,18 +1,21 @@
-export type CardVariant = 'elevated' | 'outlined' | 'filled';
+export type CardVariant =
+  | 'cardStyle1'
+  | 'cardStyle2'
+  | 'cardStyle3'
+  | 'cardStyle4';
 
 export type CardAs = 'div' | 'article' | 'section';
 
 export type CardProps = {
   variant?: CardVariant;
   as?: CardAs;
-  borderRadius?: number;
   children?: React.ReactNode;
   className?: string;
   style?: React.CSSProperties;
 };
 
 export type StyleFieldsProps = {
-  variantLabel?: string;
-  variantName?: string;
-  variantDefault?: CardVariant;
+  cardVariantLabel?: string;
+  cardVariantName?: string;
+  cardVariantDefault?: { variantName?: string, variant_name?: string };
 };

package/components/componentLibrary/Form/StyleFields.tsx

@@ -0,0 +1,19 @@
+import { VariantSelectionField } from '@hubspot/cms-components/fields';
+import { StyleFieldsProps } from './types.js';
+
+const StyleFields = ({
+  formVariantLabel = 'Form variant',
+  formVariantName = 'formVariant',
+  formVariantDefault = { variant_name: 'primaryForm' },
+}: StyleFieldsProps) => {
+  return (
+    <VariantSelectionField
+      label={formVariantLabel}
+      name={formVariantName}
+      variantDefinitionName="form"
+      default={formVariantDefault}
+    />
+  );
+};
+
+export default StyleFields;

package/components/componentLibrary/Form/index.tsx

@@ -5,6 +5,7 @@ import LegacyFormIsland from './islands/LegacyFormIsland.js?island';
 import { FormProps } from './types.js';
 import { Island } from '@hubspot/cms-components';
 import ContentFields from './ContentFields.js';
+import StyleFields from './StyleFields.js';
 
 const FormComponent = ({
   formField,
@@ -13,16 +14,21 @@ const FormComponent = ({
   ...rest
 }: FormProps) => {
   const resolvedFormId = formField != null ? formField.form_id : formId;
-  const FormModule = formVersion === 'v4' ? FormIsland : LegacyFormIsland;
+  const resolvedVersion =
+    formField != null ? formField.embed_version : formVersion;
+  const isV4 = resolvedVersion === 'v4';
+  const FormModule = isV4 ? FormIsland : LegacyFormIsland;
 
   return <Island module={FormModule} formId={resolvedFormId} {...rest} />;
 };
 
 type FormComponentType = typeof FormComponent & {
   ContentFields: typeof ContentFields;
+  StyleFields: typeof StyleFields;
 };
 
 const Form = FormComponent as FormComponentType;
 Form.ContentFields = ContentFields;
+Form.StyleFields = StyleFields;
 
 export default Form;

package/components/componentLibrary/Form/islands/FormIsland.tsx

@@ -1,6 +1,8 @@
 import { useEffect } from 'react';
 import { FormProps } from '../types.js';
 import { getHubID, getHSEnv } from '@hubspot/cms-components';
+import cx from '../../utils/classname.js';
+import styles from './v4Form.module.css';
 
 const getScriptSrc = (portalId: number, env: string) => {
   const host = env === 'qa' ? 'js.hsformsqa.net' : 'js.hsforms.net';
@@ -43,7 +45,7 @@ const FormIsland = ({ formId }: FormProps) => {
 
   return (
     <div
-      className="hs-form-frame"
+      className={cx('hs-form-html', styles.v4FormStyles)}
       data-form-id={formId}
       data-portal-id={portalId}
       data-env={resolvedEnv}

package/components/componentLibrary/Form/islands/LegacyFormIsland.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useId } from 'react';
 import { FormProps } from '../types.js';
 import { getHubID, getHSEnv } from '@hubspot/cms-components';
+import styles from './legacyForm.module.css';
 
 declare global {
   interface Window {
@@ -71,7 +72,7 @@ const LegacyFormIsland = ({ formId }: FormProps) => {
     return null;
   }
 
-  return <div id={containerId} />;
+  return <div id={containerId} className={styles.legacyFormStyles} />;
 };
 
 export default LegacyFormIsland;