keystone-design-bootstrap 1.0.13 → 1.0.14

package/README.md

@@ -2,13 +2,30 @@
 
 A comprehensive design system for Keystone customer websites. Provides themed sections, elements, and utilities for building consistent, server-rendered Next.js sites.
 
-**Rules:**
-- Theme variants MUST use identical props interface as base component (e.g., if base uses `title`, variant must use `title`, not `headline`)
-- Use CSS variables only (no hardcoded colors/fonts in components)
-- Add theme fonts to customer template's `globals.css` (see below)
-- Use semantic classes (`bg-primary`, `text-fg-primary`, `font-display`)
-- Keep CSS overrides minimal (~100 lines max)
-- Mirror color variables to both `--color-*` and `--background-*` prefixes
+## 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
 
@@ -53,21 +70,6 @@ export default async function HomePage() {
 
 **Available:** `HeroHome`, `ServicesHome`, `TestimonialsHome`, `BlogSection`, `ContactSection`, `HeaderNavigation`, `FooterHome`, and more.
 
-## 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
-
-
-## Installation
-
-```bash
-npm install @keystone-pzjr/design-bootstrap
-```
-
 ## Package Exports
 
 ```typescript
@@ -93,53 +95,57 @@ import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types
 import { themes } from '@keystone-pzjr/design-bootstrap/themes'
 ```
 
-## Quick Start
-
-Set your theme in `config/index.ts`:
-```typescript
-export const config = {
-  site: { theme: "aman" } // or "classic", "barelux"
-}
-```
+## Architecture
 
-CSS is auto-imported based on config. Run `npm run dev` and you're ready.
+- **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 CSS imports are handled automatically.
+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
-`src/themes/index.ts`:
+#### 1. Register Theme
+Add to `src/themes/index.ts`:
 ```typescript
 export const THEME_CONFIG = {
   classic: '',
   aman: '.aman',
-  mytheme: '.mytheme',
+  barelux: '.barelux',
+  mytheme: '.mytheme', // Add your theme
 } as const;
 ```
 
-### 2. Add Fonts to Customer Template
-In customer template's `app/globals.css`, add font imports after `@import "tailwindcss"`:
-```css
-@import "tailwindcss";
-
-/* Add your theme fonts here */
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600&family=Playfair+Display:wght@400;700&display=swap');
+#### 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
+```
 
-/* Rest of file... */
+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
-`src/styles/style-overrides.mytheme.css`:
+#### 3. Create CSS Overrides
+Create `src/styles/style-overrides.mytheme.css`:
 ```css
 [data-theme="mytheme"] {
   /* Typography */
-  --font-body: "Inter", sans-serif;
-  --font-display: "Playfair Display", serif;
+  --font-body: "YourBodyFont", sans-serif;
+  --font-display: "YourDisplayFont", serif;
   
   /* Colors - set both prefixes */
   --color-bg-primary: #FFFFFF;
@@ -158,38 +164,45 @@ In customer template's `app/globals.css`, add font imports after `@import "tailw
 }
 ```
 
-### 4. Test Theme
-Set in customer site's `config/index.ts`:
+#### 4. Use in Customer Site
+In `config/index.ts`:
 ```typescript
 export const config: SiteConfig = {
-  site: {
-    theme: "mytheme"
-  }
+  site: { theme: "mytheme" }
 }
 ```
 
-**Note:** Fonts are loaded in `globals.css` for all themes. While this means all theme fonts load upfront, it's simpler than dynamic loading and fonts are cached anyway. For ~5-10 themes this is acceptable overhead.
+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)
-Use the exact same props interface as the base component (otherwise switching between themes will break).
+#### 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 {
-  headline?: string;  // ← Use these prop names
-  subhead?: string;
-  // ...
+  title?: string;  // ← Use these exact prop names
+  subtitle?: string;
+  ctaText?: string;
+  ctaHref?: string;
 }
 ```
 
-Then create variant with matching interface:
+Create variant with matching interface:
 ```typescript
 // src/design_system/sections/hero-home.mytheme.tsx
-export const HeroHome = ({ headline, subhead, ctaText, ctaHref }: HeroHomeProps) => (
+export const HeroHome = ({ title, subtitle, ctaText, ctaHref }: HeroHomeProps) => (
   <section className="bg-primary py-20">
-    <h1 className="font-display text-display-xl">{headline}</h1>
-    <p className="font-body text-lg">{subhead}</p>
+    <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>
 );
@@ -198,8 +211,16 @@ import { registerThemeVariant } from '../../lib/component-registry';
 registerThemeVariant('hero-home', 'mytheme', HeroHome);
 ```
 
-### 6. Register Component Variants
-`src/design_system/sections/index.tsx`:
+#### 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",
@@ -42,6 +42,10 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
+    "@fontsource/inter": "^5.2.8",
+    "@fontsource/merriweather": "^5.2.11",
+    "@fontsource/playfair-display": "^5.2.8",
+    "@fontsource/poppins": "^5.2.7",
     "@untitledui/icons": "^0.0.19",
     "clsx": "^2.1.1",
     "embla-carousel-react": "^8.6.0",

package/src/styles/fonts.css

@@ -0,0 +1,21 @@
+/**
+ * Theme Fonts
+ * Self-hosted via Fontsource for better performance and reliability
+ */
+
+/* Aman Theme Fonts */
+@import "@fontsource/inter/300.css";
+@import "@fontsource/inter/400.css";
+@import "@fontsource/inter/600.css";
+@import "@fontsource/playfair-display/400.css";
+@import "@fontsource/playfair-display/700.css";
+
+/* Barelux Theme Fonts */
+@import "@fontsource/merriweather/300.css";
+@import "@fontsource/merriweather/400.css";
+@import "@fontsource/merriweather/700.css";
+@import "@fontsource/poppins/300.css";
+@import "@fontsource/poppins/400.css";
+@import "@fontsource/poppins/500.css";
+@import "@fontsource/poppins/600.css";
+@import "@fontsource/poppins/700.css";

package/src/styles/theme.css

@@ -3,10 +3,6 @@
  * Contains the colors and utilities used by the site template
  */
 
-/* Import fonts for all themes */
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600&family=Playfair+Display:wght@400;700&display=swap');
-@import url('https://fonts.googleapis.com/css2?family=Merriweather:wght@300;400;700&family=Poppins:wght@300;400;500;600;700&display=swap');
-
 @theme {
     /* ==================== FONTS ==================== */
     --font-body: var(--font-inter, "Inter"), -apple-system, "Segoe UI", Roboto, Arial, sans-serif;