cloudflare/kumo
Publicmirrored fromhttps://github.com/cloudflare/kumoAvailable
packages/kumo-figma/AGENTS.md
126lines · modecode
| 1 | # Figma Plugin Knowledge Base |
| 2 | |
| 3 | Kumo UI Kit Generator - generates production-quality Figma components from Kumo component definitions. |
| 4 | |
| 5 | **Parent docs:** See [root AGENTS.md](../../AGENTS.md) for full project context. |
| 6 | |
| 7 | ## Quick Start |
| 8 | |
| 9 | ```bash |
| 10 | # Optional: enable auto token sync during build |
| 11 | # cp packages/kumo-figma/scripts/.env.example packages/kumo-figma/scripts/.env |
| 12 | # $EDITOR packages/kumo-figma/scripts/.env # set FIGMA_TOKEN (and optionally FIGMA_FILE_KEY) |
| 13 | |
| 14 | pnpm --filter @cloudflare/kumo-figma build |
| 15 | # In Figma: Plugins > Development > Import plugin from manifest... |
| 16 | # Select: packages/kumo-figma/src/manifest.json |
| 17 | ``` |
| 18 | |
| 19 | ## Structure |
| 20 | |
| 21 | ``` |
| 22 | kumo-figma/ |
| 23 | ├── src/ |
| 24 | │ ├── manifest.json # Figma plugin manifest |
| 25 | │ ├── code.ts # Main entry + GENERATORS array |
| 26 | │ ├── ui.html # Plugin UI |
| 27 | │ ├── generated/ # Generated data files (JSON) |
| 28 | │ ├── parsers/ |
| 29 | │ │ ├── tailwind-to-figma.ts # Parse Tailwind → Figma values |
| 30 | │ │ └── opacity-extractor.ts # Extract opacity modifiers |
| 31 | │ └── generators/ |
| 32 | │ ├── shared.ts # Centralized constants + utilities |
| 33 | │ ├── badge.ts # Badge generator |
| 34 | │ ├── button.ts # Button generator |
| 35 | │ └── ... # 30+ component generators |
| 36 | └── scripts/ |
| 37 | └── sync-tokens-to-figma.ts # CSS → Figma Variables API |
| 38 | ``` |
| 39 | |
| 40 | ## Key Modules |
| 41 | |
| 42 | ### `parsers/tailwind-to-figma.ts` |
| 43 | |
| 44 | Converts Tailwind classes to Figma values (colors, spacing, typography). |
| 45 | |
| 46 | ### `parsers/opacity-extractor.ts` |
| 47 | |
| 48 | Extracts opacity patterns like `bg-kumo-brand/70` for Figma variable bindings. |
| 49 | |
| 50 | ### `generators/shared.ts` |
| 51 | |
| 52 | **Centralized constants** - all magic numbers live here: |
| 53 | |
| 54 | - `SECTION_PADDING`, `SECTION_GAP` - Layout spacing |
| 55 | - `SHADOWS` - Dialog, subtle shadow definitions |
| 56 | - `GRID_LAYOUT` - Row gaps, column widths |
| 57 | - `FALLBACK_VALUES` - Parser fallback values |
| 58 | |
| 59 | ## Workflow |
| 60 | |
| 61 | ### Token Sync First |
| 62 | |
| 63 | ```bash |
| 64 | FIGMA_TOKEN="your-token" pnpm --filter @cloudflare/kumo-figma figma:sync |
| 65 | ``` |
| 66 | |
| 67 | This syncs CSS tokens to Figma's `kumo-colors` variable collection. |
| 68 | |
| 69 | `pnpm --filter @cloudflare/kumo-figma build` now runs this automatically when `FIGMA_TOKEN` is present (it also reads `packages/kumo-figma/scripts/.env` if it exists). To skip auto-sync: `KUMO_FIGMA_SKIP_SYNC=1 pnpm --filter @cloudflare/kumo-figma build`. |
| 70 | |
| 71 | ### Build & Run |
| 72 | |
| 73 | ```bash |
| 74 | pnpm --filter @cloudflare/kumo-figma build |
| 75 | # In Figma: Plugins > Development > Kumo UI Kit Generator |
| 76 | ``` |
| 77 | |
| 78 | ## Adding Generators |
| 79 | |
| 80 | 1. **Create generator**: `generators/yourcomponent.ts` |
| 81 | 2. **Register in `code.ts`** GENERATORS array |
| 82 | 3. **Run validation**: `pnpm --filter @cloudflare/kumo-figma validate` |
| 83 | 4. **Exclude if needed**: Add to `EXCLUDED_COMPONENTS` in `drift-detection.test.ts` |
| 84 | |
| 85 | ### Generator Template |
| 86 | |
| 87 | ```typescript |
| 88 | import { createTextNode, getVariableByName, SECTION_GAP } from "./shared"; |
| 89 | import registry from "../../../../ai/component-registry.json"; |
| 90 | |
| 91 | const componentSpec = registry.components.YourComponent; |
| 92 | |
| 93 | export function getYourComponentConfig() { |
| 94 | return componentSpec.props; |
| 95 | } |
| 96 | |
| 97 | export async function generateYourComponentComponents( |
| 98 | page: PageNode, |
| 99 | startY: number, |
| 100 | ): Promise<number> { |
| 101 | // Implementation |
| 102 | return startY + 500 + SECTION_GAP; |
| 103 | } |
| 104 | ``` |
| 105 | |
| 106 | ## Drift Prevention |
| 107 | |
| 108 | CI enforces generator ↔ registry sync: |
| 109 | |
| 110 | - `drift-detection.test.ts` validates all components have generators |
| 111 | - Fails MRs touching `component-registry.json` without generator updates |
| 112 | - Exclusions documented in test file |
| 113 | |
| 114 | ## Technical Constraints |
| 115 | |
| 116 | - **ES2020 target** - Figma runtime requirement |
| 117 | - **No external dependencies** - Bundled into single `code.js` |
| 118 | - **Variable bindings** - Requires `kumo-colors` collection from token sync |
| 119 | |
| 120 | ## Troubleshooting |
| 121 | |
| 122 | | Error | Solution | |
| 123 | | ---------------------------------- | -------------------------------------- | |
| 124 | | "kumo-colors collection not found" | Run token sync first | |
| 125 | | "Variable not found" | Check token name matches CSS | |
| 126 | | "Font not found" | Inter is required (default Figma font) | |
| 127 | |