@hubspot/cms-component-library 0.2.0 → 0.3.1

package/components/componentLibrary/Button/StyleFields.tsx

@@ -1,11 +1,21 @@
-import { ChoiceField } from '@hubspot/cms-components/fields';
+import { ChoiceField, Visibility } from '@hubspot/cms-components/fields';
 import { StyleFieldsProps } from './types.js';
 
 const StyleFields = ({
   buttonVariantLabel = 'Button variant',
   buttonVariantName = 'buttonVariant',
   buttonVariantDefault = 'primary',
+  buttonIconPositionLabel = 'Icon position',
+  buttonIconPositionName = 'buttonIconPosition',
+  buttonIconPositionDefault = 'right',
 }: StyleFieldsProps) => {
+  // iconComponentShowIcon is the hardcoded id in @components/componentLibrary/Icon/ContentFields.tsx
+  const iconPositionVisibility: Visibility = {
+    operator: 'EQUAL',
+    controlling_field: 'iconComponentShowIcon',
+    controlling_value_regex: 'true',
+  };
+
   return (
     <>
       <ChoiceField
@@ -18,6 +28,16 @@ const StyleFields = ({
         ]}
         default={buttonVariantDefault}
       />
+      <ChoiceField
+        label={buttonIconPositionLabel}
+        name={buttonIconPositionName}
+        choices={[
+          ['left', 'Left'],
+          ['right', 'Right'],
+        ]}
+        default={buttonIconPositionDefault}
+        visibility={iconPositionVisibility}
+      />
     </>
   );
 };

package/components/componentLibrary/Button/index.tsx

@@ -39,7 +39,7 @@ const ButtonComponent = ({
     const icon = (
       <Icon
         fieldPath={iconFieldPath}
-        height={iconSize}
+        size={iconSize}
         className={styles.icon}
         showIcon={showIcon}
         purpose={iconPurpose}

package/components/componentLibrary/Button/llm.txt

@@ -234,18 +234,22 @@ Configurable props for customizing field labels, names, and defaults:
 
 #### StyleFields.tsx
 
-Configurable props for variant selection:
+Configurable props for variant and icon position:
 
 ```tsx
 <Button.StyleFields
   buttonVariantLabel="Button variant"
   buttonVariantName="buttonVariant"
   buttonVariantDefault="primary"
+  buttonIconPositionLabel="Icon position"
+  buttonIconPositionName="buttonIconPosition"
+  buttonIconPositionDefault="right"
 />
 ```
 
 **Fields:**
 - `buttonVariant`: ChoiceField for selecting visual style (primary, secondary, tertiary)
+- `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
 

package/components/componentLibrary/Button/types.ts

@@ -4,6 +4,8 @@ import {
 } from '@hubspot/cms-components/fields';
 import { IconContentFieldsWithToggleProps } from '../Icon/types.js';
 
+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.
@@ -11,7 +13,7 @@ export type BaseButtonProps = {
   style?: React.CSSProperties;
   children?: React.ReactNode;
   iconFieldPath?: string;
-  iconPosition?: 'left' | 'right';
+  iconPosition?: IconPositionHorizontal;
   iconSize?: number;
   showIcon?: boolean;
   iconPurpose?: 'SEMANTIC' | 'DECORATIVE';
@@ -56,6 +58,9 @@ export type StyleFieldsProps = {
   buttonVariantLabel?: string;
   buttonVariantName?: string;
   buttonVariantDefault?: string;
+  buttonIconPositionLabel?: string;
+  buttonIconPositionName?: string;
+  buttonIconPositionDefault?: IconPositionHorizontal;
 };
 
 export type RenderWithIconProps = Pick<

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

@@ -9,12 +9,10 @@
   align-items: var(--hscl-flex-alignItems, stretch);
   align-content: var(--hscl-flex-alignContent, stretch);
   gap: var(--hscl-flex-gap, 0);
-  padding: var(--hscl-flex-padding, 0);
-  padding-inline: var(--hscl-flex-paddingInline);
-  padding-block: var(--hscl-flex-paddingBlock);
-  margin: var(--hscl-flex-margin, 0);
-  margin-inline: var(--hscl-flex-marginInline);
-  margin-block: var(--hscl-flex-marginBlock);
+  padding-inline: var(--hscl-flex-paddingInline, 0);
+  padding-block: var(--hscl-flex-paddingBlock, 0);
+  margin-inline: var(--hscl-flex-marginInline, 0);
+  margin-block: var(--hscl-flex-marginBlock, 0);
   max-width: var(--hscl-flex-maxWidth, 100%);
   max-height: var(--hscl-flex-maxHeight, auto);
 }

package/components/componentLibrary/Flex/llm.txt

@@ -47,7 +47,7 @@ Flex/
   maxHeight?: string;  // Maximum height constraint
   inline?: boolean;  // Use inline-flex instead of flex (default: false)
   className?: string;  // Additional CSS classes
-  style?: React.CSSProperties;  // Inline styles
+  style?: CSSVariables;  // Inline styles and CSS variable overrides
   children?: React.ReactNode;  // Child elements
 }
 ```
@@ -169,12 +169,10 @@ The Flex component uses CSS variables for all styling properties:
 - `--hscl-flex-alignItems`: Cross axis alignment (default: 'stretch')
 - `--hscl-flex-alignContent`: Multi-line alignment (default: 'stretch')
 - `--hscl-flex-gap`: Gap between items
-- `--hscl-flex-padding`: Padding (default: 0)
-- `--hscl-flex-paddingInline`: Horizontal padding
-- `--hscl-flex-paddingBlock`: Vertical padding
-- `--hscl-flex-margin`: Margin (default: 0)
-- `--hscl-flex-marginInline`: Horizontal margin
-- `--hscl-flex-marginBlock`: Vertical margin
+- `--hscl-flex-paddingInline`: Horizontal padding (default: 0)
+- `--hscl-flex-paddingBlock`: Vertical padding (default: 0)
+- `--hscl-flex-marginInline`: Horizontal margin (default: 0)
+- `--hscl-flex-marginBlock`: Vertical margin (default: 0)
 - `--hscl-flex-maxWidth`: Maximum width (default: 100%)
 - `--hscl-flex-maxHeight`: Maximum height (default: auto)
 

package/components/componentLibrary/Flex/types.ts

@@ -48,12 +48,8 @@ export type FlexProps = {
   alignItems?: FlexAlignItems;
   alignContent?: FlexAlignContent;
   gap?: string;
-  rowGap?: string;
-  columnGap?: string;
-  padding?: string;
   paddingInline?: string;
   paddingBlock?: string;
-  margin?: string;
   marginInline?: string;
   marginBlock?: string;
   inline?: boolean;

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

@@ -4,6 +4,6 @@
   justify-content: center;
   fill: var(--hscl-icon-fill);
   stroke: var(--hscl-icon-stroke);
-  width: var(--hscl-icon-width); // !todo: not sure if we want this or not
-  height: var(--hscl-icon-height); // !todo: not sure if we want this or not
+  width: var(--hscl-icon-size);
+  height: var(--hscl-icon-size);
 }

package/components/componentLibrary/Icon/index.tsx

@@ -8,7 +8,7 @@ import { IconProps } from './types.js';
 const IconComponent = ({
   fieldPath,
   showIcon = true,
-  height = 12,
+  size = 12,
   className = '',
   style = {},
   purpose = 'DECORATIVE',
@@ -21,13 +21,14 @@ const IconComponent = ({
   const combinedClasses = cx(defaultClasses, className);
 
   const cssVariables: CSSVariables = {
+    '--hscl-icon-size': `${size}px`,
     ...(fill && { '--hscl-icon-fill': fill }),
   };
 
   return (
     <CMSIcon
       fieldPath={fieldPath}
-      height={height}
+      height={size}
       className={combinedClasses}
       style={{ ...cssVariables, ...style }}
       purpose={purpose}

package/components/componentLibrary/Icon/llm.txt

@@ -35,7 +35,7 @@ Icon/
 ```tsx
 {
   fieldPath?: string;                              // Path to icon in HubSpot fields
-  height?: number;                                 // Icon height in pixels (default: 12)
+  size?: number;                                   // Icon size in pixels, sets both width and height (default: 12)
   fill?: string;                                   // Icon fill color (overrides CSS variable)
   className?: string;                              // Additional CSS classes
   style?: React.CSSProperties;                     // Inline styles (including CSS variables)
@@ -54,7 +54,7 @@ import Icon from '@hubspot/cms-component-library/Icon';
 
 <Icon
   fieldPath="icon"
-  height={24}
+  size={24}
 />
 ```
 
@@ -63,7 +63,7 @@ import Icon from '@hubspot/cms-component-library/Icon';
 ```tsx
 <Icon
   fieldPath="icon"
-  height={24}
+  size={24}
   purpose="SEMANTIC"
   title="Download file"
 />
@@ -74,7 +74,7 @@ import Icon from '@hubspot/cms-component-library/Icon';
 ```tsx
 <Icon
   fieldPath="icon"
-  height={32}
+  size={32}
   fill="#FF7A59"
 />
 ```
@@ -84,7 +84,7 @@ import Icon from '@hubspot/cms-component-library/Icon';
 ```tsx
 <Icon
   fieldPath="icon"
-  height={20}
+  size={20}
   showIcon={shouldShowIcon}
 />
 ```
@@ -128,7 +128,7 @@ export default function IconModule({ fieldValues }) {
   return (
     <Icon
       fieldPath="icon"
-      height={fieldValues.iconSize || 24}
+      size={fieldValues.iconSize || 24}
       showIcon={fieldValues.showIcon}
       purpose="DECORATIVE"
     />
@@ -159,6 +159,7 @@ The Icon component uses CSS variables for theming and customization:
 
 **Base Styles:**
 - `--hscl-icon-fill`: Icon fill color (default: currentColor)
+- `--hscl-icon-size`: Icon width and height (set automatically from the `size` prop)
 
 
 ## Accessibility

package/components/componentLibrary/Icon/stories/Icon.stories.tsx

@@ -25,7 +25,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     fieldPath: 'icon',
-    height: 24,
+    size: 24,
     showIcon: true,
     purpose: 'DECORATIVE',
   },
@@ -37,27 +37,27 @@ export const IconSizes: Story = {
     <SBContainer flex direction="row" gap="large" alignItems="center">
       <SBContainer addBackground flex alignItems="center">
         <h4>12px (default)</h4>
-        <Icon fieldPath="icon" height={12} />
+        <Icon fieldPath="icon" size={12} />
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>16px</h4>
-        <Icon fieldPath="icon" height={16} />
+        <Icon fieldPath="icon" size={16} />
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>24px</h4>
-        <Icon fieldPath="icon" height={24} />
+        <Icon fieldPath="icon" size={24} />
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>32px</h4>
-        <Icon fieldPath="icon" height={32} />
+        <Icon fieldPath="icon" size={32} />
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>48px</h4>
-        <Icon fieldPath="icon" height={48} />
+        <Icon fieldPath="icon" size={48} />
       </SBContainer>
     </SBContainer>
   ),
@@ -69,34 +69,34 @@ export const Colors: Story = {
     <SBContainer flex direction="row" gap="large" alignItems="center">
       <SBContainer addBackground flex alignItems="center">
         <h4>Default (currentColor)</h4>
-        <Icon fieldPath="icon" height={32} />
+        <Icon fieldPath="icon" size={32} />
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>Blue Fill</h4>
         <div className={styles.blueFill}>
-          <Icon fieldPath="icon" height={32} />
+          <Icon fieldPath="icon" size={32} />
         </div>
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>Red Fill</h4>
         <div className={styles.redFill}>
-          <Icon fieldPath="icon" height={32} />
+          <Icon fieldPath="icon" size={32} />
         </div>
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>Green Fill</h4>
         <div className={styles.greenFill}>
-          <Icon fieldPath="icon" height={32} />
+          <Icon fieldPath="icon" size={32} />
         </div>
       </SBContainer>
 
       <SBContainer addBackground flex alignItems="center">
         <h4>Custom Stroke</h4>
         <div className={styles.customStroke}>
-          <Icon fieldPath="icon" height={32} />
+          <Icon fieldPath="icon" size={32} />
         </div>
       </SBContainer>
     </SBContainer>

package/components/componentLibrary/Icon/stories/IconDecorator.module.scss

@@ -2,8 +2,7 @@
   padding: 20px;
   --hscl-icon-fill: currentColor;
   --hscl-icon-stroke: none;
-  --hscl-icon-width: auto;
-  --hscl-icon-height: auto;
+  --hscl-icon-size: auto;
 }
 
 .blueFill {

package/components/componentLibrary/Icon/types.ts

@@ -7,7 +7,7 @@ export type IconPurpose = 'SEMANTIC' | 'DECORATIVE';
 
 export type IconProps = {
   fieldPath?: string;
-  height?: number;
+  size?: number;
   fill?: string;
   className?: string;
   style?: React.CSSProperties;

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

@@ -7,7 +7,7 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 **Pattern:** `--hscl-componentName-[elementName]-cssProperty-[state]`
 
 - **Prefix:** Always start with `--hscl-` (HubSpot Component Library)
-- **Component name:** Lowercase component name in camelCase, with name taken from the index.tsx file (e.g., `button`, `heading`, `icon`, `divider`, `image`, `accordion`)
+- **Component name:** Lowercase component name in camelCase, with name taken from the index.tsx file (e.g., `button`, `icon`, `divider`, `image`, `accordion`, `card`)
 - **Element name (optional):** For sub-elements within a component, specify the element name in camelCase (e.g., `icon`, `body`, `title`, `header`, `overlay`, `submenu`)
   - Omit for properties that apply to the main component element itself
   - Include for properties that apply to specific sub-elements
@@ -19,8 +19,6 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 --hscl-button-backgroundColor
 --hscl-button-backgroundColor-hover
 --hscl-button-backgroundColor-focus
---hscl-heading-fontSize
---hscl-heading-textAlign
 --hscl-divider-borderColor
 --hscl-icon-fill
 --hscl-card-padding
@@ -47,12 +45,12 @@ This document outlines CSS variable naming conventions, styling patterns, and CS
 
 **Nested/Dynamic Variables:**
 ```typescript
-// Example from Heading component - uses template variables
-'--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`
-'--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`
+// Components can use template variables to dynamically reference nested variables
+'--hscl-component-font': `var(--hscl-component-${variantValue}-font)`
+'--hscl-component-fontSize': `var(--hscl-component-${variantValue}-fontSize)`
 ```
 
-**Note:** When using dynamic variants (like h1, h2, display1), use numbers without underscores (e.g., `display1` not `display_1`).
+**Note:** When using dynamic variants, use numbers without underscores (e.g., `variant1` not `variant_1`).
 
 ## CSS Variables Application
 
@@ -105,15 +103,6 @@ const elementStyle: CSSVariables = {
 ```typescript
 import type { CSSVariables } from '../utils/types.js';
 
-// Heading - dynamic variable references
-const cssVariables: CSSVariables = {
-  '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
-  '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
-  ...(alignment && {
-    '--hscl-heading-textAlign': alignment.toLowerCase(),
-  }),
-};
-
 // Divider - direct values with units
 const cssVariables: CSSVariables = {
   '--hscl-divider-alignment': getAlignmentCSSVar(alignment),
@@ -235,8 +224,8 @@ Variables can reference other variables for dynamic behavior:
 
 ```typescript
 const cssVariables = {
-  '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
-  '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
+  '--hscl-component-font': `var(--hscl-component-${variantValue}-font)`,
+  '--hscl-component-fontSize': `var(--hscl-component-${variantValue}-fontSize)`,
 };
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/cms-component-library",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "HubSpot CMS React component library for building CMS modules",
   "license": "Apache-2.0",
   "exports": {
@@ -16,7 +16,8 @@
     "url": "git@git.hubteam.com:HubSpot/cms-component-library.git"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "type": "module",
   "dependencies": {

package/components/componentLibrary/Heading/ContentFields.tsx

@@ -1,37 +0,0 @@
-import { ChoiceField, TextField } from '@hubspot/cms-components/fields';
-import type { ContentFieldsProps } from './types.js';
-
-const ContentFields = ({
-  headingTextLabel = 'Heading text',
-  headingTextName = 'headingText',
-  headingTextDefault = 'Heading Text',
-  headingLevelLabel = 'Heading level',
-  headingLevelName = 'headingLevel',
-  headingLevelDefault = 'h1',
-}: ContentFieldsProps) => {
-  return (
-    <>
-      <TextField
-        label={headingTextLabel}
-        name={headingTextName}
-        default={headingTextDefault}
-      />
-      <ChoiceField
-        label={headingLevelLabel}
-        name={headingLevelName}
-        choices={[
-          ['h1', 'h1'],
-          ['h2', 'h2'],
-          ['h3', 'h3'],
-          ['h4', 'h4'],
-          ['h5', 'h5'],
-          ['h6', 'h6'],
-        ]}
-        required={true}
-        default={headingLevelDefault}
-      />
-    </>
-  );
-};
-
-export default ContentFields;

package/components/componentLibrary/Heading/StyleFields.tsx

@@ -1,40 +0,0 @@
-import { AlignmentField, ChoiceField } from '@hubspot/cms-components/fields';
-import type { StyleFieldsProps } from './types.js';
-
-const StyleFields = ({
-  textAlignLabel = 'Heading alignment',
-  textAlignName = 'headingTextAlign',
-  textAlignDefault = 'LEFT',
-  displayAsLabel = 'Display as',
-  displayAsName = 'headingDisplayAs',
-  displayAsDefault = 'h1',
-}: StyleFieldsProps) => {
-  return (
-    <>
-      <AlignmentField
-        label={textAlignLabel}
-        name={textAlignName}
-        alignmentDirection="HORIZONTAL"
-        default={{ horizontal_align: textAlignDefault }}
-      />
-      <ChoiceField
-        label={displayAsLabel}
-        name={displayAsName}
-        choices={[
-          ['h1', 'h1'],
-          ['h2', 'h2'],
-          ['h3', 'h3'],
-          ['h4', 'h4'],
-          ['h5', 'h5'],
-          ['h6', 'h6'],
-          ['display_1', 'Display 1'],
-          ['display_2', 'Display 2'],
-        ]}
-        required={true}
-        default={displayAsDefault}
-      />
-    </>
-  );
-};
-
-export default StyleFields;

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

@@ -1,11 +0,0 @@
-.heading {
-  font-family: var(--hscl-heading-font);
-  font-size: var(--hscl-heading-fontSize);
-  font-style: var(--hscl-heading-fontStyle);
-  font-weight: var(--hscl-heading-fontWeight);
-  line-height: var(--hscl-heading-lineHeight);
-  margin-block: var(--hscl-heading-margin);
-  color: var(--hscl-heading-color);
-  text-align: var(--hscl-heading-textAlign);
-}
-

package/components/componentLibrary/Heading/index.tsx

@@ -1,52 +0,0 @@
-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 { HeadingProps } from './types.js';
-
-const HeadingComponent = ({
-  headingLevel,
-  displayAs,
-  textAlign,
-  className = '',
-  style = {},
-  children = 'A clear and bold heading',
-  ...rest
-}: HeadingProps) => {
-  const HeadingLevel = headingLevel;
-  const displayAsValue = displayAs || headingLevel;
-
-  const cssVariables: CSSVariables = {
-    '--hscl-heading-font': `var(--hscl-heading-${displayAsValue}-font)`,
-    '--hscl-heading-fontSize': `var(--hscl-heading-${displayAsValue}-fontSize)`,
-    '--hscl-heading-fontStyle': `var(--hscl-heading-${displayAsValue}-fontStyle)`,
-    '--hscl-heading-fontWeight': `var(--hscl-heading-${displayAsValue}-fontWeight)`,
-    ...(textAlign && {
-      '--hscl-heading-textAlign': textAlign.toLowerCase(),
-    }),
-  };
-
-  const defaultClasses = cx(styles.heading, className);
-
-  return (
-    <HeadingLevel
-      className={defaultClasses}
-      style={{ ...cssVariables, ...style }}
-      {...rest}
-    >
-      {children}
-    </HeadingLevel>
-  );
-};
-
-type HeadingComponentType = typeof HeadingComponent & {
-  ContentFields: typeof ContentFields;
-  StyleFields: typeof StyleFields;
-};
-
-const Heading = HeadingComponent as HeadingComponentType;
-Heading.ContentFields = ContentFields;
-Heading.StyleFields = StyleFields;
-
-export default Heading;

package/components/componentLibrary/Heading/llm.txt

@@ -1,175 +0,0 @@
-# Heading Component
-
-A semantic heading component that renders HTML heading elements (h1-h6) with flexible visual styling and alignment controls, allowing the semantic level to differ from the visual appearance.
-
-## Import path
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-```
-
-## Purpose
-
-The Heading component provides proper semantic structure while maintaining visual design flexibility. It solves the common challenge where semantic HTML hierarchy (h1-h6) needs to differ from visual styling - for example, an h3 element styled to look like an h1. This separation of semantic meaning from visual presentation ensures both accessibility and design consistency.
-
-## Component Structure
-
-```
-Heading/
-├── index.tsx                      # Main component with render logic
-├── types.ts                       # TypeScript type definitions
-├── ContentFields.tsx              # HubSpot field definitions for content
-├── StyleFields.tsx                # HubSpot field definitions for styling
-├── index.module.scss              # CSS module with design tokens
-└── stories/
-    ├── Heading.stories.tsx        # Component usage examples
-    ├── HeadingDecorator.tsx       # Storybook decorator
-    └── HeadingDecorator.module.css # Decorator styles
-```
-
-## Props
-
-```tsx
-{
-  headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';  // Semantic HTML level (required)
-  displayAs?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display_1' | 'display_2';  // Visual style (defaults to headingLevel)
-  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT';  // Text alignment
-  className?: string;  // Additional CSS classes
-  style?: React.CSSProperties;  // Inline styles (including CSS variables)
-  children?: React.ReactNode;  // Heading text content
-}
-```
-
-## Usage Examples
-
-### Basic Heading
-
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-
-<Heading headingLevel="h1">
-  Welcome to Our Site
-</Heading>
-```
-
-### Semantic vs Visual Styling
-
-When you need a lower-level heading to look like a higher-level one:
-
-```tsx
-<Heading
-  headingLevel="h3"  // Semantic: third-level heading
-  displayAs="h1"     // Visual: styled like an h1
->
-  Section Title
-</Heading>
-```
-
-### With Text Alignment
-
-```tsx
-<Heading
-  headingLevel="h2"
-  textAlign="CENTER"
->
-  Centered Heading
-</Heading>
-```
-
-
-## HubSpot CMS Integration
-
-### Field Definitions
-
-#### ContentFields.tsx
-
-```tsx
-<Heading.ContentFields
-  headingTextLabel="Heading text"
-  headingTextName="headingText"
-  headingTextDefault="Heading Text"
-  headingLevelLabel="Heading Level"
-  headingLevelName="headingLevel"
-  headingLevelDefault="h1"
-/>
-```
-
-**Fields:**
-- `headingText`: TextField for heading content
-- `headingLevel`: ChoiceField for semantic level (h1-h6)
-
-#### StyleFields.tsx
-
-```tsx
-<Heading.StyleFields
-  textAlignLabel="Heading text align"
-  textAlignName="headingTextAlign"
-  textAlignDefault="LEFT"
-  displayAsLabel="Display as"
-  displayAsName="headingDisplayAs"
-  displayAsDefault="h1"
-/>
-```
-
-**Fields:**
-- `headingTextAlign`: AlignmentField for text alignment
-- `headingDisplayAs`: ChoiceField for visual style (h1-h6, display_1, display_2)
-
-### Module Usage Example
-
-```tsx
-import Heading from '@hubspot/cms-component-library/Heading';
-
-export default function HeroModule({ fieldValues }) {
-  return (
-    <Heading
-      headingLevel={fieldValues.headingLevel}
-      displayAs={fieldValues.headingDisplayAs}
-      textAlign={fieldValues.headingTextAlign?.horizontal_align}
-    >
-      {fieldValues.headingText}
-    </Heading>
-  );
-}
-```
-
-## Styling
-
-### CSS Variables
-
-The Heading component uses CSS variables for theming and customization:
-
-**Base Styles:**
-- `--hscl-heading-font`: Font family
-- `--hscl-heading-fontSize`: Font size (set by displayAs level)
-- `--hscl-heading-fontStyle`: Font style (set by displayAs level)
-- `--hscl-heading-fontWeight`: Font weight (set by displayAs level)
-- `--hscl-heading-lineHeight`: Line height
-- `--hscl-heading-margin`: Vertical margin (margin-block)
-- `--hscl-heading-color`: Text color
-- `--hscl-heading-textAlign`: Text alignment
-
-**Level-specific Variables:**
-Each heading level has its own design tokens:
-- `--hscl-heading-h1-font`, `--hscl-heading-h1-fontSize`, etc.
-- `--hscl-heading-h2-font`, `--hscl-heading-h2-fontSize`, etc.
-- Through `--hscl-heading-h6-font`, `--hscl-heading-h6-fontSize`, etc.
-- `--hscl-heading-display_1-font`, `--hscl-heading-display_1-fontSize`, etc.
-- `--hscl-heading-display_2-font`, `--hscl-heading-display_2-fontSize`, etc.
-
-## Accessibility
-
-The Heading component follows accessibility best practices:
-
-- **Semantic HTML**: Always renders the appropriate heading element (h1-h6) based on `headingLevel` for proper document structure
-- **Visual Hierarchy Independence**: The `displayAs` prop allows visual styling to differ from semantic structure, ensuring flexibility without breaking accessibility
-- **Proper Nesting**: Ensure headings follow logical order in your document (h1 → h2 → h3, etc.) regardless of visual styling
-- **Screen Readers**: Screen readers announce the semantic level (`headingLevel`), not the visual style
-- **Keyboard Navigation**: Native heading element support for keyboard navigation and focus management
-
-## Best Practices
-
-- **Follow semantic order**: Use headings in logical order (h1 for main title, h2 for sections, h3 for subsections, etc.)
-- **One h1 per page**: Each page should have exactly one h1 element representing the main topic
-- **Use displayAs for visual flexibility**: When you need a different visual style than the semantic level requires, use the `displayAs` prop
-- **Don't skip levels**: Don't jump from h2 to h4; maintain proper hierarchy
-

package/components/componentLibrary/Heading/stories/Heading.stories.tsx

@@ -1,88 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import Heading from '../index.js';
-import { HeadingProps } from '../types.js';
-import { withHeadingStyles } from './HeadingDecorator.js';
-import { SBContainer } from '@sb-utils/SBContainer.js';
-
-const meta: Meta<HeadingProps> = {
-  title: 'Component Library/Heading',
-  component: Heading,
-  parameters: {
-    layout: 'centered',
-    docs: {
-      description: {
-        component: `The Heading component provides a flexible and accessible way to render semantic HTML headings (h1-h6) with customizable visual styles through the displayAs prop.`,
-      },
-    },
-  },
-  decorators: [withHeadingStyles],
-};
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {
-    headingLevel: 'h2',
-    children: 'A clear and bold heading',
-  },
-};
-
-export const AllHeadingLevels: Story = {
-  name: 'All Heading Levels',
-  render: () => (
-    <SBContainer flex direction="column" gap="large">
-      <SBContainer addBackground>
-        <p>
-          Each heading level has different semantic meaning and default styling
-        </p>
-        <Heading headingLevel="h1">Heading Level 1</Heading>
-        <Heading headingLevel="h2">Heading Level 2</Heading>
-        <Heading headingLevel="h3">Heading Level 3</Heading>
-        <Heading headingLevel="h4">Heading Level 4</Heading>
-        <Heading headingLevel="h5">Heading Level 5</Heading>
-        <Heading headingLevel="h6">Heading Level 6</Heading>
-      </SBContainer>
-    </SBContainer>
-  ),
-};
-
-export const TextAlignment: Story = {
-  name: 'Text Alignment',
-  render: () => (
-    <SBContainer flex direction="column" gap="large" minWidth="500px">
-      <SBContainer addBackground>
-        <Heading headingLevel="h2" textAlign="LEFT">
-          Left Aligned
-        </Heading>
-      </SBContainer>
-      <SBContainer addBackground>
-        <Heading headingLevel="h2" textAlign="CENTER">
-          Center Aligned
-        </Heading>
-      </SBContainer>
-      <SBContainer addBackground>
-        <Heading headingLevel="h2" textAlign="RIGHT">
-          Right Aligned
-        </Heading>
-      </SBContainer>
-    </SBContainer>
-  ),
-};
-
-export const LongText: Story = {
-  name: 'Long Text',
-  render: () => (
-    <SBContainer flex direction="column" gap="large" maxWidth="500px">
-      <SBContainer addBackground>
-        <h4>Long Heading Text</h4>
-        <p>Headings should handle long text gracefully</p>
-        <Heading headingLevel="h2">
-          This is a very long heading that demonstrates how the component
-          handles extensive text content that may wrap across multiple lines in
-          the layout
-        </Heading>
-      </SBContainer>
-    </SBContainer>
-  ),
-};

package/components/componentLibrary/Heading/stories/HeadingDecorator.module.scss

@@ -1,47 +0,0 @@
-.decoratorContainer {
-  padding: 20px;
-  --hscl-heading-h1-font: Arial, sans-serif;
-  --hscl-heading-h1-fontSize: 48px;
-  --hscl-heading-h1-fontStyle: normal;
-  --hscl-heading-h1-fontWeight: 700;
-  --hscl-heading-h2-font: Arial, sans-serif;
-  --hscl-heading-h2-fontSize: 36px;
-  --hscl-heading-h2-fontStyle: normal;
-  --hscl-heading-h2-fontWeight: 600;
-  --hscl-heading-h3-font: Arial, sans-serif;
-  --hscl-heading-h3-fontSize: 28px;
-  --hscl-heading-h3-fontStyle: normal;
-  --hscl-heading-h3-fontWeight: 600;
-  --hscl-heading-h4-font: Arial, sans-serif;
-  --hscl-heading-h4-fontSize: 24px;
-  --hscl-heading-h4-fontStyle: normal;
-  --hscl-heading-h4-fontWeight: 500;
-  --hscl-heading-h5-font: Arial, sans-serif;
-  --hscl-heading-h5-fontSize: 20px;
-  --hscl-heading-h5-fontStyle: normal;
-  --hscl-heading-h5-fontWeight: 500;
-  --hscl-heading-h6-font: Arial, sans-serif;
-  --hscl-heading-h6-fontSize: 16px;
-  --hscl-heading-h6-fontStyle: normal;
-  --hscl-heading-h6-fontWeight: 500;
-  --hscl-heading-display_1-font: Arial, sans-serif;
-  --hscl-heading-display_1-fontSize: 72px;
-  --hscl-heading-display_1-fontStyle: normal;
-  --hscl-heading-display_1-fontWeight: 800;
-  --hscl-heading-display_2-font: Arial, sans-serif;
-  --hscl-heading-display_2-fontSize: 60px;
-  --hscl-heading-display_2-fontStyle: normal;
-  --hscl-heading-display_2-fontWeight: 800;
-  --hscl-heading-lineHeight: 1.2;
-  --hscl-heading-margin: 0;
-  --hscl-heading-color: #2d3e50;
-}
-
-.decoratorContainer h1,
-.decoratorContainer h2,
-.decoratorContainer h3,
-.decoratorContainer h4,
-.decoratorContainer h5,
-.decoratorContainer h6 {
-  margin-bottom: 1rem;
-}

package/components/componentLibrary/Heading/stories/HeadingDecorator.tsx

@@ -1,8 +0,0 @@
-import type { Decorator } from '@storybook/react';
-import styles from './HeadingDecorator.module.scss';
-
-export const withHeadingStyles: Decorator = Story => (
-  <div className={styles.decoratorContainer}>
-    <Story />
-  </div>
-);

package/components/componentLibrary/Heading/types.ts

@@ -1,35 +0,0 @@
-import {
-  AlignmentFieldDefaults,
-  TextFieldDefaults,
-} from '@hubspot/cms-components/fields';
-
-export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-
-export type DisplayAs = HeadingLevel | 'display_1' | 'display_2';
-
-export type HeadingProps = {
-  headingLevel: HeadingLevel;
-  displayAs?: DisplayAs;
-  textAlign?: (typeof AlignmentFieldDefaults)['horizontal_align'];
-  className?: string;
-  style?: React.CSSProperties;
-  children?: React.ReactNode;
-};
-
-export type ContentFieldsProps = {
-  headingTextLabel?: string;
-  headingTextName?: string;
-  headingTextDefault?: typeof TextFieldDefaults;
-  headingLevelLabel?: string;
-  headingLevelName?: string;
-  headingLevelDefault?: HeadingLevel;
-};
-
-export type StyleFieldsProps = {
-  textAlignLabel?: string;
-  textAlignName?: string;
-  textAlignDefault?: (typeof AlignmentFieldDefaults)['horizontal_align'];
-  displayAsLabel?: string;
-  displayAsName?: string;
-  displayAsDefault?: DisplayAs;
-};