@zoyth/simple-site-framework 1.0.0

package/docs/core-concepts/overview.md

@@ -0,0 +1,351 @@
+# Core Concepts
+
+Understanding these core concepts will help you work effectively with Simple Site Framework.
+
+## The Framework Philosophy
+
+Simple Site Framework is built on three foundational principles:
+
+### 1. Configuration Over Code
+
+Instead of writing component markup repeatedly, you define your site in configuration files. The framework handles rendering, responsive design, accessibility, and performance automatically.
+
+**Traditional Approach:**
+```typescript
+// Repeated across every page
+<section className="py-20 px-4">
+  <div className="max-w-6xl mx-auto">
+    <h1 className="text-4xl font-bold text-center mb-4">
+      Welcome to Our Site
+    </h1>
+    <p className="text-xl text-gray-600 text-center max-w-2xl mx-auto">
+      We help businesses grow
+    </p>
+    <div className="flex justify-center gap-4 mt-8">
+      <a href="/contact" className="px-6 py-3 bg-blue-600 text-white rounded-lg">
+        Get Started
+      </a>
+    </div>
+  </div>
+</section>
+```
+
+**Framework Approach:**
+```typescript
+<HeroSection
+  heading="Welcome to Our Site"
+  description="We help businesses grow"
+  cta={{ text: 'Get Started', href: '/contact' }}
+  variant="centered"
+/>
+```
+
+The framework ensures consistency, accessibility, and responsive design automatically.
+
+### 2. Type Safety First
+
+Every configuration option, prop, and utility function is fully typed with TypeScript. This catches errors at build time, provides autocomplete in your editor, and serves as inline documentation.
+
+```typescript
+import type { HeroSectionProps, LocalizedString, ThemeConfig } from '@zoyth/simple-site-framework';
+
+// TypeScript knows exactly what's expected
+const heading: LocalizedString = {
+  en: 'Welcome',
+  fr: 'Bienvenue'
+};
+
+// Autocomplete shows all available variants
+<HeroSection variant="centered" | "split" | "minimal" />
+```
+
+### 3. Progressive Enhancement
+
+Start simple and add complexity only when needed:
+
+1. **Basic:** Use pre-built sections with minimal props
+2. **Customized:** Add your content and theme
+3. **Enhanced:** Override specific props or add custom styling
+4. **Advanced:** Create custom variants while keeping framework benefits
+
+You're never locked in - every component accepts `className` for escape hatches.
+
+## Key Architectural Decisions
+
+### Server Components by Default
+
+The framework leverages Next.js Server Components for optimal performance:
+
+- **Most components** are server-rendered by default (HeroSection, AboutSection, etc.)
+- **Client-only components** are explicitly marked and exported from `/client`
+- **No unnecessary JavaScript** - only interactive components ship client code
+
+```typescript
+// Server component (default export)
+import { HeroSection } from '@zoyth/simple-site-framework';
+
+// Client component (explicit /client export)
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/client';
+```
+
+See **[Server/Client Split](./server-client-split.md)** for details.
+
+### Composition Over Inheritance
+
+Components are designed to compose together naturally:
+
+```typescript
+<main>
+  <HeroSection {...heroProps} />
+  <FeaturesGrid {...featuresProps} />
+  <TestimonialSection {...testimonialProps} />
+  <CTASection {...ctaProps} />
+</main>
+```
+
+Each section is self-contained but works seamlessly with others.
+
+### Minimal Dependencies
+
+The framework has intentionally minimal dependencies:
+
+- **Required:** `clsx`, `tailwind-merge` (tiny utilities)
+- **Peer dependencies:** Next.js, React, Tailwind (you install what you need)
+- **Optional:** `framer-motion`, `react-hook-form`, `zod` (only if you use those features)
+
+This keeps your bundle small and gives you control over what's included.
+
+## How Components Work
+
+### Section Components
+
+Large, complete page sections ready to use:
+
+```typescript
+<HeroSection />      // Hero banner with heading, description, CTA
+<AboutSection />     // Company story, team, stats
+<ServicesSection />  // Service offerings grid
+<ContactSection />   // Contact form with location info
+<CTASection />       // Conversion-focused call-to-action
+```
+
+These handle:
+- Responsive layout
+- Accessibility (ARIA, keyboard nav, focus management)
+- Internationalization
+- Theme integration
+- Performance (lazy loading where appropriate)
+
+### Layout Components
+
+Persistent elements that appear across pages:
+
+```typescript
+<Header />    // Site navigation with logo, menu, CTA
+<Footer />    // Site footer with links, social, legal
+```
+
+### UI Components
+
+Building blocks for custom layouts:
+
+```typescript
+<Button />    // Themeable button with variants
+<Card />      // Container with shadow and border
+<Input />     // Form input with validation support
+<Modal />     // Accessible dialog
+```
+
+### Form Components
+
+Production-ready forms with validation:
+
+```typescript
+<ContactForm />  // Complete contact form with React Hook Form + Zod
+<FormField />    // Individual field with label, error, help text
+```
+
+### Conversion Components
+
+Specialized components for improving conversion rates:
+
+```typescript
+<MobileCTA />    // Sticky mobile CTA that appears on scroll
+<CTASection />   // Full-width conversion section
+<LiveProof />    // Social proof notification system
+```
+
+## Content Management
+
+### LocalizedString Type
+
+All user-facing text uses the `LocalizedString` type:
+
+```typescript
+type LocalizedString = {
+  [locale: string]: string;
+};
+
+// Single language
+const heading = "Welcome";
+
+// Multi-language
+const heading: LocalizedString = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido"
+};
+```
+
+Components automatically display the correct language based on the `locale` prop.
+
+### Configuration Files
+
+Organize content and settings in dedicated config files:
+
+```typescript
+// src/config/site.ts
+export const siteConfig = {
+  name: 'Your Company',
+  description: 'Professional services',
+  url: 'https://yourcompany.com',
+};
+
+// src/config/theme.ts
+export const themeConfig = {
+  colors: {
+    primary: '#F16531',
+    secondary: '#2D3748',
+  },
+  fonts: {
+    heading: 'Playfair Display',
+    body: 'Inter',
+  },
+};
+
+// src/config/navigation.ts
+export const navigation = [
+  { label: 'Home', href: '/' },
+  { label: 'About', href: '/about' },
+  { label: 'Services', href: '/services' },
+];
+```
+
+This separates content from code and makes updates easier.
+
+## Styling System
+
+### Tailwind CSS Integration
+
+The framework is built on Tailwind CSS:
+
+- **Utility-first** - Use Tailwind classes directly
+- **Theme tokens** - Define once in `tailwind.config.ts`, use everywhere
+- **Custom classes** - Every component accepts `className` prop
+
+```typescript
+<HeroSection
+  heading="Welcome"
+  className="bg-gradient-to-r from-blue-600 to-purple-600"
+/>
+```
+
+### Theme Tokens
+
+Components use semantic theme tokens:
+
+```typescript
+// In tailwind.config.ts
+colors: {
+  primary: '#F16531',
+  'primary-hover': '#D9551C',
+}
+
+// Components automatically use these
+<Button variant="filled" /> // Uses bg-primary
+```
+
+See **[Theme System](./theme-system.md)** for complete customization.
+
+## Performance Strategy
+
+### Code Splitting
+
+The framework uses smart code splitting:
+
+- **Heavy dependencies** (framer-motion) are loaded only when used
+- **Client components** are separated from server components
+- **Dynamic imports** for optional features
+
+### Lazy Loading
+
+Sections below the fold can be lazy-loaded:
+
+```typescript
+<LazySection>
+  <TestimonialSection {...props} />
+</LazySection>
+```
+
+### Optimized Assets
+
+Framework components work with Next.js optimizations:
+
+```typescript
+import Image from 'next/image';
+
+<HeroSection
+  backgroundImage="/hero.jpg" // Automatically optimized by Next.js
+/>
+```
+
+## Error Handling
+
+### Type Safety
+
+TypeScript catches most errors at build time:
+
+```typescript
+// ❌ TypeScript error - missing required prop
+<HeroSection description="..." />
+
+// ✅ Correct
+<HeroSection heading="..." description="..." />
+```
+
+### Runtime Validation
+
+Components validate props at runtime in development:
+
+```typescript
+// Warns in development if locale is missing
+<HeroSection
+  heading={{ en: 'Welcome', fr: 'Bienvenue' }}
+  locale={undefined} // ⚠️ Warning in dev console
+/>
+```
+
+### Graceful Degradation
+
+Components handle missing data gracefully:
+
+```typescript
+// If testimonials array is empty, section doesn't render
+<TestimonialSection testimonials={[]} />
+```
+
+## Next Steps
+
+Dive deeper into specific concepts:
+
+- **[Configuration-Driven Design](./configuration-driven.md)** - Learn the config approach
+- **[Internationalization](./internationalization.md)** - Multi-language support
+- **[Server/Client Split](./server-client-split.md)** - Understanding the architecture
+- **[Theme System](./theme-system.md)** - Customize appearance
+- **[Performance](./performance.md)** - Optimization strategies
+
+Or jump to practical guides:
+
+- **[Components Overview](../components/overview.md)** - Explore all components
+- **[Building a Landing Page](../guides/landing-page.md)** - Complete tutorial
+- **[SEO Optimization](../guides/seo-optimization.md)** - Ranking and discoverability

package/docs/features/accessibility/README.md

@@ -0,0 +1,73 @@
+# Accessibility
+
+Build inclusive, accessible websites that work for everyone.
+
+## Overview
+
+Simple Site Framework is built with accessibility as a core concern:
+
+- Semantic HTML throughout
+- ARIA attributes on interactive components
+- Keyboard navigation support
+- Screen reader compatibility
+- Color contrast compliance
+- Focus management
+
+## Topics
+
+- [ARIA Support](./aria-support.md) - ARIA attributes and roles
+- [Keyboard Navigation](../../accessibility/keyboard-navigation.md) - Keyboard interaction patterns
+- [Screen Readers](../../accessibility/screen-readers.md) - Screen reader compatibility
+- [Color Contrast](./color-contrast.md) - Color contrast guidelines
+- [Focus Management](./focus-management.md) - Focus handling patterns
+- [Testing](./testing.md) - Accessibility testing
+- [WCAG Compliance](../../accessibility/wcag-compliance.md) - WCAG 2.1 conformance
+
+## Additional Resources
+
+- [Common Accessibility Patterns](../../accessibility/common-patterns.md) - Frequently used patterns
+- [Accessibility Overview](../../accessibility/overview.md) - Architecture overview
+
+## Quick Reference
+
+### Semantic HTML
+
+Framework components output semantic HTML:
+
+```html
+<!-- HeroSection renders as -->
+<section aria-labelledby="hero-heading">
+  <h1 id="hero-heading">Welcome</h1>
+  <p>Description text</p>
+  <a href="/start" role="button">Get Started</a>
+</section>
+```
+
+### ARIA in Components
+
+```typescript
+// Button with accessible label
+<Button aria-label="Close menu">
+  <Icon name="x" />
+</Button>
+
+// Form with accessible errors
+<FormField
+  label="Email"
+  error="Please enter a valid email"
+  required
+/>
+```
+
+### Keyboard Support
+
+All interactive components support:
+- `Tab` / `Shift+Tab` - Navigate between elements
+- `Enter` / `Space` - Activate buttons and links
+- `Escape` - Close modals and dropdowns
+- Arrow keys - Navigate within component groups
+
+## See Also
+
+- [Accessibility Components](../../components/overview.md)
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)

package/docs/features/accessibility/aria-support.md

@@ -0,0 +1,177 @@
+# ARIA Support
+
+ARIA (Accessible Rich Internet Applications) implementation across framework components.
+
+## Built-in ARIA Attributes
+
+Framework components include appropriate ARIA attributes by default.
+
+### Sections
+
+```html
+<!-- HeroSection -->
+<section aria-labelledby="hero-heading">
+  <h1 id="hero-heading">...</h1>
+</section>
+
+<!-- FAQAccordion -->
+<div role="region" aria-labelledby="faq-heading">
+  <button aria-expanded="true" aria-controls="faq-1-content">
+    Question text
+  </button>
+  <div id="faq-1-content" role="region" aria-labelledby="faq-1-heading">
+    Answer text
+  </div>
+</div>
+```
+
+### Navigation
+
+```html
+<!-- Header -->
+<header role="banner">
+  <nav aria-label="Main navigation">
+    <ul role="menubar">...</ul>
+  </nav>
+</header>
+
+<!-- Footer -->
+<footer role="contentinfo">
+  <nav aria-label="Footer navigation">...</nav>
+</footer>
+
+<!-- Breadcrumb -->
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li aria-current="page">About</li>
+  </ol>
+</nav>
+```
+
+### Forms
+
+```html
+<!-- FormField -->
+<div>
+  <label for="email">Email <span aria-hidden="true">*</span></label>
+  <input
+    id="email"
+    type="email"
+    aria-required="true"
+    aria-invalid="true"
+    aria-describedby="email-error email-help"
+  />
+  <span id="email-error" role="alert">Please enter a valid email</span>
+  <span id="email-help">We'll never share your email</span>
+</div>
+```
+
+### Modals
+
+```html
+<!-- Modal -->
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="modal-title"
+  aria-describedby="modal-description"
+>
+  <h2 id="modal-title">Modal Title</h2>
+  <p id="modal-description">Modal content</p>
+  <button aria-label="Close dialog">×</button>
+</div>
+```
+
+## Common ARIA Patterns
+
+### Live Regions
+
+For dynamic content updates:
+
+```typescript
+// Toast notifications
+<div role="status" aria-live="polite">
+  Message sent successfully
+</div>
+
+// Error alerts
+<div role="alert" aria-live="assertive">
+  Form submission failed
+</div>
+```
+
+### Loading States
+
+```typescript
+<div aria-busy="true" aria-live="polite">
+  <LoadingSpinner aria-label="Loading content" />
+</div>
+```
+
+### Tabs
+
+```html
+<div role="tablist" aria-label="Service categories">
+  <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  Panel content
+</div>
+```
+
+## Custom ARIA Props
+
+Pass additional ARIA attributes to components:
+
+```typescript
+<Button
+  aria-label="Submit contact form"
+  aria-describedby="form-instructions"
+>
+  Submit
+</Button>
+
+<Card aria-labelledby="card-title">
+  <h3 id="card-title">Card Title</h3>
+</Card>
+```
+
+## ARIA Roles Reference
+
+### Landmark Roles
+
+| Role | Usage | Framework Component |
+|------|-------|-------------------|
+| `banner` | Site header | Header |
+| `navigation` | Nav sections | Header, Footer |
+| `main` | Main content | Layout wrapper |
+| `contentinfo` | Site footer | Footer |
+| `complementary` | Sidebar | - |
+| `search` | Search form | - |
+
+### Widget Roles
+
+| Role | Usage | Framework Component |
+|------|-------|-------------------|
+| `button` | Clickable action | Button |
+| `dialog` | Modal/popup | Modal, ExitIntentModal |
+| `tablist` / `tab` / `tabpanel` | Tab interface | Tabs |
+| `alert` | Important message | Toast |
+| `status` | Status update | Toast, LiveProof |
+
+## Best Practices
+
+- Don't add ARIA roles that duplicate native HTML semantics
+- Use `aria-label` for icon-only buttons
+- Use `aria-describedby` for additional context
+- Use `aria-live` for dynamic content changes
+- Test with actual screen readers, not just automated tools
+
+## See Also
+
+- [Screen Readers](../../accessibility/screen-readers.md)
+- [Common Patterns](../../accessibility/common-patterns.md)
+- [WCAG Compliance](../../accessibility/wcag-compliance.md)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)