uniweb 0.8.5 → 0.8.6

package/package.json

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

package/partials/agents.md

@@ -67,8 +67,11 @@ The name is both the directory name and the package name. Use `--project <name>`
 pnpm install    # Install dependencies
 pnpm dev        # Start dev server
 pnpm build      # Build for production
+pnpm preview    # Preview production build (SSG + SPA)
 ```
 
+> **npm works too.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command above.
+
 ## Content Authoring
 
 ### Section Format
@@ -112,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
@@ -127,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
@@ -186,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.
@@ -198,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
@@ -215,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:
@@ -235,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
@@ -417,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.
 
@@ -430,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
@@ -437,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:
@@ -467,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
@@ -509,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
@@ -577,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`):
@@ -853,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
 
@@ -863,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/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)',
   },
 }