|
| 1 | +# PROJECT KNOWLEDGE BASE |
| 2 | + |
| 3 | +**Generated:** 2026-02-10 |
| 4 | +**Commit:** 0a8c481 |
| 5 | +**Branch:** main |
| 6 | + |
| 7 | +## OVERVIEW |
| 8 | + |
| 9 | +Figma plugin that generates React/TypeScript components using `@devup-ui/react` from Figma designs, plus design system (Devup config) import/export. No UI iframe — codegen + menu commands only. |
| 10 | + |
| 11 | +## STRUCTURE |
| 12 | + |
| 13 | +``` |
| 14 | +. |
| 15 | +├── src/ |
| 16 | +│ ├── code.ts # Entry point (thin wrapper → code-impl) |
| 17 | +│ ├── code-impl.ts # Plugin bootstrap: codegen registration + command routing |
| 18 | +│ ├── types.ts # Shared types: ComponentType, DevupElement, DevupNode |
| 19 | +│ ├── utils.ts # Core helpers: getComponentName, space |
| 20 | +│ ├── codegen/ # ** Code generation engine (see src/codegen/AGENTS.md) |
| 21 | +│ ├── commands/ # Plugin menu commands (9 commands) |
| 22 | +│ │ ├── devup/ # Design system export/import (JSON + Excel via SheetJS) |
| 23 | +│ │ ├── exportAssets.ts # Asset export (stub — commented out implementation) |
| 24 | +│ │ ├── exportComponents.ts |
| 25 | +│ │ └── exportPagesAndComponents.ts |
| 26 | +│ └── utils/ # Shared utilities (color, typography, file I/O) |
| 27 | +├── manifest.json # Figma plugin manifest (id: 1412341601954480694) |
| 28 | +├── rspack.config.js # Bundler: single entry → dist/code.js |
| 29 | +├── ui.html # Legacy UI (not referenced in manifest) |
| 30 | +└── dist/code.js # Compiled bundle (gitignored) |
| 31 | +``` |
| 32 | + |
| 33 | +## WHERE TO LOOK |
| 34 | + |
| 35 | +| Task | Location | Notes | |
| 36 | +|------|----------|-------| |
| 37 | +| Add new CSS property support | `src/codegen/props/` | Create `your-prop.ts`, import in `props/index.ts` | |
| 38 | +| Add new plugin command | `src/commands/` + `manifest.json` + `code-impl.ts` | Add to manifest menu, route in `runCommand()` | |
| 39 | +| Fix code generation output | `src/codegen/Codegen.ts` | Tree-build phase: `buildTree()`, render phase: `renderTree()` | |
| 40 | +| Fix responsive behavior | `src/codegen/responsive/` | Breakpoints in `index.ts`, merge logic in `ResponsiveCodegen.ts` | |
| 41 | +| Fix component rendering | `src/codegen/render/index.ts` | `renderNode()` for JSX, `renderComponent()` for wrappers | |
| 42 | +| Add shared utility | `src/utils/` | One function per file, pure functions | |
| 43 | +| Fix design system export | `src/commands/devup/export-devup.ts` | JSON and Excel paths | |
| 44 | +| Fix design system import | `src/commands/devup/import-devup.ts` | Applies typography via `apply-typography.ts` | |
| 45 | +| Understand prop filtering | `src/codegen/props/index.ts` | `filterPropsWithComponent()` removes defaults per component | |
| 46 | +| Debug node processing | `src/codegen/utils/node-proxy.ts` | `nodeProxyTracker` logs all property access when `debug=true` | |
| 47 | + |
| 48 | +## CONVENTIONS |
| 49 | + |
| 50 | +- **No semicolons**, single quotes, 2-space indent (Biome enforced) |
| 51 | +- **Strict TypeScript** — `noImplicitAny` on, no DOM types (Figma sandbox only) |
| 52 | +- **No `any` in production code** — `noExplicitAny: off` only in `__tests__/` files |
| 53 | +- **Warnings = errors** — `biome check --error-on-warnings` |
| 54 | +- **One function per utility file** — `src/utils/*.ts` and `src/codegen/utils/*.ts` |
| 55 | +- **Prop getters return spread-compatible objects** — `getXxxProps(node) → Record<string, unknown>` |
| 56 | +- **Test co-location** — `__tests__/` directory adjacent to source, with `__snapshots__/` |
| 57 | +- **No barrel exports in utils** — import each utility directly by path |
| 58 | +- **Barrel exports via index.ts** — used in `codegen/props`, `codegen/render`, `codegen/responsive`, `commands/devup` |
| 59 | + |
| 60 | +## ANTI-PATTERNS (THIS PROJECT) |
| 61 | + |
| 62 | +- **Never treat responsive arrays as default values** — Arrays bypass `isDefaultProp` filtering (`is-default-prop.ts:27`) |
| 63 | +- **Never pass `effect` or `viewport` as component props** — Reserved internal variant keys, handled via pseudo-selectors/responsive arrays |
| 64 | +- **Never append rotation transforms** — Always replace entire value (`reaction.ts`) |
| 65 | +- **Animation targets are not assets** — Nodes with `SMART_ANIMATE` reactions must not be exported as images (`check-asset-node.ts:35`) |
| 66 | +- **Tile-mode fills are not images** — `PATTERN`/`TILE` fills are backgrounds, not exportable assets |
| 67 | +- **Padding/margin zero-filtering is disabled** — Commented-out regexes in `is-default-prop.ts` were intentionally abandoned |
| 68 | +- **`exportAssets` is a stub** — Entire implementation commented out, marked "in development" |
| 69 | + |
| 70 | +## COMMANDS |
| 71 | + |
| 72 | +```bash |
| 73 | +bun run dev # Rspack dev server |
| 74 | +bun run build # Production bundle → dist/code.js |
| 75 | +bun run watch # Build in watch mode |
| 76 | +bun run test # tsc --noEmit && bun test --coverage |
| 77 | +bun run lint # biome check --error-on-warnings |
| 78 | +bun run lint:fix # biome check --fix |
| 79 | +``` |
| 80 | + |
| 81 | +## TOOLCHAIN |
| 82 | + |
| 83 | +| Tool | Version | Purpose | |
| 84 | +|------|---------|---------| |
| 85 | +| Bun | latest | Package manager + test runner | |
| 86 | +| Rspack | 1.7.6 | Bundler (SWC transpilation) | |
| 87 | +| TypeScript | 5.9 | Type checking (es2015 target) | |
| 88 | +| Biome | 2.3 | Linting + formatting | |
| 89 | +| Husky | 9 | Pre-commit: `bun run lint && bun run test` | |
| 90 | + |
| 91 | +## CI |
| 92 | + |
| 93 | +GitHub Actions (`.github/workflows/CI.yml`): `bun install` → `bun run lint` → `bun test --coverage` → Codecov upload (main only). Cancel-in-progress on same ref. |
| 94 | + |
| 95 | +## DEPENDENCIES |
| 96 | + |
| 97 | +Only **1 runtime dep**: `jszip` (ZIP creation for component/asset export). Network: only `https://cdn.sheetjs.com` allowed (Excel support via dynamic import). |
| 98 | + |
| 99 | +## NOTES |
| 100 | + |
| 101 | +- Plugin runs in **Figma sandbox** — no `window`, `document`, or DOM APIs |
| 102 | +- `ui.html` exists at root but is NOT referenced in `manifest.json` — appears to be legacy |
| 103 | +- `debug = true` in `code-impl.ts` enables `nodeProxyTracker` which logs all Figma node property access for test case generation |
| 104 | +- Coverage threshold is `0.9999` (`bunfig.toml`) — near 100% coverage required |
| 105 | +- `exportPagesAndComponents.ts` is excluded from coverage (`coveragePathIgnorePatterns`) |
| 106 | +- Codegen test file is massive: `codegen.test.ts` = 59,673 lines (snapshot-heavy) |
| 107 | +- Only 2 lint suppressions in entire codebase (both justified with comments) |
0 commit comments