diff --git a/99 Daily/2026-05-13.md b/99 Daily/2026-05-13.md index 3628bcb..f0c57bb 100644 --- a/99 Daily/2026-05-13.md +++ b/99 Daily/2026-05-13.md @@ -41,3 +41,6 @@ tags: [daily] - 11:59 (<1min) | `cc-dashboard` - **Asked:** Review design across all pages for spacing, element interactions, filters, and sorting. - **Done:** Added project auto-fill dropdown to OMG form and improved DevOps Work Items counter display. +- 12:08 (6min) | `Shumiland` + - **Asked:** Checked hero section matches design mockup | Verified visual parity with Figma design | Hero.tsx + - **Done:** Write wiki articles and fix background | Completed 3 wiki articles, committed background fix, pushed changes | Wiki articles, Hero.tsx diff --git a/wiki/concepts/figma-design-to-code-workflow.md b/wiki/concepts/figma-design-to-code-workflow.md new file mode 100644 index 0000000..ff29dc0 --- /dev/null +++ b/wiki/concepts/figma-design-to-code-workflow.md @@ -0,0 +1,145 @@ +--- +title: "Figma Design-to-Code — Workflow, Best Practices, Pixel-Perfect Positioning" +aliases: [figma-workflow, figma-to-code, figma-pixel-perfect] +tags: [figma, mcp, workflow, pixel-perfect, positioning] +sources: + - "raw/Structure your Figma file for better code.md" + - "raw/Write effective prompts to guide the AI.md" + - "raw/Avoid selecting large, heavy frames.md" + - "raw/Add custom rules and instructions.md" + - "daily/2026-05-13.md" +created: 2026-05-13 +updated: 2026-05-13 +--- + +# Figma Design-to-Code — Workflow & Best Practices + +## The Required Workflow (do not skip steps) + +``` +1. Parse URL → extract fileKey + nodeId +2. get_design_context(fileKey, nodeId) ← primary tool, always first +3. get_screenshot(fileKey, nodeId) ← source of truth for validation +4. [if truncated] get_metadata → identify child nodes → re-call get_design_context per child +5. Download assets (use localhost URLs from MCP directly — do NOT modify) +6. Translate to project conventions (framework, components, tokens, file structure) +7. Validate visually against the screenshot before marking done +``` + +The Figma MCP output is React + Tailwind — treat it as a *design reference*, not final code. Always adapt to the project's actual stack, components, and naming. + +--- + +## Pixel-Perfect Proportional Positioning + +When implementing hero sections or complex layouts from Figma, convert absolute Figma coordinates to **CSS percentages of the containing panel**. This gives Figma-accurate layout that scales to any viewport. + +### Scale Factor +Figma frames are typically designed at **1920px**. If the project's lg breakpoint is **1440px** (as in Tailwind v4 Shumiland), the scale factor is: +``` +scale = 1440 / 1920 = 0.75 +``` + +### Panel Width Convention +If the right panel in the design is `W px` wide out of a `1920px` frame, set its CSS width as: +```css +width: calc(W / 1920 * 100vw) +/* e.g. 1228/1920 = 64vw */ +``` + +Position the panel **outside** the max-width content container as `position: absolute; right: 0` on the `
` — this lets it extend to the viewport edge. + +### Convert Absolute Figma Positions to % of Panel + +From Figma dev panel, read the node's `x`, `y`, `width`, `height` relative to the panel frame: +``` +element.left% = element.x / panelWidth (can be negative for bleed) +element.top% = element.y / panelHeight +element.width% = element.width / panelWidth +``` + +**Real example — Shumiland DyvoLis hero (Figma node 3-546, 1920px frame):** + +| Element | Figma (px) | CSS (% of panel=1228px) | +|---------|-----------|-------------------------| +| Cat left | -247 | -20.1% | +| Cat top | -334 | -20.7% of panel height | +| Cat width | 1558 | 126.9% | +| Orange circle container left | -153 | -12.5% | +| Orange circle container top | 130 | 8.1% | +| Orange circle container size | 2267 | 184.6% | +| Ellipse SVG inside container | 1858 | 82% of container | + +Negative percentages allow elements to bleed outside the panel (e.g. a cat that bleeds left). The panel has `overflow: hidden` to clip anything that escapes the section. + +### Z-layering rule +Cat renders on top of the orange circle — declare cat *after* circle in DOM order, or use `z-index`. + +--- + +## Prompting Best Practices + +### Be specific about framework + file path +``` +"Implement using our existing BtnPrimary component from src/components/ui" +"Add to src/components/sections/HeroSection.tsx, not a new file" +"Use Tailwind v4 with lg=1440px breakpoint, not default 1024px" +``` + +### Avoid large frames +Select **individual components or sections**, not full pages. Large selections cause truncation or incomplete output. If stuck: +1. Reduce selection to a single section +2. Call `get_metadata` first to map the structure +3. Fetch each major child with `get_design_context` separately + +### Frame selection tip +Resize the frame in Figma before exporting to verify Auto Layout behaves as expected at different widths. + +--- + +## Structuring Figma Files for Better Code Output + +These Figma-side practices improve MCP output quality: + +| Practice | Why it helps | +|----------|-------------| +| Use components (not raw frames) for repeated elements | Enables Code Connect reuse | +| Use variables for colors, spacing, radius | MCP maps tokens to CSS vars instead of hardcoded values | +| Semantic layer names (`CardContainer`, not `Frame1268`) | AI understands intent and functionality | +| Auto Layout everywhere | Results in flexbox/grid code, not absolute positioning | +| Use annotations | Communicates behavior (hover states, responsive rules) that visuals can't | + +--- + +## CLAUDE.md Rules for Figma MCP Projects + +Add these to `CLAUDE.md` to avoid repeating yourself every session: + +```markdown +## Figma MCP Integration Rules + +### Required flow +1. Run get_design_context first for the exact node(s) +2. If truncated: run get_metadata → re-fetch child nodes individually +3. Run get_screenshot for visual reference +4. Adapt output to project conventions (not copy-paste React+Tailwind) +5. Validate against screenshot before marking complete + +### Assets +- Use localhost URLs from MCP directly — do NOT modify or replace them +- DO NOT import new icon packages — all assets come from Figma payload +- DO NOT create placeholders if a localhost source is provided +``` + +--- + +## Common Failure Modes + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Response truncated | Frame too large | Use `get_metadata` → fetch children | +| Orange circle invisible | Wrong z-order or opacity | Check DOM order; circle before cat | +| Panel doesn't reach viewport edge | Panel inside max-width container | Move panel outside container to `
` | +| Wrong breakpoint behavior | Tailwind v4 cascade: `md:` beats `lg:` alphabetically | Remove conflicting `md:` where `lg:` should dominate | +| Figma MCP auth error after restart | Stale OAuth token | See [[figma-mcp-oauth-reconnect-restart]] | +| Code Connect tool returns permissions error | Not on Org/Enterprise plan | Use CLI instead — see [[figma-code-connect-plan-requirements]] | diff --git a/wiki/concepts/figma-mcp-tools-reference.md b/wiki/concepts/figma-mcp-tools-reference.md new file mode 100644 index 0000000..9d24ac5 --- /dev/null +++ b/wiki/concepts/figma-mcp-tools-reference.md @@ -0,0 +1,97 @@ +--- +title: "Figma MCP Server — Tool Reference" +aliases: [figma-mcp-tools, figma-mcp-api] +tags: [figma, mcp, tools, reference] +sources: + - "raw/Tools and prompts Developer Docs.md" + - "raw/Guide to the Figma MCP server.md" +created: 2026-05-13 +updated: 2026-05-13 +--- + +# Figma MCP Server — Tool Reference + +Complete list of the 18 tools exposed by the Figma MCP server. The primary 3 are bolded — they cover 90% of design-to-code work. + +## Core Design-to-Code Tools + +### **`get_design_context`** ← use first +Returns structured React + Tailwind code, a screenshot, and component context for the selected node. This is the primary tool for implementing Figma designs. If Code Connect mappings exist for components in the selection, it returns real component snippets instead of generated code. + +Output is a *reference*, not final code — always adapt to project conventions. + +``` +get_design_context(fileKey=":fileKey", nodeId="1-2") +``` + +### **`get_screenshot`** ← use second (visual validation) +Returns a screenshot of the selected node. Use immediately after `get_design_context` — this is the source of truth for pixel-perfect validation. Keep it open throughout implementation. + +``` +get_screenshot(fileKey=":fileKey", nodeId="1-2") +``` + +### **`get_metadata`** ← use when response is too large +Returns a sparse XML tree with layer IDs, names, types, positions, and sizes. Does NOT return code or full design data. Use this when `get_design_context` truncates — identify child node IDs from the tree, then call `get_design_context` on each child individually. + +``` +get_metadata(fileKey=":fileKey", nodeId="1-2") +``` + +### `get_variable_defs` +Returns all variables (design tokens) and styles used in the selection: colors, spacing, typography. Useful for mapping Figma tokens to project tokens. + +## Canvas Write Tools (remote only) + +### `use_figma` +General-purpose write-to-canvas. Creates, edits, or inspects any object in a Figma Design file. Powers the `figma-use` skill. Requires edit access to the file. + +### `generate_diagram` +Creates a FigJam diagram from Mermaid syntax or natural language. Supports flowchart, Gantt, sequence, ERD, state, architecture diagrams. + +### `generate_figma_design` +Captures live web UI (localhost, staging, prod) as editable design layers in Figma. Select-client only (Claude Code, Cursor, VS Code, Augment, Copilot CLI). + +### `create_new_file` +Creates a blank Figma Design or FigJam file in the user's drafts. Requires `planKey` from `whoami`. Needed before `use_figma` when no file exists. + +### `upload_assets` +Uploads PNG, JPG, GIF, WebP to a Figma file. For SVG — use `use_figma` directly. + +### `get_libraries` +Returns subscribed team/org libraries and available community UI kits for the current file. + +## FigJam / Make + +### `get_figjam` +Converts a FigJam board to XML. Use for reading architecture diagrams, flowcharts, and brainstorm boards into code context. + +## Code Connect Tools + +These 5 tools power the `figma-code-connect-components` skill. Usually invoked automatically by the skill, not manually. + +| Tool | Purpose | +|------|---------| +| `add_code_connect_map` | Save a Figma node → code component mapping | +| `get_code_connect_map` | Retrieve existing mappings for selected nodes | +| `get_code_connect_suggestions` | AI-suggested component matches (Figma-triggered) | +| `get_context_for_code_connect` | Get component metadata for generating `.figma.tsx` files (Figma-triggered) | +| `send_code_connect_mappings` | Confirm + publish suggested mappings (requires Org/Enterprise plan) | + +See [[figma-code-connect-plan-requirements]] for the MCP vs CLI plan requirements. + +## Auth / Identity + +### `whoami` (remote only) +Returns the authenticated user's identity and plan keys. Use it to get `planKey` for `create_new_file`. + +## URL Parsing + +Extract `fileKey` and `nodeId` from a Figma URL: +``` +https://figma.com/design/:fileKey/:fileName?node-id=1-2 +→ fileKey = segment after /design/ +→ nodeId = node-id query param (convert "-" to ":" if needed for desktop MCP) +``` + +The desktop MCP (`figma-desktop`) does not require `fileKey` — it reads from the currently open file in the desktop app. diff --git a/wiki/concepts/figma-skills-reference.md b/wiki/concepts/figma-skills-reference.md new file mode 100644 index 0000000..a837d3d --- /dev/null +++ b/wiki/concepts/figma-skills-reference.md @@ -0,0 +1,104 @@ +--- +title: "Figma Skills Reference — All Official Skills" +aliases: [figma-skills, figma-plugin-skills] +tags: [figma, mcp, skills, claude-code] +sources: + - "raw/Figma skills for MCP.md" + - "raw/Skill create_new_file — Create a New Figma File.md" +created: 2026-05-13 +updated: 2026-05-13 +--- + +# Figma Skills Reference + +Skills = pre-built workflow instructions bundled with the Figma plugin. They tell the AI which tools to call, in which order, and how to handle results. Without skills, you'd have to describe the steps manually every time. + +## Setup + +```bash +claude plugin install figma@claude-plugins-official +``` + +After install + restart: `/plugin` → Installed → `figma` → Allow access (OAuth in browser). + +If OAuth fails mid-flow, see [[figma-mcp-oauth-reconnect-restart]] for the restart fix. + +--- + +## Skills for Developers (Code-Focused) + +### `figma-implement-design` ← the main one +Turns a Figma frame into working code. Reads design context, pulls assets, generates code matching project conventions, and validates against the original design. + +**Trigger:** provide a Figma URL + ask to implement +**Requires:** link to a specific frame or component +**Workflow:** get_design_context → get_screenshot → download assets → adapt to project → validate + +See [[figma-design-to-code-workflow]] for the full step-by-step. + +### `figma-code-connect-components` +Scans the codebase for components matching selected Figma components, shows proposed connections, then bulk-creates Code Connect mappings. After this, Dev Mode shows real component code instead of generated CSS. + +**Trigger:** "connect these Figma components to code" +**Requires:** Figma URL with published library components + Org/Enterprise plan for MCP publishing (or use CLI for any plan — see [[figma-code-connect-plan-requirements]]) + +### `figma-create-design-system-rules` +Analyzes the codebase and writes a `CLAUDE.md` (or equivalent) section with project-specific Figma integration rules: component paths, naming, design tokens, layout primitives. Run once, saves repetitive prompting. + +**Trigger:** "generate design system rules for Figma" or "set up Figma CLAUDE.md rules" +**Requires:** access to the codebase + +--- + +## Skills for Designers (Canvas-Focused) + +### `figma-use` +The foundational write-to-canvas skill. Creates/modifies real Figma content: frames, components, variables, Auto Layout. Other write-to-canvas skills build on top of it. + +**Requires:** Figma file URL + edit access + Full or Dev seat on paid plan +**Note:** Usage-based paid feature (currently free in beta) + +### `figma-use-figjam` +Same as `figma-use` but for FigJam boards: stickies, sections, connectors, shapes, tables. + +### `figma-create-new-file` +Creates a blank Figma Design or FigJam file in drafts. + +``` +/figma-create-new-file [editorType] [fileName] +# Examples: +/figma-create-new-file +/figma-create-new-file figjam My Whiteboard +/figma-create-new-file design Homepage Redesign +``` + +Internally calls `whoami` to get `planKey`, then `create_new_file`. Use before `figma-use` when no file exists yet. + +--- + +## Example Skills (Reference Implementations) + +These are fully functional but also serve as templates for building custom skills. + +### `figma-generate-library` +Builds a full Figma design system library from your codebase in phases: Discovery → Foundations (color/spacing variables) → File structure (pages) → Components (with variants + Code Connect) → QA. + +**Requires:** codebase access + existing Figma file (create with `figma-create-new-file`) + +### `figma-generate-design` +Builds full-page Figma screens from code using real components from the design system. Can also take a live screenshot of the running app as layout reference. + +**Requires:** codebase access + Figma file with connected design system + +--- + +## Skill vs Tool + +| | Skill | Tool | +|---|---|---| +| What it is | Pre-built workflow instructions | Raw MCP function | +| Where it lives | Plugin / SKILL.md file | MCP server | +| How to invoke | `/skill-name` or natural language | Called by Claude Code automatically | +| Example | `figma-implement-design` | `get_design_context` | + +Skills orchestrate tool calls. The skill tells Claude *when* and *why* to call tools; the tools do the actual data retrieval.