← Back
← Back
# CMS Widgets + Tools — FVW v8 structural analysis
**Date**: 2026-08-06
**Author**: fv-gallery-mavis (HQ id 8, session 422350917177458)
**Source repo**: `avidtech6/fv-module-gallery` (commit at 2026-08-06)
**Status**: Investigation complete, ready for plan + UI sync
## TL;DR
- 22 widgets + 5 tools in `cms-widgets/` + `cms-widgets/tools/`
- All 27 use the **same 5-file shape** (only `widget.js` vs `tool.js` differs)
- The 5-file shape is a **pruned subset** of the FVW v8 Recipe Book (2/10 items)
- 7 missing tools are referenced by widget deps but not yet implemented
- 4 widgets have no `recipe-book/recipe.md` (stubs)
- 1 widget (`theme-presets`) has no `module.json`
- The shape is consistent across widgets and tools — but it diverges from the 9-folder app shape in FVW v8 §02 and the §17.0 module-folder shape
## Widget folder structure (per FVW v8 §11 + §17)
cms-widgets/<name>/
├── module.json # constitutional document (FVW §17.1, schema fields: id, name, version, kind, content_type_binding, view, provenance, evolution, dependencies, interface, tags, tier_meta, template, icon)
├── module-meta.json # Recipe Book provenance (§11.2 item 1 of 5)
├── preview.png # visual reference (no FVW section)
├── recipe-book/
│ └── recipe.md # "what this is" doc (§11.1 item 1 of 3, Section A only — no B/C)
└── src/
└── widget.js # the code (for tools: tool.js)
## Tool folder structure (identical 5-file shape, tools/ subfolder)
cms-widgets/tools/<name>/
├── module.json
├── module-meta.json
├── preview.png
├── recipe-book/
│ └── recipe.md
└── src/
└── tool.js
## Inventory: 22 widgets
| # | Module ID | Name | Icon | Tier | v | Recipe | Notes |
|---|---|---|---|---|---|---|---|
| 1 | `M-accordion` | Accordion | ⏷ | stable | 0.5.0 | ✅ | collapsible items |
| 2 | `M-blog-post-card` | Blog Post Card | 📰 | experimental | 0.5.0 | ❌ | no recipe.md — deps: image-selector, color-palette, typography-control |
| 3 | `M-blog-post-list` | Blog Post List | ☷ | experimental | 0.5.0 | ❌ | no recipe.md — deps: image-selector, color-palette, spacing-control |
| 4 | `M-breadcrumb` | Breadcrumb | ⤴ | stable | 0.5.0 | ✅ | |
| 5 | `M-button` | Button | ⏵ | stable | 0.5.0 | ✅ | |
| 6 | `M-carousel` | Carousel | ↔ | stable | 0.5.0 | ✅ | |
| 7 | `M-contact-form` | Contact Form | ✉ | stable | 0.5.0 | ✅ | |
| 8 | `M-cta` | Call to Action | ➤ | stable | 0.5.0 | ✅ | |
| 9 | `M-cta-box` | CTA Box | ◰ | stable | 0.5.0 | ✅ | |
| 10 | `M-heading` | Heading | 🅷 | stable | 0.5.0 | ✅ | migrated from freshvibe-cms/modules/heading.js |
| 11 | `M-icon-list` | Icon List | ☰ | stable | 0.5.0 | ✅ | |
| 12 | `M-image` | Image | 🖼 | stable | 0.5.0 | ✅ | |
| 13 | `M-info-box` | Info Box | ⓘ | stable | 0.5.0 | ✅ | |
| 14 | `M-listing-grid` | Listing Grid | 🏘 | experimental | 0.5.0 | ❌ | no recipe.md — deps: image-selector, color-palette, spacing-control |
| 15 | `M-menu` | Menu | ☰ | stable | 0.5.0 | ✅ | |
| 16 | `M-paragraph` | Paragraph | ¶ | stable | 0.5.0 | ✅ | |
| 17 | `M-recipe-detail` | Recipe Detail | 🍳 | experimental | 0.5.0 | ❌ | no recipe.md — deps: image-selector, color-palette, typography-control, spacing-control |
| 18 | `M-social-icons` | Social Icons | 🔗 | stable | 0.5.0 | ✅ | |
| 19 | `M-testimonial` | Testimonial | ❝ | stable | 0.5.0 | ✅ | |
| 20 | `M-theme-presets` | Theme Presets | — | — | — | ❌ | **no module.json** — folder exists but no constitutional doc |
| 21 | `M-video` | Video | ▶ | stable | 0.5.0 | ✅ | |
| 22 | — | (one slot empty) | — | — | — | — | 22 dirs total, 21 with module.json — 1 stub theme-presets |
## Inventory: 5 tools
| # | Module ID | Name | Tier | v | Recipe | Used by | Notes |
|---|---|---|---|---|---|---|---|
| 1 | `T-color-picker` | Color Picker | stable | 0.1.0 | ✅ | gradient-picker + (implicit) many widgets | "World-class color picker. Used by every widget that needs a color field." |
| 2 | `T-favicon-picker` | Favicon Picker | experimental | 0.1.0 | ❌ | — | deps: image-selector |
| 3 | `T-font-picker` | Font Picker | experimental | 0.1.0 | ❌ | — | stub |
| 4 | `T-gradient-picker` | Gradient Picker | experimental | 0.1.0 | ❌ | — | deps: color-picker |
| 5 | `T-image-selector` | Image Selector | stable | 0.1.0 | ✅ | favicon-picker + 6 widgets | "World-class image selector. 3 tabs: Library / Upload / URL. Alt text required." |
## FVW v8 doctrine compliance — what's MISSING
The FVW v8 §11 Recipe Book requires 10 files per module. The cms-widgets/ tree has only 2 of them per entry:
| FVW v8 § | File | Present? | Notes |
|---|---|---|---|
| §11.1 — main | `recipe.md` | ✅ | Section A only (no B structural contract, no C reconstruction notes) |
| §11.1 — main | `codex.md` | ❌ | behaviour, state machine, events |
| §11.1 — main | `rules.md` | ❌ | 9 universal things instantiated per-module |
| §11.2 — provenance | `module-meta.json` | ✅ | identity, category, gallery linkage |
| §11.2 — provenance | `ingredients.json` | ❌ | provenance scaffolding |
| §11.2 — provenance | `diffs/` | ❌ | version diffs |
| §11.2 — provenance | `trace-atlas/` | ❌ | lineage, forks, shadows |
| §11.2 — provenance | `dna/` | ❌ | DNA artefacts |
| §11.9 — workflow | `plan.md` | ❌ | per-item workflow |
| §11.9 — workflow | `coverage-matrix.md` | ❌ | per-item coverage |
**Score: 2/10 files per widget/tool.** The cms-widgets/ tree is a **pruned app-shape** — not a full Recipe Book.
## 7 missing tools (referenced by widget deps, not yet implemented)
These tool IDs are referenced in widget `dependencies.tools[]` but don't exist as folders under `cms-widgets/tools/`:
| Tool | Referenced by |
|---|---|
| `text-input` | heading, button, paragraph, breadcrumb, cta, cta-box, info-box, testimonial, icon-list, menu, accordion, contact-form, carousel (13 widgets) |
| `url-input` | breadcrumb, icon-list, menu, carousel (4 widgets) |
| `select-input` | video, social-icons, contact-form (3 widgets) |
| `toggle-input` | accordion, menu (2 widgets) |
| `color-palette` | blog-post-card, blog-post-list, listing-grid, recipe-detail (4 widgets) — **NOT the same as `color-picker`** |
| `typography-control` | blog-post-card, recipe-detail (2 widgets) |
| `spacing-control` | blog-post-list, listing-grid, recipe-detail (3 widgets) |
The 4 experimental widgets (blog-post-card, blog-post-list, listing-grid, recipe-detail) all depend on missing tools — that's why they're experimental and have no recipe.md yet.
## Shape comparison — 3 module shapes coexist in fv-module-gallery
| Shape | Location | Per-entry structure | Recipe Book score |
|---|---|---|---|
| **cms-widgets/ flat** | `cms-widgets/<name>/` | 5 files (module.json + module-meta.json + preview.png + recipe-book/recipe.md + src/widget.js) | 2/10 |
| **modules/ single-folder** | `modules/<name>/` | `module.json` only (per FVW §17.0) — no Recipe Book | 0/10 |
| **bundles/ bundle** | `bundles/<b>/` | module.json + bundle-manifest.json + bundle-features.md + recipe-book/ (per §17.5.7) | 1-2/10 |
These three shapes diverge from each other. The cms-widgets/ shape is the most complete (has 2 Recipe Book items) but the modules/ shape is the most "FVW v8 §17.0 pure" (just module.json).
## The wider fv-module-gallery tree
fv-module-gallery/ (canonical repo, avidtech6/fv-module-gallery)
├── cms-widgets/ (THIS TREE)
│ ├── <22 widget dirs at this level>
│ └── tools/ (5 tool dirs)
├── modules/ (29 FVW-aligned modules, single-folder §17.0)
├── bundles/ (1 bundle: ai-bundle v2.2.1, 14 submodules)
├── apps/ (4 sovereign app-pointers: vibecoder, freshcards, vibescope, fvs)
├── gallery-pact/ (FVW v8 doctrine + schemas)
│ ├── fvw/freshvibe-way-v8/ (the FVW v8 doctrine files)
│ ├── module-meta.schema.json
│ ├── registry.schema.json
│ ├── facets.schema.json
│ ├── bundle-manifest.schema.json
│ ├── fvw-versioning-rules.md
│ ├── AI-PUBLISHING-GUIDE.md
│ ├── MIRROR-WORKFLOW.md
│ └── CLEANUP-WORKFLOW.md
├── registry.json (the published index — 29 modules + 1 bundle + 4 apps)
├── scripts/ (registry generator, mirror workflow, etc.)
├── STATUS.md
└── README.md
## What this means for plan a478 (the fv-gallery-ui sync)
The Jul 23 `registry.json` (already copied to fv-gallery-ui/public/registry.json in Phase 1.5) has 29 modules + 1 bundle + 4 apps. **It does NOT include the 22 widgets + 5 tools from cms-widgets/.** That's a third category of content that needs to land in the registry before the gallery UI is "complete".
**Two design questions** (block Phase 2):
1. **Schema**: should cms-widgets and cms-tools be:
- (a) `modules[]` entries with `_module_kind: 'gallery-original'` and `layout: 'bundle-local'`, OR
- (b) new top-level `widgets[]` and `tools[]` arrays in the registry
2. **Recipe Book completeness**: should the gallery UI show a "2/10 Recipe Book items present" badge on each widget/tool, and surface the 8 missing files as the path to FVW v8 full compliance?
## Open issues to flag to operator
1. **`theme-presets/` has no module.json** — is this a stub folder or in-progress?
2. **7 missing tools** — when do they ship? The 4 experimental widgets can't go to stable until these tools exist.
3. **2/10 Recipe Book score** — operator direction on whether to backfill the missing 8 files per widget, or accept the pruned shape as the "cms-widgets convention" (de facto FVW §17.0 lite).
4. **Three module shapes coexist** — operator direction on whether to normalise them or accept the divergence.
---
**Verbatim source**: `/tmp/fv-mg/cms-widgets/` and `/tmp/fv-mg/gallery-pact/fvw/freshvibe-way-v8/11-recipe-book.md`, `02-folder-layout.md`, `17-modules-and-tiers.md` (cloned 2026-08-06 from `avidtech6/fv-module-gallery` main).