# 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`

### Themes

- **classic**: Default professional theme, Inter font, neutral colors
- **aman**: Luxury theme with Playfair Display serifs, warm beige, bronze accents
- **barelux**: Modern minimal theme with Poppins, clean lines

### Creating a Theme

See [`docs/theme-system.md`](./docs/theme-system.md) for complete instructions.

**With AI assistance:**
```
I am creating a new theme. Here is a link to an example: https://www.example.com
[Attach screenshots of various pages]

Please follow the prompt in /docs/ai-prompt-template.md
```

**Manual steps:**
1. Register in `src/themes/index.ts`
2. Install fonts via Fontsource
3. Create `src/styles/style-overrides.{theme}.css`
4. Create component variants (optional)
5. Add to design gallery app
6. Pass lint, typecheck, and build

**Critical rules:**
- Never modify base components or foundation CSS
- Use semantic variables/classes only
- Set BOTH `--color-*` and `--background-*` prefixes
- Match base component props exactly
- Ensure `npm run lint`, `npm run typecheck`, `npm run build` pass with zero errors/warnings

See [`.cursor/rules/theme-creation.mdc`](./.cursor/rules/theme-creation.mdc) for detailed rules
