Cline rules

1---
2description: "Use when: writing or modifying React components, TypeScript, CSS, or Zustand stores in src/. Covers component patterns, import order, styling, state management, and TypeScript rules."
3globs: "src/**"
4alwaysApply: false
5---
6 
7# Frontend Rules
8 
9<!-- React / TypeScript / CSS / Zustand 规范，操作 src/ 目录时自动加载 -->
10 
11## Component Pattern
12 
13Always use functional components with hooks. NEVER use class components or HOCs.
14 
15Always place page-level components in `src/pages/`, one file per route.
16 
17Always annotate component return type as `React.JSX.Element`.
18 
19```tsx
20function MyComponent({ name }: MyComponentProps): React.JSX.Element {
21  return <div>{name}</div>;
22}
23```
24 
25NEVER export components as anonymous default exports. Always use named functions:
26 
27✅ `export default function BacklogPage(): React.JSX.Element { ... }`
28❌ `export default () => { ... }`
29 
30## Props & Types
31 
32Always declare props via `interface`. Use `type` for unions and lookup types.
33 
34```tsx
35interface TaskCardProps {
36  task: DownloadTask;
37  onPause: (id: string) => void;
38}
39```
40 
41NEVER use `any`. NEVER use `@ts-ignore` without an explanatory comment on the same line.
42 
43✅ `// @ts-expect-error: third-party type mismatch in bangumi-api-client v2026`
44❌ `// @ts-ignore`
45 
46Use type guards with `is` predicates when validating unknown shapes at runtime.
47 
48```tsx
49function isWatchEntry(v: unknown): v is WatchEntry {
50  if (typeof v !== 'object' || v === null) return false;
51  const e = v as Record<string, unknown>;
52  return typeof e.status === 'string' && typeof e.updatedAt === 'number';
53}
54```
55 
56## Imports
57 
58Always group imports in this order, separated by blank lines:
59 
601. Tauri API (`@tauri-apps/api/*`)
612. Third-party UI / libraries
623. React and React hooks
634. Internal modules (relative paths)
645. CSS imports (always last)
65 
66```tsx
67import { invoke } from '@tauri-apps/api/core';
68 
69import { Button } from 'animal-island-ui';
70 
71import { useState, useCallback } from 'react';
72 
73import { useDownload } from '../store/downloadStore';
74 
75import './MyPage.css';
76```
77 
78## CSS
79 
80Always use plain CSS. NEVER add Tailwind CSS or any CSS-in-JS library (styled-components, emotion, etc.).
81 
82### File Responsibilities
83 
84|File|Purpose|
85|----|-------|
86|`src/styles/theme.css`|The ONLY place for `--theme-*` CSS variables — colors, spacing, typography tokens. Replace this file to change themes.|
87|`src/styles/fonts.css`|`@font-face` declarations only. No colors, no layout.|
88|`src/App.css`|App shell layout (topbar, sidebar, page containers). All colors MUST reference `var(--theme-*)`.|
89|`src/pages/*.css`|Page-level component styles. Co-located with their component. All colors MUST reference `var(--theme-*)`.|
90 
91### Color Rule
92 
93NEVER write raw color values (`#xxx`, `rgb()`, `hsl()`) in any CSS file except `src/styles/theme.css`. All colors MUST use CSS variables defined in `theme.css`.
94 
95✅ `color: var(--theme-text-primary);`
96❌ `color: #4a3525;`
97 
98### Naming
99 
100Use BEM-style naming: `.block__element--modifier`
101 
102```text
103dl-card                  # Block
104dl-card__header          # Element
105dl-card--error           # Modifier
106dl-progress-bar--done    # Modifier with state
107```
108 
109## State Management
110 
111Always use Zustand for state management. NEVER introduce Redux, Jotai, MobX, or other state libraries.
112 
113Place store files in `src/store/`. Name stores in camelCase:
114 
115```text
116src/store/watchStore.ts
117src/store/downloadStore.tsx
118```
119 
120Encapsulate store logic in custom hooks when exposing to components:
121 
122```tsx
123// src/store/downloadStore.tsx
124export function useDownload() {
125  return useDownloadStore((s) => ({
126    tasks: s.tasks,
127    pauseTask: s.pauseTask,
128    // ...
129  }));
130}
131```
132 
133## Pre-existing Dependencies
134 
135NEVER suggest installing or re-installing these — already in `package.json`:
136 
137- `@tauri-apps/api`, `@tauri-apps/plugin-dialog`, `@tauri-apps/plugin-opener`
138- `animal-island-ui`, `bangumi-api-client`
139- `react`, `react-dom`, `zustand`
140 
141Always invoke Tauri commands via `invoke()` from `@tauri-apps/api/core`. NEVER use other Tauri IPC methods.
142 
143```tsx
144import { invoke } from '@tauri-apps/api/core';
145 
146void invoke('reveal_in_folder', { path: task.saveDir });
147```
148 
149## File Naming
150 
151|Type|Convention|Example|
152|----|----------|-------|
153|Page component|PascalCase|`DownloadPage.tsx`|
154|Store|camelCase|`watchStore.ts`|
155|Styles (global)|kebab-case|`theme.css`, `fonts.css`|
156|Styles (component)|PascalCase + `.css`|`DownloadPage.css`|
157 
158## Inline Styles
159 
160Inline styles are permitted only for dynamic layout values (widths, visibility). NEVER use inline styles for static design — use CSS classes instead.
161