| name | design-system |
| description | Documentation, standardization, and governance of the Vue + shadcn-vue design system. Use when creating component documentation, auditing consistency, defining naming conventions, or generating usage guides for the team.
|
Skill: Design System — Vue 3 + shadcn-vue
Recommended documentation structure
docs/
design-system/
foundations/
colors.md # Semantic tokens and palette
typography.md # Typographic scale
spacing.md # Grid and spacing
motion.md # Vue transitions and animations
components/
[ComponentName].md
patterns/
forms.md # vee-validate + Zod + shadcn-vue
navigation.md # RouterLink + NavigationMenu
feedback.md # toast (vue-sonner), Alert, Dialog
empty-states.md # Empty component patterns
loading.md # Skeleton patterns
decisions/
adr-001.md # Architecture Decision Records
Vue component documentation template
# ComponentName
## When to use
[Correct use case]
## When NOT to use
[Alternatives and when another component is better]
## Installation
\`\`\`bash
npx shadcn-vue@latest add [component-name]
\`\`\`
## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `'default' \| 'outline'` | `'default'` | Visual style |
| `class` | `string` | `''` | Additional classes via cn() |
## Emits
| Event | Payload | Description |
|---|---|---|
| `update:modelValue` | `string` | New selected value |
## Examples
### Basic usage
\`\`\`vue
<ComponentName :label="'Action'" @click="handleClick" />
\`\`\`
### With loading state
\`\`\`vue
<ComponentName :loading="isLoading" />
\`\`\`
## Accessibility
- Reka UI manages: [list]
- Project must ensure: [list]
## Pattern with vee-validate (when form)
\`\`\`vue
<FormField v-slot="{ componentField }" name="field">
<FormItem>
<FormLabel>Label</FormLabel>
<FormControl>
<ComponentName v-bind="componentField" />
</FormControl>
<FormMessage />
</FormItem>
</FormField>
\`\`\`
## Gotchas
- [gotcha specific to this component]
Required Vue patterns to document
Form pattern with vee-validate + Zod
## Form Pattern
### Stack
- vee-validate 4.x + @vee-validate/zod + Zod
### Standard structure
1. Zod schema with localized messages
2. useForm({ validationSchema: toTypedSchema(schema) })
3. FormField + FormItem + FormLabel + FormControl + FormMessage
4. Button with :disabled="form.isSubmitting.value" + Spinner
5. toast.success/error after submit
### Alternative without vee-validate
- Field + FieldGroup + FieldLabel + FieldDescription + FieldError
- For simple forms without complex validation
Empty states pattern
<Empty>
<EmptyHeader>
<EmptyTitle>No [item] found</EmptyTitle>
<EmptyDescription>
[Instruction on what the user can do]
</EmptyDescription>
</EmptyHeader>
<EmptyContent>
<Button @click="primaryAction">Primary action</Button>
</EmptyContent>
</Empty>
Loading states pattern
<!-- Rule: Skeleton must have the SAME dimensions as the actual content -->
<template>
<div v-if="isLoading" aria-live="polite" aria-busy="true">
<!-- Mirrors the structure of the actual content -->
<Skeleton class="h-[exact dimension of the element]" />
</div>
<div v-else>
<!-- Actual content -->
</div>
</template>
User feedback pattern
## Feedback hierarchy
1. **Inline** (FormMessage, FieldError) — field validation errors
2. **Toast** (vue-sonner) — confirmations and async operation errors
3. **Alert** — persistent on-page warnings, not dismissible
4. **AlertDialog** — confirmation of destructive actions (always use)
5. **Dialog** — complex actions requiring additional input
### Never:
- Toast for form errors (use FormMessage)
- Alert for temporary notifications (use Toast)
- Dialog for simple confirmations (use AlertDialog)
DS consistency checklist
Run before each release:
Conventional commits for DS
feat(ds): add UserCard component
fix(ds): correct Skeleton dimensions in OrderList
docs(ds): document Button component variants
chore(ds): update shadcn-vue components to latest
