uniweb 0.5.14 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,7 +13,7 @@ pnpm install
13
13
  pnpm dev
14
14
  ```
15
15
 
16
- Open http://localhost:5173 to see your site. Edit files in `site/pages/` and `foundation/src/components/` to see changes instantly.
16
+ Open http://localhost:5173 to see your site. Edit files in `site/pages/` and `foundation/src/sections/` to see changes instantly.
17
17
 
18
18
  > **Need pnpm?** Run `npm install -g pnpm` or see [pnpm installation](https://pnpm.io/installation).
19
19
 
@@ -27,7 +27,7 @@ pnpm build # Build foundation + site for production
27
27
  pnpm preview # Preview the production build
28
28
  ```
29
29
 
30
- The `build` command generates static HTML in `site/dist/`. Open those files to verify your output before deploying.
30
+ The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere.
31
31
 
32
32
  The `marketing` template includes real components (Hero, Features, Pricing, Testimonials, FAQ, and more) with sample content—a working site you can explore and modify.
33
33
 
@@ -72,10 +72,13 @@ my-project/
72
72
 
73
73
  └── foundation/ # Your components
74
74
  ├── src/
75
- └── components/
76
- └── Hero/
77
- ├── index.jsx
78
- └── meta.js
75
+ ├── sections/ # Section types (addressable from markdown)
76
+ │ ├── Hero.jsx # Bare file → section type (no meta.js needed)
77
+ │ └── Features/
78
+ │ ├── meta.js # Content interface (params, presets)
79
+ │ │ └── Features.jsx
80
+ │ └── components/ # Regular React components
81
+ │ └── Button.jsx
79
82
  ├── vite.config.js # 3-line config
80
83
  └── dist/ # Built output
81
84
  ```
@@ -128,22 +131,19 @@ Natural content stays in markdown; structured data goes in tagged blocks (YAML o
128
131
  ### Components as React
129
132
 
130
133
  ```jsx
131
- export function Hero({ content, params }) {
134
+ export default function Hero({ content, params }) {
132
135
  const { title, paragraphs, links } = content
133
- const { theme = 'light' } = params
134
136
 
135
137
  return (
136
- <section
137
- className={`py-20 text-center ${theme === 'dark' ? 'bg-gray-900 text-white' : ''}`}
138
- >
138
+ <section className="py-20 text-center">
139
139
  <h1 className="text-4xl font-bold">{title}</h1>
140
140
  <p className="text-xl text-gray-600">{paragraphs[0]}</p>
141
141
  {links[0] && (
142
142
  <a
143
- href={links[0].url}
143
+ href={links[0].href}
144
144
  className="mt-8 px-6 py-3 bg-blue-600 text-white rounded inline-block"
145
145
  >
146
- {links[0].text}
146
+ {links[0].label}
147
147
  </a>
148
148
  )}
149
149
  </section>
@@ -151,7 +151,7 @@ export function Hero({ content, params }) {
151
151
  }
152
152
  ```
153
153
 
154
- Standard React. Standard Tailwind. The `{ content, params }` interface is only for _exposed_ componentsthe ones content creators select in markdown frontmatter. Internal components use regular React props.
154
+ Standard React. Standard Tailwind. The `{ content, params }` interface is only for _section types_ components that content creators select in markdown frontmatter. Everything else uses regular React props.
155
155
 
156
156
  ## Next Steps
157
157
 
@@ -163,7 +163,7 @@ After creating your project:
163
163
 
164
164
  3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
165
165
 
166
- 4. **Create a component** — Add a folder in `foundation/src/components/`, create `index.jsx` and `meta.js`, then rebuild. See the [Component Metadata Guide](https://github.com/uniweb/cli/blob/main/docs/component-metadata.md) for the full schema.
166
+ 4. **Create a section type** — Add a file to `foundation/src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Guide](./docs/component-metadata.md) for the full schema.
167
167
 
168
168
  The `meta.js` file defines what content and parameters a component accepts. The runtime uses this metadata to apply defaults and guarantee content structure—no defensive null checks needed in your component code.
169
169
 
@@ -187,10 +187,10 @@ Save and see the change instantly in your browser.
187
187
 
188
188
  ### Your First Component Change
189
189
 
190
- Open `foundation/src/components/Hero/index.jsx`. The component receives parsed content:
190
+ Open `foundation/src/sections/Hero.jsx`. The component receives parsed content:
191
191
 
192
192
  ```jsx
193
- export function Hero({ content, params }) {
193
+ export default function Hero({ content }) {
194
194
  const { title, paragraphs, links, imgs, items } = content
195
195
  // Edit the JSX below...
196
196
  }
@@ -198,25 +198,6 @@ export function Hero({ content, params }) {
198
198
 
199
199
  The parser extracts semantic elements from markdown—`title` from the first heading, `paragraphs` from body text, `links` from `[text](url)`, and so on. The `items` array contains child groups created when headings appear after content (useful for features, pricing tiers, team members, etc.).
200
200
 
201
- **Learn more:**
202
-
203
- - [Site Configuration](./docs/site-configuration.md) — Complete site.yml reference
204
- - [Page Configuration](./docs/page-configuration.md) — Complete page.yml reference
205
- - [Content Structure](./docs/content-structure.md) — How content is parsed and structured
206
- - [Navigation Patterns](./docs/navigation-patterns.md) — Building navbars, menus, and sidebars
207
- - [Special Sections](./docs/special-sections.md) — @header, @footer, and sidebars
208
- - [Linking](./docs/linking.md) — Stable page references that survive reorganization
209
- - [Component Metadata](./docs/component-metadata.md) — Full meta.js schema reference
210
- - [Foundation Configuration](./docs/foundation-configuration.md) — CSS variables and custom Layout
211
- - [Site Theming](./docs/site-theming.md) — Colors, typography, and dark mode
212
- - [Internationalization](./docs/internationalization.md) — Multi-language sites
213
- - [Data Fetching](./docs/data-fetching.md) — Load external data from files or APIs
214
- - [Dynamic Routes](./docs/dynamic-routes.md) — Generate pages from data (blogs, catalogs)
215
- - [Content Collections](./docs/content-collections.md) — Manage articles, team members, and more
216
- - [Versioning](./docs/versioning.md) — Multi-version documentation
217
- - [Site Search](./docs/search.md) — Built-in full-text search
218
- - [Runtime API](./docs/runtime-api.md) — Hooks and core objects
219
-
220
201
  ## Foundations Are Portable
221
202
 
222
203
  The `foundation/` folder ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
@@ -253,249 +234,26 @@ Start with local files deployed anywhere. The same foundation works across all t
253
234
 
254
235
  ---
255
236
 
256
- ## Create a Project
257
-
258
- ```bash
259
- # pnpm (recommended)
260
- pnpm create uniweb my-site --template marketing
261
-
262
- # npm (use -- before options)
263
- npm create uniweb@latest my-site -- --template marketing
264
-
265
- # npx
266
- npx uniweb@latest create my-site --template marketing
267
- ```
268
-
269
- Alternatively, install the CLI globally:
270
-
271
- ```bash
272
- npm install -g uniweb
273
- uniweb create my-site --template marketing
274
- ```
275
-
276
- **Requirements:**
277
-
278
- - Node.js 20.19 or later
279
- - pnpm 10+ (recommended) or npm 10+
280
-
281
- Projects use Vite 7 and Tailwind CSS v4 by default.
282
-
283
- ### Setting up pnpm
284
-
285
- We recommend pnpm for dependency management (npm also works). Install pnpm via npm:
286
-
287
- ```bash
288
- npm install -g pnpm
289
- ```
290
-
291
- Or see the [official pnpm installation guide](https://pnpm.io/installation) for other options including Corepack, Homebrew, and more.
292
-
293
- ## Commands
294
-
295
- ### `create`
296
-
297
- Create a new Uniweb project. See [Create a Project](#create-a-project) for usage examples.
298
-
299
- ```bash
300
- uniweb create [project-name] [options]
301
- ```
302
-
303
- **Options:**
304
-
305
- | Option | Description |
306
- | ------------------- | ---------------------------- |
307
- | `--template <type>` | Project template (see below) |
308
-
309
- **Template Sources:**
310
-
311
- | Source | Example | Description |
312
- | ---------- | ------------------------------ | ------------------------------- |
313
- | Built-in | `single`, `multi` | Minimal starter templates |
314
- | Official | `marketing` | Feature-rich showcase templates |
315
- | npm | `@org/my-template` | Published npm packages |
316
- | GitHub | `github:user/repo` | GitHub repositories |
317
- | GitHub URL | `https://github.com/user/repo` | Full GitHub URLs |
318
-
319
- ### `build`
320
-
321
- Build the current project.
322
-
323
- ```bash
324
- uniweb build [options]
325
- ```
326
-
327
- **Options:**
328
-
329
- | Option | Description |
330
- | ------------------- | --------------------------------------------------------------------- |
331
- | `--target <type>` | Build target: `foundation` or `site` (auto-detected if not specified) |
332
- | `--prerender` | Force pre-rendering (overrides site.yml) |
333
- | `--no-prerender` | Skip pre-rendering (overrides site.yml) |
334
- | `--foundation-dir` | Path to foundation directory (for prerendering) |
335
- | `--platform <name>` | Deployment platform (e.g., `vercel`) for platform-specific output |
336
-
337
- **Examples:**
338
-
339
- ```bash
340
- # Auto-detect and build
341
- uniweb build
342
-
343
- # Explicitly build as foundation
344
- uniweb build --target foundation
345
-
346
- # Explicitly build as site
347
- uniweb build --target site
348
-
349
- # Build site with pre-rendering (SSG) - force on
350
- uniweb build --prerender
351
-
352
- # Skip pre-rendering even if enabled in site.yml
353
- uniweb build --no-prerender
354
-
355
- # Build for Vercel deployment
356
- uniweb build --platform vercel
357
- ```
358
-
359
- ### Pre-rendering (SSG)
360
-
361
- Pre-rendering generates static HTML for each page at build time. Enable it in `site.yml`:
362
-
363
- ```yaml
364
- build:
365
- prerender: true
366
- ```
367
-
368
- Or use the `--prerender` flag. This gives you:
369
-
370
- - **SEO**: Search engines see fully rendered content immediately
371
- - **Performance**: First contentful paint is instant
372
- - **Hosting**: Deploy to any static host (GitHub Pages, Netlify, S3, etc.)
373
-
374
- The pre-rendered HTML includes embedded site content. When the page loads, React hydrates the existing DOM—no flash of loading state, then full client-side interactivity.
375
-
376
- ## Built-in Templates
377
-
378
- ### Single (Default)
379
-
380
- A minimal workspace with a site and foundation as sibling packages. The recommended starting point.
381
-
382
- ```
383
- my-project/
384
- ├── package.json # Workspace root
385
- ├── pnpm-workspace.yaml
386
- ├── site/
387
- │ ├── package.json
388
- │ ├── vite.config.js
389
- │ ├── site.yml
390
- │ ├── main.js
391
- │ └── pages/
392
- └── foundation/
393
- ├── package.json
394
- ├── vite.config.js
395
- └── src/components/
396
- ```
397
-
398
- ### Multi
399
-
400
- A monorepo for foundation development or multi-site projects.
401
-
402
- ```
403
- my-workspace/
404
- ├── sites/
405
- │ ├── marketing/ # Main site or test site
406
- │ └── docs/ # Additional site
407
- └── foundations/
408
- ├── marketing/ # Primary foundation
409
- └── documentation/ # Additional foundation
410
- ```
411
-
412
- Use this when you need multiple sites sharing foundations, multiple foundations for different purposes, or test sites for foundation development.
413
-
414
- ## Official Templates
415
-
416
- Feature-rich templates with real components and sample content. **[View all demos](https://uniweb.github.io/templates/)**
417
-
418
- ### Marketing
419
-
420
- [**Live Demo**](https://uniweb.github.io/templates/marketing/) · `pnpm create uniweb my-site --template marketing`
421
-
422
- **Includes:** Hero, Features, Pricing, Testimonials, CTA, FAQ, Stats, LogoCloud, Video, Gallery, Team
423
-
424
- Perfect for product launches, SaaS websites, and business landing pages.
425
-
426
- **Tailwind v3 variant:** `--variant tailwind3`
427
-
428
- ### Academic
429
-
430
- [**Live Demo**](https://uniweb.github.io/templates/academic/) · `pnpm create uniweb my-site --template academic`
431
-
432
- **Includes:** ProfileHero, PublicationList, ResearchAreas, TeamGrid, Timeline, ContactCard, Navbar, Footer
433
-
434
- Perfect for researcher portfolios, lab websites, and academic department sites.
435
-
436
- ### Docs
437
-
438
- [**Live Demo**](https://uniweb.github.io/templates/docs/) · `pnpm create uniweb my-site --template docs`
439
-
440
- **Includes:** Header, LeftPanel, DocSection, CodeBlock, Footer
237
+ ## Guides and Documentation
441
238
 
442
- Perfect for technical documentation, guides, and API references.
239
+ [Developer Guides](./guides/developers/) Building foundations and components, converting designs, component patterns, theming contexts
443
240
 
444
- ### International
241
+ [Content Author Guides](./guides/authors/) — Writing pages in markdown, writing dynamic content, site setup, theming, recipes
445
242
 
446
- [**Live Demo**](https://uniweb.github.io/templates/international/) · `pnpm create uniweb my-site --template international`
243
+ [Reference Docs](./docs/) Full reference for all configuration, commands, and framework
447
244
 
448
- **Includes:** Hero, Features, Team, CTA, Header (with language switcher), Footer (with language links)
245
+ ### Quick Reference
449
246
 
450
- **Languages:** English (default), Spanish, French
247
+ | Topic | Guide |
248
+ | ------------------ | ------------------------------------------------------------------- |
249
+ | Content Structure | [How markdown becomes component props](./docs/content-structure.md) |
250
+ | Component Metadata | [The meta.js schema](./docs/component-metadata.md) |
251
+ | Site Configuration | [site.yml reference](./docs/site-configuration.md) |
252
+ | CLI Commands | [create, build, docs, i18n](./docs/cli-commands.md) |
253
+ | Templates | [Built-in, official, and external templates](./docs/templates.md) |
254
+ | Deployment | [Vercel, Netlify, Cloudflare, and more](./docs/deployment.md) |
451
255
 
452
- A multilingual business site demonstrating Uniweb's i18n capabilities. Includes pre-configured translation files and a complete localization workflow:
453
-
454
- ```bash
455
- uniweb i18n extract # Extract translatable strings
456
- uniweb i18n status # Check translation coverage
457
- uniweb build # Generates dist/es/, dist/fr/
458
- ```
459
-
460
- Perfect for international businesses and learning the i18n workflow.
461
-
462
- ## External Templates
463
-
464
- Use templates from npm or GitHub:
465
-
466
- ```bash
467
- # npm package
468
- pnpm create uniweb my-site --template @myorg/template-name
469
-
470
- # GitHub repository
471
- pnpm create uniweb my-site --template github:user/repo
472
-
473
- # GitHub with specific branch/tag
474
- pnpm create uniweb my-site --template github:user/repo#v1.0.0
475
- ```
476
-
477
- ## Dependency Management
478
-
479
- Each package manages its own dependencies:
480
-
481
- **`site/package.json`:**
482
-
483
- - `@uniweb/runtime`
484
- - `@my-project/foundation` (workspace link)
485
- - Vite, Tailwind (dev)
486
-
487
- **`foundation/package.json`:**
488
-
489
- - Component libraries (carousel, icons, etc.)
490
- - React as peer dependency
491
-
492
- ```bash
493
- # Add component dependency
494
- cd foundation && pnpm add embla-carousel
495
-
496
- # Site references foundation via workspace
497
- # No path gymnastics needed
498
- ```
256
+ ---
499
257
 
500
258
  ## Configuration
501
259
 
@@ -542,30 +300,7 @@ export default defineFoundationConfig({
542
300
  })
543
301
  ```
544
302
 
545
- ## Foundation Build Process
546
-
547
- When you run `uniweb build` on a foundation:
548
-
549
- 1. **Discovers** components from `src/components/*/meta.js`
550
- 2. **Generates** entry point (`_entry.generated.js`)
551
- 3. **Runs** Vite build
552
- 4. **Processes** preview images (converts to WebP)
553
- 5. **Generates** `schema.json` with full metadata
554
-
555
- **Output:**
556
-
557
- ```
558
- dist/
559
- ├── foundation.js # Bundled components
560
- ├── foundation.js.map # Source map
561
- ├── schema.json # Component metadata
562
- └── assets/
563
- ├── style.css # Compiled CSS
564
- └── [Component]/ # Preview images
565
- └── [preset].webp
566
- ```
567
-
568
- ## Workspace Configuration
303
+ ### Workspace Configuration
569
304
 
570
305
  Both templates use the same unified workspace configuration:
571
306
 
@@ -588,25 +323,6 @@ Also set in `package.json` for npm compatibility.
588
323
 
589
324
  This means no config changes when evolving from single to multi-site.
590
325
 
591
- ## Releasing a Foundation
592
-
593
- Publish your foundation to npm:
594
-
595
- ```bash
596
- cd foundation
597
- npm publish
598
- ```
599
-
600
- Or to [uniweb.app](https://uniweb.app) for use with platform-managed sites:
601
-
602
- ```bash
603
- uniweb login # First time only
604
- uniweb build
605
- uniweb publish
606
- ```
607
-
608
- Sites control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version.
609
-
610
326
  ## FAQ
611
327
 
612
328
  **How is this different from MDX?**
@@ -623,7 +339,7 @@ No. Local markdown files work great for developer-managed sites. The platform ad
623
339
 
624
340
  **Can I use an existing component library?**
625
341
 
626
- Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to exposed components—internal components use regular props.
342
+ Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to section types (components with `meta.js`) everything else uses regular React props.
627
343
 
628
344
  **Is this SEO-friendly?**
629
345
 
@@ -633,80 +349,6 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
633
349
 
634
350
  Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
635
351
 
636
- ## Common Gotchas
637
-
638
- ### Homepage Configuration
639
-
640
- Set your homepage with `index:` in `site.yml`:
641
-
642
- ```yaml
643
- # site.yml
644
- index: home # The page folder that becomes /
645
- ```
646
-
647
- The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
648
-
649
- Don't confuse this with `pages:` (which explicitly lists pages and hides any not listed).
650
-
651
- ### Content Shapes
652
-
653
- Lists and items in markdown become **objects**, not strings. A bullet list:
654
-
655
- ```markdown
656
- - First item
657
- - Second item
658
- ```
659
-
660
- Becomes:
661
-
662
- ```js
663
- content.items = [
664
- { title: 'First item', paragraphs: [], links: [], imgs: [] },
665
- { title: 'Second item', paragraphs: [], links: [], imgs: [] },
666
- ]
667
- ```
668
-
669
- Each item has the same structure as a content block. See [Content Structure](./docs/content-structure.md) for the full shape.
670
-
671
- ### Tagged Data Blocks
672
-
673
- Tagged code blocks like:
674
-
675
- ````markdown
676
- ```yaml:team-member
677
- name: Sarah Chen
678
- role: Lead Architect
679
- ```
680
- ````
681
-
682
- Are accessible via `content.data`:
683
-
684
- ```jsx
685
- function TeamMember({ content }) {
686
- const member = content.data['team-member']
687
- return (
688
- <div>
689
- {member.name} - {member.role}
690
- </div>
691
- )
692
- }
693
- ```
694
-
695
- The tag name (after the colon) becomes the key in `content.data`.
696
-
697
- ### Root vs Package Commands
698
-
699
- In a Uniweb workspace, commands run differently at different levels:
700
-
701
- | Location | Command | What it does |
702
- | ------------- | -------------- | --------------------------------------- |
703
- | Project root | `pnpm build` | Builds all packages (foundation + site) |
704
- | Project root | `pnpm dev` | Starts dev server for site |
705
- | `foundation/` | `uniweb build` | Builds just the foundation |
706
- | `site/` | `uniweb build` | Builds just the site |
707
-
708
- For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
709
-
710
352
  ## Related Packages
711
353
 
712
354
  - [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "0.5.14",
3
+ "version": "0.6.0",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -40,9 +40,9 @@
40
40
  "js-yaml": "^4.1.0",
41
41
  "prompts": "^2.4.2",
42
42
  "tar": "^7.0.0",
43
- "@uniweb/build": "0.4.9",
44
- "@uniweb/runtime": "0.5.11",
43
+ "@uniweb/build": "0.5.0",
45
44
  "@uniweb/core": "0.3.10",
46
- "@uniweb/kit": "0.4.11"
45
+ "@uniweb/kit": "0.4.11",
46
+ "@uniweb/runtime": "0.5.11"
47
47
  }
48
48
  }
@@ -1,6 +1,6 @@
1
1
  # AGENTS.md
2
2
 
3
- Guidance for AI agents working with this Uniweb project. For deeper reference, see the [developer guides](./guides/developers/) and [content author guides](./guides/authors/).
3
+ Guidance for AI agents working with this Uniweb project.
4
4
 
5
5
  ## Project Structure
6
6
 
@@ -13,8 +13,8 @@ project/
13
13
 
14
14
  Multi-site variant uses `foundations/` and `sites/` (plural) folders.
15
15
 
16
- - **Foundation**: React components. Those with `meta.js` are *exposed* — selectable by content authors via `type:` in frontmatter.
17
- - **Site**: Markdown content + configuration. Each section file references an exposed component.
16
+ - **Foundation**: React components. Those with `meta.js` are *section types* — selectable by content authors via `type:` in frontmatter. Everything else is ordinary React.
17
+ - **Site**: Markdown content + configuration. Each section file references a section type.
18
18
 
19
19
  ## Commands
20
20
 
@@ -212,7 +212,7 @@ theme: dark ← sets context-dark, all tokens resolve to dark values
212
212
 
213
213
  **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.
214
214
 
215
- **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. See the [Thinking in Contexts](./guides/developers/thinking-in-contexts.md) guide.
215
+ **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.
216
216
 
217
217
  ## Component Development
218
218
 
@@ -277,24 +277,25 @@ All defaults belong in `meta.js`, not inline in component code.
277
277
 
278
278
  **Utilities:** `cn()` (Tailwind class merge), `filterSocialLinks(links)`, `getSocialPlatform(url)`
279
279
 
280
- ### Component Organization
280
+ ### Foundation Organization
281
281
 
282
282
  ```
283
283
  foundation/src/
284
- ├── components/ # Exposed (auto-discovered via meta.js)
284
+ ├── sections/ # Section types (auto-discovered via meta.js)
285
285
  │ ├── Hero/
286
- │ │ ├── index.jsx
286
+ │ │ ├── Hero.jsx # Entry — or index.jsx, both work
287
287
  │ │ └── meta.js
288
288
  │ └── Features/
289
- │ ├── index.jsx
289
+ │ ├── Features.jsx
290
290
  │ └── meta.js
291
- ├── shared/ # Internal helpers (no meta.js, not selectable)
292
- │ ├── Button.jsx
291
+ ├── components/ # Your React components (no meta.js, not selectable)
292
+ │ ├── ui/ # shadcn-compatible primitives
293
+ │ │ └── button.jsx
293
294
  │ └── Card.jsx
294
295
  └── styles.css
295
296
  ```
296
297
 
297
- Components without `meta.js` are internal imported by exposed components but invisible to content authors.
298
+ Only folders with `meta.js` in `sections/` (or `components/` for older foundations) become section types. Everything else is ordinary React — organize however you like.
298
299
 
299
300
  ### Website and Page APIs
300
301
 
@@ -325,7 +326,7 @@ const firstBody = block.page.getFirstBodyBlockInfo()
325
326
 
326
327
  ### Custom Layouts
327
328
 
328
- Export a Layout from `foundation/src/exports.js`. Kit provides `SidebarLayout` for sidebar-based sites (docs, dashboards):
329
+ Export a Layout from `foundation/src/foundation.js`. Kit provides `SidebarLayout` for sidebar-based sites (docs, dashboards):
329
330
 
330
331
  ```jsx
331
332
  import { SidebarLayout } from '@uniweb/kit/styled'
@@ -341,9 +342,9 @@ When given a monolithic React file (AI-generated or hand-built), don't port line
341
342
  1. **Name by purpose** — `Institutions` → `Testimonial`, `WorkModes` → `FeatureColumns`. Components render a *kind* of content, not specific content.
342
343
  2. **Separate content from code** — Hardcoded strings → markdown. Layout/styling stays in JSX. Content authors edit words without touching code.
343
344
  3. **Use semantic tokens** — Replace `text-slate-900` with `text-heading`, `bg-white` with `bg-surface`. Component works in any context and any brand.
344
- 4. **Shared UI → `shared/`** — Buttons, badges, cards become internal components (no `meta.js`).
345
+ 4. **UI components → `components/`** — Buttons, badges, cards go in `src/components/` (no `meta.js` needed).
345
346
 
346
- You don't have to convert everything at once. Each section is independent — one can use hardcoded content while another reads from markdown. See the [Converting Existing Designs](./guides/developers/converting-existing-designs.md) guide for the full walkthrough.
347
+ You don't have to convert everything at once. Each section is independent — one can use hardcoded content while another reads from markdown.
347
348
 
348
349
  ## Tailwind CSS v4
349
350
 
@@ -351,7 +352,7 @@ Theme defined in `foundation/src/styles.css`:
351
352
 
352
353
  ```css
353
354
  @import "tailwindcss";
354
- @source "./components/**/*.{js,jsx}";
355
+ @source "./sections/**/*.{js,jsx}";
355
356
  @source "../node_modules/@uniweb/kit/src/**/*.jsx";
356
357
 
357
358
  @theme {
@@ -9,7 +9,7 @@
9
9
  * Identity (name, version, description) comes from package.json.
10
10
  */
11
11
 
12
- // import Layout from './components/Layout'
12
+ // import Layout from './sections/Layout'
13
13
 
14
14
  /**
15
15
  * CSS custom properties that sites can override in theme.yml
@@ -1,6 +1,6 @@
1
1
  @import "tailwindcss";
2
2
 
3
- @source "./components/**/*.{js,jsx}";
3
+ @source "./sections/**/*.{js,jsx}";
4
4
  @source "../node_modules/@uniweb/kit/src/**/*.{js,jsx}";
5
5
 
6
6
  @theme {
@@ -9,7 +9,7 @@
9
9
  * Identity (name, version, description) comes from package.json.
10
10
  */
11
11
 
12
- // import Layout from './components/Layout'
12
+ // import Layout from './sections/Layout'
13
13
 
14
14
  /**
15
15
  * CSS custom properties that sites can override in theme.yml
@@ -1,6 +1,6 @@
1
1
  @import "tailwindcss";
2
2
 
3
- @source "./components/**/*.{js,jsx}";
3
+ @source "./sections/**/*.{js,jsx}";
4
4
  @source "../node_modules/@uniweb/kit/src/**/*.{js,jsx}";
5
5
 
6
6
  @theme {
@@ -1,14 +0,0 @@
1
- // Auto-generated foundation entry point
2
- // DO NOT EDIT - This file is regenerated during build
3
-
4
- import './styles.css'
5
- import Section from './components/Section/index.jsx'
6
-
7
- export const components = { Section }
8
-
9
- export { Section }
10
-
11
- export const capabilities = null
12
-
13
- // Per-component runtime metadata (from meta.js)
14
- export const meta = {}
@@ -1,14 +0,0 @@
1
- // Auto-generated foundation entry point
2
- // DO NOT EDIT - This file is regenerated during build
3
-
4
- import './styles.css'
5
- import Section from './components/Section/index.jsx'
6
-
7
- export const components = { Section }
8
-
9
- export { Section }
10
-
11
- export const capabilities = null
12
-
13
- // Per-component runtime metadata (from meta.js)
14
- export const meta = {}