uniweb 0.8.4 → 0.8.6

package/README.md

@@ -27,6 +27,7 @@ Edit files in `site/pages/` and `foundation/src/sections/` to see changes instan
 | Template | Description |
 | --- | --- |
 | **Starter** | Foundation + site + sample content (default) |
+| **None** | Foundation + site with no content |
 | **Marketing** | Landing page, features, pricing, testimonials |
 | **Docs** | Documentation with sidebar and search |
 | **Academic** | Research site with publications and team |
@@ -34,7 +35,8 @@ Edit files in `site/pages/` and `foundation/src/sections/` to see changes instan
 | **Dynamic** | Live API data fetching with loading states |
 | **Store** | E-commerce with product grid |
 | **Extensions** | Multi-foundation with visual effects extension |
-| **Blank** | Empty workspace — grow with `uniweb add` |
+
+Use `--blank` for an empty workspace (no packages) — grow with `uniweb add`.
 
 **See them live:** [View all template demos](https://uniweb.github.io/templates/)
 
@@ -234,31 +236,32 @@ Start simple. Add what you need, when you need it:
 ```bash
 cd my-site
 
-# Add a second foundation
-npx uniweb add foundation blog
+# Add a co-located foundation + site pair
+npx uniweb add project blog
+
+# Add a second foundation at root
+npx uniweb add foundation ui
 
-# Add a site wired to the blog foundation
-npx uniweb add site blog --foundation blog
+# Add a site wired to a specific foundation
+npx uniweb add site docs --foundation ui
 
 # Add an extension (auto-wired to the only site)
 npx uniweb add extension effects
 
 # Scaffold + apply content from an official template
-npx uniweb add foundation marketing --from marketing
-npx uniweb add site main --from marketing --foundation marketing
+npx uniweb add project marketing --from marketing
 ```
 
-The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. Use `--path` to override default placement, or `--project` for co-located layouts (e.g., `marketing/foundation/` + `marketing/site/`).
+The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. The name you provide becomes both the directory name and the package name. Use `--path` to override default placement, or `--project` for explicit co-located layouts.
 
 > `npx uniweb` works before and after install. Once dependencies are installed, you can also use `pnpm uniweb` directly since `uniweb` is a project dependency.
 
 **Or start blank and build up:**
 
 ```bash
-pnpm create uniweb acme --template blank
+pnpm create uniweb acme --blank
 cd acme
-npx uniweb add foundation
-npx uniweb add site
+npx uniweb add project main
 pnpm install
 pnpm dev
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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.4",
+    "@uniweb/build": "0.8.5",
+    "@uniweb/kit": "0.7.3",
     "@uniweb/core": "0.5.4",
-    "@uniweb/runtime": "0.6.4",
-    "@uniweb/kit": "0.7.3"
+    "@uniweb/runtime": "0.6.4"
   }
 }

package/partials/agents.md

@@ -27,17 +27,27 @@ pnpm create uniweb my-project
 cd my-project && pnpm install
 ```
 
-Use `--template blank` for an empty workspace, or `--template <name>` for an official template (`marketing`, `docs`, `academic`, etc.).
+This creates a workspace with foundation + site + starter content — two commands to a dev server. Use `--template <name>` for an official template (`marketing`, `docs`, `academic`, etc.), `--template none` for foundation + site with no content, or `--blank` for an empty workspace.
 
-### Adding to an existing workspace
+### Adding a co-located project
 
 ```bash
-pnpm uniweb add foundation myname --project myname
-pnpm uniweb add site myname --project myname
+pnpm uniweb add project docs
 pnpm install
 ```
 
-The `--project` flag co-locates foundation and site under `myname/`. The CLI names them `myname` (foundation) and `myname-site` (site) to avoid workspace name collisions.
+This creates `docs/foundation/` + `docs/site/` with package names `docs-foundation` and `docs-site`. Use `--from <template>` to apply template content to both packages.
+
+### Adding individual packages
+
+```bash
+pnpm uniweb add foundation           # First foundation → ./foundation/
+pnpm uniweb add foundation ui        # Named → ./ui/
+pnpm uniweb add site                 # First site → ./site/
+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/`).
 
 ### What the CLI generates
 
@@ -57,8 +67,11 @@ The `--project` flag co-locates foundation and site under `myname/`. The CLI nam
 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
@@ -102,7 +115,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
@@ -117,12 +130,16 @@ 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.
+
 **Lists** contain bullet or ordered list items. Each list item is an object with the same content shape — not a plain string:
 
 ```markdown
@@ -176,6 +193,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.
@@ -188,6 +206,8 @@ 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.
 
 ### Structured Data
@@ -205,19 +225,33 @@ 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.
+
 ### 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:
@@ -225,6 +259,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
@@ -407,7 +443,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.
 
@@ -420,6 +456,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: var(--neutral-900)        # Dark buttons in a light section
+  primary-hover: var(--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
@@ -427,18 +490,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:
@@ -457,23 +516,78 @@ 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.
+
+**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
@@ -499,13 +613,13 @@ 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.
 
 ### meta.js Structure
@@ -567,6 +681,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`):
@@ -805,7 +921,7 @@ Uniweb section types do more with less because the framework handles concerns th
 
 1. **Check if you're inside an existing Uniweb workspace** (look for `pnpm-workspace.yaml` and a `package.json` with `uniweb` as a dependency). If yes, use `pnpm uniweb add` to create projects inside it. If no, create a new workspace:
    ```bash
-   pnpm create uniweb my-project --template blank
+   pnpm create uniweb my-project --template none
    ```
 
 3. **Use named layouts** for different page groups — a marketing layout for landing pages, a docs layout for `/docs/*`. One site, multiple layouts, each with its own header/footer/sidebar content.
@@ -843,7 +959,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
 
@@ -853,6 +969,8 @@ 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.
+
 ## 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,9 +1,10 @@
 /**
  * Add Command
  *
- * Adds foundations, sites, or extensions to an existing workspace.
+ * Adds foundations, sites, extensions, 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>]
@@ -14,7 +15,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import prompts from 'prompts'
 import yaml from 'js-yaml'
-import { scaffoldFoundation, scaffoldSite, applyContent, mergeTemplateDependencies } from '../utils/scaffold.js'
+import { scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies } from '../utils/scaffold.js'
 import {
   readWorkspaceConfig,
   addWorkspaceGlob,
@@ -118,12 +119,13 @@ export async function add(rawArgs) {
     if (nonInteractive) {
       error(`Missing subcommand.\n`)
       log(formatOptions([
+        { label: 'project', description: 'Co-located foundation + site pair' },
         { label: 'foundation', description: 'Component library' },
         { label: 'site', description: 'Content site' },
         { label: 'extension', description: 'Additional component package' },
       ]))
       log('')
-      log(`Usage: ${prefix} add <foundation|site|extension> [name]`)
+      log(`Usage: ${prefix} add <project|foundation|site|extension> [name]`)
       process.exit(1)
     }
 
@@ -132,6 +134,7 @@ export async function add(rawArgs) {
       name: 'subcommand',
       message: 'What would you like to add?',
       choices: [
+        { title: 'Project', value: 'project', description: 'Co-located foundation + site pair' },
         { title: 'Foundation', value: 'foundation', description: 'Component library' },
         { title: 'Site', value: 'site', description: 'Content site' },
         { title: 'Extension', value: 'extension', description: 'Additional component package' },
@@ -154,6 +157,9 @@ export async function add(rawArgs) {
   const projectName = rootPkg.name || 'my-project'
 
   switch (parsed.subcommand) {
+    case 'project':
+      await addProject(rootDir, projectName, parsed, pm)
+      break
     case 'foundation':
       await addFoundation(rootDir, projectName, parsed, pm)
       break
@@ -165,7 +171,7 @@ export async function add(rawArgs) {
       break
     default:
       error(`Unknown subcommand: ${parsed.subcommand}`)
-      log(`Valid subcommands: foundation, site, extension`)
+      log(`Valid subcommands: project, foundation, site, extension`)
       process.exit(1)
   }
 }
@@ -188,31 +194,28 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Interactive name prompt when name not provided and no --path
   if (!name && !opts.path) {
-    if (isNonInteractive(process.argv)) {
-      error(`Missing foundation name.\n`)
-      log(`Usage: ${getCliPrefix()} add foundation <name>`)
-      process.exit(1)
-    }
-
-    const foundations = await discoverFoundations(rootDir)
-    const hasDefault = foundations.length === 0 && !existsSync(join(rootDir, 'foundation'))
-    const response = await prompts({
-      type: 'text',
-      name: 'name',
-      message: 'Foundation name:',
-      initial: hasDefault ? 'foundation' : undefined,
-      validate: (value) => validatePackageName(value),
-    }, {
-      onCancel: () => {
-        log('\nCancelled.')
-        process.exit(0)
-      },
-    })
-    // Only set name if user chose something other than the default —
-    // null name tells resolveFoundationTarget to use default placement (./foundation/)
-    if (!hasDefault || response.name !== 'foundation') {
-      name = response.name
+    if (!isNonInteractive(process.argv)) {
+      const foundations = await discoverFoundations(rootDir)
+      const hasDefault = foundations.length === 0 && !existsSync(join(rootDir, 'foundation'))
+      const response = await prompts({
+        type: 'text',
+        name: 'name',
+        message: 'Foundation name:',
+        initial: hasDefault ? 'foundation' : undefined,
+        validate: (value) => validatePackageName(value),
+      }, {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        },
+      })
+      // Only set name if user chose something other than the default —
+      // null name tells resolveFoundationTarget to use default placement (./foundation/)
+      if (!hasDefault || response.name !== 'foundation') {
+        name = response.name
+      }
     }
+    // Non-interactive without name: defaults to 'foundation' — resolveFoundationTarget handles it
   }
 
   const target = await resolveFoundationTarget(rootDir, name, opts)
@@ -223,10 +226,12 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
     process.exit(1)
   }
 
-  // Compute package name — auto-suffix if it collides with an existing package
-  let packageName = name || opts.project || 'foundation'
+  // Package name = name or 'foundation'
+  const packageName = name || 'foundation'
   if (existingNames.has(packageName)) {
-    packageName = resolveUniqueName(packageName, '-foundation', existingNames)
+    error(`Package name '${packageName}' already exists in this workspace.`)
+    log(`Choose a different name: ${getCliPrefix()} add foundation <name>`)
+    process.exit(1)
   }
 
   // Scaffold
@@ -274,31 +279,28 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Interactive name prompt when name not provided and no --path
   if (!name && !opts.path) {
-    if (isNonInteractive(process.argv)) {
-      error(`Missing site name.\n`)
-      log(`Usage: ${getCliPrefix()} add site <name>`)
-      process.exit(1)
-    }
-
-    const existingSites = await discoverSites(rootDir)
-    const hasDefault = existingSites.length === 0 && !existsSync(join(rootDir, 'site'))
-    const response = await prompts({
-      type: 'text',
-      name: 'name',
-      message: 'Site name:',
-      initial: hasDefault ? 'site' : undefined,
-      validate: (value) => validatePackageName(value),
-    }, {
-      onCancel: () => {
-        log('\nCancelled.')
-        process.exit(0)
-      },
-    })
-    // Only set name if user chose something other than the default —
-    // null name tells resolveSiteTarget to use default placement (./site/)
-    if (!hasDefault || response.name !== 'site') {
-      name = response.name
+    if (!isNonInteractive(process.argv)) {
+      const existingSites = await discoverSites(rootDir)
+      const hasDefault = existingSites.length === 0 && !existsSync(join(rootDir, 'site'))
+      const response = await prompts({
+        type: 'text',
+        name: 'name',
+        message: 'Site name:',
+        initial: hasDefault ? 'site' : undefined,
+        validate: (value) => validatePackageName(value),
+      }, {
+        onCancel: () => {
+          log('\nCancelled.')
+          process.exit(0)
+        },
+      })
+      // Only set name if user chose something other than the default —
+      // null name tells resolveSiteTarget to use default placement (./site/)
+      if (!hasDefault || response.name !== 'site') {
+        name = response.name
+      }
     }
+    // Non-interactive without name: defaults to 'site' — resolveSiteTarget handles it
   }
 
   const target = await resolveSiteTarget(rootDir, name, opts)
@@ -311,17 +313,13 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Resolve foundation
   const foundation = await resolveFoundation(rootDir, opts.foundation)
-  let siteName
-  if (opts.project) {
-    // Co-located: convention is {project}-site (e.g., io-site)
-    siteName = (!name || name === opts.project) ? `${opts.project}-site` : name
-  } else {
-    siteName = name || 'site'
-  }
 
-  // Auto-suffix package name if it collides with an existing package
+  // Package name = name or 'site'
+  const siteName = name || 'site'
   if (existingNames.has(siteName)) {
-    siteName = resolveUniqueName(siteName, '-site', existingNames)
+    error(`Package name '${siteName}' already exists in this workspace.`)
+    log(`Choose a different name: ${getCliPrefix()} add site <name>`)
+    process.exit(1)
   }
 
   if (foundation) {
@@ -481,8 +479,117 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
 }
 
+/**
+ * Add a co-located foundation + site pair to the workspace
+ */
+async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
+  let name = opts.name
+  const existingNames = await getExistingPackageNames(rootDir)
+
+  // Validate name format
+  if (name) {
+    const valid = validatePackageName(name)
+    if (valid !== true) {
+      error(valid)
+      process.exit(1)
+    }
+  }
+
+  // Interactive name prompt when name not provided
+  if (!name) {
+    if (isNonInteractive(process.argv)) {
+      error(`Missing project name.\n`)
+      log(`Usage: ${getCliPrefix()} add project <name>`)
+      process.exit(1)
+    }
+
+    const response = await prompts({
+      type: 'text',
+      name: 'name',
+      message: 'Project name:',
+      validate: (value) => validatePackageName(value),
+    }, {
+      onCancel: () => {
+        log('\nCancelled.')
+        process.exit(0)
+      },
+    })
+    name = response.name
+  }
+
+  // Check directory doesn't already exist
+  const projectDir = join(rootDir, name)
+  if (existsSync(projectDir)) {
+    error(`Directory already exists: ${name}/`)
+    process.exit(1)
+  }
+
+  // Compute package names
+  const foundationPkgName = `${name}-foundation`
+  const sitePkgName = `${name}-site`
+
+  // Check package name collisions
+  for (const pkgName of [foundationPkgName, sitePkgName]) {
+    if (existingNames.has(pkgName)) {
+      error(`Package name '${pkgName}' already exists in this workspace.`)
+      process.exit(1)
+    }
+  }
+
+  const progressCb = (msg) => info(`  ${msg}`)
+
+  // Scaffold foundation
+  info(`Creating foundation: ${foundationPkgName}...`)
+  await scaffoldFoundation(join(projectDir, 'foundation'), {
+    name: foundationPkgName,
+    projectName,
+    isExtension: false,
+  }, { onProgress: progressCb })
+
+  // Scaffold site
+  info(`Creating site: ${sitePkgName}...`)
+  await scaffoldSite(join(projectDir, 'site'), {
+    name: sitePkgName,
+    projectName,
+    foundationName: foundationPkgName,
+    foundationPath: 'file:../foundation',
+    foundationRef: foundationPkgName,
+  }, { onProgress: progressCb })
+
+  // Apply template content if --from specified
+  if (opts.from) {
+    await applyFromTemplate(opts.from, 'foundation', join(projectDir, 'foundation'), projectName)
+    await applyFromTemplate(opts.from, 'site', join(projectDir, 'site'), projectName)
+  }
+
+  // Update workspace globs for co-located layout
+  await addWorkspaceGlob(rootDir, '*/foundation')
+  await addWorkspaceGlob(rootDir, '*/site')
+
+  // Update root scripts
+  const sites = await discoverSites(rootDir)
+  if (!sites.find(s => s.path === `${name}/site`)) {
+    sites.push({ name: sitePkgName, path: `${name}/site` })
+  }
+  await updateRootScripts(rootDir, sites, pm)
+
+  success(`Created project '${name}' at ${name}/`)
+  log(`  ${colors.dim}Foundation: ${name}/foundation/ (${foundationPkgName})${colors.reset}`)
+  log(`  ${colors.dim}Site: ${name}/site/ (${sitePkgName})${colors.reset}`)
+  log('')
+  log(`Next: ${colors.cyan}${installCmd(pm)} && ${filterCmd(pm, sitePkgName, 'dev')}${colors.reset}`)
+}
+
 /**
  * Resolve placement for a foundation
+ *
+ * Rules:
+ * - --path: use it directly
+ * - --project: {project}/foundation (co-located)
+ * - Existing co-located glob: follow pattern
+ * - Existing segregated glob: follow pattern
+ * - First foundation: dir name is the name (default: 'foundation')
+ * - Already have one: error in non-interactive, ask in interactive
  */
 async function resolveFoundationTarget(rootDir, name, opts) {
   if (opts.path) return opts.path
@@ -495,23 +602,43 @@ async function resolveFoundationTarget(rootDir, name, opts) {
   const { packages } = await readWorkspaceConfig(rootDir)
   const hasColocated = packages.some(p => p.includes('*/foundation'))
   const hasFoundationsGlob = packages.some(p => p.startsWith('foundations/'))
-  const hasSingleFoundation = existsSync(join(rootDir, 'foundation'))
 
-  if (hasColocated && opts.project) {
-    return `${opts.project}/foundation`
+  // Respect existing co-located layout
+  if (hasColocated && name) {
+    return `${name}/foundation`
   }
 
-  // No name and no foundations exist → ./foundation/
-  if (!name && !hasSingleFoundation && !hasFoundationsGlob) {
-    return 'foundation'
+  // Respect existing segregated layout
+  if (hasFoundationsGlob) {
+    return `foundations/${name || 'foundation'}`
   }
 
-  // Named foundation or existing foundation → ./foundations/{name}/
-  return `foundations/${name || 'foundation'}`
+  // dir name = name or 'foundation'
+  const dirName = name || 'foundation'
+
+  // Check if target already exists
+  if (!existsSync(join(rootDir, dirName))) {
+    return dirName
+  }
+
+  // Already have one at the target path — error with guidance
+  if (isNonInteractive(process.argv)) {
+    error(`Directory '${dirName}' already exists.`)
+    log(`\nTo add another foundation, specify a name:`)
+    log(`  ${getCliPrefix()} add foundation <name>`)
+    log(`\nOr use --path for explicit placement:`)
+    log(`  ${getCliPrefix()} add foundation --path <dir>`)
+    process.exit(1)
+  }
+
+  // Interactive: the existsSync check in addFoundation will catch it
+  return dirName
 }
 
 /**
  * Resolve placement for a site
+ *
+ * Same rules as resolveFoundationTarget, adapted for sites.
  */
 async function resolveSiteTarget(rootDir, name, opts) {
   if (opts.path) return opts.path
@@ -523,19 +650,37 @@ async function resolveSiteTarget(rootDir, name, opts) {
   const { packages } = await readWorkspaceConfig(rootDir)
   const hasColocated = packages.some(p => p.includes('*/site'))
   const hasSitesGlob = packages.some(p => p.startsWith('sites/'))
-  const hasSingleSite = existsSync(join(rootDir, 'site'))
 
-  if (hasColocated && opts.project) {
-    return `${opts.project}/site`
+  // Respect existing co-located layout
+  if (hasColocated && name) {
+    return `${name}/site`
   }
 
-  // No name and no sites exist → ./site/
-  if (!name && !hasSingleSite && !hasSitesGlob) {
-    return 'site'
+  // Respect existing segregated layout
+  if (hasSitesGlob) {
+    return `sites/${name || 'site'}`
+  }
+
+  // dir name = name or 'site'
+  const dirName = name || 'site'
+
+  // Check if target already exists
+  if (!existsSync(join(rootDir, dirName))) {
+    return dirName
+  }
+
+  // Already have one at the target path — error with guidance
+  if (isNonInteractive(process.argv)) {
+    error(`Directory '${dirName}' already exists.`)
+    log(`\nTo add another site, specify a name:`)
+    log(`  ${getCliPrefix()} add site <name>`)
+    log(`\nOr use --path for explicit placement:`)
+    log(`  ${getCliPrefix()} add site --path <dir>`)
+    process.exit(1)
   }
 
-  // Named site or existing site → ./sites/{name}/
-  return `sites/${name || 'site'}`
+  // Interactive: the existsSync check in addSite will catch it
+  return dirName
 }
 
 /**
@@ -737,9 +882,10 @@ function showAddHelp() {
   log(`
 ${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
 
-Add foundations, sites, or extensions to your workspace.
+Add projects, foundations, sites, or extensions 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]
@@ -759,11 +905,12 @@ ${colors.bright}Extension Options:${colors.reset}
   --site <name>      Site to wire extension URL into
 
 ${colors.bright}Examples:${colors.reset}
-  uniweb add foundation                                # Create ./foundation/
-  uniweb add foundation marketing                      # Create ./foundations/marketing/
-  uniweb add foundation marketing --from marketing     # Scaffold + marketing sections
-  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
-  uniweb add site blog --from docs --foundation blog   # Scaffold + docs pages
+  uniweb add project docs                              # Create docs/foundation/ + docs/site/
+  uniweb add project docs --from academic              # Co-located pair + academic content
+  uniweb add foundation                                # Create ./foundation/ at root
+  uniweb add foundation ui                             # Create ./ui/ at root
+  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 foundation --project docs                 # Create ./docs/foundation/ (co-located)
   uniweb add site --project docs                       # Create ./docs/site/ (co-located)

package/src/index.js

@@ -44,8 +44,8 @@ const colors = {
 
 // Template choices for interactive prompt
 const TEMPLATE_CHOICES = [
+  { title: 'None', value: 'none', description: 'Foundation + site with no content' },
   { title: 'Starter', value: 'starter', description: 'Foundation + site + sample content' },
-  { title: 'Blank', value: 'blank', description: 'Empty workspace — grow with uniweb add' },
   { title: 'Marketing', value: 'marketing', description: 'Landing page, features, pricing, testimonials' },
   { title: 'Docs', value: 'docs', description: 'Documentation with sidebar and search' },
   { title: 'Academic', value: 'academic', description: 'Research site with publications and team' },
@@ -53,6 +53,7 @@ const TEMPLATE_CHOICES = [
   { title: 'International', value: 'international', description: 'Multilingual site with i18n and blog' },
   { title: 'Store', value: 'store', description: 'E-commerce with product grid' },
   { title: 'Extensions', value: 'extensions', description: 'Multi-foundation with visual effects extension' },
+  { title: 'Blank workspace', value: 'blank', description: 'Empty workspace — grow with uniweb add' },
 ]
 
 function log(message) {
@@ -75,7 +76,7 @@ function title(message) {
  * Create a project using the new package template flow (default)
  */
 async function createFromPackageTemplates(projectDir, projectName, options = {}) {
-  const { onProgress, onWarning, pm = 'pnpm' } = options
+  const { onProgress, onWarning, pm = 'pnpm', includeStarter = true } = options
 
   onProgress?.('Setting up workspace...')
 
@@ -107,9 +108,11 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
     foundationPath: 'file:../foundation',
   }, { onProgress, onWarning })
 
-  // 4. Apply starter content
-  onProgress?.('Adding starter content...')
-  await applyStarter(projectDir, { projectName }, { onProgress, onWarning })
+  // 4. Apply starter content (unless creating a "none" project)
+  if (includeStarter) {
+    onProgress?.('Adding starter content...')
+    await applyStarter(projectDir, { projectName }, { onProgress, onWarning })
+  }
 
   success(`Created project: ${projectName}`)
 }
@@ -364,6 +367,15 @@ async function main() {
     displayName = args[nameIndex + 1]
   }
 
+  // Check for --blank flag
+  let isBlank = args.includes('--blank')
+
+  // Handle --template blank as alias for --blank
+  if (templateType === 'blank') {
+    isBlank = true
+    templateType = null
+  }
+
   // Check for --no-git flag
   const noGit = args.includes('--no-git')
 
@@ -377,19 +389,13 @@ async function main() {
   // Non-interactive: fail with actionable message instead of prompting
   if (nonInteractive && !projectName) {
     error(`Missing project name.\n`)
-    log(`Usage: ${prefix} create <project-name> [--template <name>]`)
+    log(`Usage: ${prefix} create <project-name> [--template <name>] [--blank]`)
     process.exit(1)
   }
 
-  if (nonInteractive && !templateType) {
-    error(`Missing --template flag. Available templates:\n`)
-    log(formatOptions(TEMPLATE_CHOICES.map(c => ({
-      label: c.value,
-      description: c.description,
-    }))))
-    log('')
-    log(`Usage: ${prefix} create ${projectName || '<project-name>'} --template <name>`)
-    process.exit(1)
+  // Non-interactive: default to starter when no template specified
+  if (nonInteractive && !templateType && !isBlank) {
+    templateType = 'starter'
   }
 
   // Interactive prompts
@@ -421,13 +427,14 @@ async function main() {
     process.exit(1)
   }
 
-  // Prompt for template if not specified via --template
-  if (!templateType) {
+  // Prompt for template if not specified via --template or --blank
+  if (!templateType && !isBlank) {
     const templateResponse = await prompts({
       type: 'select',
       name: 'template',
       message: 'Template:',
       choices: TEMPLATE_CHOICES,
+      initial: 1,
     }, {
       onCancel: () => {
         log('\nScaffolding cancelled.')
@@ -435,6 +442,11 @@ async function main() {
       },
     })
     templateType = templateResponse.template
+    // Handle "blank" selection from interactive prompt
+    if (templateType === 'blank') {
+      isBlank = true
+      templateType = null
+    }
   }
 
   const effectiveName = displayName || projectName
@@ -451,13 +463,22 @@ async function main() {
   const progressCb = (msg) => log(`  ${colors.dim}${msg}${colors.reset}`)
   const warningCb = (msg) => log(`  ${colors.yellow}Warning: ${msg}${colors.reset}`)
 
-  if (templateType === 'blank') {
-    // Blank workspace
+  if (isBlank) {
+    // Blank workspace (--blank or --template blank)
     log('\nCreating blank workspace...')
     await createBlankWorkspace(projectDir, effectiveName, {
       onProgress: progressCb,
       onWarning: warningCb,
     })
+  } else if (templateType === 'none') {
+    // Foundation + site with no content
+    log('\nCreating project...')
+    await createFromPackageTemplates(projectDir, effectiveName, {
+      onProgress: progressCb,
+      onWarning: warningCb,
+      pm,
+      includeStarter: false,
+    })
   } else if (templateType === 'starter') {
     // Starter: foundation + site + sample content
     log('\nCreating project...')
@@ -521,11 +542,10 @@ async function main() {
   // Success message
   title('Project created successfully!')
 
-  if (templateType === 'blank') {
+  if (isBlank) {
     log(`Next steps:\n`)
     log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
-    log(`  ${colors.cyan}npx uniweb add foundation${colors.reset}`)
-    log(`  ${colors.cyan}npx uniweb add site${colors.reset}`)
+    log(`  ${colors.cyan}${prefix} add project${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
     log(`  ${colors.cyan}${runCmd(pm, 'dev')}${colors.reset}`)
   } else {
@@ -553,11 +573,13 @@ ${colors.bright}Commands:${colors.reset}
   i18n <cmd>         Internationalization (extract, sync, status)
 
 ${colors.bright}Create Options:${colors.reset}
-  --template <type>  Project template (prompts if not specified)
+  --template <type>  Project template (default: starter)
+  --blank            Create an empty workspace (grow with uniweb add)
   --name <name>      Project display name
   --no-git           Skip git repository initialization
 
 ${colors.bright}Add Subcommands:${colors.reset}
+  add project [name]      Add a co-located foundation + site pair
   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)
@@ -594,7 +616,7 @@ ${colors.bright}i18n Commands:${colors.reset}
 
 ${colors.bright}Template Types:${colors.reset}
   starter                       Foundation + site + sample content (default)
-  blank                         Empty workspace (grow with 'add')
+  none                          Foundation + site with no content
   marketing                     Official marketing template
   ./path/to/template            Local directory
   @scope/template-name          npm package
@@ -602,17 +624,17 @@ ${colors.bright}Template Types:${colors.reset}
   https://github.com/user/repo  GitHub URL
 
 ${colors.bright}Examples:${colors.reset}
-  npx uniweb create my-project                           # Interactive (prompts for template)
-  npx uniweb create my-project --template starter        # Foundation + site + starter content
-  npx uniweb create my-project --template blank          # Blank workspace
+  npx uniweb create my-project                           # Foundation + site + starter content
+  npx uniweb create my-project --template none           # Foundation + site, no content
+  npx uniweb create my-project --blank                   # Empty workspace
   npx uniweb create my-project --template marketing      # Official template
   npx uniweb create my-project --template ./my-template  # Local template
 
   cd my-project
-  npx uniweb add foundation marketing                    # Add foundations/marketing/
-  npx uniweb add foundation marketing --from marketing   # Scaffold + marketing sections
-  npx uniweb add site blog --foundation marketing        # Add sites/blog/ wired to marketing
-  npx uniweb add site blog --from docs --foundation blog # Scaffold + docs pages
+  npx uniweb add project docs                            # Add docs/foundation/ + docs/site/
+  npx uniweb add project docs --from academic            # Co-located pair + academic content
+  npx uniweb add foundation                              # Add foundation at root
+  npx uniweb add site blog --foundation marketing        # Add site wired to marketing
   npx uniweb add extension effects --site site           # Add extensions/effects/
 
   npx uniweb build

package/src/templates/resolver.js

@@ -3,7 +3,7 @@
  */
 
 // Built-in templates (programmatic, not file-based)
-export const BUILTIN_TEMPLATES = ['blank', 'starter']
+export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
 // Official templates from @uniweb/templates package (downloaded from GitHub releases)
 export const OFFICIAL_TEMPLATES = ['marketing', 'academic', 'docs', 'international', 'dynamic', 'store', 'extensions']

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)',
   },
 }