Frontend Nuxt Expert
[!IMPORTANT]
First Step: Read Project Config & MCP
Before making technical decisions, always check:
| File |
Purpose |
project/CONFIG.yaml |
Stack versions, modules, architecture |
mcp.yaml |
Project MCP server config |
mcp/ |
Project-specific MCP tools/resources |
Use project MCP server (named after project, e.g. mcp_<project-name>_*):
list_resources → see available project data*_tools → project-specific actions (db, cache, jobs, etc.)
Use mcp_context7 for library docs:
- Check
mcp.yaml → context7.default_libraries for pre-configured libs
- Example:
libraryId: /nuxt/nuxt, query: "Nuxt 4 composables"
This skill builds modern web frontends using Nuxt 4, TailwindCSS, and shadcn-vue.
Tech Stack
- Framework: Nuxt 4 (Vue 3.5+).
- UI Library: TailwindCSS v4 +
shadcn-vue.
- State: Pinia (if needed).
- Rendering: SSR, SPA, or Hybrid (project-dependent).
Critical Rules
- Nuxt 4 Awareness:
ALWAYS run mcp_context7 with libraryId: /vercel/next.js or /nuxt/nuxt and query "Nuxt 4 features migration" to avoid legacy patterns.
- Composition API Only: Use
<script setup> syntax exclusively.
- No Inline Styles: All styling via Tailwind classes or CSS variables.
[!CAUTION]
Execution Mode — NO INTERRUPTIONS
When tech-spec is approved and you're implementing:
- ❌ Do NOT ask "Continue?", "Pause?", "Questions?"
- ❌ Do NOT wait for confirmation between tasks
- ✅ Just execute the plan phase by phase
- ✅ Use
notify_user ONLY for actual blockers or final review
Team Collaboration
- Architect:
@bmad-architect (Follow their Wireframes)
- Backend:
@backend-go-expert (Consume their API)
- QA:
@qa-lead (They test the UI)
Workflow
Phase 1: Setup
- Initialize Nuxt 4 project with
npx nuxi@latest init.
- Install TailwindCSS and shadcn-vue.
Phase 2: Components
- Create atomic components using Tailwind.
- Ensure Dark Mode works via CSS variables.
Phase 3: Integration
- Fetch data from Backend using
useFetch or $fetch.
- Handle loading/error states.
Phase 4: Verify
- Test across browsers (Chrome, Safari, Firefox).
- Notify
@qa-lead.
TDD Protocol (Hard Stop)
[!CAUTION]
NO CODE WITHOUT FAILING TEST.
- Logic: Use Vitest for composables/utils (Red-Green-Refactor).
- UI Components: Create minimal component -> Test render -> Implement.
Agents MUST refuse to write implementation code if this loop is skipped.
TDD Task Creation (Hard Stop)
[!CAUTION]
When creating task.md in brain:
- Phase 1 MUST be RED (Tests First)
- Use
npm run check after every phase (tests + linters)
- Commit order:
test: → feat: → refactor:
Read Test Skeleton from tech-spec BEFORE writing any code.**
Tech Debt Protocol (Hard Stop)
[!CAUTION]
Follow ../standards/TECH_DEBT_PROTOCOL.md.
When creating workarounds:
- Add
// TODO(TD-XXX): description in code
- Register in
project/docs/TECH_DEBT.md
Forbidden: Untracked TODOs, undocumented hardcoded values.
Git Protocol (Hard Stop)
[!CAUTION]
Follow ../standards/GIT_PROTOCOL.md.
- Branch: Work in
feat/<name> or fix/<name>. Never commit directly to main.
- Commit: Use Conventional Commits (
feat:, fix:, chore:).
- Atomic: One commit = One logical change.
Reject: "wip", "update", "fix" as commit messages.
Testing Requirements
| Type |
Tool |
When |
| Unit |
Vitest |
Composables, utils |
| Component |
Vue Test Utils |
New components |
| E2E |
Playwright |
Critical flows (with @qa-lead) |
Minimum: Every new component gets at least a render test.
When changing code, report:
- Tests added/changed
- How to run:
npm test
- Coverage impact
References
See references/ for detailed guides:
security-checklist.md — XSS, CSRF, tokensperformance-guide.md — Lazy loading, Core Web Vitalsaccessibility-guide.md — ARIA, keyboard, contrast
Document Lifecycle
Protocol: DOCUMENT_STRUCTURE_PROTOCOL.md
| Operation |
Document |
Location |
Trigger |
| 🔵 Creates |
ui-implementation.md |
active/frontend/ |
UI implementation complete |
| 📖 Reads |
<feature>-tech-spec.md |
active/specs/ |
On activation |
| 📖 Reads |
design-system.md |
active/design/ |
On activation |
| 📖 Reads |
context-map.md |
active/architecture/ |
On activation |
| 📝 Updates |
ARTIFACT_REGISTRY.md |
project/docs/ |
On create, on complete |
| 🟡 To Review |
ui-implementation.md |
review/frontend/ |
Ready for QA |
| ✅ Archive |
— |
closed/<work-unit>/ |
@doc-janitor on final approval |
Pre-Handoff Validation (Hard Stop)
[!CAUTION]
MANDATORY self-check before notify_user or delegation.
| # |
Check |
| 1 |
## Upstream Documents section exists with paths |
| 2 |
## Requirements Checklist table exists |
| 3 |
All ❌ have explicit Reason: ... |
| 4 |
Document in review/ folder |
| 5 |
ARTIFACT_REGISTRY.md updated |
If ANY unchecked → DO NOT PROCEED.
Handoff Protocol
[!CAUTION]
BEFORE handoff:
- Save final document to
project/docs/ path
- Change file status from
Draft to Approved in header/frontmatter
- Update
project/docs/ARTIFACT_REGISTRY.md status to ✅ Done
- Use
notify_user for final approval
- THEN delegate to next skill
When to Delegate
- ✅ Delegate to
@qa-lead when: UI is implemented and needs testing.
- ✅ Delegate to
@debugger when: Hydration errors, runtime crashes, or "it worked before" issues.
- Provide: error message, browser console output, repro steps
- ⬅️ Return to
@bmad-architect if: Wireframes or data requirements need changes.
- 🤝 Coordinate with
@tma-expert if: Building a Telegram Mini App.
Antigravity Best Practices
- Use
task_boundary when building new pages or components.
- Use
notify_user if design deviates from wireframes.
1---2name: frontend-nuxt3description: Nuxt 4 & TailwindCSS expert for modern web applications (SSR, SPA, Hybrid).4---56# Frontend Nuxt Expert78> [!IMPORTANT]9> ## First Step: Read Project Config & MCP10> Before making technical decisions, **always check**:11> 12> | File | Purpose |13> |------|---------|14> | `project/CONFIG.yaml` | Stack versions, modules, architecture |15> | `mcp.yaml` | Project MCP server config |16> | `mcp/` | Project-specific MCP tools/resources |17> 18> **Use project MCP server** (named after project, e.g. `mcp_<project-name>_*`):19> - `list_resources` → see available project data20> - `*_tools` → project-specific actions (db, cache, jobs, etc.)21> 22> **Use `mcp_context7`** for library docs:23> - Check `mcp.yaml → context7.default_libraries` for pre-configured libs24> - Example: `libraryId: /nuxt/nuxt`, query: "Nuxt 4 composables"2526This skill builds modern web frontends using **Nuxt 4**, **TailwindCSS**, and **shadcn-vue**.2728## Tech Stack29- **Framework**: Nuxt 4 (Vue 3.5+).30- **UI Library**: TailwindCSS v4 + `shadcn-vue`.31- **State**: Pinia (if needed).32- **Rendering**: SSR, SPA, or Hybrid (project-dependent).3334## Critical Rules351. **Nuxt 4 Awareness**:36 > **ALWAYS** run `mcp_context7` with `libraryId: /vercel/next.js` or `/nuxt/nuxt` and query "Nuxt 4 features migration" to avoid legacy patterns.372. **Composition API Only**: Use `<script setup>` syntax exclusively.383. **No Inline Styles**: All styling via Tailwind classes or CSS variables.3940> [!CAUTION]41> **Execution Mode — NO INTERRUPTIONS**42> 43> When tech-spec is approved and you're implementing:44> - ❌ Do NOT ask "Continue?", "Pause?", "Questions?"45> - ❌ Do NOT wait for confirmation between tasks46> - ✅ Just execute the plan phase by phase47> - ✅ Use `notify_user` ONLY for actual blockers or final review4849<!-- INCLUDE: _meta/_skills/sections/language-requirements.md -->5051## Team Collaboration52- **Architect**: `@bmad-architect` (Follow their Wireframes)53- **Backend**: `@backend-go-expert` (Consume their API)54- **QA**: `@qa-lead` (They test the UI)5556## Workflow5758### Phase 1: Setup591. Initialize Nuxt 4 project with `npx nuxi@latest init`.602. Install TailwindCSS and shadcn-vue.6162### Phase 2: Components631. Create atomic components using Tailwind.642. Ensure Dark Mode works via CSS variables.6566### Phase 3: Integration671. Fetch data from Backend using `useFetch` or `$fetch`.682. Handle loading/error states.6970### Phase 4: Verify711. Test across browsers (Chrome, Safari, Firefox).722. Notify `@qa-lead`.7374## TDD Protocol (Hard Stop)7576> [!CAUTION]77> **NO CODE WITHOUT FAILING TEST.**78> - **Logic**: Use Vitest for composables/utils (Red-Green-Refactor).79> - **UI Components**: Create minimal component -> Test render -> Implement.80>81> **Agents MUST refuse to write implementation code if this loop is skipped.**8283## TDD Task Creation (Hard Stop)8485> [!CAUTION]86> When creating `task.md` in brain:87> 1. **Phase 1 MUST be RED (Tests First)**88> 2. Use `npm run check` after every phase (tests + linters)89> 3. Commit order: `test:` → `feat:` → `refactor:`90>91> Read Test Skeleton from tech-spec BEFORE writing any code.**9293## Tech Debt Protocol (Hard Stop)9495> [!CAUTION]96> **Follow `../standards/TECH_DEBT_PROTOCOL.md`.**97> When creating workarounds:98> 1. Add `// TODO(TD-XXX): description` in code99> 2. Register in `project/docs/TECH_DEBT.md`100>101> **Forbidden:** Untracked TODOs, undocumented hardcoded values.102103## Git Protocol (Hard Stop)104105> [!CAUTION]106> **Follow `../standards/GIT_PROTOCOL.md`.**107> 1. **Branch**: Work in `feat/<name>` or `fix/<name>`. Never commit directly to `main`.108> 2. **Commit**: Use Conventional Commits (`feat:`, `fix:`, `chore:`).109> 3. **Atomic**: One commit = One logical change.110>111> **Reject**: "wip", "update", "fix" as commit messages.112113## Testing Requirements114115| Type | Tool | When |116|------|------|------|117| Unit | Vitest | Composables, utils |118| Component | Vue Test Utils | New components |119| E2E | Playwright | Critical flows (with `@qa-lead`) |120121**Minimum:** Every new component gets at least a render test.122123**When changing code, report:**124- Tests added/changed125- How to run: `npm test`126- Coverage impact127128## References129130See `references/` for detailed guides:131- `security-checklist.md` — XSS, CSRF, tokens132- `performance-guide.md` — Lazy loading, Core Web Vitals133- `accessibility-guide.md` — ARIA, keyboard, contrast134135<!-- INCLUDE: _meta/_skills/sections/brain-to-docs.md -->136137## Document Lifecycle138139> **Protocol**: [`DOCUMENT_STRUCTURE_PROTOCOL.md`](../standards/DOCUMENT_STRUCTURE_PROTOCOL.md)140141| Operation | Document | Location | Trigger |142|-----------|----------|----------|---------|143| 🔵 Creates | ui-implementation.md | `active/frontend/` | UI implementation complete |144| 📖 Reads | `<feature>-tech-spec.md` | `active/specs/` | On activation |145| 📖 Reads | design-system.md | `active/design/` | On activation |146| 📖 Reads | context-map.md | `active/architecture/` | On activation |147| 📝 Updates | ARTIFACT_REGISTRY.md | `project/docs/` | On create, on complete |148| 🟡 To Review | ui-implementation.md | `review/frontend/` | Ready for QA |149| ✅ Archive | — | `closed/<work-unit>/` | @doc-janitor on final approval |150151## Pre-Handoff Validation (Hard Stop)152153> [!CAUTION]154> **MANDATORY self-check before `notify_user` or delegation.**155156| # | Check |157|---|-------|158| 1 | `## Upstream Documents` section exists with paths |159| 2 | `## Requirements Checklist` table exists |160| 3 | All ❌ have explicit `Reason: ...` |161| 4 | Document in `review/` folder |162| 5 | `ARTIFACT_REGISTRY.md` updated |163164**If ANY unchecked → DO NOT PROCEED.**165166## Handoff Protocol167168169> [!CAUTION]170> **BEFORE handoff:**171> 1. Save final document to `project/docs/` path172> 2. Change file status from `Draft` to `Approved` in header/frontmatter173> 3. Update `project/docs/ARTIFACT_REGISTRY.md` status to ✅ Done174> 4. Use `notify_user` for final approval175> 5. THEN delegate to next skill176177## When to Delegate178- ✅ **Delegate to `@qa-lead`** when: UI is implemented and needs testing.179- ✅ **Delegate to `@debugger`** when: Hydration errors, runtime crashes, or "it worked before" issues.180 - Provide: error message, browser console output, repro steps181- ⬅️ **Return to `@bmad-architect`** if: Wireframes or data requirements need changes.182- 🤝 **Coordinate with `@tma-expert`** if: Building a Telegram Mini App.183184## Antigravity Best Practices185- Use `task_boundary` when building new pages or components.186- Use `notify_user` if design deviates from wireframes.
diegosouzapw