From 2d85a280e86d4509ff6a05ef1e2e569e0741c858 Mon Sep 17 00:00:00 2001
From: bender <kudin.dima@gmail.com>
Date: Fri, 17 Apr 2026 21:16:15 +0000
Subject: [PATCH] Switch to version 1: remove docs/THEME_AND_STYLING.md

---
 docs/THEME_AND_STYLING.md | 521 --------------------------------------
 1 file changed, 521 deletions(-)
 delete mode 100644 docs/THEME_AND_STYLING.md

diff --git a/docs/THEME_AND_STYLING.md b/docs/THEME_AND_STYLING.md
deleted file mode 100644
index 20e85dc..0000000
--- a/docs/THEME_AND_STYLING.md
+++ /dev/null
@@ -1,521 +0,0 @@
-# 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