**Note that all of the following are suggestions and should be amended on a component to component basis.**

# [COMPONENT_NAME] Component

[One-sentence description of what this component does and its primary use case. Important to highlight if it's interactive (an island).]

## Import path
`@hubspot/cms-component-library/[COMPONENT_NAME]`

## Purpose

[2-3 sentences explaining:
- What problem this component solves
- When developers should use it
- Key functionality or features
- Any important behavioral notes or defaults]

## Component Structure

```
[COMPONENT_NAME]/
├── index.tsx                     # [Brief description of main file]
├── types.ts                      # [Brief description of types file, if exists]
├── [FIELD_FILE_1].tsx           # [Brief description, e.g., "HubSpot field definitions for content"]
├── [FIELD_FILE_2].tsx           # [Brief description, e.g., "HubSpot field definitions for styling"]
├── index.module.scss             # [Brief description, e.g., "CSS module with design tokens"]
└── stories/
    ├── [StoryFile1].stories.tsx  # [Brief description of story purpose]
    ├── [StoryFile2].stories.tsx  # [Brief description of story purpose]
    ├── [Component]Args.ts        # [Brief description, usually "Storybook argument types"]
    ├── [Component]Decorator.tsx  # [Brief description, usually "Storybook decorator"]
    └── [Component]Decorator.module.css  # [Brief description, usually "Decorator styles"]
```

## Components

### [COMPONENT_NAME] (Main Component)

**Purpose:** [One sentence describing the component's main purpose and functionality]

**Props:**
```tsx
{
  [propName1]?: [type];  // [Description of what this prop does]
  [propName2]?: [type];  // [Description of what this prop does]
  [propName3]?: [type];  // [Description of what this prop does]
  // ... continue for all props
}
```

[If component has multiple variants/types, add sections for each:]

**[Variant/Type Name] - Additional Props:**
```tsx
{
  [variantProp1]: [type];  // [Description]
  [variantProp2]?: [type]; // [Description]
}
```

## Usage Examples

### Island Usage (If applicable)
[Include instructions on how to consume the component as an island if it has interactive pieces. Likely one of two options will appear. If the component contains `Island` usage then the component is just consumed normally `<Component>`. Otherwise -- the component will need to be consumed in an island context when implemented `<Island module={Component} {...props}/>]

[Not all Components will have an island usage. If unclear please ask.]

[More docs on islands](https://developers.hubspot.com/docs/cms/reference/react/islands#islands)
### [Example 1 Name - Most Common Use Case]

```tsx
import [COMPONENT_NAME] from '@components/componentLibrary/[COMPONENT_NAME]';

<[COMPONENT_NAME]
  [prop1]="[value]"
  [prop2]={[value]}
>
  [Content if applicable]
</[COMPONENT_NAME]>
```

### [Example 2 Name - Second Most Common Use Case]

```tsx
<[COMPONENT_NAME]
  [prop1]="[value]"
  [prop2]={[value]}
>
  [Content if applicable]
</[COMPONENT_NAME]>
```

### [Example 3 Name - Important Variant or Edge Case]

```tsx
<[COMPONENT_NAME]
  [prop1]="[value]"
  [prop2]={[value]}
>
  [Content if applicable]
</[COMPONENT_NAME]>
```

[Continue with 5-8 examples total covering:]
- Basic usage
- Common variants
- Edge cases
- With other props/features
- Custom styling
- Accessibility features

## HubSpot CMS Integration

### Field Definitions

[Brief description of field definitions and their purpose for HubSpot CMS modules.]

#### [FieldFile1].tsx

[Description of what this field file configures]

```tsx
<[COMPONENT_NAME].[FieldFile1]
  [fieldProp1]="[value]"
  [fieldProp2]="[value]"
  [fieldProp3]={[value]}
/>
```

**Fields:**
- `[fieldName1]`: [FieldType] for [description]
- `[fieldName2]`: [FieldType] for [description]
- `[fieldName3]`: [FieldType] for [description]

#### [FieldFile2].tsx

[Description of what this field file configures]

```tsx
<[COMPONENT_NAME].[FieldFile2]
  [fieldProp1]="[value]"
  [fieldProp2]="[value]"
/>
```

**Fields:**
- `[fieldName1]`: [FieldType] for [description]
- `[fieldName2]`: [FieldType] for [description]

### Module Usage Example

```tsx
import [COMPONENT_NAME] from '@hubspot/cms-component-library/[COMPONENT_NAME]';

const [ModuleName] = ({ fieldValues }) => {
  return (
    <[COMPONENT_NAME]
      [prop1]={fieldValues.[fieldValue1]}
      [prop2]={fieldValues.[fieldValue2]}
    >
      {fieldValues.[contentField]}
    </[COMPONENT_NAME]>
  );
};

export default [ModuleName];
```

## Styling

### CSS Variables

[Brief description of the CSS variable system used in this component]

**Base Styles:**
- `--hscl-[component]-[property]`: [Description and default value]
- `--hscl-[component]-[property]`: [Description and default value]
- `--hscl-[component]-[property]`: [Description and default value]

**[State Name] States:** [e.g., Hover, Focus, Active, Disabled]
- `--hscl-[component]-[property]-[state]`: [Description]
- `--hscl-[component]-[property]-[state]`: [Description]

[Add additional state sections as needed]

### Custom Styling Example

```tsx
<[COMPONENT_NAME]
  [props]="[values]"
  style={{
    '--hscl-[component]-[property]': '[value]',
    '--hscl-[component]-[property]': '[value]',
  }}
>
  [Content]
</[COMPONENT_NAME]>
```

## Accessibility

[Brief introduction to accessibility features]

- **[Feature 1]**: [Description of accessibility feature]
- **[Feature 2]**: [Description of accessibility feature]
- **[Feature 3]**: [Description of accessibility feature]
  - [Sub-point if needed]
  - [Sub-point if needed]
- **[Feature 4]**: [Description of accessibility feature]

[Include keyboard navigation, focus management, ARIA attributes, semantic HTML, etc.]

## Best Practices

- **[Practice 1]**: [Explanation of why and when to follow this practice]
- **[Practice 2]**: [Explanation of why and when to follow this practice]
- **[Practice 3]**: [Explanation of why and when to follow this practice]
- **[Practice 4]**: [Explanation of why and when to follow this practice]
- **[Practice 5]**: [Explanation of why and when to follow this practice]

[Include 3-7 best practices covering:]
- When to use this component vs alternatives
- Common pitfalls to avoid
- Performance considerations
- Styling recommendations
- Integration patterns
- How to use as an island (if applicable)

## Common Patterns

### [Pattern 1 Name]

```tsx
<[COMPONENT_NAME]
  [props specific to this pattern]
>
  [Content]
</[COMPONENT_NAME]>
```

### [Pattern 2 Name]

```tsx
<[COMPONENT_NAME]
  [props specific to this pattern]
>
  [Content]
</[COMPONENT_NAME]>
```

### [Pattern 3 Name]

```tsx
<[COMPONENT_NAME]
  [props specific to this pattern]
>
  [Content]
</[COMPONENT_NAME]>
```

[Include 1-4 common patterns that show real-world use cases]

## Related Components

- **[Related Component 1]**: [Brief description of relationship and when to use together]
- **[Related Component 2]**: [Brief description of relationship and when to use together]

[Only include if there are related components that are commonly used together]
