mirror of
https://github.com/langgenius/dify.git
synced 2026-07-21 18:58:35 +08:00
98d9b11f7b
Co-authored-by: Joel <iamjoel007@gmail.com> Co-authored-by: 林玮 (Jade Lin) <linw1995@icloud.com> Co-authored-by: 盐粒 Yanli <mail@yanli.one> Co-authored-by: Asuka Minato <i@asukaminato.eu.org> Co-authored-by: Jashwanth Reddy Gummula <gmrnlg1971@gmail.com> Co-authored-by: WH-2099 <wh2099@pm.me> Co-authored-by: 非法操作 <hjlarry@163.com> Co-authored-by: wangxiaolei <fatelei@gmail.com> Co-authored-by: FFXN <31929997+FFXN@users.noreply.github.com> Co-authored-by: Yansong Zhang <916125788@qq.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
## Frontend Workflow
|
|
|
|
- Refer to the `./docs/test.md` and `./docs/lint.md` for detailed frontend workflow instructions.
|
|
- For frontend coding tasks, also apply the repo-local `how-to-write-component` skill when the change touches React components, state ownership, routing, styling, or Tailwind classes.
|
|
- For frontend reviews, use the repo-local `frontend-code-review` skill as the canonical checklist.
|
|
|
|
## i18n
|
|
|
|
- User-facing strings must use `web/i18n/en-US/` keys instead of hardcoded text.
|
|
- When adding or renaming an i18n key, update all supported locale files with correct localized values. Do not leave fallback English in non-English locales unless the repo already intentionally does so for that exact key.
|
|
|
|
## Backend API Calls
|
|
|
|
- For new backend calls, and for surfaces already migrated to generated contracts, use `consoleQuery` / `consoleClient` from `@/service/client`. Do not add handwritten REST helpers, handwritten API types, mock-backed app state, or direct edits to generated contract files.
|
|
|
|
## Overlay Components (Mandatory)
|
|
|
|
- `../packages/dify-ui/README.md` is the permanent contract for overlay primitives, portals, root `isolation: isolate`, and the `z-50` / `z-60` layering.
|
|
- `./docs/overlay.md` records the current web overlay best practices.
|
|
- In new or modified code, use only overlay primitives from `@langgenius/dify-ui/*`.
|
|
- Do not introduce overlay imports from `@/app/components/base/*`; when touching existing callers, migrate them.
|
|
|
|
## UI Components
|
|
|
|
- Use `@langgenius/dify-ui/*` primitives and primitive data/CSS selectors first. Add call-site Tailwind only for real design deltas, avoid arbitrary values when token utilities exist, and keep focus rings visible without making inert layout regions focusable.
|
|
|
|
## SVG Icons (Mandatory)
|
|
|
|
- New custom SVG icons must be added under `../packages/iconify-collections/assets/...`.
|
|
- Run `pnpm --filter @dify/iconify-collections generate` and consume generated icons with Tailwind `i-custom-*` classes.
|
|
- Restart the web dev server after regenerating icons because Tailwind loads the custom icon collection at startup.
|
|
- Do not add new generated React icon components or JSON files under `app/components/base/icons/src/...`.
|
|
- See `../packages/iconify-collections/README.md` for the full workflow.
|
|
|
|
## Design Token Mapping
|
|
|
|
- When translating Figma designs to code, read `../packages/dify-ui/AGENTS.md` for the Figma `--radius/*` token to Tailwind `rounded-*` class mapping. The two scales are offset by one step.
|
|
|
|
## Client State Management
|
|
|
|
- Use local component state for state owned by one component.
|
|
- Use feature-level Jotai atoms for simple client state shared across components in the same feature, especially when components need a shared source of truth, derived values, or shared actions.
|
|
- Use existing feature stores for complex or high-frequency interaction state such as workflow canvas, drag, resize, and panel runtime state.
|
|
- For shared low-frequency, client-only persistence such as user preferences, dismissed notices, and UI defaults, use feature-owned storage modules built with `createLocalStorageState`.
|
|
- For high-frequency interactions, update the feature state during interaction and persist storage only on commit or settled updates.
|
|
- Keep storage keys and raw/custom formats in the owner module; callers should import the named storage hooks instead of scattering direct storage access.
|
|
- Do not add ad hoc global event listeners for shared state. Prefer atoms, existing stores, or a shared subscription hook so listeners are centralized and deduplicated.
|
|
|
|
## Automated Test Generation
|
|
|
|
- Use `./docs/test.md` as the canonical instruction set for generating frontend automated tests.
|
|
- When proposing or saving tests, re-read that document and follow every requirement.
|
|
- All frontend tests MUST also comply with the `frontend-testing` skill. Treat the skill as a mandatory constraint, not optional guidance.
|