# Theme and Styling Standards

This document covers the centralized theme system, color theming, and styling patterns used throughout the component library.

## Theme Provider System

All sections and components use a centralized ThemeProvider to maintain consistent styling across the entire site.

### Location & Setup

**Import:**
```tsx
import { ThemeProvider } from "@/providers/themeProvider/ThemeProvider";
```

**Usage:** Wrap the entire app/page (not individual sections) in a **single** ThemeProvider:

```tsx
export default function Page() {
  return (
    <ThemeProvider
      defaultButtonVariant="text-stagger"
      defaultTextAnimation="entrance-slide"
      borderRadius="rounded"
      contentWidth="medium"
      sizing="medium"
      background="animatedGrid"
      cardStyle="glass-flat"
      primaryButtonStyle="gradient"
      secondaryButtonStyle="glass"
      headingFontWeight="medium"
    >
      <HeroBillboard {...props} />
      <FeatureSection {...props} />
      <Footer {...props} />
    </ThemeProvider>
  );
}
```

### Theme Configuration Options

#### defaultButtonVariant
Controls the button style for ALL buttons in sections.

**Options:**
- `"text-stagger"` - Character stagger animation on hover (default)
- `"shift-hover"` - Text shifts on hover
- `"icon-arrow"` - Text + right arrow icon
- `"hover-magnetic"` - Cursor-tracking magnetic effect
- `"hover-bubble"` - Expanding circle on hover
- `"expand-hover"` - Width expansion on hover

#### defaultTextAnimation
Controls the text animation type for ALL text in sections.

**Options:**
- `"entrance-slide"` - Slide up from below (default)
- `"reveal-blur"` - Blur to clear reveal
- `"background-highlight"` - Background highlight effect

#### borderRadius
Controls border radius for buttons and cards.

**Options:**
- `"rounded"` - Standard rounded corners
- `"pill"` - Fully rounded (pill shape)
- `"sharp"` - No border radius

#### contentWidth
Controls the max width of section content.

**Options:**
- `"small"` - Narrow content width
- `"medium"` - Standard content width (default)
- `"large"` - Wide content width

Maps to `w-content-width` CSS class.

#### sizing
Controls spacing and size scale throughout components.

**Options:**
- `"small"` - Compact spacing
- `"medium"` - Standard spacing (default)
- `"large"` - Generous spacing

#### background
Default background pattern for the page.

**Options:**
- `"plain"` - Solid background color
- `"animatedGrid"` - Animated grid pattern
- `"aurora"` - Aurora gradient effect
- `"dotGrid"` - Dot grid pattern
- And more...

#### cardStyle
Visual style for all card components.

**Options:**
- `"glass-flat"` - Flat glass effect (default)
- `"glass-depth"` - Glass with depth/shadow
- `"glass-outline"` - Outlined glass
- `"solid-accent-light"` - Solid light accent
- `"outline"` - Simple outline
- `"elevated"` - Elevated shadow effect
- `"frosted"` - Frosted glass
- And more...

#### primaryButtonStyle
Style for primary buttons (first button in array).

**Options:**
- `"gradient"` - Gradient background
- `"solid"` - Solid color background
- `"glass"` - Glass effect
- `"outline"` - Outlined button

#### secondaryButtonStyle
Style for secondary buttons (second+ button in array).

**Options:**
- `"glass"` - Glass effect (default)
- `"outline"` - Outlined button
- `"solid"` - Solid color background
- `"gradient"` - Gradient background

#### headingFontWeight
Font weight for all headings.

**Options:**
- `"normal"` - Regular weight
- `"medium"` - Medium weight (default)
- `"semibold"` - Semi-bold weight
- `"bold"` - Bold weight

### Using Theme in Components

#### useTheme Hook

```tsx
import { useTheme } from "@/providers/themeProvider/ThemeProvider";

const Component = () => {
  const theme = useTheme();

  // Access theme properties:
  // - theme.defaultButtonVariant
  // - theme.defaultTextAnimation
  // - theme.borderRadius
  // - theme.cardStyle
  // - theme.contentWidth
  // - theme.sizing
  // - theme.background
  // - theme.primaryButtonStyle
  // - theme.secondaryButtonStyle
  // - theme.headingFontWeight

  return <div>{/* component */}</div>;
};
```

#### TextBox Component Example

TextBox automatically applies theme defaults:

```tsx
const TextBox = ({ type, buttons, ...props }: TextBoxProps) => {
  const theme = useTheme();

  // Use default text animation from theme if not specified
  const animationType = type || theme.defaultTextAnimation;

  // Button variant comes from theme
  const variant = theme.defaultButtonVariant;

  // ...
};
```

### Important Rules

❌ **DO NOT:**
- Specify button `variant` in section button configs (controlled by ThemeProvider)
- Wrap individual sections in ThemeProvider (use ONE provider per site/page)
- Override theme defaults unless explicitly required by component design

✅ **DO:**
- Wrap the entire app/page in a single ThemeProvider
- Let all sections inherit theme defaults automatically
- Use `useTheme()` hook to access theme configuration
- Document when components don't follow theme defaults (with clear reason)

## Color & Theming

### CSS Custom Properties

**Always use CSS custom properties for colors** to ensure theme consistency:

```tsx
// ✅ CORRECT - Uses theme variables
<div className="bg-background text-foreground">
  <button className="bg-foreground text-background">Click me</button>
</div>

// ❌ WRONG - Hardcoded colors break theming
<div className="bg-white text-black">
  <button className="bg-black text-white">Click me</button>
</div>
```

### Standard Color Variables

**Background & Text:**
- `bg-background` - Main background color
- `text-foreground` - Main text color
- `bg-foreground` - Inverse background (for buttons, accents)
- `text-background` - Inverse text (for text on dark backgrounds)

**Cards & Surfaces:**
- `card` - Card/surface background with border (theme-aware)
- Maps to different styles based on `theme.cardStyle`

**Buttons:**
- `primary-button` - Primary button styling (index 0)
- `secondary-button` - Secondary button styling (index 1+)

**Opacity Modifiers:**
```tsx
text-foreground/75    // 75% opacity
text-background/50    // 50% opacity
bg-foreground/10      // 10% opacity
```

### When to Use Theme Colors

✅ **Always prefer theme variables:**
- Backgrounds, text, borders, shadows
- Ensures proper dark mode support
- Allows theme customization
- Maintains visual consistency

❌ **Only use hardcoded colors:**
- Very specific one-off cases with clear justification
- Decorative elements that shouldn't change with theme
- Must be documented in component comments

## Inverted Background Pattern

Section components support three modes for background styling, allowing flexible visual contrast and card-style layouts.

### Three Background Modes

**`"noInvert"`** - Standard background (default page background color)
- No background color applied to section
- Text uses standard `text-foreground` color
- Full-width section

**`"invertDefault"`** - Full-width inverted background
- Section gets `bg-foreground` background
- Text uses `text-background` color for contrast
- Full-width section with inverted colors

### Implementation Pattern

```tsx
import { cls } from "@/lib/utils";
import { useTheme } from "@/providers/themeProvider/ThemeProvider";

interface SectionProps {
  title: string;
  description: string;
  useInvertedBackground: "noInvert" | "invertDefault"; // Required
  // ... other props
}

const Section = ({
  title,
  description,
  useInvertedBackground,
  className = "",
  // ... other props
}: SectionProps) => {
  const theme = useTheme();

  return (
    <section
      className={cls(
        "relative py-20 w-full",
        useInvertedBackground === "invertDefault" && "bg-foreground",
        className
      )}
    >
      <div className="w-content-width mx-auto">
        <h1 className={cls(
          "text-6xl font-medium",
          useInvertedBackground === "invertDefault" && "text-background",
          titleClassName
        )}>
          {title}
        </h1>
        <p className={cls(
          "text-lg",
          useInvertedBackground === "invertDefault"
            ? "text-background/75"
            : "text-foreground/75",
          descriptionClassName
        )}>
          {description}
        </p>
      </div>
    </section>
  );
};
```

### Key Points

1. **Required Prop**: `useInvertedBackground` should be a required string union type (no `?`), forcing explicit choice
2. **Two Modes**: `"noInvert"`, `"invertDefault"`
3. **Section Width**: Always `w-full`
4. **Background Color**:
   - `"invertDefault"` → `bg-foreground`
   - `"noInvert"` → no background
5. **Text Colors**: Apply `text-background` or `text-background/75` for `"invertDefault"` mode
6. **Relative Positioning**: Section needs `relative` class for proper z-index stacking
7. **Conditional Logic**: Use explicit string equality checks (not truthy/falsy)

### Section className Pattern

**Standard pattern for all sections:**

```tsx
<section
  className={cls(
    "relative py-20 w-full",
    useInvertedBackground === "invertDefault" && "bg-foreground",
    className
  )}
>
```

### Text Color Pattern

**For text elements:**

```tsx
// Single check for invert mode:
useInvertedBackground === "invertDefault" && "text-background"

// Ternary for opacity variants:
useInvertedBackground === "invertDefault"
  ? "text-background/75"
  : "text-foreground/75"
```

### For Components with Cards (Advanced)

When a section contains cards with light backgrounds, use the `shouldUseInvertedText` utility:

```tsx
import { cls, shouldUseInvertedText } from "@/lib/utils";
import { useTheme } from "@/providers/themeProvider/ThemeProvider";

const SectionWithCards = ({
  useInvertedBackground,
  // ... other props
}: SectionProps) => {
  const theme = useTheme();
  const shouldUseLightText = shouldUseInvertedText(
    useInvertedBackground,
    theme.cardStyle
  );

  return (
    <section
      className={cls(
        "relative py-20 w-full",
        useInvertedBackground === "invertDefault" && "bg-foreground",
        className
      )}
    >
      {/* For elements inside cards or with card backgrounds */}
      <h3 className={cls(
        "text-xl",
        shouldUseLightText && "text-background",
        bulletTitleClassName
      )}>
        {point.title}
      </h3>
    </section>
  );
};
```

**What it does:**
The `shouldUseInvertedText` utility checks if:
- `useInvertedBackground` is `"invertDefault"` AND
- Current `cardStyle` is a "light" style (e.g., `glass-elevated`, `outline`, etc.)

This ensures text inside cards remains readable regardless of theme configuration.

### Width Classes Explained

**`w-content-width`** - Content container width
- Controlled by `theme.contentWidth` (small/medium/large)
- Used for inner content wrapper in all sections

## Content Width Pattern

All section content must use the `w-content-width` class:

```tsx
<section className="w-full py-20">
  <div className="w-content-width mx-auto">
    {/* content */}
  </div>
</section>
```

**What it does:**
- Controlled by `theme.contentWidth` (small/medium/large)
- Automatically adjusts max-width based on theme setting
- Centers content with `mx-auto`

## Section Spacing

**Standard sections:**
```tsx
className="w-full py-20"
```

Vertical padding of `py-20` (5rem = 80px) on top and bottom.

**Exceptions (NO py-20):**
- Hero sections (custom spacing based on design)
- Footer sections (custom spacing)
- Full-bleed sections with background colors/images

## Card Styling Pattern

Use the `card` class for all card components:

```tsx
<div className={cls("card p-6 rounded-theme-capped h-full min-h-0", cardClassName)}>
  {/* card content */}
</div>
```

**Classes explained:**
- `card` - Theme-aware background/border (maps to `theme.cardStyle`)
- `p-6` - Standard padding (1.5rem = 24px)
- `rounded-theme-capped` - Border radius from theme (respects `theme.borderRadius`)
- `h-full` - Fill parent height (for grid layouts)
- `min-h-0` - Prevent height conflicts (important for flex layouts)

## Border Radius Pattern

**For cards:**
```tsx
className="rounded-theme-capped"
```

**For buttons:**
```tsx
className="rounded-theme"
```

Both respect `theme.borderRadius` setting (rounded/pill/sharp).

## Button Styling Classes

**Primary button (first in array):**
```tsx
className="primary-button"
```

**Secondary button (second+ in array):**
```tsx
className="secondary-button"
```

These classes are theme-aware and map to:
- `theme.primaryButtonStyle` (gradient/solid/glass/outline)
- `theme.secondaryButtonStyle` (glass/outline/solid/gradient)

## Styling Checklist

### Color Usage
- [ ] Use `bg-background` and `text-foreground` for main colors
- [ ] Use `bg-foreground` and `text-background` for inverted sections
- [ ] Use `card` class for card backgrounds
- [ ] Use `primary-button` and `secondary-button` for buttons
- [ ] Avoid hardcoded colors (white, black, gray-X) unless justified

### Theme Integration
- [ ] Wrap app/page in single ThemeProvider
- [ ] Use `useTheme()` hook when needed
- [ ] Don't specify button variants in ButtonConfig
- [ ] Let TextBox inherit default text animation
- [ ] Use `w-content-width mx-auto` for content

### Inverted Background (if applicable)
- [ ] Accept `useInvertedBackground` as required string union: `"noInvert" | "invertDefault"`
- [ ] Add `relative` class to section
- [ ] Implement two-mode section className pattern (invertDefault with bg-foreground, noInvert standard)
- [ ] Apply `text-background` to text for `"invertDefault"` mode (not `"noInvert"`)
- [ ] Use explicit string equality checks (not truthy/falsy)
- [ ] Use `shouldUseInvertedText` for card content if needed

### Card Styling
- [ ] Use `card` class for theme-aware background
- [ ] Use `rounded-theme-capped` for border radius
- [ ] Include `min-h-0` for flex compatibility
- [ ] Provide `cardClassName` override prop

### Spacing
- [ ] Use `py-20` on sections (except hero/footer)
- [ ] Use `w-content-width mx-auto` wrapper
- [ ] Follow theme spacing guidelines