From 789698cddd2077b99eff14ea8bea3283ec9edeab Mon Sep 17 00:00:00 2001 From: Jingyi Date: Mon, 8 Jun 2026 20:21:29 -0700 Subject: [PATCH] docs: merge frontend agent guidance (#37121) --- .agents/skills/frontend-code-review/SKILL.md | 1 + .../references/code-quality.md | 6 ++-- .../references/component-architecture.md | 4 +++ .../references/dify-ui.md | 11 +++++++ .agents/skills/karpathy-guidelines/SKILL.md | 33 +++++++++++++++++++ .claude/skills/karpathy-guidelines | 1 + web/AGENTS.md | 15 +++++++++ 7 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 .agents/skills/karpathy-guidelines/SKILL.md create mode 120000 .claude/skills/karpathy-guidelines diff --git a/.agents/skills/frontend-code-review/SKILL.md b/.agents/skills/frontend-code-review/SKILL.md index 6915624c0f..85a8b1d9ef 100644 --- a/.agents/skills/frontend-code-review/SKILL.md +++ b/.agents/skills/frontend-code-review/SKILL.md @@ -25,6 +25,7 @@ Before reviewing, read the relevant local contracts: - `packages/dify-ui/README.md` and `packages/dify-ui/AGENTS.md` when code uses or changes `@langgenius/dify-ui/*`. - `web/docs/overlay.md` when reviewing dialogs, drawers, popovers, tooltips, menus, selects, comboboxes, or other floating UI. - `web/docs/test.md` and the `frontend-testing` skill when reviewing tests or testability. +- `karpathy-guidelines` for scope control and focused, verifiable changes. - `how-to-write-component` when reviewing React component structure, ownership, effects, query/mutation contracts, or memoization. For any UI, UX, or accessibility review, fetch the latest Web Interface Guidelines before finalizing findings. Treat them as a required baseline, not the complete source of accessibility truth: diff --git a/.agents/skills/frontend-code-review/references/code-quality.md b/.agents/skills/frontend-code-review/references/code-quality.md index 06341cc1f3..9e014a9322 100644 --- a/.agents/skills/frontend-code-review/references/code-quality.md +++ b/.agents/skills/frontend-code-review/references/code-quality.md @@ -29,10 +29,11 @@ Prefer: Flag: - New CSS modules or ad hoc CSS when Tailwind utilities and Dify tokens cover the need. +- 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. - Generic color utilities where Dify semantic tokens exist. - Hardcoded magic class values for colors, spacing, radius, shadow, z-index, or typography when Dify tokens, component variants, or documented radius mappings exist. - `!` important modifiers or important CSS overrides without a narrow, documented reason. -- Manual string concatenation for conditional classes. +- Manual string concatenation, template strings, array `.join(' ')`, or custom ternaries for conditional or multi-line classes. - JS conditional class branches for primitive visual states already exposed by Dify UI/Base UI `data-*` selectors. - Incoming `className` placed before default classes in `cn(...)`, preventing call-site overrides. - Arbitrary z-index or one-off layering fixes on overlays. @@ -59,8 +60,9 @@ Flag: Flag: - User-facing hardcoded strings in `web/`. +- Added or renamed i18n keys that are not present in every supported locale file for the touched namespace. - Translation namespace drift, especially using unrelated module namespaces for local feature copy. - Generic button labels like `Continue` where the action is specific. - Error messages that state only the failure and not the next step. -Use feature-local translation keys by default. Alias only when crossing namespaces. +Use feature-local translation keys by default. Alias only when crossing namespaces. `pnpm i18n:check --file ` should pass for any touched translation namespace. diff --git a/.agents/skills/frontend-code-review/references/component-architecture.md b/.agents/skills/frontend-code-review/references/component-architecture.md index 5936f60a9e..9f66533d21 100644 --- a/.agents/skills/frontend-code-review/references/component-architecture.md +++ b/.agents/skills/frontend-code-review/references/component-architecture.md @@ -18,6 +18,7 @@ Accept repeated TanStack Query calls in siblings when each component independent Flag: +- React component files over 300 lines when the file mixes multiple responsibilities that can be split into focused colocated components, hooks, or utilities. - Shallow wrappers that only rename props or hide the real primitive. - Extra DOM wrappers that do not provide layout, semantics, accessibility, state ownership, or library integration. - Dialog/dropdown/popover hidden surfaces that obscure the parent flow when they should be extracted into a small local component. @@ -29,6 +30,7 @@ Prefer colocated components split by actual data and state needs. Flag: +- Refactors of existing navigation, sidebar, dropdown, webapp list, or app-switching UI that do not preserve behavior-sensitive interactions such as expand/collapse arrows, hover persistence, pin/delete controls, routing, keyboard/focus handling, or open-state ownership. - Components that mix data fetching, mutation side effects, popup state, form validation, layout, and row rendering without a clear owner. - Generic components with many boolean props that encode one feature's workflow. - A shared component that imports feature-specific copy, routes, or API contracts. @@ -38,6 +40,8 @@ Flag: - A component that exposes controlled props but still keeps a competing private state for the same value. - A component that cannot render empty, loading, or missing optional API fields without caller-side preprocessing. +When existing components already own interaction logic, prefer reusing or extending them. If a refactor is necessary, preserve the old interaction contract and add or update focused tests for changed behavior. + ## Props And Types Flag: diff --git a/.agents/skills/frontend-code-review/references/dify-ui.md b/.agents/skills/frontend-code-review/references/dify-ui.md index 01c8035e98..b482b67d52 100644 --- a/.agents/skills/frontend-code-review/references/dify-ui.md +++ b/.agents/skills/frontend-code-review/references/dify-ui.md @@ -91,6 +91,7 @@ Use: Flag: +- Manually recreating UI behavior or chrome already owned by `@langgenius/dify-ui/*` or `web/app/components/base/*`, such as buttons, inputs, toggle groups, popovers, dropdown menus, alert dialogs, switches, avatars, scroll areas, toasts, borders, focus states, disabled states, segmented controls, or existing feature components. - Styling a raw Base UI primitive directly in `web/` when a Dify UI primitive exists. - Wrapping a Dify UI primitive in a feature component that hides its label, error, disabled, or focus contract. - Replacing a semantic primitive with a generic `div` plus classes to match a screenshot. @@ -121,3 +122,13 @@ Use `!` only for a tightly scoped compatibility override after confirming the pr ## Focus Details Flag focus rings attached to the wrong element. For example, Base UI `Slider.Thumb` focuses an internal `input[type=range]`, so the visible thumb wrapper needs `has-[:focus-visible]` rather than direct wrapper `focus-visible`. + +## Custom SVG Icons + +Flag: + +- New generated React icon components or JSON files under `web/app/components/base/icons/src/...` for custom SVG icons. +- Custom SVG icons consumed outside the Tailwind `i-custom-*` icon class pipeline. +- Generated `packages/iconify-collections/custom-*/icons.json` diffs where unrelated existing icons lost or changed intrinsic `width` or `height`. + +New custom SVG icons belong in `packages/iconify-collections/assets/...`. Regenerate with `pnpm --filter @dify/iconify-collections generate`, validate with `pnpm --filter @dify/iconify-collections check:dimensions`, and consume the generated icon with Tailwind `i-custom-*` classes. diff --git a/.agents/skills/karpathy-guidelines/SKILL.md b/.agents/skills/karpathy-guidelines/SKILL.md new file mode 100644 index 0000000000..2b7330f5b8 --- /dev/null +++ b/.agents/skills/karpathy-guidelines/SKILL.md @@ -0,0 +1,33 @@ +--- +name: karpathy-guidelines +description: Lightweight coding guardrails for making focused, simple, and verifiable changes in this repo. Use for all coding work. +--- + +# Karpathy Guidelines + +Use this skill whenever you touch code in this repository. + +## Principles + +- Keep the change small and directly tied to the user request. +- Prefer the simplest implementation that fits the existing codebase. +- Read the nearby code first, then match its patterns. +- Avoid unrelated refactors, broad rewrites, or style churn. +- Preserve existing behavior unless the user explicitly asked to change it. +- Treat regressions as a signal to narrow the change, not to add workaround layers. + +## Workflow + +1. Inspect the current implementation and tests around the change. +2. Make the smallest coherent edit. +3. Add or update focused tests when the behavior changes or the risk is non-trivial. +4. Run the narrowest relevant verification first. +5. Report exactly what was verified and anything left unverified. + +## Review Checklist + +- Does this change solve the stated problem without expanding scope? +- Did it preserve existing route/component/data-flow semantics? +- Are new abstractions justified by real complexity? +- Are tests focused on the behavior that could regress? +- Are unrelated files and generated artifacts left alone? diff --git a/.claude/skills/karpathy-guidelines b/.claude/skills/karpathy-guidelines new file mode 120000 index 0000000000..743bef5277 --- /dev/null +++ b/.claude/skills/karpathy-guidelines @@ -0,0 +1 @@ +../../.agents/skills/karpathy-guidelines \ No newline at end of file diff --git a/web/AGENTS.md b/web/AGENTS.md index cb175a6bed..8dc91be1a2 100644 --- a/web/AGENTS.md +++ b/web/AGENTS.md @@ -1,6 +1,13 @@ ## 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. ## Overlay Components (Mandatory) @@ -9,6 +16,14 @@ - 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. +## 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.