feat: add Comfy Design Standards Figma reference for agents (#10696)

## Summary Add design standards instructions so agents consult the canonical [Comfy Design Standards](https://www.figma.com/design/QreIv5htUaSICNuO2VBHw0/Comfy-Design-Standards) Figma file before implementing user-facing features. ### Changes - **`docs/guidance/design-standards.md`** — Auto-loaded guidance for `src/components/**/*.vue` and `src/views/**/*.vue` with Figma MCP fetch instructions, section node IDs, and component set references - **`AGENTS.md`** — Added Design Standards section and Figma link in External Resources ### Design All content is fetched **live from Figma** via the Figma MCP tool — designers can update the file and agents will always see the latest version. No hardcoded design rules that can go stale. Ref: COM-17639 ┆Issue is synchronized with this [Notion page](https://www.notion.so/PR-10696-feat-add-Comfy-Design-Standards-Figma-reference-for-agents-3326d73d36508181844fdcaa5c17cf00) by [Unito](https://www.unito.io) --------- Co-authored-by: GitHub Action <action@github.com>
2026-04-20 14:30:41 +00:00 · 2026-04-08 14:13:57 -07:00
parent 6f98fe5ba7
commit 934f1487bd
2 changed files with 73 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -179,6 +179,12 @@ This project uses **pnpm**. Always prefer scripts defined in `package.json` (e.g
 24. Do not use function expressions if it's possible to use function declarations instead
 25. Watch out for [Code Smells](https://wiki.c2.com/?CodeSmell) and refactor to avoid them

+## Design Standards
+
+Before implementing any user-facing feature, consult the [Comfy Design Standards](https://www.figma.com/design/QreIv5htUaSICNuO2VBHw0/Comfy-Design-Standards) Figma file. Use the Figma MCP to fetch it live — the file is the single source of truth and may be updated by designers at any time.
+
+See `docs/guidance/design-standards.md` for Figma file keys, section node IDs, and component references.
+
 ## Testing Guidelines

 See @docs/testing/\*.md for detailed patterns.
@@ -226,6 +232,7 @@ See @docs/testing/\*.md for detailed patterns.
 - shadcn/vue: <https://www.shadcn-vue.com/>
 - Reka UI: <https://reka-ui.com/>
 - PrimeVue: <https://primevue.org>
+- Comfy Design Standards: <https://www.figma.com/design/QreIv5htUaSICNuO2VBHw0/Comfy-Design-Standards>
 - ComfyUI: <https://docs.comfy.org>
 - Electron: <https://www.electronjs.org/docs/latest/>
 - Wiki: <https://deepwiki.com/Comfy-Org/ComfyUI_frontend/1-overview>
--- a/docs/guidance/design-standards.md
+++ b/docs/guidance/design-standards.md
@@ -0,0 +1,66 @@
+---
+globs:
+  - 'src/components/**/*.vue'
+  - 'src/views/**/*.vue'
+---
+
+# Comfy Design Standards
+
+Applies when implementing or modifying user-facing components and views.
+
+## Before Implementing UI Changes
+
+Consult the **Comfy Design Standards** Figma file to ensure your changes follow the agreed-upon design principles. Use the Figma MCP tool to fetch the current standards:
+
+```javascript
+get_figma_data({ fileKey: 'QreIv5htUaSICNuO2VBHw0', nodeId: '0:1' })
+```
+
+The Figma file is the single source of truth. Always fetch it live — do not rely on cached assumptions.
+
+> **Note:** The Figma MCP is read-only. It cannot detect changes or diffs between versions. Always fetch the latest state before implementing.
+
+### Key Sections
+
+| Section              | Node ID   | When to consult                                                               |
+| -------------------- | --------- | ----------------------------------------------------------------------------- |
+| Hover States         | `1:2`     | Adding/modifying interactive elements (buttons, inputs, links, nav items)     |
+| Click Targets        | `4:243`   | Adding clickable elements, especially small ones (icons, handles, connectors) |
+| Affordances          | `15:2202` | Any interactive element — ensuring visual feedback on interaction             |
+| Feedback             | `15:2334` | User actions that need confirmation, success/error states                     |
+| Slips and How to Fix | `15:2337` | Error prevention, undo patterns, destructive actions                          |
+| Design Pillars       | `15:2340` | New features, architectural UI decisions                                      |
+| The User             | `16:2348` | User flows, onboarding, accessibility                                         |
+
+Fetch the specific section relevant to your task:
+
+```javascript
+get_figma_data({ fileKey: 'QreIv5htUaSICNuO2VBHw0', nodeId: '<node-id>' })
+```
+
+## Figma Component Reference
+
+The Figma file contains component specifications. When implementing these components, fetch details to match the design:
+
+| Component         | Component Set ID |
+| ----------------- | ---------------- |
+| Button/Default    | `4:314`          |
+| Search            | `4:2366`         |
+| Base Node Example | `4:4739`         |
+
+## Figma Token Translation Rules
+
+When translating Figma design tokens into code:
+
+- **Skip `-hover` and `-selected` suffixed tokens.** These states exist in Figma only for prototype demonstrations. On the frontend, hover and selected states must be derived programmatically (e.g., via `color-mix()` or Tailwind modifier classes like `hover:`).
+- **Color tier system:** Figma uses a tiered color hierarchy:
+  - **Base** — default surface/background colors
+  - **Secondary** — elevated surfaces (e.g., sidebars, cards)
+  - **Tertiary** — elements on modal panels (one shade lighter than base)
+- Map Figma token names directly to Tailwind 4 semantic tokens — never hardcode hex values.
+
+## Integration with Codebase
+
+- Map Figma color values to Tailwind 4 semantic tokens — never hardcode hex values
+- Use `cn()` from `@/utils/tailwindUtil` for conditional class merging
+- Use the `dark:` avoidance rule from AGENTS.md — semantic tokens handle both themes