inkbridge 0.1.0-beta.15 → 0.1.0-beta.17

package/README.md

@@ -131,6 +131,70 @@ The scanner re-reads this file on every scan — no server restart needed.
 
 ---
 
+## Supported styling
+
+Inkbridge reads styling from **Tailwind class names** (`className="…"`).
+The Figma renderer is built to handle the breadth of Tailwind utilities:
+flex / grid layouts, responsive variants (`sm:`, `md:`, `lg:`, …),
+arbitrary values (`left-[18.33%]`, `aspect-5/3`), color / spacing
+tokens, and SVG attribute inheritance.
+
+### What's not supported yet
+
+- **Inline `style={{ … }}` props.** Currently ignored by the renderer.
+  If you set `style={{ color: '#0a0', padding: 8 }}` on an element, the
+  Figma rendering will use whatever the Tailwind class list says — your
+  inline overrides won't be applied. Use Tailwind utilities or arbitrary
+  values instead (`text-[#0a0] p-2`). A consumer-side ESLint rule
+  (`react/forbid-dom-props` + `react/forbid-component-props`) is
+  recommended to catch this — see "Recommended lint rules" below.
+
+- **CSS variables in arbitrary classes** (`text-[var(--accent)]`) —
+  not yet resolved through the scanner's token map; the literal CSS
+  variable name reaches Figma and renders as black. Use a Tailwind
+  token alias (`text-accent`) instead.
+
+- **`<g transform="…">`** — the transform isn't composed onto child
+  positions yet, so paths inside a transformed group render at their
+  pre-transform coordinates.
+
+- **`clip-path` / `mask` on `<g>`** — clipping is honored at the
+  element level (`overflow-hidden`, `clip-path-decorative-*`) but not
+  via SVG `<g clip-path="url(…)">`.
+
+These are tracked as universality enhancements. File an issue if one
+blocks you and we'll prioritize.
+
+### Recommended lint rules
+
+Until inline-style support lands, add these rules to your project's
+ESLint config so you don't accidentally rely on patterns the plugin
+ignores:
+
+```json
+{
+  "rules": {
+    "react/forbid-dom-props": ["error", {
+      "forbid": [{
+        "propName": "style",
+        "message": "Inkbridge ignores inline styles — use Tailwind classes (or arbitrary values like text-[#0a0]) so Figma rendering matches the browser."
+      }]
+    }],
+    "react/forbid-component-props": ["error", {
+      "forbid": [{
+        "propName": "style",
+        "message": "Inkbridge ignores inline styles — use Tailwind classes (or arbitrary values like text-[#0a0]) so Figma rendering matches the browser."
+      }]
+    }]
+  }
+}
+```
+
+Skip this rule on any component where Figma rendering doesn't matter
+(e.g. animation-only effects).
+
+---
+
 ## Troubleshooting
 
 ### "Dev server not reachable"

package/bin/inkbridge.mjs

@@ -106,13 +106,35 @@ async function postinstall() {
   const pkg = JSON.parse(await readFile(join(PACKAGE_DIR, "package.json"), "utf8"));
   const manifestPath = join(PROJECT_ROOT, "node_modules/inkbridge/manifest.json");
 
+  // If setup has already run, the scanner route file exists. Re-installs and
+  // version bumps shouldn't shout "RUN SETUP" again — that's misleading.
+  const scanRouteExists = existsSync(
+    join(PROJECT_ROOT, "src/app/api/inkbridge/scan-components/route.ts")
+  );
+
   console.log("");
   console.log(`  ✓ inkbridge v${pkg.version} installed`);
+
+  if (scanRouteExists) {
+    console.log("");
+    console.log("  Setup already done. Run `pnpm inkbridge:dev` and open the plugin in Figma.");
+    console.log("");
+    return;
+  }
+
+  // First install — the next step is non-obvious and easy to miss in a long
+  // install log. Make it loud.
   console.log("");
-  console.log("  Next: run setup to wire up the scanner endpoint and scripts:");
-  console.log("    pnpm exec inkbridge setup");
+  console.log("  ┌─────────────────────────────────────────────────────────────┐");
+  console.log("  │  ⚠  One more step — wire up the scanner API routes:        │");
+  console.log("  │                                                             │");
+  console.log("  │      pnpm exec inkbridge setup                              │");
+  console.log("  │                                                             │");
+  console.log("  │  Without this the plugin will show \"Dev server not          │");
+  console.log("  │  running\" because the routes it calls don't exist yet.      │");
+  console.log("  └─────────────────────────────────────────────────────────────┘");
   console.log("");
-  console.log("  Then load the plugin in Figma Desktop:");
+  console.log("  After setup, load the plugin in Figma Desktop:");
   console.log("    Plugins → Development → Import plugin from manifest");
   console.log(`    ${manifestPath}`);
   console.log("");
@@ -196,6 +218,14 @@ async function setup() {
   // 6. Print manifest path
   const manifestPath = resolve(PROJECT_ROOT, "node_modules/inkbridge/manifest.json");
   console.log("");
+  console.log("  About the routes:");
+  console.log("    src/app/api/inkbridge/scan-components/route.ts");
+  console.log("        runs the scanner and returns your component definitions");
+  console.log("        (the plugin calls this every time you click Generate).");
+  console.log("    src/app/api/inkbridge/patch-tokens/route.ts");
+  console.log("        writes Figma-edited tokens back to your CSS source on Push.");
+  console.log("    Don't move or delete these — the plugin won't work without them.");
+  console.log("");
   console.log("  Setup complete. Load the plugin in Figma Desktop:");
   console.log("    Plugins → Development → Import plugin from manifest");
   console.log(`    ${manifestPath}`);