uniweb 0.8.6 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.6",
+  "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/build": "0.8.5",
-    "@uniweb/kit": "0.7.3",
-    "@uniweb/core": "0.5.4",
-    "@uniweb/runtime": "0.6.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`):
@@ -84,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.
 
@@ -97,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:
@@ -140,6 +172,28 @@ 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
@@ -210,6 +264,22 @@ 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[]
+```
+
 ### Structured Data
 
 Tagged code blocks pass structured data via `content.data`:
@@ -239,6 +309,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 +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 |
@@ -477,8 +592,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.
@@ -586,6 +701,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 +745,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
@@ -702,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)`
 
@@ -748,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
@@ -776,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
@@ -969,7 +1212,15 @@ 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** — 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/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/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