Keystone Design Bootstrap

The shared design system and runtime package powering all Keystone customer websites. Provides themed sections, UI elements, the member portal, server-side API helpers, form handling, Meta Pixel tracking, and the Next.js app shell.

Documentation

| Doc | Description | |---|---| | docs/architecture.md | Package structure, rendering model, theme system, publishing workflow | | docs/server-api.md | All data-fetching functions, caching strategy, environment variables | | docs/navigation-and-layout.md | KeystoneRootLayout, SiteConfig, CTA URL resolution, dynamic nav, mobile sticky footer | | docs/member-portal.md | Member portal setup, tabs, auth flow, iframe booking, messaging | | docs/forms.md | Dynamic forms, ContactSection, form route, custom form pattern | | docs/meta-tracking.md | Meta Pixel initialization, automatic events, custom form tracking | | docs/site-customization.md | Per-site config, style overrides, component customization hierarchy | | docs/theme-system.md | Creating and registering themes, CSS tokens, component variants |

Quick start (new customer site)

1. Environment variables

# .env.local
API_URL=http://localhost:3000/api/v1
API_KEY=your-api-key-here

2. Config

// config/index.ts
import type { SiteConfig } from 'keystone-design-bootstrap/types';

export const config: SiteConfig = {
  site: { title: "Business Name", description: "…", theme: "aman" },
  navigation: { header: […], footer: [[…], […], […], […]] },
};

3. Root layout

// app/layout.tsx
import { KeystoneRootLayout } from 'keystone-design-bootstrap/next/layouts/root-layout';
import { config } from '@/config';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <KeystoneRootLayout config={config}>{children}</KeystoneRootLayout>;
}

4. CSS imports

/* app/globals.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.aman.css"; /* match your theme */
@import "../styles/custom-overrides.css";

Package exports reference

| Import path | Contents | |---|---| | keystone-design-bootstrap/sections | All section components | | keystone-design-bootstrap/elements | UI element components | | keystone-design-bootstrap/portal | PortalPage and portal sub-components | | keystone-design-bootstrap/next/layouts/root-layout | KeystoneRootLayout | | keystone-design-bootstrap/next/routes/consumer-auth | createConsumerAuthHandlers | | keystone-design-bootstrap/next/routes/form | createFormRouteHandlers (re-exported as POST) | | keystone-design-bootstrap/lib/server-api | Server-side data fetching functions | | keystone-design-bootstrap/lib/cta-urls | resolveCtaUrls, resolvePortalPath, isExternalCtaUrl | | keystone-design-bootstrap/tracking | firePixelEvent, setPixelUserData | | keystone-design-bootstrap/types | TypeScript types | | keystone-design-bootstrap/hooks | Client-side hooks | | keystone-design-bootstrap/styles/* | CSS files |

Local development

Use yalc to test local builds in a customer site:

# In this package
npm run build && yalc publish

# In the customer site
yalc update keystone-design-bootstrap

# To restore the published npm version
yalc remove keystone-design-bootstrap && npm install

Creating a new theme

See docs/theme-system.md for the full guide.

Quick checklist:

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
6. npm run lint && npm run typecheck && npm run build — must all pass

Available themes: classic, aman, barelux, balance