chore: update project docs to reflect Nuxt UI as primary building blocks - #10
Conversation
|
Claude finished @toolpathguy's task in 2m 43s —— View job Review complete ✅
Verdict: request-changes (follow-up — PR is already merged). The Nuxt UI wrapping approach is sound and keeps registry purity intact. But the two changed MD Instructions now contradict the docs meant to be the source of truth, which weren't updated in sync:
Full write-up is in the summary comment and two inline comments. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - **Building blocks:** The Component Registry wraps real Nuxt UI page-building | ||
| components (UPageHero, UPageSection, UPageColumns, UPageGrid, UPageCTA, | ||
| UPageFeature, UPageCard, UButton, UCard, USeparator) as the primary placeable | ||
| blocks. A small set of custom gap-filler blocks (RichText, Image, Spacer) | ||
| covers functionality Nuxt UI doesn't provide. The compiled output uses Nuxt UI | ||
| components directly — no custom component layer. |
There was a problem hiding this comment.
Blocking (consistency): this new direction is not reflected in the two docs that are supposed to be the source of truth, so the doc set now contradicts itself.
This bullet (and the UI-framework bullet above) now say blocks are the primary Nuxt UI wrappers. But:
CLAUDE.md:20— non-negotiable convention: "Blocks (app/components/blocks/) use Tailwind only — never Nuxt UI.".kiro/steering/AI-MAP.md:119— "Block components use Tailwind utilities (portable, no Nuxt UI dependency)."
Both still assert the opposite of this PR. An implementer following CLAUDE.md's "non-negotiable conventions" would build Tailwind-only blocks and directly violate these specs. The project's own Decisions Log requires these be kept in sync:
AI-MAP.md:148— "When conventions in.kiro/steering/change,CLAUDE.mdmust be updated in sync."
Since this is a design change (relates to #2), AI-MAP.md (line 119, and "exclusively" on line 120) and CLAUDE.md (line 20) should be updated in the same change. As merged, the docs disagree.
| | type | compileAs | category | key props | children | | ||
| |------|-----------|----------|-----------|----------| | ||
| | `PageHero` | UPageHero | layout | `title(string)`, `description(text)`, `headline(string)`, `orientation(enum vertical/horizontal)` | none | | ||
| | `PageSection` | UPageSection | layout | `title(string)`, `description(text)`, `headline(string)`, `orientation(enum)`, `reverse(boolean)` | acceptsChildren | | ||
| | `PageColumns` | UPageColumns | layout | (none) | acceptsChildren | | ||
| | `PageGrid` | UPageGrid | layout | (none) | acceptsChildren | | ||
| | `PageCTA` | UPageCTA | content | `title(string)`, `description(text)`, `headline(string)` | none | | ||
| | `PageFeature` | UPageFeature | content | `title(string)`, `description(text)`, `icon(string)`, `orientation(enum)` | none | | ||
| | `PageCard` | UPageCard | content | `title(string)`, `description(text)`, `to(url)` | none | | ||
| | `Button` | UButton | content | `label(string)`, `to(url)`, `color(enum)`, `variant(enum)`, `size(enum)` | none | | ||
| | `Card` | UCard | content | (none) | acceptsChildren | | ||
| | `Separator` | USeparator | layout | `orientation(enum horizontal/vertical)`, `label(string)` | none | | ||
| | `RichText` | (custom) | content | `body(text)`, `align(enum)` | none | | ||
| | `Image` | (custom) | media | `src(image)`, `alt(string)`, `rounded(boolean)` | none | | ||
| | `Spacer` | (custom) | layout | `size(enum sm/md/lg)` | none | |
There was a problem hiding this comment.
Consistency: the new starter set orphans two AI-MAP.md statements.
-
The old
Columns/Columnblock types are gone (replaced byPageColumnswith plainacceptsChildren). ButAI-MAP.md:127still lists the convention "Columns block: only accepts Column children (enforced by registry + validation)", and the Decisions Log atAI-MAP.md:147documents theallowedChildren: ['Column']/allowedParents: ['Columns']rule. Those now reference types this table no longer defines. Not relitigating the decision — flagging that the entries it depends on were removed, so eitherPageColumnsshould carry the constraint forward or the log/convention needs a sync note. -
This table now defines 13 blocks, but
AI-MAP.md:61still says the registry task delivers "8 starter blocks", and the same "8" wording likely lives in the registry test acceptance (registry.test.ts) an implementer will write.
Neither is in this diff, so as merged the map is stale against the spec.
Review: docs update for Nuxt UI building blocksVerdict: request-changes (follow-up — PR is already merged). The design pivot itself is sound and well-motivated: wrapping real Nuxt UI page components ( The problem is scope: the two changed files now contradict the docs that are meant to be the source of truth, and those weren't updated in the same change. Blocking / follow-up
Nits
Details are in the two inline comments. Since #10 is merged, a small follow-up PR syncing Note: this is a docs-only, code-level review; the CI gate job is separate and not evaluated here. |
1 participant
Relates to #2\n\nUpdates project-level documentation to reflect the architectural decision to use Nuxt UI components as the primary building blocks in the visual builder.\n\n## Changes\n-
00-START-HERE.md: Added Nuxt UI building blocks to global conventions\n-02-component-registry.md: Replaced custom block table with Nuxt UI component table + 3 custom gap-fillers\n\n## Context\nThe original design used hand-rolled Tailwind blocks (Section, Columns, Hero, etc.). The updated approach wraps real Nuxt UI page-building components (UPageHero, UPageSection, UPageColumns, etc.) so the editor preview matches production output and compiled pages use Nuxt UI directly.