Simple Site Framework

A configuration-driven framework for building professional service websites with Next.js, React, and TypeScript.

Features

• Configuration-Driven: Define your site's theme, content, and navigation in simple config files
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Flexible i18n: Configurable internationalization with slug translation, locale-prefixed routing, and rewrite/redirect generation
• 40+ Components: Pre-built sections, layouts, UI, content, and MDX components
• Themeable: Colors, fonts, design tokens, and prose typography presets (minimal/editorial/docs)
• Content System: Blog, policy, and generic MDX content pages with per-locale markdown loading
• SEO: Metadata generation, JSON-LD structured data, sitemap, and OG image generation from ThemeConfig
• Security: CSP and security headers with preset system (Google Analytics, Maps, Fonts)
• A/B Testing: PostHog experiment integration with localStorage fallback
• Next.js Optimized: Built for Next.js 14-16 with App Router and RSC compatibility
• CLI Tools: Scaffold new projects and manage framework tasks with built-in commands
• Accessibility First: WCAG 2.1 AA compliant with ARIA form support and keyboard navigation
• Performance Optimized: Lazy loading, code splitting, and optimized animations

Quick Start with CLI

The fastest way to get started is with the CLI scaffolding tool:

npx @zoyth/simple-site-framework create my-site
cd my-site
npm install
npm run dev

This creates a complete Next.js project with:

• All framework dependencies configured
• Sample theme and content configs
• Example pages using all major components
• Tailwind CSS properly configured

Installation

For existing projects:

npm install @zoyth/simple-site-framework

Peer Dependencies

This framework requires the following peer dependencies:

npm install next@16 react@19 react-dom@19 tailwindcss@4

Note: Tailwind CSS v3.4+ and v4.x are both fully supported. The framework uses standard Tailwind utility classes that work across both versions.

⚠️ Components Rendering Without Styling?

If your site renders but looks plain/unstyled, see TROUBLESHOOTING.md for a complete setup checklist. The framework requires custom theme tokens to be defined in your Tailwind config.

Tailwind CSS Compatibility

The framework is built with Tailwind CSS and works seamlessly with both v3.4+ and v4.x.

Required Tailwind Configuration

Your project's tailwind.config.ts must include the framework components in the content array:

import type { Config } from 'tailwindcss';
import { getTailwindColors } from '@zoyth/simple-site-framework';
import { myTheme } from './src/config/theme';

const config: Config = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    // Include framework components for Tailwind to scan
    './node_modules/@zoyth/simple-site-framework/dist/**/*.{js,mjs}',
  ],
  theme: {
    extend: {
      // v2: auto-generate all color utilities from your theme config
      colors: getTailwindColors(myTheme),
      fontFamily: {
        heading: ['var(--font-heading)', 'serif'],
        body: ['var(--font-body)', 'sans-serif'],
      },
    },
  },
};

export default config;

Why Both Versions Work

The framework only uses standard Tailwind utility classes that haven't changed between v3 and v4:

• Spacing: px-4, py-6, mt-8
• Layout: flex, grid, items-center
• Colors: bg-primary, text-white, border-slate-200
• Typography: text-lg, font-bold
• Effects: hover:opacity-80, transition-colors

These utilities are stable and work identically in both Tailwind v3.4+ and v4.x.

Quick Start

1. Create Theme Configuration

// src/config/theme.ts
import { ThemeConfigV2 } from '@zoyth/simple-site-framework';

export const myTheme: ThemeConfigV2 = {
  version: 2,
  brand: {
    name: 'My Company',
    palette: {
      coral: '#F16531',
      navy: '#1A202C',
    },
    shadeBase: '#0f172a',   // darkest neutral
    shadeLight: '#f8fafc',  // lightest neutral
    fonts: {
      heading: { family: 'Playfair Display', weights: [400, 700, 900], fallback: 'serif' },
      body: { family: 'IBM Plex Sans', weights: [300, 400, 600], fallback: 'sans-serif' },
    },
  },
  design: {
    borderRadius: 'rounded',
    shadows: 'subtle',
    spacing: 'comfortable',
  },
  // Optional: override derived semantic tokens
  // semantic: { primary: 'coral', accent: 'navy' },
  // Optional: enable dark mode
  // darkMode: { enabled: true },
};

v1 configs still work. The framework auto-detects the version. See migrateThemeV1toV2() for automated migration.

2. Create Content Configuration

// src/config/content.ts
import { SiteContent } from 'simple-site-framework';

export const myContent: SiteContent = {
  metadata: {
    siteName: 'My Company',
    siteUrl: 'https://example.com',
    // ... more metadata
  },
  hero: {
    headline: {
      fr: 'Bienvenue',
      en: 'Welcome',
    },
    // ... more hero content
  },
  // ... more content sections
};

3. Create Navigation Configuration

// src/config/navigation.ts
import { NavigationConfig } from 'simple-site-framework';

export const myNavigation: NavigationConfig = {
  header: {
    logo: {
      image: '/logo.png',
      imageAlt: {
        fr: 'Mon Entreprise',
        en: 'My Company',
      },
      href: '/',
      width: 1674,        // Actual image width (for Next.js optimization)
      height: 613,        // Actual image height (for Next.js optimization)
      displayHeight: 48,  // Rendered height in header (defaults to 48px)
    },
    mainNav: [
      // ... nav items
    ],
  },
  // ... more navigation config
};

4. Use Components in Your Pages

// src/app/[locale]/page.tsx
import { HeroSection, ServicesSection, ContactSection } from 'simple-site-framework';
import { myContent } from '@/config/content';

export default function HomePage({ params }: { params: { locale: string } }) {
  return (
    <>
      <HeroSection
        content={myContent.hero}
        locale={params.locale}
        animations={{ headline: 'fadeInUp', cta: 'fadeInUp' }}
        stickyCtaAfterScroll={true}
      />
      <ServicesSection content={myContent.services} locale={params.locale} />
      <ContactSection
        locale={params.locale}
        content={myContent.contact}
        formConfig={{
          enabled: true,
          fields: ['name', 'email', 'phone', 'subject', 'message'],
          requiredFields: ['name', 'email', 'message']
        }}
      />
    </>
  );
}

Enhanced Component Examples

Button with Loading State

import { Button } from 'simple-site-framework';

<Button
  variant="filled"
  size="lg"
  loading={isSubmitting}
  loadingText="Sending..."
  success={isSuccess}
  successText="Sent!"
  icon={<Icons.Send />}
  ripple
>
  Submit
</Button>

Icon Usage

import { Icon, Icons } from 'simple-site-framework';

// Type-safe icon by name
<Icon name="Mail" size={24} />

// Pre-configured preset
<Icons.Mail size={24} />

// With custom styling
<Icon name="Check" className="text-green-600" />

CodeBlock for Documentation

import { CodeBlock } from 'simple-site-framework';

<CodeBlock
  code={`const example = "Hello World";`}
  language="typescript"
  showLineNumbers
  showCopy
/>

5. Use Layout Components

// src/app/[locale]/layout.tsx
import { Header, Footer } from 'simple-site-framework';
import { myNavigation } from '@/config/navigation';

export default function Layout({ children, params }: LayoutProps) {
  return (
    <html lang={params.locale}>
      <body>
        <Header config={myNavigation.header} locale={params.locale} />
        <main>{children}</main>
        <Footer config={myNavigation.footer} locale={params.locale} />
      </body>
    </html>
  );
}

Available Components (40+)

Layout Components

• Header - Responsive header with mobile menu, navigation, and language switcher
• Footer - Multi-column footer with links, social media, and copyright
• LanguageSelector - Auto-adapting language selector (text toggle for 2 languages, dropdown for 3+)
• PageLayout - Standard page wrapper with consistent spacing
• ServicePageLayout - Specialized layout for service detail pages with auto BreadcrumbList JSON-LD
• BlogLayout - Blog post layout with author/date, featured image, prose content, and TOC sidebar
• BlogIndex - Blog listing page with tag filtering and pagination
• PolicyLayout - Legal/policy document layout with TOC and contact footer
• LazySection - Wrapper for lazy-loading sections with intersection observer

Section Components

• HeroSection - Advanced hero with animations, video backgrounds, parallax, sticky CTA, trust badges
• AboutSection - About section with rich content, timeline, team grid
• ServicesSection - Services grid with hover effects and filtering
• FeaturesGrid - Feature showcase with icons and descriptions
• TestimonialsSection - Customer testimonials with ratings and rotation
• FAQSection - Searchable, expandable FAQ accordion
• TeamSection - Team member grid with bios and social links
• ContactSection - Full contact form with validation, multiple locations, maps, office hours
• CTASection - Call-to-action sections with variants (banner, split, card)
• PricingSection - Pricing tables with feature comparison
• StatsSection - Statistics showcase with counter animations
• TimelineSection - Company history or process timeline
• LiveProof - Real-time social proof notifications
• NewsletterSignup - Email newsletter subscription form

UI Components

• Button - Enhanced button with loading/success states, icons, ripple effects, 6 variants, 5 sizes, tooltips
• Card - Flexible card container with variants and hover effects
• Icon - Type-safe Lucide icon wrapper with 1000+ icons
• Input / Textarea / Select / Checkbox / Radio - Form inputs with validation states
• LeadForm - Lead capture form with validation and honeypot spam protection
• FormField - Form field wrapper with label and error display
• Breadcrumb - Breadcrumb navigation
• Tabs / Accordion / Dialog / Tooltip - Interactive elements (Radix UI)
• Toast - Toast notifications
• CookieConsent - Cookie consent banner for Loi 25 / GDPR compliance

Content & MDX Components

• ExternalLink - MDX link component that opens external URLs in new windows
• defaultMdxComponents - Sensible default component map for MDX content

SEO & Metadata Components

• SEOMetaTags - Page-level meta tags
• I18nMetaTags - Hreflang and locale alternate tags
• StructuredData - JSON-LD structured data rendering

Experimentation

• Experiment - Render-prop component for PostHog A/B test variants

Development & Documentation Tools

• StyleGuide - Comprehensive interactive style guide displaying all brand elements
• CodeBlock - Syntax-highlighted code blocks with copy button
• ComponentDemo - Live component preview with code examples

Using the Style Guide

The framework includes a StyleGuide component that displays all your brand elements in one place - perfect for development reference, design reviews, and stakeholder presentations.

Create a Style Guide Page

// src/app/[locale]/style-guide/page.tsx
import { type Locale, StyleGuide } from 'simple-site-framework/components';
import { myTheme } from '@/config/theme';
import { myNavigation } from '@/config/navigation';

export default async function StyleGuidePage({
  params,
}: {
  params: Promise<{ locale: Locale }>;
}) {
  const { locale } = await params;

  return (
    <StyleGuide
      locale={locale}
      theme={myTheme}
      logo={myNavigation.header.logo}
      favicon="/favicon.ico"
    />
  );
}

Visit /style-guide to see:

• Logo and favicon with dimensions
• Complete color palette with hex codes
• Brand gradients
• Typography (all heading levels, body text, font families)
• Button variants and sizes
• Form components and states
• UI components (cards, breadcrumbs)
• Spacing scale reference

Tip: Add robots: 'noindex, nofollow' to metadata to hide from search engines.

Internationalization (i18n)

The framework provides a flexible internationalization system that supports any number of languages. Projects configure their own locale preferences and the framework handles routing, detection, and SEO.

Quick Start

1. Create i18n configuration:

// src/config/i18n.ts
import type { I18nConfig } from 'simple-site-framework/lib/i18n';

export const i18nConfig: I18nConfig = {
  locales: ['en', 'fr', 'es'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',
  localeDetection: true,
  localeNames: {
    en: 'English',
    fr: 'Français',
    es: 'Español',
  },
};

2. Create middleware:

// src/middleware.ts
import { createI18nMiddleware } from 'simple-site-framework/lib/i18n';
import { i18nConfig } from './src/config/i18n';

export default createI18nMiddleware(i18nConfig);

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

3. Initialize in layout:

// src/app/[locale]/layout.tsx
import { setI18nConfig } from 'simple-site-framework/lib/i18n';
import { i18nConfig } from '../../config/i18n';

setI18nConfig(i18nConfig);

export default function Layout({ children, params }) {
  // ... rest of layout
}

Key Features

• 3 Locale Prefix Modes: 'always' (all URLs prefixed), 'as-needed' (only non-default prefixed), 'never' (no prefixes)
• Automatic Detection: Browser language detection with cookie persistence
• Auto-Adapting Selector: Text toggle for 2 languages, dropdown for 3+
• SEO Optimized: Automatic hreflang tags, canonical URLs, OpenGraph locale tags
• RTL Support: Built-in right-to-left language support
• Slug Translation: Custom URL translations per language
• Formatters: Locale-aware date, number, currency, and relative time formatting

Documentation

• Configuration Reference - Complete I18nConfig options
• Migration Guide - Upgrade from hardcoded system
• Examples - Common i18n scenarios
• SEO Guide - Multilingual SEO best practices

Utilities

Content

• getLocalizedString(localizedString, locale) - Get localized text
• loadContent(slug, locale, options) - Load and compile MDX content pages
• getContentSlugs(locale, contentDir) - Discover available content slugs per locale
• loadBlogPost(slug, locale) / getBlogPostSlugs(locale) - Blog content loading
• loadPolicy(slug, locale) / getPolicySlugs(locale) - Policy content loading
• generateBlogRssFeed(posts, options) - RSS feed generation

i18n

• formatDate(date, locale, options) - Locale-aware date formatting
• formatNumber(value, locale, options) - Locale-aware number formatting
• formatCurrency(amount, locale, currency) - Locale-aware currency formatting
• formatRelativeTime(value, unit, locale) - Locale-aware relative time
• translateSlug(path, fromLocale, toLocale) - Translate URL slugs between locales
• localePath(path, locale) - Build locale-prefixed internal links
• generateI18nRewrites(config) - Generate Next.js rewrites from slug translations
• generateI18nRedirects(config) - Generate Next.js redirects from slug translations

SEO

• generateMetadata(options) - Generate Next.js metadata with i18n alternates
• generateOgImage(theme, options) - Generate branded OG images from ThemeConfig
• ogImageSize - Standard OG image dimensions (1200x630)
• createBreadcrumbList(items) / createFAQPage(items) - JSON-LD structured data helpers
• generateSitemap(config) - Multi-language sitemap generation

Theme

• generateThemeCSS(theme) - Generate CSS custom properties from theme (v1 or v2)
• generateDesignTokens(theme) - Generate design token CSS
• generateDarkModeCSS(theme) - Generate dark mode CSS for v2 themes
• generateProseCSS(theme) - Generate prose typography CSS (minimal/editorial/docs presets)
• resolveTokens(config) - Resolve a v2 config into concrete hex values
• getTailwindColors(config) - Generate Tailwind v3 color mapping from v2 config
• migrateThemeV1toV2(v1) - Migrate a v1 config to v2 format
• hexToRgb, rgbToHex, rgbToOklch, oklchToRgb - Color conversions
• generateShadeRamp(light, dark) - Generate 30-step shade ramp via OKLCH interpolation
• darken(hex, amount), lighten(hex, amount) - Adjust color lightness
• PROSE_CLASSES - Shared Tailwind prose class string for content layouts
• cn(...classes) - Merge Tailwind classes with clsx

Security

• generateSecurityHeaders(options) - Generate security headers with CSP presets (google-analytics, google-maps, google-fonts)

Experiments (Client-Only)

• useExperiment(config) - PostHog experiment hook with localStorage fallback
• <Experiment> - Render-prop component for declarative variant rendering

Configuration Schemas

The framework exports TypeScript types for all configurations:

• ThemeConfig - Theme configuration (union of V1 and V2)
• ThemeConfigV1 - v1 flat theme configuration
• ThemeConfigV2 - v2 3-layer design token configuration
• SiteContent - Content configuration
• NavigationConfig - Navigation configuration
• LocalizedString - Bilingual string type
• And many more...

CLI Tools

The framework includes two CLI commands for project management:

create-simple-site

Scaffold a new Next.js project with the framework pre-configured:

npx @zoyth/simple-site-framework create my-site

simple-site

Framework management commands:

# Run migrations when upgrading versions
npx simple-site migrate

# Dry run to see what would change
npx simple-site migrate --dry-run

# Migrate to specific version
npx simple-site migrate --to=0.2.0

Key Features

Enhanced Button Component

• 6 variants: outlined, filled, text, ghost, link, destructive
• 5 sizes: xs, sm, md, lg, xl
• States: loading, success, disabled
• Icons: left, right, or icon-only buttons
• Effects: ripple animation, hover states
• Tooltips: automatic disabled state tooltips

Advanced HeroSection

• Animations: fadeInUp, fadeIn, slideInLeft, with stagger
• Backgrounds: gradient, video, parallax effects
• Interactive: sticky CTA that appears on scroll
• Trust signals: badge display, social proof
• Scroll indicator: animated scroll hint

Full-Featured ContactSection

• Dynamic forms: configurable fields with validation
• Multiple locations: office cards with maps, hours, directions
• Spam protection: honeypot and rate limiting
• File uploads: optional attachment support
• Integrations: ready for email/CRM services

Type-Safe Icons

• 1000+ icons: from Lucide React library
• Type safety: autocomplete for all icon names
• Presets: common icons pre-configured
• Consistent: automatic sizing and styling

Documentation

Getting Started

• QUICKSTART.md - Complete step-by-step guide to building a new site
• TROUBLESHOOTING.md - Solutions for common setup issues

Internationalization

• docs/i18n/CONFIGURATION.md - Complete i18n configuration reference
• docs/i18n/MIGRATION.md - Migration guide from hardcoded system
• docs/i18n/EXAMPLES.md - Common i18n scenarios and patterns
• docs/i18n/SEO.md - Multilingual SEO best practices

Accessibility

• docs/accessibility/overview.md - Accessibility commitment and quick start
• docs/accessibility/wcag-compliance.md - WCAG 2.1 AA compliance checklist
• docs/accessibility/keyboard-navigation.md - Keyboard patterns and focus management
• docs/accessibility/screen-readers.md - Screen reader testing and ARIA guidelines
• docs/accessibility/common-patterns.md - Reusable accessibility patterns

Migration & Upgrading

• docs/migration/overview.md - Version support, upgrade process, deprecation policy
• docs/migration/changelog.md - Complete version history

Architecture

• docs/architecture/decisions.md - Architecture Decision Records (ADRs)

License

MIT

Author

François Lane