# Kutby Theme — Architecture Foundation

Premium commercial-grade WordPress theme foundation for educational platforms.

## Version

2.5.0 — Foundation v2.5 (Module Manager, Design Tokens PHP, Admin DS components, Field Registry, events, live-settings stubs). No finished frontend UI yet.

## Build assets

```bash
cd wp-content/themes/kutby
npm install
npm run build    # → assets/dist/* + manifest.json
npm run dev      # Vite HMR (set define('KUTBY_DEV', true) in wp-config.php)
```

Production loads hashed files from `assets/dist` via the Vite manifest. If dist is missing, the theme falls back to legacy `assets/css` + `assets/js`.

See `FOUNDATION-V2-REPORT.md` for the upgrade report.

## Goals

- Extreme performance (Core Web Vitals)
- SEO-first semantic HTML
- Mobile-first, accessibility (WCAG AA)
- Modular PHP architecture (no bloated `functions.php`)
- Custom Theme Options (Settings API — no Redux/Kirki/ACF)

## Forbidden on frontend

Elementor, Divi, Bootstrap, Tailwind, jQuery (frontend), Font Awesome, Google Fonts CDN, external CSS/JS libraries.

## Structure

```
kutby/
├── assets/
│   ├── css/          # Modular CSS (base, layout, components, pages, utilities)
│   ├── js/           # Vanilla JS modules (defer)
│   ├── fonts/        # Local @font-face only
│   ├── images/
│   └── icons/        # SVG only
├── inc/
│   ├── Admin/        # Dashboard UI
│   ├── Assets/       # AssetLoader
│   ├── Core/         # Theme, Setup, Autoloader, Constants
│   ├── Fields/       # Field renderer
│   ├── Helpers/      # Utils
│   ├── Hooks/        # Frontend hooks
│   ├── Integrations/ # Plugin bridges
│   ├── Pages/        # Options panels
│   ├── Performance/  # Perf switches
│   ├── Sanitizers/   # Sanitization helpers
│   ├── SEO/          # OG / Twitter / Schema foundation
│   ├── TemplateTags/ # Template helpers
│   └── ThemeOptions/ # Defaults, Manager, Registry, Sanitizer
├── template-parts/
├── templates/
├── functions.php     # Bootstrap only
└── style.css         # Theme header only
```

## Bootstrap flow

1. `functions.php` loads Constants + Autoloader
2. `Kutby\Core\Theme::instance()->boot()`
3. Registers Setup, Options, Assets, Performance, SEO, Hooks, Admin

## Theme Options

Admin menu **Kutby** → panels: Dashboard, General, Appearance, Colors, Typography, Header, Footer, Homepage, Buttons, Cards, Sidebar, Breadcrumb, Search, Social, SEO, Performance, Import/Export, System.

Options stored in `wp_options` under key `kutby_options`.

CSS custom properties are generated at runtime from Colors / Typography / General.

## Activation

Appearance → Themes → **Kutby** → Activate  
Then open **Kutby** in the admin sidebar.

## Next tasks (not in this foundation)

- Visual frontend design system
- Homepage section designs
- Local font packaging
- SVG icon set
- CSS build step (concat/minify instead of `@import`)
- Full import validation workflow
