# Keystone Design Bootstrap

A comprehensive design system for Keystone customer websites. Provides themed sections, elements, and utilities for building consistent, server-rendered Next.js sites.

## Quick Start

1. **Set your theme** in `config/index.ts`:
```typescript
export const config = {
  site: { theme: "barelux" } // or "aman", "classic"
}
```

2. **Import theme CSS** in your `app/globals.css`:
```css
@import "keystone-design-bootstrap/styles/fonts.css";
@import "keystone-design-bootstrap/styles/theme.css";
@import "keystone-design-bootstrap/styles/typography.css";
@import "keystone-design-bootstrap/styles/style-overrides.barelux.css"; /* Change to match your theme */
```

3. **Run** `npm run dev` and you're ready!

## Installation

```bash
npm install @keystone-pzjr/design-bootstrap
```

## Using the Design System

### Elements
Reusable UI components:

```typescript
import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'

<Button color="primary" size="md">Click Me</Button>
<Input label="Email" type="email" />
<Carousel items={photos} />
```

### Server API
Async functions for fetching data server-side:

```typescript
import { getServices, getTestimonials, getBlogPosts } from '@keystone-pzjr/design-bootstrap/lib/server-api'

const services = await getServices()
const testimonials = await getTestimonials()
```

### Sections
Pre-built page components that accept data via props:

```typescript
import { HeroHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
import { getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'

export default async function HomePage() {
  const testimonials = await getTestimonials()
  return (
    <main>
      <HeroHome />
      <TestimonialsHome testimonials={testimonials} />
    </main>
  )
}
```

**Available:** `HeroHome`, `ServicesHome`, `TestimonialsHome`, `BlogSection`, `ContactSection`, `HeaderNavigation`, `FooterHome`, and more.

## Package Exports

```typescript
// Sections (hero, footer, header, testimonials, etc.)
import { HeroHome, FooterHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'

// Elements (buttons, inputs, carousels, etc.)
import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'

// Hooks
import { useBreakpoint } from '@keystone-pzjr/design-bootstrap/hooks'

// Theme context
import { ThemeProvider } from '@keystone-pzjr/design-bootstrap/contexts'

// Server API utilities
import { getServices, getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'

// Types
import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types'

// Themes
import { themes } from '@keystone-pzjr/design-bootstrap/themes'
```

## Architecture

- **Server-first**: Data fetching happens server-side, components render as Server Components where possible
- **Theme variants**: Components automatically select variants based on active theme
- **Tailwind-first**: Use semantic utility classes (`bg-primary`, `text-fg-primary`, `font-display`)
- **Type-safe**: Full TypeScript support throughout
- **CSS variables**: Themes customize via CSS custom properties
- **Self-hosted fonts**: Uses Fontsource for optimized, bundled font loading

## Theme System

**Available themes:** `classic`, `aman`, `barelux`

Components automatically load theme-specific variants. Set theme in your config and import the corresponding CSS file in `globals.css`.

### Creating a New Theme

#### 1. Register Theme
Add to `src/themes/index.ts`:
```typescript
export const THEME_CONFIG = {
  classic: '',
  aman: '.aman',
  barelux: '.barelux',
  mytheme: '.mytheme', // Add your theme
} as const;
```

#### 2. Add Fonts
Install Fontsource packages in the design bootstrap:
```bash
cd keystone-design-bootstrap
npm install @fontsource/your-body-font @fontsource/your-display-font
```

Add to `src/styles/fonts.css`:
```css
/* MyTheme Fonts */
@import "@fontsource/your-body-font/400.css";
@import "@fontsource/your-body-font/600.css";
@import "@fontsource/your-display-font/400.css";
@import "@fontsource/your-display-font/700.css";
```

#### 3. Create CSS Overrides
Create `src/styles/style-overrides.mytheme.css`:
```css
[data-theme="mytheme"] {
  /* Typography */
  --font-body: "YourBodyFont", sans-serif;
  --font-display: "YourDisplayFont", serif;
  
  /* Colors - set both prefixes */
  --color-bg-primary: #FFFFFF;
  --background-color-primary: #FFFFFF;
  --color-bg-secondary: rgb(240, 240, 245);
  --background-color-secondary: rgb(240, 240, 245);
  --color-bg-brand-solid: rgb(100, 120, 200);
  --background-color-brand-solid: rgb(100, 120, 200);
  --color-bg-brand-solid_hover: rgb(80, 100, 180);
  --background-color-brand-solid_hover: rgb(80, 100, 180);
}

/* Override Tailwind utilities if needed */
[data-theme="mytheme"] .bg-secondary {
  background-color: rgb(240, 240, 245) !important;
}
```

#### 4. Use in Customer Site
In `config/index.ts`:
```typescript
export const config: SiteConfig = {
  site: { theme: "mytheme" }
}
```

In `app/globals.css`:
```css
@import "keystone-design-bootstrap/styles/fonts.css";
@import "keystone-design-bootstrap/styles/theme.css";
@import "keystone-design-bootstrap/styles/typography.css";
@import "keystone-design-bootstrap/styles/style-overrides.mytheme.css"; /* Your theme */
```

Restart your dev server. Fonts are self-hosted via Fontsource and automatically loaded.

#### 5. Create Component Variants (Optional)
**CRITICAL:** Use the exact same props interface as the base component.

Check the base component first:
```typescript
// Check: src/design_system/sections/hero-home.tsx
interface HeroHomeProps {
  title?: string;  // ← Use these exact prop names
  subtitle?: string;
  ctaText?: string;
  ctaHref?: string;
}
```

Then create variant with matching interface. Props should have empty string defaults, not `*TR*` markers. Translation strings belong in the customer template.

```typescript
// src/design_system/sections/hero-home.mytheme.tsx
export const HeroHome = ({ title, subtitle, ctaText, ctaHref }: HeroHomeProps) => (
  <section className="bg-primary py-20">
    <h1 className="font-display text-display-xl">{title}</h1>
    <p className="font-body text-lg">{subtitle}</p>
    <Button href={ctaHref} color="primary" size="md">{ctaText}</Button>
  </section>
);

import { registerThemeVariant } from '../../lib/component-registry';
registerThemeVariant('hero-home', 'mytheme', HeroHome);
```

#### 6. Register Component Variants
In `src/design_system/sections/index.tsx`:
```typescript
import './hero-home.mytheme';
```

## Design Rules

- **Prop Consistency**: Theme variants MUST use identical props interface as base component
- **CSS Variables Only**: No hardcoded colors/fonts in components
- **Semantic Classes**: Use `bg-primary`, `text-fg-primary`, `font-display` (not hardcoded values)
- **Minimal Overrides**: Keep theme CSS files ~100 lines max
- **Dual Color Prefixes**: Mirror variables to both `--color-*` and `--background-*` prefixes for compatibility
