# Component Style Prop Naming Patterns

**Default:** Use exact CSS property names for style props. Never abbreviate or modify them.

**Exception:** Use semantic names when describing intrinsic component characteristics (e.g., Divider's `thickness` instead of `borderWidth`). Use sparingly.

## Pattern Rules

### Rule 1: Main Component Props

For props that style the main component element, use the exact CSS property name with optional state suffix:

**Pattern:** `propertyState`

**Examples:**

- ✅ `color`, `colorHover`, `colorFocus`
- ✅ `backgroundColor`, `backgroundColorHover`, `backgroundColorFocus`
- ✅ `borderColor`, `borderWidth`, `borderStyle`
- ✅ `padding`, `paddingBlock`, `paddingInline`

**Common Mistakes:**

- ❌ `textColor` (wrong - use `color`)
- ❌ `background` (wrong - use `backgroundColor`)
- ❌ `bgColor` (wrong - use `backgroundColor`)

### Rule 2: Subcomponent Props

For props that style subcomponents or nested elements, prefix with the element name:

**Pattern:** `elementPropertyState`

**Examples:**

- ✅ `menuBackgroundColor`, `menuBackgroundColorHover`
- ✅ `linkColor`, `linkColorHover`
- ✅ `iconFill`, `iconStroke`
- ✅ `titleColor`, `contentPadding`

**Common Mistakes:**

- ❌ `menuTextColor` (wrong - use `menuColor`)
- ❌ `menuBackground` (wrong - use `menuBackgroundColor`)

### Rule 3: State Suffixes

State suffixes must be capitalized and match CSS pseudo-classes:

**Valid Suffixes:**

- `Hover` - for `:hover` state
- `Focus` - for `:focus` state
- `Active` - for `:active` state
- `Disabled` - for `:disabled` state
- `Visited` - for `:visited` state (links)
- `Checked` - for `:checked` state (inputs)

**Examples:**

- ✅ `colorHover`, `backgroundColorFocus`, `borderColorActive`
- ❌ `colorHOVER`, `colorHovering`, `colorOnHover`

## Field Props Pattern

Field configuration props (for CMS) build on the style prop name by adding standard suffixes:

**Pattern:** `{propName}Label`, `{propName}Name`, `{propName}Default`

**Examples:**
```typescript
// Style prop (follows CSS naming)
color?: ColorFieldValue;

// Field configuration props (use the prop name + suffix)
colorLabel?: string;
colorName?: string;
colorDefault?: ColorFieldValue;
```

**Important:** The field props inherit the correct naming from the style prop. If your style prop is `color`, your field props are `colorLabel`, `colorName`, `colorDefault` - not `textColorLabel`, `textColorName`, `textColorDefault`.

## Complete Component Example

### LanguageSwitcher (Reference Implementation)

```typescript
// types.ts
export type LanguageSwitcherProps = {
  // Main component styles
  color?: ColorFieldValue;
  colorHover?: ColorFieldValue;

  // Subcomponent styles
  menuBackgroundColor?: ColorFieldValue;
  menuBackgroundColorHover?: ColorFieldValue;
};

export type StyleFieldsProps = {
  // Field props for main component
  colorLabel?: string;
  colorName?: string;
  colorDefault?: ColorFieldValue;
  colorHoverLabel?: string;
  colorHoverName?: string;
  colorHoverDefault?: ColorFieldValue;

  // Field props for subcomponent
  menuBackgroundColorLabel?: string;
  menuBackgroundColorName?: string;
  menuBackgroundColorDefault?: ColorFieldValue;
  menuBackgroundColorHoverLabel?: string;
  menuBackgroundColorHoverName?: string;
  menuBackgroundColorHoverDefault?: ColorFieldValue;
};
```

```typescript
// index.tsx
const LanguageSwitcherComponent = ({
  color,
  colorHover,
  menuBackgroundColor,
  menuBackgroundColorHover,
}: LanguageSwitcherProps) => {
  const cssVariables = {
    ...(color?.rgba && { '--hscl-languageSwitcher-color': color.rgba }),
    ...(colorHover?.rgba && { '--hscl-languageSwitcher-color-hover': colorHover.rgba }),
    ...(menuBackgroundColor?.rgba && {
      '--hscl-languageSwitcher-backgroundColor': menuBackgroundColor.rgba
    }),
    ...(menuBackgroundColorHover?.rgba && {
      '--hscl-languageSwitcher-backgroundColor-hover': menuBackgroundColorHover.rgba
    }),
  };

  return <div style={cssVariables}>...</div>;
};
```

## Edge Cases

### 1. Multiple Background Properties

When a component needs multiple background-related properties, use exact CSS names:

- ✅ `backgroundColor`, `backgroundImage`, `backgroundSize`
- ❌ `background`, `bgImage`, `bgSize`

### 2. Logical Properties

Prefer logical properties for better internationalization:

- ✅ `paddingBlock`, `paddingInline`, `marginBlock`, `marginInline`
- ⚠️ `padding`, `margin` (acceptable but less specific)

### 3. Shorthand vs Longhand

When both exist, prefer the specific property:

- ✅ `borderColor`, `borderWidth`, `borderStyle` (specific)
- ⚠️ `border` (acceptable for simple use cases)

### 4. Prop Types

- **Style Props:** Use CSS property names (`color`, `backgroundColor`, `padding`)
- **Behavior Props:** Use descriptive names (`onClick`, `disabled`, `variant`)
- **Semantic Props:** Use sparingly for intrinsic characteristics (`thickness`, `length` for Divider)

### 5. Semantic Props Example

Divider uses semantic props because they describe what a divider *is*:

```typescript
thickness?: number;  // Divider's thickness (not borderWidth)
length?: number;     // Divider's length (abstracts width/height based on orientation)
spacing?: string;    // Space around it (abstracts marginBlock/marginInline)
```

Use semantic props when the name matches users' mental model better than CSS properties. Otherwise, use CSS property names.

### 6. HTML Attributes vs CSS Properties

Some props map to HTML attributes rather than CSS properties (e.g., Image's `width`/`height`):

```typescript
// Image component - props map to HTML attributes
width?: number;   // Sets <img width="..."> (intrinsic sizing)
height?: number;  // Sets <img height="..."> (intrinsic sizing)
```

This is acceptable because these control intrinsic rendering, not just styling. For CSS-based sizing, use `style` prop or `className`. If CSS props are needed in the future, they can be added separately (e.g., `cssWidth`).

### 7. Shared vs Subcomponent Styles

- Use `property` (main) when value is inherited/reused: `color`
- Use `elementProperty` (sub) when specific to a subcomponent: `menuBackgroundColor`
- Prefer sharing colors for consistency

## Validation

- ✅ Style props match exact CSS property names (no abbreviations)
- ✅ State suffixes are capitalized (`colorHover`)
- ✅ Subcomponent props include element prefix (`menuBackgroundColor`)
- ✅ Field props follow `{propName}Label/Name/Default` pattern
- ✅ Semantic props are documented and used sparingly

**When in doubt, use CSS property names.**
