uniweb 0.8.6 → 0.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "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/build": "0.8.5",
-    "@uniweb/kit": "0.7.3",
-    "@uniweb/core": "0.5.4",
-    "@uniweb/runtime": "0.6.4"
+    "@uniweb/build": "0.8.7",
+    "@uniweb/kit": "0.7.5",
+    "@uniweb/core": "0.5.6",
+    "@uniweb/runtime": "0.6.6"
   }
 }

package/partials/agents.md

@@ -1,7 +1,30 @@
 # AGENTS.md
 
+> A comprehensive guide to building with Uniweb — for developers and AI assistants alike.
+
 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 +72,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`):
@@ -84,11 +116,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.
 
@@ -97,15 +129,17 @@ 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:
 
 ```js
 content = {
-  title: '',        // Main heading
+  title: '',        // Main heading (string or string[] for multi-line)
   pretitle: '',     // Heading before main title (auto-detected)
-  subtitle: '',     // Heading after title
+  subtitle: '',     // Heading after title (string or string[] for multi-line)
   subtitle2: '',    // Third-level heading
   paragraphs: [],   // Text blocks
   links: [],        // { href, label, role } — standalone links become buttons
@@ -140,6 +174,77 @@ 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.
+
+### Multi-Line Headings
+
+Consecutive headings at the same level merge into a title array — a single heading split across visual lines:
+
+```markdown
+# Build the future              │  content.title = ["Build the future", "with confidence"]
+# with confidence               │
+```
+
+Kit's `<H1>`, `<H2>`, etc. render arrays as a single tag with line breaks. This is how you create dramatic multi-line hero headlines.
+
+**Works with accent styling:**
+
+```markdown
+# Build the future              │  content.title = [
+# [with confidence]{accent}     │    "Build the future",
+                                │    "<span accent=\"true\">with confidence</span>"
+                                │  ]
+```
+
+**Works at any heading slot** — title, subtitle, items:
+
+```markdown
+### Our Mission                 │  content.pretitle = "Our Mission"
+# Build the future              │  content.title = ["Build the future",
+# with confidence               │                   "with confidence"]
+## The platform for             │  content.subtitle = ["The platform for",
+## modern teams                 │                      "modern teams"]
+```
+
+**Rule:** Same-level continuation only applies before going deeper. Once a subtitle level is reached, same-level headings start new items instead of merging:
+
+```markdown
+# Features                      │  title = "Features"
+                                │
+We built this for you.          │  paragraph
+                                │
+### Fast                        │  items[0].title = "Fast"
+### Secure                      │  items[1].title = "Secure" ← new item, not merged
+```
+
+Use `---` to force separate items when same-level headings would otherwise merge:
+
+```markdown
+# Line one                      │  title = "Line one"
+---                             │  ← divider forces split
+# Line two                      │  items[0].title = "Line two"
+```
+
 **Lists** contain bullet or ordered list items. Each list item is an object with the same content shape — not a plain string:
 
 ```markdown
@@ -210,6 +315,65 @@ Inset components must declare `inset: true` in their `meta.js`. They render at t
 
 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[]
+```
+
+### Inline Text Styling
+
+Style specific words or phrases using bracketed spans with boolean attributes:
+
+```markdown
+# Build [faster]{accent} with structure
+
+This is [less important]{muted} context.
+```
+
+The framework provides two defaults: `accent` (colored + bold) and `muted` (subtle). These adapt to context automatically — in dark sections, `accent` resolves to a lighter shade.
+
+**What you write → what components receive:**
+
+| Markdown | HTML in content string |
+|----------|----------------------|
+| `[text]{accent}` | `<span accent="true">text</span>` |
+| `[text]{muted}` | `<span muted="true">text</span>` |
+| `[text]{color=red}` | `<span style="color: red">text</span>` |
+
+CSS is generated from `theme.yml`'s `inline:` section using attribute selectors (`span[accent] { ... }`). Sites can define additional named styles:
+
+```yaml
+inline:
+  accent:
+    color: var(--link)
+    font-weight: '600'
+  callout:
+    color: var(--accent-600)
+    font-style: italic
+```
+
+**Common pattern — accented multi-line hero heading:**
+
+```markdown
+# Build the future
+# [with confidence]{accent}
+```
+
+This produces `content.title = ["Build the future", "<span accent=\"true\">with confidence</span>"]` — an array rendered as a single `<h1>` with visual line breaks. See [Multi-Line Headings](#multi-line-headings) for details.
+
+Components receive HTML strings with the spans already applied. Kit's `<H1>`, `<P>`, etc. render them correctly via `dangerouslySetInnerHTML`.
+
 ### Structured Data
 
 Tagged code blocks pass structured data via `content.data`:
@@ -239,6 +403,46 @@ 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. The string form auto-detects the type:
@@ -411,7 +615,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 |
@@ -477,8 +686,8 @@ theme: dark
 ```yaml
 theme:
   mode: light
-  primary: var(--neutral-900)        # Dark buttons in a light section
-  primary-hover: var(--neutral-800)
+  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.
@@ -506,7 +715,7 @@ fonts:
   body: "'Inter', system-ui, sans-serif"
 
 inline:
-  emphasis:                 # For [text]{emphasis} in markdown
+  accent:                   # For [text]{accent} in markdown
     color: var(--link)
     font-weight: '600'
 
@@ -586,6 +795,14 @@ These compose with semantic tokens — they adapt per context because they refer
 
 **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
@@ -622,6 +839,88 @@ export default Hero
 - `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
@@ -629,7 +928,7 @@ export default {
   title: 'Feature Grid',
   description: 'Grid of feature cards with icons',
   category: 'marketing',
-  // hidden: true,          // Hide from content authors
+  // hidden: true,          // Exclude from export (internal/helper component)
   // background: 'self',    // Component renders its own background
   // inset: true,           // Available for @ComponentName references in markdown
   // visuals: 1,            // Expects 1 visual (image, video, or inset)
@@ -667,11 +966,13 @@ Content fields (`title`, `pretitle`, `paragraphs[]`, list item text) are **HTML
 **Rendering text** (`@uniweb/kit`):
 
 ```jsx
-import { H2, P, Span } from '@uniweb/kit'
+import { H1, H2, P, Span } from '@uniweb/kit'
 
-<H2 text={content.title} className="text-heading text-3xl font-bold" />
-<P text={content.paragraphs[0]} className="text-body" />
-<P text={content.paragraphs} />   // array → each string becomes its own <p>
+<H1 text={content.title} className="text-heading text-5xl font-bold" />
+  // string → single <h1>, array → single <h1> with line breaks (multi-line headings)
+<H2 text={content.subtitle} className="text-heading text-3xl font-bold" />
+<P text={content.paragraphs} className="text-body" />
+  // array → each string becomes its own <p>
 <Span text={listItem.paragraphs[0]} className="text-subtle" />
 ```
 
@@ -702,15 +1003,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)`
 
@@ -737,7 +1052,8 @@ Only folders with `meta.js` in `sections/` (or `components/` for older foundatio
 ### Website and Page APIs
 
 ```jsx
-const { website } = useWebsite()
+const { website } = useWebsite()  // or block.website
+const page = website.activePage   // or block.page 
 
 // Navigation
 const pages = website.getPageHierarchy({ for: 'header' })  // or 'footer'
@@ -748,6 +1064,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
@@ -776,17 +1114,20 @@ 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`)
 
-Inset components declare `inset: true` in meta.js. Use `hidden: true` for inset-only components:
+**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:
 
 ```js
 // sections/insets/NetworkDiagram/meta.js
 export default {
   inset: true,
-  hidden: true,
   params: { variant: { type: 'select', options: ['full', 'compact'], default: 'full' } },
 }
 ```
 
+Whether an inset appears in a section palette is a concern of the parent component (via `children` and `insets` in its meta.js), not a property of the inset itself. Don't use `hidden: true` on insets — `hidden` means "don't export this component at all" (internal helpers, not-yet-ready components).
+
 ### 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`:
@@ -965,11 +1306,19 @@ Semantic color tokens (`text-heading`, `bg-section`, `bg-primary`, etc.) come fr
 
 **"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`.
+**Component not appearing** — Verify `meta.js` exists. Check for `hidden: true` (means component is excluded from export — only use for internal helpers). Rebuild: `cd foundation && pnpm build`.
 
 **Styles not applying** — Verify `@source` in `styles.css` includes your component paths. Check custom colors match `@theme` definitions.
 
-**Prerender warnings about hooks/useState** — During `pnpm build`, you may see `Warning: Failed to render /: Cannot read properties of null (reading 'useState')` for pages. This is a known limitation of the SSG pipeline (dual React instances in development). The site works correctly client-side — these warnings only affect the static HTML preview, not functionality.
+**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
 

package/partials/ai-assistance.hbs

@@ -1,8 +1,10 @@
-## AI Assistance
+## Developer Guide
 
-This project includes an [AGENTS.md](./AGENTS.md) file with detailed instructions for AI coding assistants (Claude Code, Cursor, Copilot, etc.).
+[AGENTS.md](./AGENTS.md) is a comprehensive guide to building with Uniweb — content authoring, component development, theming, configuration, and the kit API. Despite the name, it's written for developers and AI assistants alike. Read it to get productive fast.
 
-### Example Prompts
+### AI Prompts
+
+AI coding assistants (Claude Code, Cursor, Copilot, etc.) read AGENTS.md automatically. Some prompts to try:
 
 **Converting an existing design:**
 ```

package/partials/learn-more.hbs

@@ -1,5 +1,6 @@
 ## Learn More
 
-- [Uniweb Documentation](https://github.com/uniweb/cli)
-- [@uniweb/kit Components](https://www.npmjs.com/package/@uniweb/kit)
+- [AGENTS.md](./AGENTS.md) — comprehensive guide to building with Uniweb
+- [Uniweb Documentation](https://github.com/uniweb/docs) — full reference docs
+- [Uniweb CLI](https://github.com/uniweb/cli) — project scaffolding and build tools
 - [Tailwind CSS v4](https://tailwindcss.com)

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/sections/Section/index.jsx

@@ -1,37 +1,25 @@
-import React from 'react'
 import { H1, H2, P, Link, cn } from '@uniweb/kit'
 
 /**
  * Section Component
  *
  * A versatile content section that handles headings, text, and links.
- * This is the default component for rendering markdown content.
+ * Uses semantic tokens so it adapts to any theme context automatically.
  */
-function Section({ content, params }) {
-  // Content fields: title, pretitle, subtitle, paragraphs, links, imgs, items
+export default function Section({ content, params }) {
   const { title, pretitle, subtitle, paragraphs = [], links = [], imgs = [] } = content || {}
 
   const {
-    theme = 'light',
     align = 'center',
     width = 'default',
   } = params || {}
 
-  // Theme styles
-  const themes = {
-    light: 'bg-white text-gray-900',
-    dark: 'bg-gray-900 text-white',
-    primary: 'bg-primary text-white',
-  }
-
-  // Alignment styles
   const alignments = {
     left: 'text-left',
     center: 'text-center',
     right: 'text-right',
   }
 
-  // Width styles
   const widths = {
     narrow: 'max-w-2xl',
     default: 'max-w-4xl',
@@ -40,58 +28,47 @@ function Section({ content, params }) {
   }
 
   return (
-    <section className={cn('py-16 px-6', themes[theme])}>
-      <div className={cn('mx-auto', widths[width], alignments[align])}>
-        {/* Pretitle / Eyebrow */}
+    <div className={cn('py-16 px-6', alignments[align])}>
+      <div className={cn('mx-auto', widths[width])}>
         {pretitle && (
-          <p className="text-sm font-medium text-primary mb-4 uppercase tracking-wide">
+          <p className="text-sm font-medium text-link mb-4 uppercase tracking-wide">
             {pretitle}
           </p>
         )}
 
-        {/* Title */}
         {title && (
           <H1
             text={title}
-            className="text-3xl sm:text-4xl font-bold mb-4"
+            className="text-heading text-3xl sm:text-4xl font-bold mb-4"
           />
         )}
 
-        {/* Subtitle */}
         {subtitle && (
           <H2
             text={subtitle}
-            className={cn(
-              'text-xl mb-6',
-              theme === 'light' ? 'text-gray-600' : 'text-gray-300'
-            )}
+            className="text-body text-xl mb-6"
           />
         )}
 
-        {/* Paragraphs */}
         {paragraphs.map((para, index) => (
           <P
             key={index}
             text={para}
-            className={cn(
-              'text-lg mb-4 leading-relaxed',
-              theme === 'light' ? 'text-gray-700' : 'text-gray-300'
-            )}
+            className="text-body text-lg mb-4 leading-relaxed"
           />
         ))}
 
-        {/* Links */}
         {links.length > 0 && (
-          <div className={cn('mt-8 flex gap-4 flex-wrap', alignments[align] === 'text-center' && 'justify-center')}>
+          <div className={cn('mt-8 flex gap-4 flex-wrap', align === 'center' && 'justify-center')}>
             {links.map((link, index) => (
               <Link
                 key={index}
-                href={link.href}
+                to={link.href}
                 className={cn(
                   'inline-flex items-center px-6 py-3 font-medium rounded-lg transition-colors',
                   index === 0
-                    ? 'bg-primary-600 text-white hover:bg-primary-700'
-                    : 'border border-current hover:bg-gray-100'
+                    ? 'bg-primary text-primary-foreground hover:bg-primary-hover'
+                    : 'bg-secondary text-secondary-foreground hover:bg-secondary-hover'
                 )}
               >
                 {link.label}
@@ -100,7 +77,6 @@ function Section({ content, params }) {
           </div>
         )}
 
-        {/* Images */}
         {imgs.length > 0 && (
           <div className="mt-8">
             {imgs.map((img, index) => (
@@ -114,8 +90,6 @@ function Section({ content, params }) {
           </div>
         )}
       </div>
-    </section>
+    </div>
   )
 }
-
-export default Section

package/starter/foundation/src/sections/Section/meta.js

@@ -1,8 +1,3 @@
-/**
- * Section Component Metadata (v2)
- *
- * A versatile content section for headings, text, and links.
- */
 export default {
   title: 'Section',
   description: 'A versatile content section for headings, text, and links',
@@ -19,12 +14,6 @@ export default {
   },
 
   params: {
-    theme: {
-      type: 'select',
-      label: 'Theme',
-      options: ['light', 'dark', 'primary'],
-      default: 'light',
-    },
     align: {
       type: 'select',
       label: 'Alignment',
@@ -47,15 +36,11 @@ export default {
   presets: {
     default: {
       label: 'Centered',
-      params: { theme: 'light', align: 'center' },
-    },
-    dark: {
-      label: 'Dark Theme',
-      params: { theme: 'dark', align: 'center' },
+      params: { align: 'center' },
     },
     left: {
       label: 'Left Aligned',
-      params: { theme: 'light', align: 'left' },
+      params: { align: 'left' },
     },
   },
 }

package/starter/site/pages/home/1-welcome.md.hbs

@@ -8,7 +8,7 @@ align: center
 
 ## Your Uniweb project is ready
 
-This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and customize the components in `foundation/src/components/`.
+This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and build section types in `foundation/src/sections/`.
 
 [About](/about)
 [Documentation](https://github.com/uniweb)

package/templates/site/theme.yml

@@ -51,25 +51,25 @@ 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
 
 # ─── Inline Text Styles ───────────────────────────────────────────────────────
-# Named styles for inline text in markdown: [text]{emphasis}
+# Named styles for inline text in markdown: [text]{accent}
 # Each name maps to CSS properties.
-# Defaults: emphasis (colored + bold), muted (subtle).
+# Defaults: accent (colored + bold), muted (subtle).
 
 # inline:
-#   emphasis:
+#   accent:
 #     color: 'var(--link)'
 #     font-weight: '600'
 #   muted:

package/templates/workspace/README.md.hbs

@@ -10,7 +10,7 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 {{projectName}}/
 ├── foundation/          # React component library
 │   ├── src/
-│   │   ├── components/  # Your components
+│   │   ├── sections/    # Section types (selectable by content authors)
 │   │   └── styles.css   # Tailwind CSS v4 theme
 │   └── vite.config.js   # defineFoundationConfig()
 │
@@ -22,7 +22,7 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 │   ├── site.yml         # Site configuration
 │   └── vite.config.js   # defineSiteConfig()
 │
-└── AGENTS.md            # AI assistant instructions
+└── AGENTS.md            # Developer guide (human + AI)
 ```
 
 ## Content Authoring
@@ -46,27 +46,25 @@ Your content here.
 
 ## Component Development
 
-Components live in `foundation/src/components/`:
+Section types live in `foundation/src/sections/`. Each is a folder with an `index.jsx` and a `meta.js`:
 
 ```jsx
-// foundation/src/components/Hero/index.jsx
-import { H1, P, cn } from '@uniweb/kit'
+// foundation/src/sections/Hero/index.jsx
+import { H1, P } from '@uniweb/kit'
 
-export function Hero({ content, params }) {
-  const { title } = content.main?.header || {}
-  const { theme = 'light' } = params
+export default function Hero({ content }) {
+  const { title, paragraphs = [] } = content || {}
 
   return (
-    <section className={cn('py-20', theme === 'dark' && 'bg-gray-900')}>
-      <H1 text={title} />
-    </section>
+    <div className="max-w-4xl mx-auto px-6">
+      <H1 text={title} className="text-heading text-4xl font-bold" />
+      <P text={paragraphs} className="text-body mt-4" />
+    </div>
   )
 }
-
-export default Hero
 ```
 
-Exposed components (selectable via `type:` in frontmatter) need a `meta.js` file.
+Components receive parsed content from markdown. Classes like `text-heading` and `text-body` are semantic tokens — the site controls their actual colors through theming, so the same component adapts to any context automatically.
 
 {{> components-docs}}