uniweb 0.8.5 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,9 +41,9 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.5.4",
-    "@uniweb/kit": "0.7.3",
-    "@uniweb/runtime": "0.6.4",
-    "@uniweb/build": "0.8.4"
+    "@uniweb/build": "0.8.6",
+    "@uniweb/runtime": "0.6.5",
+    "@uniweb/kit": "0.7.4",
+    "@uniweb/core": "0.5.5"
   }
 }

package/partials/agents.md

@@ -2,6 +2,27 @@
 
 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.
 
+## Documentation
+
+This project was created with [Uniweb](https://github.com/uniweb/cli). Full documentation (markdown, fetchable): https://github.com/uniweb/docs
+
+**To read a specific page:** `https://raw.githubusercontent.com/uniweb/docs/main/{section}/{page}.md`
+
+**By task:**
+
+| Task | Doc page |
+|------|----------|
+| Writing page content | `authoring/writing-content.md` |
+| Theming and styling | `authoring/theming.md` |
+| Building components | `development/creating-components.md` |
+| Kit API (hooks, components) | `reference/kit-reference.md` |
+| Site configuration | `reference/site-configuration.md` |
+| Content shape reference | `reference/content-structure.md` |
+| Component metadata (meta.js) | `reference/component-metadata.md` |
+| Migrating existing designs | `development/converting-existing.md` |
+
+> **npm registry:** Use `https://registry.npmjs.org/uniweb` for package metadata — the npmjs.com website blocks automated requests.
+
 ## Project Structure
 
 ```
@@ -49,6 +70,15 @@ pnpm uniweb add site blog            # Named → ./blog/
 
 The name is both the directory name and the package name. Use `--project <name>` to co-locate under a project directory (e.g., `--project docs` → `docs/foundation/`).
 
+### Adding section types
+
+```bash
+pnpm uniweb add section Hero
+pnpm uniweb add section Hero --foundation ui   # When multiple foundations exist
+```
+
+Creates `src/sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starter. The dev server picks it up automatically — no build or install needed.
+
 ### What the CLI generates
 
 **Foundation** (`vite.config.js`, `package.json`, `src/foundation.js`, `src/styles.css`):
@@ -67,8 +97,11 @@ The name is both the directory name and the package name. Use `--project <name>`
 pnpm install    # Install dependencies
 pnpm dev        # Start dev server
 pnpm build      # Build for production
+pnpm preview    # Preview production build (SSG + SPA)
 ```
 
+> **npm works too.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command above.
+
 ## Content Authoring
 
 ### Section Format
@@ -81,11 +114,11 @@ type: Hero
 theme: dark
 ---
 
-### Eyebrow Text        ← pretitle (heading before a more important one)
+### V1.0.0 IS OUT         ← pretitle (small label above the title)
 
-# Main Headline         ← title
+# Build the system.       ← title (the big headline)
 
-## Subtitle             ← subtitle
+## Not every page.         ← subtitle
 
 Description paragraph.
 
@@ -94,6 +127,8 @@ Description paragraph.
 ![Image](./image.jpg)
 ```
 
+Content authors don't need to understand *why* `###` means pretitle — just that putting a smaller heading before the main heading creates a small label above it. Heading levels set *structure* (pretitle, title, subtitle), not font size — the component controls visual sizing.
+
 ### Content Shape
 
 The semantic parser extracts markdown into a flat, guaranteed structure. No null checks needed — empty strings/arrays if content is absent:
@@ -112,7 +147,7 @@ content = {
   insets: [],       // Inline @Component references — { refId }
   lists: [],        // [[{ paragraphs, links, lists, ... }]] — each list item is an object, not a string
   quotes: [],       // Blockquotes
-  data: {},         // From tagged code blocks (```yaml:tagname)
+  data: {},         // From tagged code blocks (```yaml:tagname) and (```js:tagname)
   headings: [],     // Overflow headings after subtitle2
   items: [],        // Each has the same flat structure — from headings after body content
   sequence: [],     // All elements in document order
@@ -127,12 +162,38 @@ content = {
 We built this for you.  ← paragraph
 
 ### Fast                ← items[0].title
+![](lu-zap)             ← items[0].icons[0]
 Lightning quick.        ← items[0].paragraphs[0]
 
 ### Secure              ← items[1].title
+![](lu-shield)          ← items[1].icons[0]
 Enterprise-grade.       ← items[1].paragraphs[0]
 ```
 
+Each item has the same content shape as the top level — `title`, `paragraphs`, `icons`, `links`, `lists`, etc. are all available per item.
+
+**Complete example — markdown and resulting content shape side by side:**
+
+```markdown
+### Eyebrow                    │  content.pretitle = "Eyebrow"
+# Our Features                 │  content.title = "Our Features"
+## Build better products       │  content.subtitle = "Build better products"
+                               │
+We help teams ship faster.     │  content.paragraphs[0] = "We help teams..."
+                               │
+[Get Started](/start)          │  content.links[0] = { href: "/start", label: "Get Started" }
+                               │
+### Fast                       │  content.items[0].title = "Fast"
+![](lu-zap)                    │  content.items[0].icons[0] = { library: "lu", name: "zap" }
+Lightning quick.               │  content.items[0].paragraphs[0] = "Lightning quick."
+                               │
+### Secure                     │  content.items[1].title = "Secure"
+![](lu-shield)                 │  content.items[1].icons[0] = { library: "lu", name: "shield" }
+Enterprise-grade security.     │  content.items[1].paragraphs[0] = "Enterprise-grade..."
+```
+
+Headings before the main title become `pretitle`. Headings after the main title at a lower importance become `subtitle`. Headings that appear after body content (paragraphs, links, images) start the `items` array.
+
 **Lists** contain bullet or ordered list items. Each list item is an object with the same content shape — not a plain string:
 
 ```markdown
@@ -186,6 +247,7 @@ The three parts carry distinct information:
 ![Architecture diagram](@NetworkDiagram){variant=compact}
 ![Cache metrics](@PerformanceChart){period=30d}
 ![](@GradientBlob){position=top-right}
+![npm create uniweb](@CommandBlock){note="Vite + React + Routing — ready to go"}
 ```
 
 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.
@@ -198,8 +260,26 @@ Inset components must declare `inset: true` in their `meta.js`. They render at t
 ![alt](./img.jpg){role=banner}          <!-- Role determines array: imgs, icons, or videos -->
 ```
 
+**Quote values that contain spaces:** `{note="Ready to go"}` not `{note=Ready to go}`. Unquoted values end at the first space.
+
 Standalone links (alone on a line) become buttons. Inline links stay as text links.
 
+**Standalone links** — paragraphs that contain *only* links (no other text) are promoted to `content.links[]`. This works for single links and for multiple links sharing a paragraph:
+
+```markdown
+[Primary](/start)              ← standalone → content.links[0]
+
+[Secondary](/learn)            ← standalone → content.links[1]
+
+[One](/a) [Two](/b)            ← links-only paragraph → content.links[0], content.links[1]
+```
+
+Links mixed with non-link text stay as inline `<a>` tags within `content.paragraphs[]`:
+
+```markdown
+Check out [this](/a) and [that](/b).   ← inline links in paragraph text, NOT in content.links[]
+```
+
 ### Structured Data
 
 Tagged code blocks pass structured data via `content.data`:
@@ -215,19 +295,73 @@ submitLabel: Send
 
 Access: `content.data?.form` → `{ fields: [...], submitLabel: "Send" }`
 
+**Code blocks need tags too.** Untagged code blocks (plain ```js) are only visible to sequential-rendering components like Article or DocSection. If a component needs to access code blocks by name, tag them:
+
+````markdown
+```jsx:before
+const old = fetch('/api')
+```
+
+```jsx:after
+const data = useData()
+```
+````
+
+Access: `content.data?.before`, `content.data?.after` → raw code strings.
+
+### Lists as Navigation Menus
+
+Markdown lists are ideal for navigation, menus, and grouped link structures. Each list item is a full content object with `paragraphs`, `links`, `icons`, and nested `lists`.
+
+**Header nav — flat list with icons and links:**
+
+```markdown
+- ![](lu-home) [Home](/)
+- ![](lu-book) [Docs](/docs)
+- ![](lu-mail) [Contact](/contact)
+```
+
+Access: `content.lists[0]` — each item has `item.links[0]` (href + label) and `item.icons[0]` (icon).
+
+**Footer — nested list for grouped links:**
+
+```markdown
+- Product
+  - [Features](/features)
+  - [Pricing](/pricing)
+- Company
+  - [About](/about)
+  - [Careers](/careers)
+```
+
+Access: `content.lists[0]` — each top-level item has `item.paragraphs[0]` (group label) and `item.lists[0]` (array of sub-items, each with `subItem.links[0]`).
+
+```jsx
+content.lists[0]?.map((group, i) => (
+  <div key={i}>
+    <Span text={group.paragraphs[0]} className="font-semibold text-heading" />
+    <ul>
+      {group.lists[0]?.map((subItem, j) => (
+        <li key={j}><Link to={subItem.links[0]?.href}>{subItem.links[0]?.label}</Link></li>
+      ))}
+    </ul>
+  </div>
+))
+```
+
 ### Section Backgrounds
 
-Set `background` in frontmatter — the runtime renders it automatically:
+Set `background` in frontmatter — the runtime renders it automatically. The string form auto-detects the type:
 
 ```yaml
----
-type: Hero
-theme: dark
-background: /images/hero.jpg              # Simple: URL (image or video auto-detected)
----
+background: /images/hero.jpg                             # Image (by extension)
+background: /videos/hero.mp4                             # Video (by extension)
+background: linear-gradient(135deg, #667eea, #764ba2)    # CSS gradient
+background: '#1a1a2e'                                    # Color (hex — quote in YAML)
+background: var(--primary-900)                            # Color (CSS variable)
 ```
 
-Full syntax supports `image`, `video`, `gradient`, `color` modes plus overlays:
+The object form gives more control:
 
 ```yaml
 background:
@@ -235,6 +369,8 @@ background:
   overlay: { enabled: true, type: dark, opacity: 0.5 }
 ```
 
+Overlay shorthand — `overlay: 0.5` is equivalent to `{ enabled: true, type: dark, opacity: 0.5 }`.
+
 Components that render their own background declare `background: 'self'` in `meta.js`.
 
 ### Page Organization
@@ -385,7 +521,12 @@ CCA separates theme from code. Components use **semantic CSS tokens** instead of
 | `text-link` | Link color |
 | `bg-primary` | Primary action background |
 | `text-primary-foreground` | Text on primary background |
+| `hover:bg-primary-hover` | Primary hover state |
+| `border-primary-border` | Primary border (transparent by default) |
 | `bg-secondary` | Secondary action background |
+| `text-secondary-foreground` | Text on secondary background |
+| `hover:bg-secondary-hover` | Secondary hover state |
+| `border-secondary-border` | Secondary border |
 | `text-success` / `bg-success-subtle` | Status: success |
 | `text-error` / `bg-error-subtle` | Status: error |
 | `text-warning` / `bg-warning-subtle` | Status: warning |
@@ -417,7 +558,7 @@ The runtime does significant work that other frameworks push onto components. Un
 | `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. |
+| Parallel color system (`--ink`, `--paper`) that duplicates what tokens already provide | Map source color roles to `theme.yml` colors/neutral. The build generates `--primary-50` through `--primary-950`, `--neutral-50` through `--neutral-950`, etc. Use palette shades directly (`var(--primary-300)`) for specific tones. Additive design classes that BUILD ON tokens are fine — a parallel system that REPLACES them bypasses context adaptation. |
 
 **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.
 
@@ -430,6 +571,33 @@ theme: dark           ← sets context-dark, all tokens resolve to dark values
 ---
 ```
 
+Alternate between `light` (default), `medium`, and `dark` across sections for visual rhythm — no CSS needed. A typical marketing page:
+
+```markdown
+<!-- 1-hero.md -->
+theme: dark
+
+<!-- 2-features.md -->
+(no theme — defaults to light)
+
+<!-- 3-testimonials.md -->
+theme: medium
+
+<!-- 4-cta.md -->
+theme: dark
+```
+
+**Per-section token overrides** — the object form lets authors fine-tune individual tokens for a specific section:
+
+```yaml
+theme:
+  mode: light
+  primary: neutral-900               # Dark buttons in a light section
+  primary-hover: neutral-800
+```
+
+Any semantic token (`section`, `heading`, `body`, `primary`, `link`, etc.) can be overridden this way. The overrides are applied as inline CSS custom properties on the section wrapper — components don't need to know about them.
+
 **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
@@ -437,18 +605,14 @@ theme: dark           ← sets context-dark, all tokens resolve to dark values
 ```yaml
 # site/theme.yml
 colors:
-  primary:
-    base: '#3b82f6'
-    exactMatch: true        # Use this exact hex at the 500 shade
+  primary: '#3b82f6'          # Your exact hex appears at shade 500
   secondary: '#64748b'
   accent: '#8b5cf6'
-  neutral: stone            # Named preset: stone, zinc, gray, slate, neutral
+  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)
+    section: '#fafaf9'        # Override individual tokens per context
 
 fonts:
   import:
@@ -467,23 +631,86 @@ vars:                       # Override foundation-declared variables
 
 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:`.
 
+### How colors reach components
+
+Your hex color → 11 shades (50–950) → semantic tokens → components.
+
+**Shade 500 = your exact input color.** The build generates lighter shades (50–400) above it and darker shades (600–950) below it, redistributing lightness proportionally to maintain a smooth scale. Set `exactMatch: false` on a color to opt out and use fixed lightness values instead.
+
+Semantic tokens map shades to roles. The defaults for light/medium contexts:
+
+| Token | Shade | Purpose |
+|-------|-------|---------|
+| `--primary` | 600 | Button background |
+| `--primary-hover` | 700 | Button hover |
+| `--link` | 600 | Link color |
+| `--ring` | 500 | Focus ring |
+
+In dark contexts, `--primary` uses shade 500 and `--link` uses shade 400.
+
+**Buttons and links use shade 600 — darker than your input.** This is an accessibility choice: shade 600 provides better contrast with white button text. For medium-bright brand colors like orange, buttons will be noticeably darker than the brand color.
+
+**Recipe — brand-exact buttons:**
+
+```yaml
+colors:
+  primary: "#E35D25"
+
+contexts:
+  light:
+    primary: primary-500         # Your exact color on buttons
+    primary-hover: primary-600   # Darker on hover
+```
+
+> **Contrast warning:** Bright brand colors (orange, yellow, light green) at shade 500 may not meet WCAG contrast (4.5:1) with white foreground text. Test buttons for readability — if contrast is insufficient, keep the default shade 600 mapping or darken your base color.
+
 ### Foundation variables
 
-Foundations declare customizable layout/spacing values in `foundation.js`:
+Foundations declare customizable layout/spacing values in `foundation.js`. The starter includes:
 
 ```js
-export default {
-  vars: {
-    'header-height': { default: '4rem' },
-    'sidebar-width': { default: '280px' },
-  },
+export const vars = {
+  'header-height': { default: '4rem', description: 'Fixed header height' },
+  'max-content-width': { default: '80rem', description: 'Maximum content width' },
+  'section-padding-y': { default: 'clamp(4rem, 6vw, 7rem)', description: 'Vertical padding for sections' },
 }
 ```
 
-Sites override them in `theme.yml` under `vars:`. Components use them as `var(--header-height)`.
+Sites override them in `theme.yml` under `vars:`. Components use them via Tailwind arbitrary values or CSS: `py-[var(--section-padding-y)]`, `h-[var(--header-height)]`, etc.
+
+The `section-padding-y` default uses `clamp()` for fluid spacing — tighter on mobile, more breathing room on large screens. Use this variable for consistent section spacing instead of hardcoding padding in each component. Sites can override to a fixed value (`section-padding-y: 3rem`) or a different clamp in `theme.yml`.
 
 **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.
 
+### Design richness beyond tokens
+
+Semantic tokens handle context adaptation — the hard problem of making colors work in light, medium, and dark sections. **They are a floor, not a ceiling.** A great foundation adds its own design vocabulary on top.
+
+The token set is deliberately small (24 tokens). It covers the dimensions that change per context. Everything that stays constant across contexts — border weights, shadow depth, radius scales, gradient angles, accent borders, glassmorphism, elevation layers — belongs in your foundation's `styles.css` or component code.
+
+**Don't flatten a rich design to fit the token set.** If a source design has 4 border tones, create them:
+
+```css
+/* foundation/src/styles.css */
+.border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
+.border-strong { border-color: color-mix(in oklch, var(--border), var(--heading) 30%); }
+.border-accent { border-color: var(--primary-300); }
+```
+
+These compose with semantic tokens — they adapt per context because they reference `--border`, `--heading`, or palette shades. But they add design nuance the token set alone doesn't provide.
+
+**The priority:** Design quality > portability > configurability. It's better to ship a foundation with beautiful, detailed design that's less configurable than to ship a generic one that looks flat. A foundation that looks great for one site is more valuable than one that looks mediocre for any site.
+
+**Text tones beyond the 3-token set.** Source designs often have 4+ text tones (primary, secondary, tertiary, disabled). Uniweb provides 3 (`text-heading`, `text-body`, `text-subtle`). Don't collapse the extras — create them with `color-mix()` so they still adapt per context:
+
+```css
+/* foundation/src/styles.css */
+.text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
+.text-disabled { color: color-mix(in oklch, var(--subtle), transparent 40%); }
+```
+
+**When migrating from an existing design**, map every visual detail — not just the ones that have a semantic token. Shadow systems, border hierarchies, custom hover effects, accent tints: create CSS classes or Tailwind utilities in `styles.css` for anything the original has that tokens don't cover. Use palette shades directly (`var(--primary-300)`, `bg-neutral-200`) for fine-grained color control beyond the semantic tokens.
+
 ## Component Development
 
 ### Props Interface
@@ -509,15 +736,97 @@ function Hero({ content, params }) {
   )
 }
 
-Hero.className = 'pt-32 md:pt-48'   // Classes on the <section> wrapper
+Hero.className = 'pt-32 md:pt-48'   // Override spacing for hero (more top padding)
 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.className` — adds classes to the runtime's wrapper. Use for section-level spacing, borders, overflow. Set `py-[var(--section-padding-y)]` for consistent spacing from the theme variable, or override for specific sections (e.g., hero needs extra top padding). 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.
 
+**Layout components** (Header, Footer) typically need `Component.className = 'p-0'` to suppress the runtime's default section padding, since they control their own padding. Also set `Component.as = 'header'` or `'footer'` for semantic HTML:
+
+```jsx
+function Header({ content, block }) { /* ... */ }
+Header.className = 'p-0'
+Header.as = 'header'
+export default Header
+```
+
+### Content Patterns for Header and Footer
+
+Header and Footer are the hardest components to content-model because they combine several content categories. Use different parts of the content shape for each role:
+
+**Header** — title for logo, list for nav links, standalone link for CTA, tagged YAML for metadata:
+
+````markdown
+---
+type: Header
+---
+
+# Acme Inc
+
+- ![](lu-search) [How It Works](/how-it-works)
+- ![](lu-users) [For Teams](/for-teams)
+- ![](lu-book) [Docs](/docs)
+
+[Get Started](/docs/quickstart)
+
+```yaml:config
+github: https://github.com/acme
+version: v2.1.0
+```
+````
+
+```jsx
+function Header({ content, block }) {
+  const logo = content.title                    // "Acme Inc"
+  const navItems = content.lists[0] || []       // [{icons, links}, ...]
+  const cta = content.links[0]                  // {href, label}
+  const config = content.data?.config           // {github, version}
+  // ...
+}
+```
+
+**Footer** — paragraph for tagline, nested list for grouped columns, tagged YAML for legal:
+
+````markdown
+---
+type: Footer
+---
+
+Build something great.
+
+- Product
+  - [Features](/features)
+  - [Pricing](/pricing)
+- Developers
+  - [Docs](/docs)
+  - [GitHub](https://github.com/acme){target=_blank}
+- Community
+  - [Discord](#)
+  - [Blog](/blog)
+
+```yaml:legal
+copyright: © 2025 Acme Inc
+```
+````
+
+```jsx
+function Footer({ content, block }) {
+  const tagline = content.paragraphs[0]         // "Build something great."
+  const columns = content.lists[0] || []        // [{paragraphs, lists}, ...]
+  const legal = content.data?.legal             // {copyright}
+
+  // Each column: group.paragraphs[0] = label, group.lists[0] = links
+  columns.map(group => ({
+    label: group.paragraphs[0],
+    links: group.lists[0]?.map(item => item.links[0])
+  }))
+}
+```
+
 ### meta.js Structure
 
 ```javascript
@@ -577,6 +886,8 @@ import { H2, P, Span } from '@uniweb/kit'
 <Text text={content.title} as="h2" className="..." />  // explicit tag
 ```
 
+These components render their own HTML tag — don't wrap them in a matching tag. `<h2><H2 text={...} /></h2>` creates a nested `<h2><h2>...</h2></h2>`, which is invalid HTML. Just use `<H2 text={...} />` directly.
+
 Don't render content strings with `{content.paragraphs[0]}` in JSX — that shows HTML tags as visible text. Use `<P>`, `<H2>`, `<Span>`, etc. for content strings.
 
 **Rendering full content** (`@uniweb/kit`):
@@ -596,15 +907,29 @@ import { Section, Render } from '@uniweb/kit'
 
 **Other primitives** (`@uniweb/kit`): `Link`, `Image`, `Icon`, `Media`, `Asset`, `SafeHtml`, `SocialIcon`, `FileLogo`, `cn()`
 
+`Link` props: `to` (or `href`), `target`, `reload`, `download`, `className`, `children`:
+
+```jsx
+<Link to="/about">About</Link>            // SPA navigation via React Router
+<Link to="page:about">About</Link>        // Resolves page ID to route
+<Link reload href={localeUrl}>ES</Link>    // Full page reload, prepends basePath
+// External URLs auto-get target="_blank" and rel="noopener noreferrer"
+```
+
 **Other styled** (`@uniweb/kit`): `SidebarLayout`, `Prose`, `Article`, `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)
+- `useActiveRoute()` → `{ route, rootSegment, isActive(page), isActiveOrAncestor(page) }` for nav highlighting (SSG-safe)
 - `useGridLayout(columns, { gap })` → responsive grid class string
 - `useTheme(name)` → standardized theme classes
+- `useAppearance()` → `{ scheme, toggle, canToggle, setScheme, schemes }` — light/dark mode control with localStorage persistence
+- `useRouting()` → `{ useLocation, useParams, useNavigate, Link, isRoutingAvailable }` — SSG-safe routing access (returns no-op fallbacks during prerender)
+- `useWebsite()` → `{ website, localize, makeHref, getLanguage, getLanguages, getRoutingComponents }` — primary runtime hook
+- `useThemeData()` → Theme instance for programmatic color access (`getColor(name, shade)`, `getPalette(name)`)
+- `useColorContext(block)` → `'light' | 'medium' | 'dark'` — current section's color context
 
 **Utilities:** `cn()` (Tailwind class merge), `filterSocialLinks(links)`, `getSocialPlatform(url)`
 
@@ -642,6 +967,28 @@ website.hasMultipleLocales()
 website.getLocales()        // [{ code, label, isDefault }]
 website.getActiveLocale()   // 'en'
 website.getLocaleUrl('es')
+
+// Core properties
+website.name              // Site name from site.yml
+website.basePath          // Deployment base path (e.g., '/docs/')
+
+// Route detection
+const { isActive, isActiveOrAncestor } = useActiveRoute()
+isActive(page)            // Exact match
+isActiveOrAncestor(page)  // Ancestor match (for parent highlighting in nav)
+
+// Appearance (light/dark mode)
+const { scheme, toggle, canToggle } = useAppearance()
+
+// Page properties
+page.title                // Page title
+page.label                // Short label for nav (falls back to title)
+page.route                // Route path
+page.isHidden()           // Hidden from navigation
+page.showInHeader()       // Visible in header nav
+page.showInFooter()       // Visible in footer nav
+page.hasChildren()        // Has child pages
+page.children             // Array of child Page objects
 ```
 
 ### Insets and the Visual Component
@@ -670,6 +1017,8 @@ function SplitContent({ content, block }) {
 - `block.getInset(refId)` — lookup by refId (used by sequential renderers)
 - `content.insets` — flat array of `{ refId }` entries (parallel to `content.imgs`)
 
+**SSG and hooks:** Inset components that use React hooks (useState, useEffect) will trigger prerender warnings during `pnpm build`. This is expected — the SSG pipeline cannot render hooks due to dual React instances in the build. The warnings are informational; the page renders correctly client-side. If you see `"Skipped SSG for /..."` or `"Invalid hook call"`, this is the cause.
+
 Inset components declare `inset: true` in meta.js. Use `hidden: true` for inset-only components:
 
 ```js
@@ -853,7 +1202,7 @@ Foundation styles in `foundation/src/styles.css`:
 
 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.
+**Custom CSS is expected alongside Tailwind.** Your foundation's `styles.css` is the design layer — shadow systems, border hierarchies, gradient effects, accent treatments, elevation scales, glassmorphism. If the source design has a visual detail, create a class for it. Tailwind handles layout and spacing; semantic tokens handle context adaptation; `styles.css` handles everything else that makes the design rich and distinctive.
 
 ## Troubleshooting
 
@@ -863,6 +1212,16 @@ Semantic color tokens (`text-heading`, `bg-section`, `bg-primary`, etc.) come fr
 
 **Styles not applying** — Verify `@source` in `styles.css` includes your component paths. Check custom colors match `@theme` definitions.
 
+**Prerender warnings about hooks/useState** — Components with React hooks (useState/useEffect) — especially insets — will show SSG warnings during `pnpm build`. This is expected and harmless; see the note in the Insets section above.
+
+**Content not appearing as expected?** In dev mode, open the browser console and inspect the parsed content shape your component receives:
+
+```js
+globalThis.uniweb.activeWebsite.activePage.bodyBlocks[0].parsedContent
+```
+
+Compare with the Content Shape table above to identify mapping issues (e.g., headings becoming items instead of title, links inline in paragraphs instead of in `links[]`).
+
 ## Further Documentation
 
 Full Uniweb documentation is available at **https://github.com/uniweb/docs** — raw markdown files you can fetch directly.

package/src/commands/add.js

@@ -1,17 +1,18 @@
 /**
  * Add Command
  *
- * Adds foundations, sites, extensions, or co-located projects to an existing workspace.
+ * Adds foundations, sites, extensions, section types, or co-located projects to an existing workspace.
  *
  * Usage:
  *   uniweb add project [name] [--from <template>]
  *   uniweb add foundation [name] [--from <template>] [--path <dir>] [--project <name>]
  *   uniweb add site [name] [--from <template>] [--foundation <name>] [--path <dir>] [--project <name>]
  *   uniweb add extension [name] [--from <template>] [--site <name>] [--path <dir>]
+ *   uniweb add section <name> [--foundation <name>]
  */
 
 import { existsSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import prompts from 'prompts'
 import yaml from 'js-yaml'
@@ -123,9 +124,10 @@ export async function add(rawArgs) {
         { label: 'foundation', description: 'Component library' },
         { label: 'site', description: 'Content site' },
         { label: 'extension', description: 'Additional component package' },
+        { label: 'section', description: 'Section type in a foundation' },
       ]))
       log('')
-      log(`Usage: ${prefix} add <project|foundation|site|extension> [name]`)
+      log(`Usage: ${prefix} add <project|foundation|site|extension|section> [name]`)
       process.exit(1)
     }
 
@@ -138,6 +140,7 @@ export async function add(rawArgs) {
         { title: 'Foundation', value: 'foundation', description: 'Component library' },
         { title: 'Site', value: 'site', description: 'Content site' },
         { title: 'Extension', value: 'extension', description: 'Additional component package' },
+        { title: 'Section', value: 'section', description: 'Section type in a foundation' },
       ],
     }, {
       onCancel: () => {
@@ -169,9 +172,12 @@ export async function add(rawArgs) {
     case 'extension':
       await addExtension(rootDir, projectName, parsed, pm)
       break
+    case 'section':
+      await addSection(rootDir, parsed)
+      break
     default:
       error(`Unknown subcommand: ${parsed.subcommand}`)
-      log(`Valid subcommands: project, foundation, site, extension`)
+      log(`Valid subcommands: project, foundation, site, extension, section`)
       process.exit(1)
   }
 }
@@ -875,6 +881,138 @@ async function wireExtensionToSite(rootDir, siteName, extensionName, extensionPa
   }
 }
 
+/**
+ * Add a section type to a foundation
+ */
+async function addSection(rootDir, opts) {
+  let name = opts.name
+
+  // Interactive name prompt when not provided
+  if (!name) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing section name.\n`)
+      log(`Usage: ${getCliPrefix()} add section <Name>`)
+      log(`\nSection names use PascalCase: Hero, FeatureGrid, CallToAction`)
+      process.exit(1)
+    }
+
+    const response = await prompts({
+      type: 'text',
+      name: 'name',
+      message: 'Section name (PascalCase):',
+      validate: (value) => /^[A-Z][a-zA-Z0-9]*$/.test(value) || 'Use PascalCase: Hero, FeatureGrid, CallToAction',
+    }, {
+      onCancel: () => {
+        log('\nCancelled.')
+        process.exit(0)
+      },
+    })
+    name = response.name
+  }
+
+  // Validate PascalCase
+  if (!/^[A-Z][a-zA-Z0-9]*$/.test(name)) {
+    error(`Section name must be PascalCase (e.g., Hero, FeatureGrid, CallToAction).`)
+    process.exit(1)
+  }
+
+  // Find the foundation
+  const foundations = await discoverFoundations(rootDir)
+  let foundation
+
+  if (foundations.length === 0) {
+    error('No foundation found in this workspace.')
+    log(`Create one first: ${getCliPrefix()} add foundation`)
+    process.exit(1)
+  } else if (foundations.length === 1) {
+    foundation = foundations[0]
+  } else if (opts.foundation) {
+    foundation = foundations.find(f => f.name === opts.foundation)
+    if (!foundation) {
+      error(`Foundation '${opts.foundation}' not found.`)
+      log(`Available: ${foundations.map(f => f.name).join(', ')}`)
+      process.exit(1)
+    }
+  } else if (isNonInteractive(process.argv)) {
+    error(`Multiple foundations found. Specify which to use:\n`)
+    log(formatOptions(foundations.map(f => ({ label: f.name, description: f.path }))))
+    log('')
+    log(`Usage: ${getCliPrefix()} add section ${name} --foundation <name>`)
+    process.exit(1)
+  } else {
+    const response = await prompts({
+      type: 'select',
+      name: 'foundation',
+      message: 'Which foundation?',
+      choices: foundations.map(f => ({ title: f.name, description: f.path, value: f })),
+    }, {
+      onCancel: () => {
+        log('\nCancelled.')
+        process.exit(0)
+      },
+    })
+    foundation = response.foundation
+  }
+
+  // Resolve sections directory
+  const sectionsDir = join(rootDir, foundation.path, 'src', 'sections')
+  const sectionDir = join(sectionsDir, name)
+
+  if (existsSync(sectionDir)) {
+    error(`Section '${name}' already exists at ${foundation.path}/src/sections/${name}/`)
+    process.exit(1)
+  }
+
+  // Create section directory and files
+  await mkdir(sectionDir, { recursive: true })
+
+  const componentContent = `import { H2, P, Link, cn } from '@uniweb/kit'
+
+export default function ${name}({ content, params }) {
+  const { title, paragraphs = [], links = [] } = content || {}
+
+  return (
+    <div className="max-w-4xl mx-auto px-6">
+      {title && <H2 text={title} className="text-heading text-3xl font-bold" />}
+      <P text={paragraphs} className="text-body mt-4" />
+      {links.length > 0 && (
+        <div className="mt-6 flex gap-3 flex-wrap">
+          {links.map((link, i) => (
+            <Link key={i} to={link.href} className={cn(
+              'px-5 py-2.5 rounded-lg font-medium transition-colors',
+              i === 0
+                ? 'bg-primary text-primary-foreground hover:bg-primary-hover'
+                : 'bg-secondary text-secondary-foreground hover:bg-secondary-hover'
+            )}>
+              {link.label}
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+`
+
+  const metaContent = `export default {
+  title: '${name}',
+  description: '',
+  params: {},
+}
+`
+
+  await writeFile(join(sectionDir, 'index.jsx'), componentContent)
+  await writeFile(join(sectionDir, 'meta.js'), metaContent)
+
+  success(`Created section '${name}' at ${foundation.path}/src/sections/${name}/`)
+  log(`  ${colors.dim}index.jsx${colors.reset}  — component (customize the JSX)`)
+  log(`  ${colors.dim}meta.js${colors.reset}    — metadata (add content expectations, params, presets)`)
+  if (foundations.length === 1) {
+    log('')
+    log(`${colors.dim}The dev server will pick it up automatically.${colors.reset}`)
+  }
+}
+
 /**
  * Show help for the add command
  */
@@ -882,13 +1020,14 @@ function showAddHelp() {
   log(`
 ${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
 
-Add projects, foundations, sites, or extensions to your workspace.
+Add projects, foundations, sites, extensions, or section types to your workspace.
 
 ${colors.bright}Usage:${colors.reset}
   uniweb add project [name] [options]
   uniweb add foundation [name] [options]
   uniweb add site [name] [options]
   uniweb add extension <name> [options]
+  uniweb add section <name> [options]
 
 ${colors.bright}Common Options:${colors.reset}
   --from <template>  Apply content from a template after scaffolding
@@ -904,6 +1043,9 @@ ${colors.bright}Site Options:${colors.reset}
 ${colors.bright}Extension Options:${colors.reset}
   --site <name>      Site to wire extension URL into
 
+${colors.bright}Section Options:${colors.reset}
+  --foundation <n>   Foundation to add section to (prompted if multiple exist)
+
 ${colors.bright}Examples:${colors.reset}
   uniweb add project docs                              # Create docs/foundation/ + docs/site/
   uniweb add project docs --from academic              # Co-located pair + academic content
@@ -912,6 +1054,8 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add site                                      # Create ./site/ at root
   uniweb add site blog --foundation marketing          # Create ./blog/ wired to marketing
   uniweb add extension effects --site site             # Create ./extensions/effects/
+  uniweb add section Hero                              # Create Hero section type
+  uniweb add section Hero --foundation ui              # Target specific foundation
   uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
   uniweb add site --project docs                       # Create ./docs/site/ (co-located)
 `)

package/src/index.js

@@ -583,6 +583,7 @@ ${colors.bright}Add Subcommands:${colors.reset}
   add foundation [name]   Add a foundation (--from, --path, --project)
   add site [name]         Add a site (--from, --foundation, --path, --project)
   add extension <name>    Add an extension (--from, --site, --path)
+  add section <name>      Add a section type to a foundation (--foundation)
 
 ${colors.bright}Global Options:${colors.reset}
   --non-interactive    Fail with usage info instead of prompting

package/starter/foundation/src/foundation.js

@@ -24,8 +24,8 @@ export const vars = {
     description: 'Maximum content width (1280px)',
   },
   'section-padding-y': {
-    default: '5rem',
-    description: 'Vertical padding for sections',
+    default: 'clamp(4rem, 6vw, 7rem)',
+    description: 'Vertical padding for sections (fluid: adapts to viewport)',
   },
 }
 

package/templates/site/theme.yml

@@ -51,15 +51,15 @@ colors:
 #   Text:      body, heading, subtle
 #   Border:    border, ring
 #   Links:     link, link-hover
-#   Actions:   primary, primary-foreground, primary-hover
-#              secondary, secondary-foreground, secondary-hover
+#   Actions:   primary, primary-foreground, primary-hover, primary-border
+#              secondary, secondary-foreground, secondary-hover, secondary-border
 #   Status:    success, warning, error, info (+ -subtle variants)
 
 # contexts:
 #   light:
 #     section: white
 #   medium:
-#     section: 'var(--neutral-100)'
+#     section: neutral-100
 #   dark:
 #     heading: white