Cursor rule

1---
2description: Vue component structure, styling, derived state, modals, icons, DaisyUI/Tailwind frontend component conventions
3globs: frontend/src/**/*.{vue,scss}, frontend/src/**/*.stories.ts
4alwaysApply: false
5---
6# Frontend Component Rules
7 
8Use this rule when writing or modifying Vue components, component SCSS, or Storybook stories that need component conventions. For API call patterns see `frontend-api.mdc`; for frontend tests see `frontend-testing.mdc`.
9 
10## File Organization
11 
12- Frontend code lives in `frontend/src/`.
13- Test code lives in `frontend/tests/`.
14- Generated backend API code is in `frontend/src/generated/backend`.
15 
16## Core Technologies
17 
18- Vue 3 with TypeScript.
19- DaisyUI + Tailwind for styling: unprefixed Tailwind utilities (`flex`, `text-primary`, …) and `daisy-`-prefixed DaisyUI component classes (`daisy-btn`, `daisy-card`, …).
20- Vitest for testing with Playwright browser mode.
21- Biome for linting and formatting.
22 
23## Icons
24 
25- Prefer Lucide for normal UI icons via `@lucide/vue` (`import { IconName } from "@lucide/vue"`). Import only the icons each file needs; rely on `currentColor` so icons follow text/theme color.
26- `@lucide/vue` defaults to 24x24 via the `size` prop. Use `:size="..."` and/or Tailwind `w-*`, `h-*`, or `size-*` on icons.
27 
28## Naming Conventions
29 
30- Component files should use PascalCase, for example `NoteShow.vue` or `GlobalBar.vue`.
31- Test files should match component names with a `.spec.ts` suffix.
32- Use `.vue` for components and `.ts` for TypeScript files.
33 
34## Component Structure
35 
36```vue
37<script setup lang="ts">
38import { computed, onMounted, ref } from "vue"
39 
40const props = defineProps<{
41  value: string
42}>()
43const emit = defineEmits<{
44  (e: "update:value", value: string): void
45}>()
46 
47const loading = ref(false)
48const displayValue = computed(() => props.value.toUpperCase())
49 
50const handleClick = () => {
51  emit("update:value", "new value")
52}
53 
54onMounted(() => {
55  // ...
56})
57</script>
58 
59<template>
60  <div class="daisy-component">
61    <!-- template content -->
62  </div>
63</template>
64 
65<style scoped lang="scss">
66// scoped styles
67</style>
68```
69 
70## Modals And Dialogs
71 
72- Use `Modal` from `@/components/commons/Modal.vue` for modal overlays. It wraps a native `<dialog>` teleported to `body` and centralizes stacking, ESC, backdrop click, and route-change close. The dim background is the native `::backdrop` pseudo-element.
73- Put panel content in `#body`, optionally `#header`. Listen for `@close_request` to hide the modal, such as parent `v-if` or clearing model state. The overlay X is optional via `showCloseButton` on `Modal`.
74- Use `v-if` on `Modal` when the dialog opens, or keep `Modal` mounted and drive visibility from props; wire `close_request` and cancel buttons to the same close handler.
75- Layout variants: `alignTop` pins the panel to the top of the viewport, `sidebar="left" | "right"` renders a full-height side panel. Use `isPopup` for nested popups via `usePopups` so they do not participate in the ESC modal stack.
76- In tests, the dialog renders inside `document.body`. Query the DOM via `document.querySelector("dialog")`, `.close-button`, `.modal-container`, `.modal-sidebar`, or `.modal-mask`, not the dialog's internal layout wrapper.
77 
78## Derived State
79 
80- Avoid cache state in refs. Do not keep a separate `ref` or `reactive` field that mirrors props, other refs, or store data and that you update in watchers, `onUpdated`, or event handlers to stay in sync.
81- Prefer `computed` whenever a value is fully determined by reactive inputs. Computed values stay correct when dependencies change and avoid manual sync.
82- Use `ref` / `reactive` for real mutable state: user input, explicit UI toggles, or data you own and mutate.
83 
84## CSS And Styling
85 
86- Use DaisyUI classes with the `daisy-` prefix, for example `daisy-btn` or `daisy-alert`.
87- Avoid Bootstrap classes.
88- Choose theme-neutral colors.
89- Use scoped styles with SCSS.
90- Follow mobile-first responsive design.
91