1# Code Quality Rules
2 
3## Scope Control
4 
5Flag changes that expand beyond the requested feature or review scope:
6 
7- Repo-wide cleanup mixed into a targeted fix.
8- Compatibility exports, aliases, shims, or wrapper layers added without an explicit migration requirement.
9- Shared abstractions created before there is stable cross-feature reuse.
10- Business components moved into generic shared locations without a clear ownership boundary.
11 
12## TypeScript
13 
14Flag:
15 
16- `any` or broad `Record<string, any>` where generated/API types or local domain types exist.
17- Re-declared API shapes instead of importing generated or returned types.
18- Weak route/query param typing that leaks `string | string[] | undefined` deep into components.
19- Runtime wrappers added only to satisfy TypeScript when a narrower type boundary would preserve the existing runtime shape.
20 
21Prefer:
22 
23- Explicit domain names that match the API contract.
24- Type narrowing at route/API boundaries.
25- Small conversion helpers colocated with the component that needs them.
26 
27## Styling
28 
29Flag:
30 
31- New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need.
32- Component-level plain `.css` files or component CSS imported through `globals.css`; use scoped `*.module.css` only when Tailwind and component variants cannot express the style.
33- Generic color utilities where Dify semantic tokens exist.
34- Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist.
35- `!` important modifiers or important CSS overrides without a narrow, documented reason.
36- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes.
37- JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors.
38- Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides.
39- Arbitrary z-index or one-off layering fixes on overlays.
40 
41Use:
42 
43- `cn(...)` from the local package or utility already used by the file.
44- Dify semantic tokens and Tailwind v4 utilities.
45- Existing component variants before one-off class forks.
46- Primitive selectors such as `data-disabled:*`, `data-checked:*`, `data-highlighted:*`, `group-data-*`, `peer-data-*`, and `has-[:focus-visible]` before adding React state or boolean props solely for styling.
47- Component-level variants, semantic tokens, and normal cascade/order before `!` overrides. Use `!` only for a contained compatibility override that cannot be expressed through the component API or local selector structure.
48 
49## Imports
50 
51Flag:
52 
53- Barrel imports from `@langgenius/dify-ui`; consumers must use subpath exports.
54- New overlay imports from legacy `@/app/components/base/modal`, `dialog`, or `drawer`.
55- Cross-feature imports that bypass explicit top-level public files.
56- Direct imports from generated/internal implementation files when a feature contract already exposes the intended surface.
57 
58## Copy And i18n
59 
60Flag:
61 
62- User-facing hardcoded strings in `web/`.
63- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace.
64- Translation namespace drift, especially using unrelated module namespaces for local feature copy.
65- Generic button labels like `Continue` where the action is specific.
66- Error messages that state only the failure and not the next step.
67 
68Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file <name>` should pass for any touched translation namespace.
69