# Nuxt shadcn Demo

## Workflow

- No headless-browser verification after UI changes - the user tests manually. Only ask/debug after repeated failures. Syntax checks are fine; run `npm run build` only if the user explicitly asks for it.
- Dev server: `npm run dev` (port 3000). The user usually runs it themselves - do not start it blindly, check whether it is already running first.
- DB: MariaDB via `docker-compose.yml` (container `nuxt-shadcn-demo-db`), URL in `DATABASE_URL`. Migrations: `npm run db:generate` (schema → SQL), `npm run db:migrate` (apply; also runs automatically via Nitro plugin in dev mode).
- No Git commits on your own - only commit when the user explicitly instructs it.

## Conventions

- Vue 3 `<script setup lang="ts">`, Composition API, shadcn-vue components under `app/components/ui/`.
- Theme colors via semantic tokens (`bg-primary`, `border-primary`, …), never hardcode them. Themes are maintained in `app/assets/css/tailwind.css`, `app/composables/useTheme.ts` and `app/components/ThemeSelector.vue` - `--primary` is the signature color, `--accent` the contrast; `neo` has `--radius: 0` (square), so use `rounded-md`/`rounded-sm` instead of `rounded-2xl`/`rounded-xl` there.
- Tailwind: `size-*` instead of `w-* h-*`, `gap-*` instead of `space-x/y-*`, `cn()` for conditional classes.
- Live updates run through `server/routes/_ws.ts` + `broadcastToAll`; client-side handling in `app/plugins/notifications.client.ts`.
- Comment reactions: `useCommentReactions` (state map per comment ID). Emoji selection via `UnicodeEmojiPicker.vue` (emoji-picker-element web component, all Unicode emojis with search; local data from `emoji-picker-element-data`, UI texts from `emoji-picker-element/i18n`).
- Internal terminology: **Emoji** = Unicode reactions (`UnicodeEmojiPicker.vue`, `CommentReactionPicker.vue`, `emoji` columns in the reaction tables); **Sticker** = uploaded media (`StickerPicker.vue`, `StickerMedia.vue`, `useStickers`, `shared/utils/stickers.ts`, table `stickers`, `/api/stickers`, `/uploads/stickers`, permission `sticker.standard`). Shortcode rendering `:name:` via `stickerParts()`.
- Thread notifications: `threadSubscriptions` stores subscriptions and explicit opt-outs. Creating, commenting, favoriting and post reactions call `ensureThreadSubscription()`; a disabled subscription must not be reactivated by this. `notifyComment()` notifies active subscribers and mentioned users, respects opt-outs even for mentions and groups notifications per user/thread.
- Direct messages: table `direct_messages` (sender/recipient/content/read_at). API under `/api/messages` (list, history with `?before=`, send, `read`). Live via `pushToUser` with `dm` event (message + sender/recipient user info) and `dm-read` read receipt. Client state in `useDirectMessages` - `openPartnerId` marks the open conversation; `liveMessageHandler`/`liveReadHandler`/`liveReactionHandler` are module singletons registered by the messages page. DM reactions: table `direct_message_reactions` (message/user/emoji, `seen_at`), toggle under `/api/messages/reactions/:messageId`, WS event `dm-reaction` to both participants. Unseen foreign reactions count like unread messages for the unread badge; `read` sets `seen_at` as well. DM attachments: `attachments` JSON column in `CommentAttachment` shape (`meta.voice` = voice message); `POST /api/messages/:userId` accepts multipart with `files`/`voice` fields like the comment form, rendered via `CommentAttachments`.
- Permissions: catalog in `shared/utils/permissions.ts` (`PERMISSIONS`), server check via `requirePermission(event, key)` in `server/utils/auth.ts` - the `admin` role is an implicit wildcard. Client-side `can(key)` from `useAuth`. Seeding via `seedPermissions()` in the migration plugin/script.
- i18n: `@nuxtjs/i18n`, locales `de` (default) + `en` in `i18n/locales/*.json` - always keep both files with identical key structure. All UI strings via `$t()`/`t()`, never hardcoded. `strategy: 'no_prefix'`, locale cookie `i18n_locale`. Permission labels in admin via `admin.perms.<key>`; effect/theme names remain proper nouns.

## UI & Design System Rules (Anti-Vibe-Coding)

When auditing, refactoring, or building UI, strictly apply these design rules:

### 1. Visual Hierarchy & Card Fatigue

- **Eliminate "Card-in-Card" nesting**: Never place a Card inside another Card. Use whitespace, divider lines (`<Separator />`), or subtle background shifts instead of borders.
- **Icon Restraint**: Do NOT add icons to every button, table header, or card title. Icons should only exist when they materially aid scanning (max 1 icon per actionable group).
- **Border Reduction**: If a border doesn't separate distinct functional contexts, remove it. Favor spacing (`gap`, `space-y`) over border boxes.

### 2. Spacing & Rhythm (8pt Grid)

- Stick strictly to a 4-step spacing hierarchy:
  - Tight (inline/tags): `gap-1.5` to `gap-2`
  - Grouped elements (form fields, lists): `space-y-3` / `gap-3`
  - Section spacing: `space-y-6` / `gap-6`
  - Layout/Page level: `py-8` to `py-12`, max container `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8`
- Do not mix random paddings (e.g. `p-5`, `p-7`). Stick to `p-4` (compact) or `p-6` (standard).

### 3. Typography & Contrast

- Contrast comes from weight and color, not just font size.
- Secondary text must consistently use `text-muted-foreground text-xs` or `text-sm`.
- Main headers: Use `tracking-tight font-semibold` instead of generic `font-bold`.
- Avoid 5 different font sizes on a single screen. Max 3 sizes per view (e.g. Title `text-xl`, Body `text-sm`, Metadata `text-xs`).

### 4. Nuxt 4 & Shadcn Vue Specifics

- Always leverage semantic Shadcn primitives (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`) properly—never inline custom headers inside `CardContent`.
- Keep templates clean: Move complex inline Tailwind classes into reusable Nuxt components or tailwind-variants (`cva`) if reused.
- Ensure proper empty states (`EmptyState` pattern) and loading skeletons instead of blank spaces.