agentleFS
build-dezineerbuild-dezineer/skills-nuxt4-tw-webapp/skills/sidenav/SKILL.md

sidenav

Skill0 starsChanged 46 days agoApache-2.0View on GitHub

Sidebar navigation for app layouts in four variants: collapsible (w-64/w-16), icon rail with Radix tooltips, floating elevated card, and always-fixed overlay. Handles role-based sections, `useRoute()` active state, mobile slide-in and NuxtLink routing. Use when building any `layout: default` app shell.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When SPEC.md describes an application with sidebar navigation (uses layout: 'default').

    line 22
  2. Distinctive:

    Read references/variants.md before writing — it carries the complete script setup and template for the chosen variant.

    line 33
  3. Very specific:

    If the spec's Image Prompts section includes an entry for the sidebar user (e.g.

    line 115
  4. Very specific:

    ALL nav links use <NuxtLink> — never <a href>

    line 192
  5. Very specific:

    Every icon imported from lucide-vue-next — validate ALL names against app/assets/lucide-icons.txt

    line 193
  6. Very specific:

    Always aria-label="Main navigation" on the <nav> element

    line 203
  7. Distinctive:

    userInfo card: when SPEC.md requires it, use hardcoded demo values (no store, no props).

    line 206

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SideNav Skill

When to use

When SPEC.md describes an application with sidebar navigation (uses layout: 'default'). Read the SPEC.md design brief and choose the variant that matches the product's personality. The output file is always app/components/layout/SidebarNav.vue, explicitly imported in app/layouts/default.vue.

Quick decision

SPEC.md describes...Jump to
"icon-only", "compact", "minimal"Icon rail
"floating", "elevated", "rounded edges"Floating
"overlay", "content-first", "no layout shift"Overlay
Everything else (dense dashboard, power users)Collapsible

Read references/variants.md before writing — it carries the complete script setup and template for the chosen variant. The props, structure and shared patterns below apply to every variant.

Four variants — choose based on SPEC.md

VariantChoose when SPEC.md describes…Desktop behaviourMobile
CollapsibleDense dashboard with many nav items, power usersw-64 ↔ w-16 toggleSlide-in overlay
Icon railMinimalist tools, maximum content areaPermanently w-16, tooltipsHamburger opens overlay
FloatingPremium / brand-forward app, elevated feelw-60 m-3 rounded-xl shadow-lgSlide-in overlay
OverlayContent-first layout, no layout shiftAlways fixed, slides over content on all viewportsSame as desktop

Sticky (when the Shell features list includes "Sticky sidebar")

When the wizard's shell features include sidebar:sticky, the sidebar stays pinned while the page content scrolls: on desktop give the panel its own scroll area instead of letting it scroll away with the page — e.g. lg:sticky lg:top-0 lg:h-screen lg:overflow-y-auto on the <aside> (with the collapse toggle pinned via shrink-0). Works with every variant in references/variants.md: a sticky Collapsible rail keeps the toggle visible and scrolls only the nav section; a sticky Overlay keeps the fixed panel; a sticky Icon rail/Floating behaves the same with their widths.


Props + emits (all variants)

interface Props {
  logoPath?: string
  logomarkPath?: string
  projectName: string
  mobileOpen: boolean
  currentRole?: string | null
}
defineEmits<{ 'update:mobileOpen': [v: boolean] }>()

Required imports (base)

import { ref, computed } from 'vue'
import { useRoute } from 'vue-router'
import { ChevronLeft, ChevronRight, X } from 'lucide-vue-next'
// + all navigation icons for the page — validate every name against lucide-icons.txt
import { cn } from '~/utils/cn'
// Icon rail variant only: add from 'radix-vue':
// import { TooltipProvider, TooltipRoot, TooltipTrigger, TooltipContent } from 'radix-vue'

Sidebar structure (top → bottom) — all variants

[Logo + collapse toggle header] shrink-0, border-b border-border
  [Logo / logomark]             left slot
  [Collapse toggle]             right slot, hidden lg:flex — Collapsible + Floating only
  [Mobile close (X)]            right slot, lg:hidden
[Nav sections]                  flex-1 overflow-y-auto py-4 space-y-0.5
  [Section label]               text-xs uppercase tracking-wider text-muted-foreground px-4 pt-3 pb-1
  [Nav items]
  [<hr class="border-border mx-4 my-2">]
  [Shared items — no v-if]      profile, settings
[userInfo card]                 shrink-0, border-t border-border — ONLY when SPEC.md requires it

userInfo card (when SPEC.md requires it)

Used when the sidebar feature list includes "User info card (avatar + email) at bottom". Place it after the nav, at the bottom of the sidebar. This is a frontend-only app — use hardcoded demo values; no store or props needed.

<!-- userInfo card -->
<div class="border-t border-border p-3 shrink-0">
  <div class="flex items-center gap-2.5 rounded-lg px-2 py-1.5 hover:bg-muted transition-colors duration-150">
    <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-primary/10 text-sm font-semibold text-primary ring-1 ring-primary/20">
      D
    </div>
    <div class="min-w-0 flex-1">
      <p class="truncate text-sm font-medium text-foreground leading-tight">Demo User</p>
      <p class="truncate text-xs text-muted-foreground leading-tight">demo@example.com</p>
    </div>
  </div>
</div>

Replace D, Demo User, and demo@example.com with values that fit the project (e.g. first initial of a persona name, a realistic name and email for the product's context).

If the spec's Image Prompts section includes an entry for the sidebar user (e.g. SidebarNav-userAvatar), swap the initials circle for a real photo instead: replace the <div class="...rounded-full...">D</div> with <img data-media-id="{id}" decoding="async" alt="" class="h-8 w-8 rounded-full shrink-0 object-cover" /> — the pipeline injects :src. Otherwise the initials circle above is the correct default — do not invent a data-media-id that isn't in the spec.

Collapsible variant: hide the text block when collapsed, show only the avatar:

<div class="border-t border-border p-3 shrink-0">
  <div :class="cn('flex items-center rounded-lg hover:bg-muted transition-colors duration-150', collapsed ? 'justify-center p-1.5' : 'gap-2.5 px-2 py-1.5')">
    <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-primary/10 text-sm font-semibold text-primary ring-1 ring-primary/20">
      D
    </div>
    <div v-if="!collapsed" class="min-w-0 flex-1">
      <p class="truncate text-sm font-medium text-foreground leading-tight">Demo User</p>
      <p class="truncate text-xs text-muted-foreground leading-tight">demo@example.com</p>
    </div>
  </div>
</div>

Active state detection

const route = useRoute()
const isActive = (to: string) => route.path === to || route.path.startsWith(to + '/')

Nav item (standard — used in Collapsible, Floating, Overlay)

<NuxtLink
  :to="item.to"
  class="flex items-center gap-3 px-3 py-2.5 rounded-lg mx-2 my-0.5
         border-l-2 transition-colors duration-150"
  :class="isActive(item.to)
    ? 'border-primary bg-primary/5 text-primary font-medium'
    : 'border-transparent text-muted-foreground hover:bg-muted hover:text-foreground'"
>
  <component :is="item.icon" class="w-4 h-4 shrink-0" />
  <span class="truncate text-sm">{{ item.label }}</span>
</NuxtLink>

Role-based sections

<!-- Single-role section: v-if required -->
<div v-if="currentRole === 'admin'">
  <p class="text-xs uppercase tracking-wider text-muted-foreground px-4 pt-3 pb-1">Admin</p>
  <NuxtLink v-for="item in adminNav" :key="item.to" ...>...</NuxtLink>
</div>

<!-- Shared section: no v-if (visible to all roles) -->
<div>
  <hr class="border-border mx-4 my-2" />
  <NuxtLink v-for="item in sharedNav" :key="item.to" ...>...</NuxtLink>
</div>

Mobile close button (inside sidebar header — all non-Icon-Rail variants)

<button
  @click="$emit('update:mobileOpen', false)"
  class="lg:hidden p-1.5 rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground transition-colors"
  aria-label="Close navigation"
>
  <X class="w-5 h-5" />
</button>

Non-negotiables

  1. Active state MUST use useRoute() — never hardcode active route conditions
  2. Active item: border-l-2 border-primary bg-primary/5 text-primary font-medium (except Icon Rail which uses bg-primary text-primary-foreground)
  3. Inactive: border-l-2 border-transparent text-muted-foreground hover:bg-muted hover:text-foreground
  4. ALL nav links use <NuxtLink> — never <a href>
  5. Every icon imported from lucide-vue-next — validate ALL names against app/assets/lucide-icons.txt
  6. Role-specific sections: v-if="currentRole === 'slug'". Shared sections: no v-if
  7. Mobile open: sidebar is fixed inset-y-0 left-0 z-30 — above the backdrop (z-20) in default.vue
  8. Sidebar background: bg-sidebar — matches the palette's sidebar token (SPEC.md → Palette → sidebar). NEVER bg-background
  9. Nav list container: flex-1 overflow-y-auto — long nav lists scroll, never overflow
  10. cn() for all class assembly — never raw string concatenation
  11. Icon Rail MUST use Radix-Vue TooltipRoot/TooltipContent for labels — never title attributes or bare spans
  12. Floating variant mobile: strip m-3 and rounded-xl when mobileOpen=true
  13. Overlay variant: the default.vue backdrop lg:hidden class MUST be removed so it shows on desktop too
  14. SFC block order: <script setup> → <template> → <style scoped>
  15. Always aria-label="Main navigation" on the <nav> element
  16. aria-label="Collapse sidebar" / "Expand sidebar" on the collapse toggle — which lives in the header row, right-aligned next to the logo, never at the bottom of the sidebar.
  17. Collapsed mode (w-16): remove border-l-2 and mx-2 from nav items. Icons must be centered via justify-center px-0. Active state becomes bg-primary/10 background highlight instead of a left border.
  18. userInfo card: when SPEC.md requires it, use hardcoded demo values (no store, no props). Use the Collapsible variant of the card when the sidebar has a collapse toggle. Place it after the nav, at the bottom of the sidebar.
  19. Logo header — logo and project name are mutually exclusive, NEVER both. If logoPath (or logomarkPath when collapsed) is present, render ONLY the image — do not also render a {{ projectName }} text label next to it. Only fall back to the {{ projectName }} text label when no logo path is provided at all. Do not implement this as two independent v-ifs (v-if="logo && collapsed" next to a separate v-if="!collapsed" text span) — that renders both at once. Use a single v-if / v-else (or v-if / v-else-if / v-else) chain so exactly one of image-or-text ever renders per state.
  20. Nav items are TOP-LEVEL routes only — never dynamic [id] routes (e.g. /projects/[id]). Detail pages are reached from within pages, never from the sidebar. Build the nav EXACTLY from the "Sidebar nav" list in SPEC.md → Creative Direction — the labels and routes there are authoritative. Never invent, paraphrase, or derive routes from the page list.

Colour & polish

  • Active item uses the shell treatment's own navActive classes — never bg-primary.
  • Render category colour as a tinted chip: bg-[hsl(var(--chart-N)/0.12)] text-[hsl(var(--chart-N))].
  • Hover and active transitions at --duration-fast.
  • success/destructive are for genuine good/bad meaning only — never decoration.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.