uniweb 0.8.0 → 0.8.2

package/partials/agents.md

@@ -0,0 +1,809 @@
+# AGENTS.md
+
+Uniweb is a Component Content Architecture (CCA). Content lives in markdown, code lives in React components, and a runtime connects them. The runtime handles section wrapping, background rendering, context theming, and token resolution — components receive pre-parsed content and render it with semantic tokens. Understanding what the runtime does (and therefore what components should *not* do) is the key to working effectively in this architecture.
+
+## Project Structure
+
+```
+project/
+├── foundation/     # React component library
+├── site/           # Content (markdown pages)
+└── pnpm-workspace.yaml
+```
+
+Multi-site variant uses `foundations/` and `sites/` (plural) folders.
+
+- **Foundation**: React components. Those with `meta.js` are *section types* — selectable by content authors via `type:` in frontmatter. Everything else is ordinary React.
+- **Site**: Markdown content + configuration. Each section file references a section type.
+
+## Project Setup
+
+Always use the CLI to scaffold projects — never write `package.json`, `vite.config.js`, `main.js`, or `index.html` manually. The CLI resolves correct versions and structure.
+
+### New workspace
+
+```bash
+pnpm create uniweb my-project
+cd my-project && pnpm install
+```
+
+Use `--template blank` for an empty workspace, or `--template <name>` for an official template (`marketing`, `docs`, `academic`, etc.).
+
+### Adding to an existing workspace
+
+```bash
+pnpm uniweb add foundation myname --project myname
+pnpm uniweb add site myname --project myname
+pnpm install
+```
+
+The `--project` flag co-locates foundation and site under `myname/`. The CLI names them `myname` (foundation) and `myname-site` (site) to avoid workspace name collisions.
+
+### What the CLI generates
+
+**Foundation** (`vite.config.js`, `package.json`, `src/foundation.js`, `src/styles.css`):
+- `defineFoundationConfig()` in vite.config.js
+- Dependencies pinned to current npm versions
+- `@import "@uniweb/kit/theme-tokens.css"` in styles.css
+
+**Site** (`vite.config.js`, `package.json`, `main.js`, `index.html`, `site.yml`):
+- `defineSiteConfig()` in vite.config.js
+- `react-router-dom` in devDependencies (required by pnpm strict mode)
+- Standard `start()` call in main.js
+
+## Commands
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start dev server
+pnpm build      # Build for production
+```
+
+## Content Authoring
+
+### Section Format
+
+Each `.md` file is a section. Frontmatter on top, content below:
+
+```markdown
+---
+type: Hero
+theme: dark
+---
+
+### Eyebrow Text        ← pretitle (heading before a more important one)
+
+# Main Headline         ← title
+
+## Subtitle             ← subtitle
+
+Description paragraph.
+
+[Call to Action](/link)
+
+![Image](./image.jpg)
+```
+
+### Content Shape
+
+The semantic parser extracts markdown into a flat, guaranteed structure. No null checks needed — empty strings/arrays if content is absent:
+
+```js
+content = {
+  title: '',        // Main heading
+  pretitle: '',     // Heading before main title (auto-detected)
+  subtitle: '',     // Heading after title
+  subtitle2: '',    // Third-level heading
+  paragraphs: [],   // Text blocks
+  links: [],        // { href, label, role } — standalone links become buttons
+  imgs: [],         // { src, alt, role }
+  icons: [],        // { library, name, role }
+  videos: [],       // Video embeds
+  insets: [],       // Inline @Component references — { refId }
+  lists: [],        // Bullet/ordered lists
+  quotes: [],       // Blockquotes
+  data: {},         // From tagged code blocks (```yaml:tagname)
+  headings: [],     // Overflow headings after subtitle2
+  items: [],        // Each has the same flat structure — from headings after body content
+  sequence: [],     // All elements in document order
+}
+```
+
+**Items** are repeating content groups (cards, features, FAQ entries). Created when a heading appears after body content:
+
+```markdown
+# Our Features          ← title
+
+We built this for you.  ← paragraph
+
+### Fast                ← items[0].title
+Lightning quick.        ← items[0].paragraphs[0]
+
+### Secure              ← items[1].title
+Enterprise-grade.       ← items[1].paragraphs[0]
+```
+
+### Icons
+
+Use image syntax with library prefix: `![](lu-house)`. Supported libraries: `lu` (Lucide), `hi2` (Heroicons), `fi` (Feather), `pi` (Phosphor), `tb` (Tabler), `bs` (Bootstrap), `md` (Material), `fa6` (Font Awesome 6), and others. Browse at [react-icons.github.io/react-icons](https://react-icons.github.io/react-icons/).
+
+Custom SVGs: `![Logo](./logo.svg){role=icon}`
+
+### Insets (Component References)
+
+Place a foundation component inline within content using `@` syntax:
+
+```markdown
+![description](@ComponentName)
+![description](@ComponentName){param=value other=thing}
+```
+
+The three parts carry distinct information:
+- `[description]` — text passed to the component as `block.content.title`
+- `(@Name)` — foundation component to render
+- `{params}` — configuration attributes passed as `block.properties`
+
+```markdown
+![Architecture diagram](@NetworkDiagram){variant=compact}
+![Cache metrics](@PerformanceChart){period=30d}
+![](@GradientBlob){position=top-right}
+```
+
+Inset components must declare `inset: true` in their `meta.js`. They render at the exact position in the content flow where the author placed them. See meta.js section below for details.
+
+### Links and Media Attributes
+
+```markdown
+[text](url){target=_blank}              <!-- Open in new tab -->
+[text](./file.pdf){download}            <!-- Download -->
+![alt](./img.jpg){role=banner}          <!-- Role determines array: imgs, icons, or videos -->
+```
+
+Standalone links (alone on a line) become buttons. Inline links stay as text links.
+
+### Structured Data
+
+Tagged code blocks pass structured data via `content.data`:
+
+````markdown
+```yaml:form
+fields:
+  - name: email
+    type: email
+submitLabel: Send
+```
+````
+
+Access: `content.data?.form` → `{ fields: [...], submitLabel: "Send" }`
+
+### Section Backgrounds
+
+Set `background` in frontmatter — the runtime renders it automatically:
+
+```yaml
+---
+type: Hero
+theme: dark
+background: /images/hero.jpg              # Simple: URL (image or video auto-detected)
+---
+```
+
+Full syntax supports `image`, `video`, `gradient`, `color` modes plus overlays:
+
+```yaml
+background:
+  image: { src: /img.jpg, position: center top }
+  overlay: { enabled: true, type: dark, opacity: 0.5 }
+```
+
+Components that render their own background declare `background: 'self'` in `meta.js`.
+
+### Page Organization
+
+```
+site/layout/
+├── header.md               # type: Header — rendered on every page
+├── footer.md               # type: Footer — rendered on every page
+└── left.md                 # type: Sidebar — optional sidebar
+
+site/pages/
+└── home/
+    ├── page.yml            # title, description, order
+    ├── hero.md             # Single section — no prefix needed
+    └── (or for multi-section pages:)
+    ├── 1-hero.md           # Numeric prefix sets order
+    ├── 2-features.md
+    └── 3-cta.md
+```
+
+Decimals insert between: `2.5-testimonials.md` goes between `2-` and `3-`.
+
+**Ignored files/folders:**
+- `README.md` — repo documentation, not site content
+- `_*.md` or `_*/` — drafts and private content (e.g., `_drafts/`, `_old-hero.md`)
+
+**page.yml:**
+```yaml
+title: About Us
+description: Learn about our company
+order: 2                    # Navigation sort position
+pages: [team, history, ...] # Child page order (... = rest). Without ... = strict (hides unlisted)
+index: getting-started      # Which child page is the index
+```
+
+**site.yml:**
+```yaml
+index: home                         # Just set the homepage
+pages: [home, about, ...]           # Order pages (... = rest, first = homepage)
+pages: [home, about]                # Strict: only listed pages in nav
+```
+
+Use `pages:` with `...` for ordering, without `...` for strict visibility control. Use `index:` for simple homepage selection.
+
+### Section Nesting (Child Sections)
+
+Some section types need children — a Grid that arranges cards, a TabGroup that holds panels. Use the `@` prefix and `nest:` property:
+
+```
+pages/home/
+├── page.yml
+├── 1-hero.md
+├── 2-features.md        # Parent section (type: Grid)
+├── 3-cta.md
+├── @card-a.md           # Child of features (@ = not top-level)
+├── @card-b.md
+└── @card-c.md
+```
+
+```yaml
+# page.yml
+nest:
+  features: [card-a, card-b, card-c]
+```
+
+**Rules:**
+- `@`-prefixed files are excluded from the top-level section list
+- `nest:` declares parent-child relationships (parent name → array of child names)
+- Child files **must** use the `@` prefix — the filename and YAML must agree
+- `@@` prefix signals deeper nesting (e.g., `@@sub-item.md` for grandchildren)
+- `nest:` is flat — each key is a parent: `nest: { features: [a, b], a: [sub-1] }`
+- Children are ordered by their position in the `nest:` array
+- Orphaned `@` files (no parent in `nest:`) appear at top-level with a warning
+
+Components receive children via `block.childBlocks`:
+
+```jsx
+export default function Grid({ block, params }) {
+  return (
+    <div className={`grid grid-cols-${params.columns || 2} gap-6`}>
+      {block.childBlocks.map(child => {
+        const Comp = child.initComponent()
+        return Comp ? <Comp key={child.id} block={child} /> : null
+      })}
+    </div>
+  )
+}
+```
+
+### Composition in practice
+
+Section nesting and insets together give content authors significant layout power without requiring new components. A single Grid section type composes *any* combination of children — each child is its own section type with its own content:
+
+```
+pages/home/
+├── page.yml
+├── 1-hero.md
+├── 2-highlights.md          # type: Grid, columns: 3
+├── 3-cta.md
+├── @stats.md                # type: StatCard — numbers and labels
+├── @testimonial.md          # type: Testimonial — quote with attribution
+└── @demo.md                 # type: SplitContent — text + ![](@LiveDemo) inset
+```
+
+```yaml
+nest:
+  highlights: [stats, testimonial, demo]
+```
+
+The content author chose three different section types as children, arranged them in a grid, and embedded an interactive component inside one of them — all through markdown and YAML. The developer wrote one Grid component, a few card-level section types, and an inset. No bespoke "highlights" component needed.
+
+This is functional composition applied to content: small, focused section types that combine into richer layouts. The developer builds reusable pieces (Grid, StatCard, Testimonial, SplitContent); the content author composes them. Adding a fourth card means creating one `@`-prefixed file and adding its name to the `nest:` array.
+
+### When to use which pattern
+
+| Pattern | Authoring | Use when |
+|---------|-----------|----------|
+| **Items** (`content.items`) | Heading groups in one `.md` file | Repeating content within one section (cards, FAQ entries) |
+| **Insets** (`block.insets`) | `![](@Component)` in markdown | Embedding a self-contained visual (chart, diagram, widget) |
+| **Child sections** (`block.childBlocks`) | `@`-prefixed `.md` files + `nest:` | Children with rich authored content (testimonials, carousel slides) |
+
+Does the content author write content *inside* the nested component? **Yes** → child sections. **No** (self-contained, driven by params/data) → insets. Repeating groups within one section → items. These patterns compose: a child section can contain insets, and items work inside children.
+
+**Inset rule of thumb:** If the same interactive widget or self-contained visual appears inside multiple different sections (a copy-able command block, a chart, a demo player), make it an inset. The content author places it with `![](@CommandBlock)` wherever it's needed — no prop drilling, no imports.
+
+## Semantic Theming
+
+CCA separates theme from code. Components use **semantic CSS tokens** instead of hardcoded colors. The runtime applies a context class (`context-light`, `context-medium`, `context-dark`) to each section based on `theme:` frontmatter.
+
+```jsx
+// ❌ Hardcoded — breaks in dark context, locked to one palette
+<h2 className="text-slate-900">...</h2>
+
+// ✅ Semantic — adapts to any context and brand automatically
+<h2 className="text-heading">...</h2>
+```
+
+**Core tokens** (available as Tailwind classes):
+
+| Token | Purpose |
+|-------|---------|
+| `text-heading` | Headings |
+| `text-body` | Body text |
+| `text-subtle` | Secondary/de-emphasized text |
+| `bg-section` | Section background |
+| `bg-card` | Card/panel background |
+| `bg-muted` | Hover states, zebra rows |
+| `border-border` | Borders |
+| `text-link` | Link color |
+| `bg-primary` | Primary action background |
+| `text-primary-foreground` | Text on primary background |
+| `bg-secondary` | Secondary action background |
+| `text-success` / `bg-success-subtle` | Status: success |
+| `text-error` / `bg-error-subtle` | Status: error |
+| `text-warning` / `bg-warning-subtle` | Status: warning |
+| `text-info` / `bg-info-subtle` | Status: info |
+
+### What the runtime handles (don't write this yourself)
+
+The runtime does significant work that other frameworks push onto components. Understanding this prevents writing unnecessary code:
+
+1. **Section backgrounds** — The runtime renders image, video, gradient, color, and overlay backgrounds from frontmatter. Components never set their own section background.
+2. **Context classes** — The runtime wraps every section in `<section class="context-{theme}">`, which auto-applies `background-color: var(--section)` and sets all token values.
+3. **Token resolution** — All 24+ semantic tokens resolve automatically per context. A component using `text-heading` gets dark text in light context, white text in dark context — zero conditional logic.
+4. **Colored section backgrounds** — Content authors create tinted sections via frontmatter, not component code:
+   ```yaml
+   ---
+   type: Features
+   theme: light
+   background:
+     color: var(--primary-50)       # Light blue tint with light-context tokens
+   ---
+   ```
+
+**What components should NOT contain:**
+
+| Don't write | Why |
+|-------------|-----|
+| `bg-white` or `bg-gray-900` on section wrapper | Engine applies `bg-section` via context class |
+| `const themes = { light: {...}, dark: {...} }` | Context system replaces theme maps entirely |
+| `isDark ? 'text-white' : 'text-gray-900'` | Just write `text-heading` — it adapts |
+| Background rendering code | Declare `background:` in frontmatter instead |
+| Color constants / tokens files | Colors come from `theme.yml` |
+| Custom CSS variables for colors (`--ink`, `--paper`, `--accent`) in `styles.css` | Map source colors to `theme.yml` colors/neutral. The build generates `--primary-50` through `--primary-950`, `--neutral-50` through `--neutral-950`, etc. Components use semantic tokens (`text-heading`, `bg-section`) that resolve from these palettes per context. A parallel color system bypasses all of this. |
+
+**What to hardcode** (not semantic — same in every context): layout (`grid`, `flex`, `max-w-6xl`), spacing (`p-6`, `gap-8`), typography scale (`text-3xl`, `font-bold`), animations, border-radius.
+
+**Content authors control context** in frontmatter:
+
+```markdown
+---
+type: Testimonial
+theme: dark           ← sets context-dark, all tokens resolve to dark values
+---
+```
+
+**Site controls the palette** in `theme.yml`. The same foundation looks different across sites because tokens resolve from the site's color configuration, not from component code.
+
+### theme.yml
+
+```yaml
+# site/theme.yml
+colors:
+  primary:
+    base: '#3b82f6'
+    exactMatch: true        # Use this exact hex at the 500 shade
+  secondary: '#64748b'
+  accent: '#8b5cf6'
+  neutral: stone            # Named preset: stone, zinc, gray, slate, neutral
+
+contexts:
+  light:
+    section: '#fafaf9'      # Override individual tokens per context
+    primary: var(--primary-500)
+    primary-hover: var(--primary-600)
+
+fonts:
+  import:
+    - url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap'
+  heading: "'Inter', system-ui, sans-serif"
+  body: "'Inter', system-ui, sans-serif"
+
+inline:
+  emphasis:                 # For [text]{emphasis} in markdown
+    color: var(--link)
+    font-weight: '600'
+
+vars:                       # Override foundation-declared variables
+  header-height: 5rem
+```
+
+Each color generates 11 OKLCH shades (50–950). The `neutral` palette is special — use a named preset (`stone` for warm) rather than a hex value. Three contexts are built-in: `light` (default), `medium`, `dark`. Context override keys match token names — `section:` not `bg:`, `primary:` not `btn-primary-bg:`.
+
+### Foundation variables
+
+Foundations declare customizable layout/spacing values in `foundation.js`:
+
+```js
+export default {
+  vars: {
+    'header-height': { default: '4rem' },
+    'sidebar-width': { default: '280px' },
+  },
+}
+```
+
+Sites override them in `theme.yml` under `vars:`. Components use them as `var(--header-height)`.
+
+**When to break the rules:** Header/footer components that float over content may need direct color logic (reading the first section's theme). Decorative elements with fixed branding (logos) use literal colors.
+
+## Component Development
+
+### Props Interface
+
+```jsx
+function MyComponent({ content, params, block }) {
+  const { title, paragraphs, links, items } = content  // Guaranteed shape
+  const { columns, variant } = params                    // Defaults from meta.js
+  const { website } = useWebsite()                      // Or block.website
+}
+```
+
+### Section Wrapper
+
+The runtime wraps every section type in a `<section>` element with context class, background, and semantic tokens. Use static properties to customize this wrapper:
+
+```jsx
+function Hero({ content, params }) {
+  return (
+    <div className="max-w-7xl mx-auto px-6">
+      <h1 className="text-heading text-5xl font-bold">{content.title}</h1>
+    </div>
+  )
+}
+
+Hero.className = 'pt-32 md:pt-48'   // Classes on the <section> wrapper
+Hero.as = 'div'                      // Change wrapper element (default: 'section')
+
+export default Hero
+```
+
+- `Component.className` — adds classes to the runtime's wrapper. Use for section-level padding, borders, overflow. The component's own JSX handles inner layout only (`max-w-7xl mx-auto px-6`).
+- `Component.as` — changes the wrapper element. Use `'nav'` for headers, `'footer'` for footers, `'div'` when `<section>` isn't semantically appropriate.
+
+### meta.js Structure
+
+```javascript
+export default {
+  title: 'Feature Grid',
+  description: 'Grid of feature cards with icons',
+  category: 'marketing',
+  // hidden: true,          // Hide from content authors
+  // background: 'self',    // Component renders its own background
+  // inset: true,           // Available for @ComponentName references in markdown
+  // visuals: 1,            // Expects 1 visual (image, video, or inset)
+  // children: true,        // Accepts file-based child sections
+
+  content: {
+    title: 'Section heading',
+    paragraphs: 'Introduction [0-1]',
+    items: 'Feature cards with icon, title, description',
+  },
+
+  params: {
+    columns: { type: 'number', default: 3 },
+    variant: { type: 'select', options: ['default', 'centered', 'split'], default: 'default' },
+  },
+
+  presets: {
+    default: { label: 'Standard', params: { columns: 3 } },
+    compact: { label: 'Compact', params: { columns: 4 } },
+  },
+
+  // Static capabilities for cross-block coordination
+  context: {
+    allowTranslucentTop: true,  // Header can overlay this section
+  },
+}
+```
+
+All defaults belong in `meta.js`, not inline in component code.
+
+### @uniweb/kit
+
+**Primitives** (`@uniweb/kit`): `H1`–`H6`, `P`, `Span`, `Text`, `Link`, `Image`, `Icon`, `Media`, `Asset`, `SocialIcon`, `FileLogo`, `cn()`
+
+**Styled** (`@uniweb/kit/styled`): `Section`, `Render`, `Visual`, `SidebarLayout`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
+
+**Hooks:**
+- `useScrolled(threshold)` → boolean for scroll-based header styling
+- `useMobileMenu()` → `{ isOpen, toggle, close }` with auto-close on navigation
+- `useAccordion({ multiple, defaultOpen })` → `{ isOpen, toggle }` for expand/collapse
+- `useActiveRoute()` → `{ route, isActiveOrAncestor(page) }` for nav highlighting (SSG-safe)
+- `useGridLayout(columns, { gap })` → responsive grid class string
+- `useTheme(name)` → standardized theme classes
+
+**Utilities:** `cn()` (Tailwind class merge), `filterSocialLinks(links)`, `getSocialPlatform(url)`
+
+### Foundation Organization
+
+```
+foundation/src/
+├── sections/            # Section types (auto-discovered via meta.js)
+│   ├── Hero/
+│   │   ├── Hero.jsx     # Entry — or index.jsx, both work
+│   │   └── meta.js
+│   └── Features/
+│       ├── Features.jsx
+│       └── meta.js
+├── components/          # Your React components (no meta.js, not selectable)
+│   ├── ui/              # shadcn-compatible primitives
+│   │   └── button.jsx
+│   └── Card.jsx
+└── styles.css
+```
+
+Only folders with `meta.js` in `sections/` (or `components/` for older foundations) become section types. Everything else is ordinary React — organize however you like.
+
+### Website and Page APIs
+
+```jsx
+const { website } = useWebsite()
+
+// Navigation
+const pages = website.getPageHierarchy({ for: 'header' })  // or 'footer'
+// → [{ route, navigableRoute, label, hasContent, children }]
+
+// Locale
+website.hasMultipleLocales()
+website.getLocales()        // [{ code, label, isDefault }]
+website.getActiveLocale()   // 'en'
+website.getLocaleUrl('es')
+```
+
+### Insets and the Visual Component
+
+Components access inline `@` references via `block.insets` (separate from `block.childBlocks`):
+
+```jsx
+import { Visual } from '@uniweb/kit/styled'
+
+// Visual renders the first visual: inset > video > image
+function SplitContent({ content, block, params }) {
+  return (
+    <div className="flex gap-12">
+      <div className="flex-1">
+        <h2 className="text-heading">{content.title}</h2>
+      </div>
+      <Visual content={content} block={block} className="flex-1 rounded-lg" />
+    </div>
+  )
+}
+```
+
+- `block.insets` — array of Block instances from `@` references
+- `block.getInset(refId)` — lookup by refId (used by sequential renderers)
+- `content.insets` — flat array of `{ refId }` entries (parallel to `content.imgs`)
+- `<Visual>` — renders first inset > video > image from content (from `@uniweb/kit/styled`)
+
+Inset components declare `inset: true` in meta.js. Use `hidden: true` for inset-only components:
+
+```js
+// sections/insets/NetworkDiagram/meta.js
+export default {
+  inset: true,
+  hidden: true,
+  params: { variant: { type: 'select', options: ['full', 'compact'], default: 'full' } },
+}
+```
+
+### Dispatcher Pattern
+
+One section type with a `variant` param replaces multiple near-duplicates. Instead of `HeroLeft`, `HeroCentered`, `HeroSplit` — one `Hero` with `variant: left | centered | split`:
+
+```jsx
+function SplitContent({ content, block, params }) {
+  const flipped = params.variant === 'flipped'
+  return (
+    <div className={`flex gap-16 items-center ${flipped ? 'flex-row-reverse' : ''}`}>
+      <div className="flex-1">
+        {content.pretitle && (
+          <p className="text-xs font-bold uppercase tracking-widest text-subtle mb-4">
+            {content.pretitle}
+          </p>
+        )}
+        <h2 className="text-heading text-3xl font-bold">{content.title}</h2>
+        <p className="text-body mt-4">{content.paragraphs[0]}</p>
+      </div>
+      <Visual content={content} block={block} className="flex-1 rounded-2xl" />
+    </div>
+  )
+}
+```
+
+```js
+// meta.js
+export default {
+  title: 'Split Content',
+  content: { pretitle: 'Eyebrow label', title: 'Section heading', paragraphs: 'Description' },
+  params: {
+    variant: { type: 'select', options: ['default', 'flipped'], default: 'default' },
+  },
+}
+```
+
+Content authors choose the variant in frontmatter (`variant: flipped`), or the site can alternate it across sections. One component serves every "text + visual" layout on the site.
+
+### Cross-Block Communication
+
+Components read neighboring blocks for adaptive behavior (e.g., translucent header over hero):
+
+```jsx
+const firstBody = block.page.getFirstBodyBlockInfo()
+// → { type, theme, context: { allowTranslucentTop }, state }
+
+// context = static (from meta.js), state = dynamic (from useBlockState)
+```
+
+### Custom Layouts
+
+Layouts live in `foundation/src/layouts/` and are auto-discovered. Set the default in `foundation.js`:
+
+```js
+// foundation/src/foundation.js
+export default {
+  name: 'My Template',              // Display name (falls back to package.json name)
+  description: 'A brief description', // Falls back to package.json description
+  defaultLayout: 'DocsLayout',
+}
+```
+
+```jsx
+// foundation/src/layouts/DocsLayout/index.jsx
+export default function DocsLayout({ header, body, footer, left, right, params }) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      {header && <header>{header}</header>}
+      <div className="flex-1 flex">
+        {left && <aside className="w-64">{left}</aside>}
+        <main className="flex-1">{body}</main>
+        {right && <aside className="w-64">{right}</aside>}
+      </div>
+      {footer && <footer>{footer}</footer>}
+    </div>
+  )
+}
+```
+
+Layout receives pre-rendered areas as props plus `params`, `page`, and `website`. The `body` area is always implicit.
+
+**Layout meta.js** declares which areas the layout renders:
+
+```js
+// foundation/src/layouts/DocsLayout/meta.js
+export default {
+  areas: ['header', 'footer', 'left'],
+}
+```
+
+Area names are arbitrary strings — `header`, `footer`, `left`, `right` are conventional, but a dashboard layout could use `topbar`, `sidebar`, `statusbar`.
+
+**Site-side layout content** — each layout can have its own section files:
+
+```
+site/layout/
+├── header.md              # Default layout sections
+├── footer.md
+├── left.md
+└── marketing/             # Sections for the "marketing" layout
+    ├── header.md          # Different header for marketing pages
+    └── footer.md
+```
+
+Named subdirectories are self-contained — no inheritance from the root. If `marketing/` has no `left.md`, marketing pages have no left panel.
+
+**Layout cascade** (first match wins): `page.yml` → `folder.yml` → `site.yml` → foundation `defaultLayout` → `"default"`.
+
+```yaml
+# page.yml — select layout and hide areas
+layout:
+  name: MarketingLayout
+  hide: [left, right]
+```
+
+## Migrating From Other Frameworks
+
+Don't port line-by-line. Study the original implementation, then plan a new one in Uniweb from first principles. Other frameworks produce far more components than Uniweb needs — expect consolidation, not 1:1 correspondence.
+
+### Why fewer components
+
+Uniweb section types do more with less because the framework handles concerns that other frameworks push onto components:
+
+- **Dispatcher pattern** — one section type with a `variant` param replaces multiple near-duplicate components (`HeroHomepage` + `HeroPricing` → `Hero` with `variant: homepage | pricing`)
+- **Section nesting** — `@`-prefixed child files replace wrapper components that exist only to arrange children
+- **Insets** — `![](@ComponentName)` replaces prop-drilling of visual components into containers
+- **Visual component** — `<Visual>` renders image/video/inset from content, replacing manual media handling
+- **Semantic theming** — the runtime orchestrates context classes and token resolution, replacing per-component dark mode logic
+- **Engine backgrounds** — the runtime renders section backgrounds from frontmatter, replacing background-handling code in every section
+- **Rich params** — `meta.js` params with types, defaults, and presets replace config objects and conditional logic
+
+### Migration approach
+
+1. **Check if you're inside an existing Uniweb workspace** (look for `pnpm-workspace.yaml` and a `package.json` with `uniweb` as a dependency). If yes, use `pnpm uniweb add` to create projects inside it. If no, create a new workspace:
+   ```bash
+   pnpm create uniweb my-project --template blank
+   ```
+
+3. **Use named layouts** for different page groups — a marketing layout for landing pages, a docs layout for `/docs/*`. One site, multiple layouts, each with its own header/footer/sidebar content.
+
+4. **Dump legacy components under `src/components/`** — they're not section types. Import them from section types as needed during the transition.
+
+5. **Create section types one at a time.** Each is independent — one can use hardcoded content while another reads from markdown. Staged migration levels:
+   - **Level 0**: Paste the whole original file as one section type. You get routing and dev tooling immediately.
+   - **Level 1**: Decompose into section types. Name by purpose (`Institutions` → `Testimonial`). Consolidate duplicates via dispatcher pattern.
+   - **Level 2**: Move content from JSX to markdown. Components read from `content` instead of hardcoded strings. Content authors can now edit without touching code.
+   - **Level 3**: Replace hardcoded Tailwind colors with semantic tokens. Components work in any context and any brand.
+
+6. **Map source colors to `theme.yml`, not to foundation CSS.** The most common migration mistake is recreating the source site's color tokens as CSS custom properties in `styles.css` (e.g., `--ink`, `--paper`, `--accent`). This creates a parallel color system that bypasses CCA's semantic tokens, context classes, and site-level theming entirely. Instead: identify the source's primary color → set it as `colors.primary` in theme.yml. Identify the neutral tone → set it as `colors.neutral` (e.g., `stone` for warm). Identify context needs → use `theme:` frontmatter per section. Components use `text-heading`, `bg-section`, `bg-card` — never custom color variables.
+
+7. **Name by purpose, not by content** — `TheModel` → `SplitContent`, `WorkModes` → `FeatureColumns`, `FinalCTA` → `CallToAction`. Components render a *kind* of content, not specific content.
+
+8. **UI helpers → `components/`** — Buttons, badges, cards go in `src/components/` (no `meta.js` needed, not selectable by content authors).
+
+## Tailwind CSS v4
+
+Foundation styles in `foundation/src/styles.css`:
+
+```css
+@import "tailwindcss";
+@import "@uniweb/kit/theme-tokens.css";           /* Semantic tokens from theme.yml */
+@source "./sections/**/*.{js,jsx}";
+@source "./components/**/*.{js,jsx}";             /* UI helpers (Button, Card, etc.) */
+@source "../node_modules/@uniweb/kit/src/**/*.jsx";
+
+@theme {
+  /* Additional custom values — NOT for colors already in theme.yml */
+  --breakpoint-xs: 30rem;
+}
+```
+
+Semantic color tokens (`text-heading`, `bg-section`, `bg-primary`, etc.) come from `theme-tokens.css` — which the runtime populates from the site's `theme.yml`. Don't redefine colors here that belong in `theme.yml`. Use `@theme` only for values the token system doesn't cover (custom breakpoints, animations, shadows).
+
+**Custom CSS is fine alongside Tailwind.** Animations, keyframes, gradients with masks, always-dark code blocks, and other effects that aren't expressible as utility classes can go directly in `styles.css`. Tailwind handles layout and spacing; custom CSS handles visual effects.
+
+## Troubleshooting
+
+**"Could not load foundation"** — Check `site/package.json` has `"foundation": "file:../foundation"` (or `"default": "file:../../foundations/default"` for multi-site).
+
+**Component not appearing** — Verify `meta.js` exists and doesn't have `hidden: true`. Rebuild: `cd foundation && pnpm build`.
+
+**Styles not applying** — Verify `@source` in `styles.css` includes your component paths. Check custom colors match `@theme` definitions.
+
+## Further Documentation
+
+Full Uniweb documentation is available at **https://github.com/uniweb/docs** — raw markdown files you can fetch directly.
+
+| Section | Path | Topics |
+|---------|------|--------|
+| **Getting Started** | `getting-started/` | What is Uniweb, quickstart guide, templates overview |
+| **Authoring** | `authoring/` | Writing content, site setup, collections, theming, linking, search, recipes, translations |
+| **Development** | `development/` | Building foundations, component patterns, data fetching, custom layouts, i18n, converting existing designs |
+| **Reference** | `reference/` | site.yml, page.yml, content structure, meta.js, kit hooks/components, theming tokens, CLI commands, deployment |
+
+**Quick access pattern:** `https://raw.githubusercontent.com/uniweb/docs/main/{section}/{page}.md`
+
+Examples:
+- Content structure details: `reference/content-structure.md`
+- Component metadata (meta.js): `reference/component-metadata.md`
+- Kit hooks and components: `reference/kit-reference.md`
+- Theming tokens: `reference/site-theming.md`
+- Data fetching patterns: `reference/data-fetching.md`