@affinda/react 0.0.24 → 0.0.26

package/README.md

@@ -70,6 +70,15 @@ Affinda components use the **NeuSans** font family. To get the authentic Affinda
 
 ## Usage
 
+> ⚠️ **Theme Container Requirement:** Always wrap your components in a theme-providing container like `Section`, `HeroSection`, or `Card`. These containers establish theme context via CSS custom properties that child components (Heading, Text, Button, etc.) consume for their colors.
+>
+> ```tsx
+> <Section theme="white">
+>   <Heading level="1">Title</Heading>
+>   <Text>Content with proper colors</Text>
+> </Section>
+> ```
+
 ### Import Components
 
 All components are available with or without the `Af` prefix:
@@ -84,89 +93,107 @@ import { Button, Heading, TypographyLockup } from '@affinda/react';
 
 ### Available Components
 
-**Layout & Structure:**
-- **HeroSection** / AfHeroSection - Hero sections for marketing pages
-- **Section** / AfSection - Page sections with consistent spacing
-- **Container** / AfContainer - Layout containers with max-width
-- **AspectRatio** / AfAspectRatio - Maintain aspect ratios for media
+Components are organized by complexity level. **Always compose from these levels** — don't write custom HTML/CSS for layouts that components already handle.
 
-**Navigation:**
-- **Navbar** / AfNavbar - Navigation bar with mobile hamburger menu
-- **NavItem** / AfNavItem - Navigation items
+#### Atoms (Basic Building Blocks)
 
-**Typography:**
+- **Button** / AfButton - Primary buttons with variants and icons
+- **IconButton** / AfIconButton - Icon-only buttons
 - **Heading** / AfHeading - Typography headings (H1-H6) with theme support
 - **Text** / AfText - Body text components with theme support
-- **TypographyLockup** / AfTypographyLockup - Composite heading + text + button layouts
-
-**Buttons:**
-- **Button** / AfButton - Primary buttons with variants, icons, and dark background support
-- **ButtonGroup** / AfButtonGroup - Group multiple buttons together
-- **IconButton** / AfIconButton - Icon-only buttons
-
-**Cards & Content:**
-- **Card** / AfCard - Content cards with optional backgrounds and photo variants
+- **Tag** / AfTag - Categorization labels with sand and light variants
+- **Section** / AfSection - Page sections with consistent spacing and themes ⭐ *provides theme context*
+- **Card** / AfCard - Content cards with optional backgrounds and photo variants ⭐ *provides theme context*
+- **Container** / AfContainer - Layout containers with max-width
+- **IconBox** / AfIconBox - Themed container for displaying an icon with rounded background
+- **Logo** / AfLogo - Affinda logo component
+- **LogoWell** / AfLogoWell - Rounded container for client logos
+- **AspectRatio** / AfAspectRatio - Maintain aspect ratios for media
 - **ColorSwatch** / AfColorSwatch - Display color swatches
 
-**Social Proof:**
-- **ClientCarousel** / AfClientCarousel - Infinite scrolling carousel for client logos
-- **LogoWell** / AfLogoWell - Rounded container for client logos
+#### Molecules (Composed from Atoms)
+
+- **ButtonGroup** / AfButtonGroup - Group multiple buttons together
+- **TypographyLockup** / AfTypographyLockup - Composite heading + text + button layouts
+- **IconText** / AfIconText - IconBox + TypographyLockup for feature items with icons
+- **FeatureCard** / AfFeatureCard - Card + image + TypographyLockup for feature showcase
+- **IllustratedCard** / AfIllustratedCard - Card + illustration slot
+- **NavItem** / AfNavItem - Navigation items
+- **NavCard** / AfNavCard - Navigation card with icon and description
 - **Testimonial** / AfTestimonial - Customer testimonials with background images, stats, and quotes
-- **TestimonialCarousel** / AfTestimonialCarousel - Carousel for sliding between multiple testimonials
 - **TestimonialStat** / AfTestimonialStat - Individual statistics within testimonials
-
-**Feature Showcase:**
-- **FeatureAccordion** / AfFeatureAccordion - Expandable accordion with auto-cycling timer and image display
-- **CtaSection** / AfCtaSection - Call-to-action section with illustration and buttons
-
-**Brand:**
-- **Logo** / AfLogo - Affinda logo component
-
-**Decorative:**
-- **PaperclipDecoration** - Decorative paperclip vector for hero sections
-
-**Footer:**
-- **Footer** / AfFooter - Slot-based footer layout component
 - **FooterColumn** / AfFooterColumn - Navigation column for footer
 - **FooterLink** / AfFooterLink - Styled link for footer navigation
 - **SocialLink** / AfSocialLink - Circular social media icon link
 - **ContactItem** / AfContactItem - Label/value pair for contact info
+- **PaperclipDecoration** - Decorative paperclip vector for hero sections
+
+#### Organisms (Page Sections)
+
+- **Navbar** / AfNavbar - Navigation bar with mobile hamburger menu
+- **HeroSection** / AfHeroSection - Hero sections for marketing pages ⭐ *provides theme context*
+- **FeatureGrid** / AfFeatureGrid - Responsive CSS grid container for feature cards/items
+- **FeatureAccordion** / AfFeatureAccordion - Expandable accordion with auto-cycling timer
+- **GridCallout** / AfGridCallout - Image + heading + IconText grid for feature sections
+- **SplitSection** / AfSplitSection - Two-column layouts with image and content
+- **ClientCarousel** / AfClientCarousel - Infinite scrolling carousel for client logos
+- **TestimonialCarousel** / AfTestimonialCarousel - Carousel for sliding between testimonials
+- **InPageBanner** / AfInPageBanner - Call-to-action banner card with illustration ⭐ *provides theme context*
+- **Footer** / AfFooter - Slot-based footer layout component
 
 ## Quick Start Components
 
 ### HeroSection
 
-The hero section component makes it easy to create marketing page heroes with consistent styling.
+The hero section component makes it easy to create marketing page heroes with consistent styling. It uses **TypographyLockup** internally to handle proper spacing and layout of heading, description, and buttons.
 
 ```tsx
-import { HeroSection, Heading, Text, Button, PaperclipDecoration } from '@affinda/react';
+import { HeroSection, Heading, Text, Button, ButtonGroup, PaperclipDecoration } from '@affinda/react';
 
-<HeroSection variant="dark" withDecoration={true} minHeight="60vh">
+<HeroSection 
+  theme="inkwell" 
+  withDecoration={true} 
+  minHeight="60vh"
+  headingSize={1}
+  textAlignment="center"
+  buttonAlignment="horizontal"
+>
   {/* Position the paperclip decoration - adjust bottom/right values as needed */}
   <PaperclipDecoration 
     slot="decoration" 
     style={{ position: 'absolute', bottom: -80, right: -800 }} 
   />
-  <Heading level="1" theme="dark" align="center">
+  <Heading slot="heading" level="1">
     Harness AI to transform business processes
   </Heading>
-  <Text variant="large" theme="dark" align="center">
+  <Text slot="description" variant="large">
     Around the world, leading enterprises use Affinda's AI agents...
   </Text>
-  <div style={{ display: 'flex', gap: '12px', justifyContent: 'center', marginTop: '2rem' }}>
+  <ButtonGroup slot="buttons" direction="horizontal" gap="12px">
     <Button variant="primary">Discover the platform</Button>
     <Button variant="secondary">Explore solutions</Button>
-  </div>
+  </ButtonGroup>
 </HeroSection>
 ```
 
 **Props:**
-- `variant`: `"light"` | `"dark"` (default: `"dark"`)
+- `theme`: `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` (default: `"inkwell"`)
 - `withDecoration`: boolean - Shows decoration slot
 - `minHeight`: string - CSS min-height value
+- `headingSize`: `1` | `2` | `3` | `4` | `5` - Controls heading size and spacing (default: `1`)
+- `textAlignment`: `"left"` | `"center"` - Text alignment (default: `"center"`)
+- `buttonAlignment`: `"horizontal"` | `"vertical"` - Button layout direction (default: `"horizontal"`)
+- `maxWidth`: number - Maximum width for the copy section in pixels
+
+**Slots:**
+- `heading` - The main heading (typically a `<Heading>` component)
+- `description` - Description text (typically a `<Text>` component)
+- `buttons` - CTA buttons (typically a `<ButtonGroup>` or individual buttons)
+- `decoration` - Optional decorative element (e.g., `<PaperclipDecoration>`)
 
 **Features:**
-- Automatically applies correct text colors for dark backgrounds
+- Uses TypographyLockup internally for consistent heading/description/button layout
+- Child components (Heading, Text, Button) automatically inherit theme colors - no manual theme props needed
 - Built-in padding that accounts for floating navbar
 - Responsive on mobile
 
@@ -177,7 +204,7 @@ The section component provides consistent spacing and backgrounds for page secti
 ```tsx
 import { Section, Heading, Text } from '@affinda/react';
 
-<Section padding="default" background="level1" container={true}>
+<Section padding="default" theme="mist-green" container={true}>
   <Heading level="2" align="center">Work smarter, grow faster</Heading>
   <Text variant="large" align="center">Feature content here...</Text>
 </Section>
@@ -185,26 +212,32 @@ import { Section, Heading, Text } from '@affinda/react';
 
 **Props:**
 - `padding`: `"tight"` (48px) | `"default"` (96px) | `"loose"` (120px)
-- `background`: `"white"` | `"level1"` | `"dark"` | `"inkwell"`
+- `theme`: `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` (default: `"white"`)
 - `container`: boolean - Auto-wraps content in Container
 
-> **Contrast helper:** When `background="dark"` or `background="inkwell"`, `Section` automatically exposes CSS variables so nested `Heading`, `Text`, and `TypographyLockup` components render in mist-green, even if you forget to set `theme="dark"`. Buttons still need `darkBackground={true}` (see below).
+> **Theme inheritance:** Child components (Heading, Text, Button) automatically inherit the section's theme colors. No manual theme props needed on children!
 
-### Card with Photo Background
+### Card
 
-Cards now support photo backgrounds with gradient overlays.
+Cards support themed backgrounds and photo backgrounds. Use the `theme` prop for consistent styling with theme inheritance.
 
 ```tsx
 import { Card, Heading, Text } from '@affinda/react';
 
-// Light background card
-<Card backgroundColor="var(--colour-background-level1)">
+// Themed card (recommended) - children inherit theme colors automatically
+<Card theme="mist-green">
   <Heading level="3">Automate any document with 99%+ accuracy</Heading>
   <Text variant="large">Extract any information...</Text>
   <img src="screenshot.webp" alt="Feature" />
 </Card>
 
-// Photo background card with dark overlay
+// Dark themed card
+<Card theme="inkwell">
+  <Heading level="3">Build models in minutes</Heading>
+  <Text variant="large">Affinda is the only AI platform...</Text>
+</Card>
+
+// Photo background card (for custom backgrounds)
 <Card backgroundImage="photo.jpg" darkOverlay={true}>
   <Heading level="3">Build models in minutes</Heading>
   <Text variant="large">Affinda is the only AI platform...</Text>
@@ -212,9 +245,10 @@ import { Card, Heading, Text } from '@affinda/react';
 ```
 
 **Props:**
-- `backgroundColor`: CSS color or variable
+- `theme`: `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` (recommended)
+- `backgroundColor`: CSS color or variable (legacy, use theme instead)
 - `backgroundImage`: URL to background image
-- `darkOverlay`: boolean - Applies gradient overlay with white text
+- `darkOverlay`: boolean - Applies gradient overlay for text readability on photos
 
 ### PaperclipDecoration
 
@@ -225,7 +259,7 @@ Decorative SVG paperclip graphic for hero sections.
 ```tsx
 import { HeroSection, PaperclipDecoration } from '@affinda/react';
 
-<HeroSection variant="dark" withDecoration={true}>
+<HeroSection theme="inkwell" withDecoration={true}>
   <PaperclipDecoration 
     slot="decoration" 
     style={{ 
@@ -326,10 +360,10 @@ import { HeroSection, PaperclipDecoration } from '@affinda/react';
 >
   <Heading level="1">Automate Your Workflow</Heading>
   <Text slot="description">Extract data from documents in seconds</Text>
-  <div slot="buttons">
+  <ButtonGroup slot="buttons" direction="horizontal">
     <Button variant="primary">Get Started</Button>
     <Button variant="secondary">Learn More</Button>
-  </div>
+  </ButtonGroup>
 </TypographyLockup>
 ```
 
@@ -340,7 +374,7 @@ import { HeroSection, PaperclipDecoration } from '@affinda/react';
 - Secondary actions: Use `variant="secondary"`
 - Sizes: `small`, `default`
 - Can include icons in left or right slots
-- On dark backgrounds, pass `darkBackground={true}` so borders/text flip automatically
+- Buttons automatically inherit theme colors from parent Section/HeroSection/Card
 
 ```tsx
 <Button variant="primary">Sign Up Now</Button>
@@ -364,9 +398,29 @@ import { HeroSection, PaperclipDecoration } from '@affinda/react';
 - Common uses: Close buttons, navigation arrows, menu toggles
 
 ```tsx
+import { IconButton, Close, Menu } from '@affinda/react';
+
 <IconButton variant="secondary" aria-label="Close dialog">
-  <svg>...</svg>
+  <Close size={24} />
 </IconButton>
+
+<IconButton variant="tertiary" size="small" aria-label="Toggle menu">
+  <Menu size={20} />
+</IconButton>
+```
+
+#### Tags
+
+**Tag**
+- Use for categorization, topics, filters, or metadata display
+- Variants: `sand` (default - soft-clay/tan) or `light` (mist-green)
+- Sizes: `x-small`, `small` (default), `large`
+- Can be clickable links with `href` prop
+
+```tsx
+<Tag>AI</Tag>
+<Tag variant="light">OCR</Tag>
+<Tag variant="sand" size="large" href="/topics/ml">Machine Learning</Tag>
 ```
 
 #### Navigation
@@ -377,8 +431,20 @@ import { HeroSection, PaperclipDecoration } from '@affinda/react';
 
 Site-wide navigation header with responsive design and mobile menu support.
 
+**Layout Behavior:**
+
+The Navbar renders two elements:
+1. A **spacer element** that sits in normal document flow and reserves vertical space
+2. A **fixed navbar** that floats above the page content
+
+This prevents page content from being hidden behind the navbar. The spacer automatically adjusts its height at different breakpoints:
+- Desktop: 100px
+- Tablet (≤1024px): 88px  
+- Mobile (≤991px): 72px
+
 **Props:**
 - `showDefaultLogo` (boolean, default: `true`) - Whether to show the default Affinda logo when no logo slot content is provided
+- `theme`: `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` - Sets the spacer background color to match the section below the navbar
 
 **Slots:**
 - `logo` - Brand logo (left side) - *optional*, defaults to Affinda logo
@@ -388,12 +454,6 @@ Site-wide navigation header with responsive design and mobile menu support.
 
 ```tsx
 <Navbar>
-  {/* Logo slot - optional, defaults to Affinda logo */}
-  {/* <Logo slot="logo" /> */}
-  
-  {/* Or use a custom logo */}
-  {/* <Logo slot="logo" src="/path/to/custom-logo.svg" alt="My Company" /> */}
-  
   {/* Start slot - main navigation items */}
   <div slot="start">
     <NavItem hierarchy="primary" variant="01" href="/platform">
@@ -424,29 +484,6 @@ Site-wide navigation header with responsive design and mobile menu support.
 </Navbar>
 ```
 
-**Common Mistake:**
-```tsx
-// ❌ WRONG - Direct children are ignored
-<Navbar>
-  <NavItem href="/home">Home</NavItem>
-</Navbar>
-
-// ✅ CORRECT - Use slots
-<Navbar>
-  <div slot="start">
-    <NavItem href="/home">Home</NavItem>
-  </div>
-</Navbar>
-
-// ✅ ALSO CORRECT - Custom logo via slot
-<Navbar>
-  <Logo slot="logo" src="/my-logo.svg" alt="My Company" />
-  <div slot="start">
-    <NavItem href="/home">Home</NavItem>
-  </div>
-</Navbar>
-```
-
 **NavItem**
 - Individual navigation links
 - Hierarchy: `primary` (main nav), `secondary` (utility nav)
@@ -460,29 +497,32 @@ Site-wide navigation header with responsive design and mobile menu support.
 - Auto-cycles through items with a visual progress timer
 - Displays accompanying images that change with each item
 - Timer resets when user clicks an item
+- **Must be wrapped in a Section** which provides theme context and padding
 
 ```tsx
-import { FeatureAccordion } from '@affinda/react';
-
-<FeatureAccordion
-  heading="Give AI agents your paperwork"
-  items={JSON.stringify([
-    {
-      title: "Automate document processing with 99%+ accuracy",
-      description: "Extract any information from any document with industry-leading precision.",
-      imageUrl: "https://example.com/feature1.jpg",
-      imageAlt: "Document automation"
-    },
-    {
-      title: "Build models in minutes, not months",
-      description: "Affinda learns instantly from every interaction.",
-      imageUrl: "https://example.com/feature2.jpg",
-      imageAlt: "Fast model building"
-    }
-  ])}
-  cycleInterval={6000}
-  autoCycle={true}
-/>
+import { Section, FeatureAccordion } from '@affinda/react';
+
+<Section theme="mist-green" padding="default">
+  <FeatureAccordion
+    heading="Give AI agents your paperwork"
+    items={JSON.stringify([
+      {
+        title: "Automate document processing with 99%+ accuracy",
+        description: "Extract any information from any document with industry-leading precision.",
+        imageUrl: "https://example.com/feature1.jpg",
+        imageAlt: "Document automation"
+      },
+      {
+        title: "Build models in minutes, not months",
+        description: "Affinda learns instantly from every interaction.",
+        imageUrl: "https://example.com/feature2.jpg",
+        imageAlt: "Fast model building"
+      }
+    ])}
+    cycleInterval={6000}
+    autoCycle={true}
+  />
+</Section>
 ```
 
 **Props:**
@@ -491,33 +531,43 @@ import { FeatureAccordion } from '@affinda/react';
 - `cycleInterval`: Auto-cycle interval in milliseconds (default: 6000)
 - `autoCycle`: Enable/disable auto-cycling (default: true)
 
-**CtaSection**
-- Call-to-action section with illustration and decorative background
-- Styled to match the affinda.com design
+**Section Props (wrapper):**
+- `theme`: `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` - Sets background and typography colors
+- `padding`: `"tight"` | `"default"` | `"loose"` - Vertical spacing (default: `"default"`)
+
+**InPageBanner**
+- Call-to-action banner card with illustration and decorative wave background
+- Place inside a neutral (white) Section to show off its themed background
+- Use `getIllustrationUrlByScene()` from `@affinda/illustrations` for theme-matched illustrations
 
 ```tsx
-import { CtaSection } from '@affinda/react';
+import { Section, InPageBanner } from '@affinda/react';
 import { getIllustrationUrlByScene } from '@affinda/illustrations';
 
-<CtaSection
-  heading="See what our AI agents can do for you"
-  description="Upload your documents and watch our AI agents get to work."
-  primaryButtonText="Try for free"
-  primaryButtonUrl="https://app.affinda.com/auth/register"
-  secondaryButtonText="Talk to us"
-  secondaryButtonUrl="/contact"
-  illustrationUrl={getIllustrationUrlByScene('automate', 'inkwell')}
-/>
+<Section padding="default" theme="white" container={true}>
+  <InPageBanner
+    theme="mist-green"
+    heading="See what our AI agents can do for you"
+    description="Upload your documents and watch our AI agents get to work."
+    primaryButtonText="Try for free"
+    primaryButtonUrl="https://app.affinda.com/auth/register"
+    secondaryButtonText="Talk to us"
+    secondaryButtonUrl="/contact"
+    illustrationUrl={getIllustrationUrlByScene('automate', 'mist-green')}
+  />
+</Section>
 ```
 
 **Props:**
-- `heading`: Section heading text
+- `theme`: `"white-ivory"` | `"inkwell"` | `"mist-green"` | `"soft-clay"` (default: `"mist-green"`) - Sets background and typography colors
+- `heading`: Banner heading text
 - `description`: Description text below heading
 - `primaryButtonText`: Text for primary CTA button
 - `primaryButtonUrl`: URL for primary button
-- `secondaryButtonText`: Text for secondary button
+- `secondaryButtonText`: Text for secondary button (optional)
 - `secondaryButtonUrl`: URL for secondary button
-- `illustrationUrl`: URL to illustration image (use @affinda/illustrations)
+- `illustrationUrl`: Illustration image URL. Use `getIllustrationUrlByScene(scene, theme)` from `@affinda/illustrations` for theme-matched illustrations. Available scenes: `'document-raise'`, `'thinking'`, `'shapes'`, `'team-leader'`, `'grow-business'`, `'document-type'`, `'industries'`, `'accuracy'`, `'intelligence'`, `'page-turn'`, `'automate'`
+- `showWaveDecoration`: Whether to show the decorative wave overlay (default: true)
 
 #### Social Proof & Testimonials
 
@@ -534,38 +584,40 @@ import { getIllustrationUrlByScene } from '@affinda/illustrations';
   attribution="– Jane Doe, CEO, Company Name"
   readMoreLink="https://example.com/case-study"
 >
-  <div slot="stats">
-    <TestimonialStat value="95%" description="reduction in processing time" />
-    <TestimonialStat value="10×" description="increase in throughput" />
-  </div>
+  <TestimonialStat slot="stats" value="95%" description="reduction in processing time" />
+  <TestimonialStat slot="stats" value="10×" description="increase in throughput" />
 </Testimonial>
 ```
 
 **TestimonialCarousel**
+- Wrap with Section for theming and Container for layout (like other components)
 - Automatically handles navigation between multiple testimonials
-- Includes slide animations and progress indicators
-- Navigation buttons positioned for optimal UX
-- Just wrap multiple Testimonial components
+- Includes progress indicator
 
 ```tsx
-<TestimonialCarousel>
-  <Testimonial {...testimonial1Props}>
-    <div slot="stats">...</div>
-  </Testimonial>
-  <Testimonial {...testimonial2Props}>
-    <div slot="stats">...</div>
-  </Testimonial>
-</TestimonialCarousel>
+<Section padding="default" theme="white" container>
+  <TestimonialCarousel>
+    <Testimonial {...testimonial1Props}>
+      <TestimonialStat slot="stats" value="95%" description="processing time reduction" />
+      <TestimonialStat slot="stats" value="10×" description="throughput increase" />
+    </Testimonial>
+    <Testimonial {...testimonial2Props}>
+      <TestimonialStat slot="stats" value="99%" description="accuracy rate" />
+    </Testimonial>
+  </TestimonialCarousel>
+</Section>
 ```
 
 **TestimonialStat**
 - Display key metrics within testimonials
+- Use `slot="stats"` on each stat to position correctly
 - Use 2-4 stats per testimonial for best impact
 - Optional accent border for qualitative statements
 
 ```tsx
-<TestimonialStat value="99%" description="accuracy rate" />
+<TestimonialStat slot="stats" value="99%" description="accuracy rate" />
 <TestimonialStat 
+  slot="stats"
   value="" 
   description="Reduced manual errors significantly" 
   accentBorder={true} 
@@ -578,18 +630,9 @@ import { getIllustrationUrlByScene } from '@affinda/illustrations';
 - Affinda logo component with consistent sizing
 - Use in Navbar and footer
 - Renders as inline SVG for crisp display at any size
-- Supports custom logos via the `src` prop
-
-**Props:**
-- `src` (string, optional) - Custom logo image URL. If provided, displays this instead of the default Affinda logo
-- `alt` (string, default: "Affinda") - Alt text for the logo
 
 ```tsx
-// Default Affinda logo
 <Logo />
-
-// Custom logo
-<Logo src="/path/to/my-logo.svg" alt="My Company" />
 ```
 
 **ColorSwatch**
@@ -666,10 +709,8 @@ function Hero() {
       <p slot="description">
         Extract data from documents with AI-powered accuracy
       </p>
-      <div slot="buttons">
-        <Button variant="primary">Get Started</Button>
-        <Button variant="secondary">Learn More</Button>
-      </div>
+      <Button slot="buttons" variant="primary">Get Started</Button>
+      <Button slot="buttons" variant="secondary">Learn More</Button>
     </TypographyLockup>
   );
 }
@@ -757,10 +798,274 @@ See the [@affinda/tokens documentation](https://www.npmjs.com/package/@affinda/t
 
 Full TypeScript type definitions are included for all components and props.
 
+## Custom Styling
+
+All components accept a `style` prop for applying inline CSS styles directly to the component's root element:
+
+```tsx
+import { Button, Section, Heading } from '@affinda/react';
+
+// Apply custom styles to any component
+<Button variant="primary" style={{ marginTop: '20px', opacity: 0.9 }}>
+  Custom Styled Button
+</Button>
+
+<Section theme="white" style={{ borderRadius: '16px', boxShadow: '0 4px 12px rgba(0,0,0,0.1)' }}>
+  <Heading level="2">Styled Section</Heading>
+</Section>
+```
+
+The `style` prop is passed through to the web component's host element, allowing you to override or extend component styles as needed.
+
+## Common UI Patterns
+
+Use these component combinations for common marketing page patterns. **Always check this section before writing custom CSS or HTML.**
+
+### Grid of Feature Items with Icons
+
+```tsx
+import { Section, FeatureGrid, IconText } from '@affinda/react';
+
+<Section theme="mist-green" container={true}>
+  <FeatureGrid columns={4} mobileLayout="list">
+    <IconText icon="time" headingSize={4}>
+      Fast Processing
+      <span slot="description">Process documents in seconds.</span>
+    </IconText>
+    <IconText icon="verification-01" headingSize={4}>
+      High Accuracy
+      <span slot="description">99%+ extraction accuracy.</span>
+    </IconText>
+    <IconText icon="security-01" headingSize={4}>
+      Secure & Compliant
+      <span slot="description">Enterprise-grade security.</span>
+    </IconText>
+    <IconText icon="code" headingSize={4}>
+      Easy Integration
+      <span slot="description">Works with your existing systems.</span>
+    </IconText>
+  </FeatureGrid>
+</Section>
+```
+
+### Grid of Feature Cards with Images
+
+```tsx
+import { FeatureGrid, FeatureCard } from '@affinda/react';
+
+<FeatureGrid columns={3} mobileLayout="scroll">
+  <FeatureCard theme="mist-green" cardSize="flexible" imageSrc="/feature1.jpg">
+    Extract Any Document
+    <span slot="body">AI-powered extraction for all document types.</span>
+  </FeatureCard>
+  <FeatureCard theme="soft-clay" cardSize="flexible" imageSrc="/feature2.jpg">
+    Validate Automatically
+    <span slot="body">Built-in validation catches errors.</span>
+  </FeatureCard>
+</FeatureGrid>
+```
+
+### Grouped Buttons
+
+```tsx
+import { ButtonGroup, Button } from '@affinda/react';
+
+<ButtonGroup direction="horizontal" gap="16px">
+  <Button variant="primary">Get Started</Button>
+  <Button variant="secondary">Learn More</Button>
+</ButtonGroup>
+```
+
+### Feature Section with Image + Grid of Items
+
+```tsx
+import { Section, GridCallout, IconText, Button } from '@affinda/react';
+
+<Section theme="white" container={true}>
+  <GridCallout imageSrc="/team.jpg" imagePosition="left" columns={2}>
+    Why Choose Affinda
+    <span slot="description">Industry-leading AI for document processing.</span>
+    
+    <IconText slot="items" icon="sparkle" headingSize={4}>
+      AI-Powered
+      <span slot="description">State-of-the-art machine learning.</span>
+    </IconText>
+    <IconText slot="items" icon="security-01" headingSize={4}>
+      Enterprise Security
+      <span slot="description">SOC 2 Type II certified.</span>
+    </IconText>
+    
+    <Button slot="cta" variant="primary">Learn More</Button>
+  </GridCallout>
+</Section>
+```
+
+### Icons in Feature Lists
+
+```tsx
+import { IconBox, IconText } from '@affinda/react';
+
+// Standalone icons
+<IconBox icon="verification-01" size="default" />
+
+// Icon + text combinations
+<IconText icon="time" headingSize={4}>
+  Fast Processing
+  <span slot="description">Documents processed in seconds.</span>
+</IconText>
+```
+
+### Hero with Heading, Description, and Buttons
+
+```tsx
+import { HeroSection, Heading, Text, ButtonGroup, Button } from '@affinda/react';
+
+<HeroSection theme="inkwell" minHeight="80vh" headingSize={1} textAlignment="center">
+  <Heading slot="heading" level="1">Document Automation</Heading>
+  <Text slot="description" variant="large">
+    Extract data from any document with AI.
+  </Text>
+  <ButtonGroup slot="buttons" direction="horizontal" gap="16px">
+    <Button variant="primary">Start Free Trial</Button>
+    <Button variant="secondary">Watch Demo</Button>
+  </ButtonGroup>
+</HeroSection>
+```
+
+---
+
 ## For AI Agents
 
 When generating Affinda UI code:
 
+### Component Selection (Critical!)
+
+**Always use existing components instead of custom CSS/HTML.** Before writing any layout code, check if a component exists for your use case.
+
+| If you need... | Use this component |
+|----------------|-------------------|
+| Grid of items | `FeatureGrid` |
+| Card with icon + text | `IconText` |
+| Standalone icon | `IconBox` |
+| Card with photo/screenshot | `FeatureCard` |
+| Card with @affinda/illustrations | `IllustratedCard` |
+| Button group | `ButtonGroup` |
+| Heading + description + buttons | `TypographyLockup` |
+| Section with image + feature grid | `GridCallout` |
+| Two-column layout | `SplitSection` |
+| Responsive grid container | `FeatureGrid` with `mobileLayout` prop |
+
+### Available Icons
+
+Use icons from `@affinda/icons` with `IconBox` or `IconText`. Never use emoji.
+
+**Common icons:**
+- `time` - speed/performance
+- `verification-01` - accuracy/checking
+- `security-01`, `security-02` - security/compliance
+- `sparkle` - AI/magic
+- `productivity` - efficiency
+- `code` - integration/API
+- `document-upload` - documents
+- `lending-01`, `lending-02` - lending industry
+- `check-circle` - success/checkmarks
+- `data` - data/analytics
+- `gear` - settings/configuration
+
+```tsx
+// Use with IconBox
+<IconBox icon="verification-01" size="default" />
+
+// Use with IconText
+<IconText icon="sparkle" headingSize={4}>
+  AI-Powered Processing
+  <span slot="description">State-of-the-art machine learning.</span>
+</IconText>
+```
+
+### Theme System (Important!)
+
+Use the 4-value theme system on container components. Child components inherit colors automatically:
+
+```tsx
+<Section theme="inkwell">
+  <Heading level="2">Title</Heading>  {/* Automatically light text */}
+  <Text>Content</Text>                {/* Automatically light text */}
+  <Button variant="primary">Action</Button>  {/* Automatically themed */}
+</Section>
+```
+
+**Available themes:** `"white"` | `"inkwell"` | `"mist-green"` | `"soft-clay"`
+
+### Self-Theming Components (No Section Wrapper!)
+
+Some components provide their own themed backgrounds. **Do NOT wrap these in a Section** — they handle their own background color and spacing.
+
+| Component | Provides Own Background | Correct Usage |
+|-----------|------------------------|---------------|
+| `HeroSection` | Yes | Use directly, set `theme` prop |
+| `ClientCarousel` | Yes | Use directly, set `theme` prop to match adjacent section |
+| `InPageBanner` | Yes | Wrap in neutral `Section theme="white"` to show contrast |
+
+```tsx
+<ClientCarousel theme="inkwell">...</ClientCarousel>
+```
+
+### ClientCarousel Theme Matching
+
+When using `ClientCarousel`, set its `theme` prop to match the section **above** it for visual continuity. This creates a seamless transition between sections.
+
+```tsx
+<HeroSection theme="inkwell">
+  {/* Hero content */}
+</HeroSection>
+<ClientCarousel theme="inkwell">
+  {/* Logo wells - theme matches preceding HeroSection */}
+</ClientCarousel>
+```
+
+### FeatureAccordion (Wrap in Section!)
+
+Unlike self-theming components, `FeatureAccordion` should be wrapped in a `Section` which provides the theme context, padding, and container.
+
+```tsx
+<Section theme="soft-clay" padding="default">
+  <FeatureAccordion
+    heading="Give AI agents your paperwork"
+    items={JSON.stringify([...])}
+  />
+</Section>
+```
+
+### Slot-Based Components
+
+Several components require `slot` attributes on children:
+
+```tsx
+// Navbar slots: logo, start, end, button
+<Navbar>
+  <div slot="start"><NavItem href="/">Home</NavItem></div>
+  <Button slot="button">CTA</Button>
+</Navbar>
+
+// Footer slots: logo, social, contact, nav, legal, badges
+// ClientCarousel slots: row-1, row-2
+// Button slots: icon-left, icon-right
+// TypographyLockup slots: description, buttons
+```
+
+### FeatureAccordion Items
+
+The `items` prop requires JSON.stringify():
+
+```tsx
+<Section theme="mist-green" padding="default">
+  <FeatureAccordion items={JSON.stringify([{ title: "...", description: "..." }])} />
+</Section>
+```
+
+### Brand Colors
+
 1. **Always use Affinda brand colors:**
    - Primary: Mist Green (`#C6D5D1`)
    - Text: Inkwell (`#14343B`)