inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/README.md

@@ -1,12 +1,18 @@
+<img src="https://inkbridge.ink/inkbridge-logo.png" alt="Inkbridge" width="80" />
+
 # Inkbridge
 
-Generates native Figma frames from your Tailwind React components and syncs design tokens back to your codebase via GitHub PRs.
+Generates native Figma frames and reusable Figma component instances from your Tailwind React components, and syncs design tokens back to your codebase via GitHub PRs.
+
+<img src="https://inkbridge.ink/docs/mediacards-figma.png" alt="An Inkbridge-generated Figma page showing component variants rendered as native Figma frames" />
+
+> Read the methodology behind this — stories as the single source of truth between design and code: [inkbridge.ink/methodology](https://inkbridge.ink/methodology). Browse the full docs at [inkbridge.ink/docs](https://inkbridge.ink/docs).
 
 ## What it does
 
 | Feature | Description |
 |---|---|
-| **Generate Design System Page** | Scans your Storybook stories and builds a pixel-accurate Figma page from your Tailwind classes |
+| **Generate Design System Page** | Scans your Storybook stories and builds a pixel-accurate Figma page from your Tailwind classes, including reusable component instances for symbol candidates (CVA and non-CVA) |
 | **Push to Code** | Creates a GitHub PR from Figma token changes. Source can be CSS-first (`auto`/`css`) or DTCG (`dtcg`). |
 | **Detect & Sync Changes** | Detects class-level changes in Figma frames and proposes them as a GitHub PR |
 | **Dev Mode codegen** | Shows Tailwind class names for any selected node in Figma Dev Mode |
@@ -17,7 +23,7 @@ Generates native Figma frames from your Tailwind React components and syncs desi
 
 - **Figma Desktop** (not the browser — the plugin needs localhost access)
 - **Node.js 18+** and **pnpm**
-- A project with Next.js, Tailwind CSS, and Storybook stories (`.stories.tsx`)
+- A project with Next.js, Tailwind CSS, and Storybook stories (`.stories.tsx` or `.stories.ts`)
 
 ---
 
@@ -30,11 +36,16 @@ pnpm add -D inkbridge
 pnpm exec inkbridge setup
 ```
 
-`setup` does three things automatically:
-- Creates `inkbridge.config.json` in your project root (auto-detects component paths from `.storybook/main.ts`)
-- Creates the scanner API route at `src/app/api/figma/scan-components/route.ts`
-- Creates the token patch API route at `src/app/api/figma/patch-tokens/route.ts`
-- Adds `figma:dev` and `figma:scan` scripts to your `package.json`
+`pnpm exec inkbridge setup` is the only required step after install. It prints exactly what it will change before writing anything (run with `--dry-run` to preview without applying, or `--force` to refresh route templates and `inkbridge.config.json` after a plugin update):
+
+- Creates `inkbridge.config.json` in your project root (auto-detects component paths from `.storybook/main.*`)
+- Creates the scanner API route at `src/app/api/inkbridge/scan-components/route.ts`
+- Creates the token patch API route at `src/app/api/inkbridge/patch-tokens/route.ts`
+- Adds `inkbridge:dev` and `inkbridge:scan` scripts to your `package.json`
+- Adds `headers()` to your `next.config.*` exposing CORS on `/api/inkbridge/:path*` so the Figma plugin iframe can reach those routes (scoped — your other routes are untouched)
+- Appends `.inkbridge/` to your `.gitignore` so the scanner-output JSON doesn't show up in every diff
+
+Inkbridge does not modify your ESLint config or any other tooling. The recommended `react/forbid-dom-props` rule for inline styles is suggested in "Recommended lint rules" below, but never written by setup.
 
 ### 2. Load the plugin in Figma Desktop
 
@@ -47,7 +58,7 @@ Figma remembers this path — you only do this once.
 ### 3. Start your dev server
 
 ```bash
-pnpm figma:dev
+pnpm inkbridge:dev
 ```
 
 The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
@@ -60,24 +71,32 @@ The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
 
 ### Generate Design System Page
 
-1. Start dev server: `pnpm figma:dev`
+1. Start dev server: `pnpm inkbridge:dev`
 2. Open any Figma file
 3. **Plugins → Development → Inkbridge → Generate Design System Page**
-4. The plugin scans your Storybook stories and builds a "Design System" page
+4. The plugin scans your Storybook stories and builds a "Design System" page with token tables, themed columns, grouped component sections, and responsive/state preview blocks where relevant
 
 Component data is always scanned live on every run — never stale. Re-run at any time to pick up changes.
 
+For symbol candidates, the generated page renders real Figma component instances instead of only flattened frames:
+
+- CVA components (for example `Button`) render as variant-aware instances.
+- Non-CVA reusable components (for example `Card` compounds) can render as instances too.
+- For compound instances, story text is applied by slot-aware overrides (for example title/description/content) when possible.
+
+When a story instance uses non-default style/behavior props (for example `className`, `disabled`, `aria-invalid`, or unknown props), rendering falls back to direct frames for visual correctness.
+
 ### Manual scan
 
 ```bash
-pnpm figma:scan
+pnpm inkbridge:scan
 ```
 
 Writes `.inkbridge/component-definitions.json`. Useful for debugging scanner output.
 
-### Push to Code (Pro)
+### Push to Code
 
-Requires a Pro license and GitHub configuration.
+Sync token edits from Figma back to your codebase as a GitHub PR.
 
 1. **Plugins → Development → Inkbridge → Settings**
 2. Fill in:
@@ -91,7 +110,6 @@ Requires a Pro license and GitHub configuration.
    - **Allow New Tokens from Figma** — optional; permits creating new token keys on push (off by default)
    - **New Token Prefixes** — optional comma-separated allowlist (for example `chart-, brand-`)
    - **GitHub token** — a [fine-grained PAT](https://github.com/settings/tokens?type=beta) with `Contents` and `Pull requests` read & write
-   - **License key** — from your Inkbridge account
 3. **Save Settings**
 4. **Plugins → Development → Inkbridge → Push to Code**
 5. Enter a commit message and click **Push Tokens to Code** (it auto-detects token changes and opens the PR step)
@@ -115,31 +133,95 @@ Edit `inkbridge.config.json` in your project root:
 |---|---|---|
 | `componentPaths` | auto-detected | Directories to scan for components |
 | `exclude` | `[]` | Directory or file names to skip |
-| `onlyWithStories` | `true` | Only include components with a `.stories.tsx` file |
+| `onlyWithStories` | `true` | Only include components with a `.stories.tsx` or `.stories.ts` file |
 
 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": "Use Tailwind classes — Inkbridge ignores inline styles."
+      }]
+    }],
+    "react/forbid-component-props": ["error", {
+      "forbid": [{
+        "propName": "style",
+        "message": "Use Tailwind classes — Inkbridge ignores inline styles."
+      }]
+    }]
+  }
+}
+```
+
+Skip this rule on any component where Figma rendering doesn't matter
+(e.g. animation-only effects).
+
+---
+
 ## Troubleshooting
 
 ### "Dev server not reachable"
 
 The plugin cannot connect to `localhost:4000`, `:3000`, or `:5173`.
 
-- Make sure `pnpm figma:dev` is running
+- Make sure `pnpm inkbridge:dev` is running
 - Check the terminal for errors in the Next.js server
 - Make sure you're using **Figma Desktop** — the browser version blocks localhost
 
 ### "Create Pull Request" does nothing / no PR opens
 
-- Restart your dev server (`pnpm figma:dev`) so `/api/figma/patch-tokens` is available
+- Restart your dev server (`pnpm inkbridge:dev`) so `/api/inkbridge/patch-tokens` is available
 - Re-import the plugin from `node_modules/inkbridge/manifest.json` after updating
 - Re-open the plugin and retry **Push Tokens to Code**
 
 ### Theme rename/new theme only commits one changed token
 
-- Ensure your project route `src/app/api/figma/patch-tokens/route.ts` is up to date:
+- Ensure your project route `src/app/api/inkbridge/patch-tokens/route.ts` is up to date:
 
 ```bash
 pnpm exec inkbridge setup
@@ -184,15 +266,16 @@ Component data is always scanned live — you only need to update when a new `in
 
 ```
 Figma plugin (sandboxed)
-    └── code.js            Main logic — cannot make network requests directly
-    └── ui.html            Hidden iframe — relays all network requests to code.js
+    └── code.js     Main logic — no direct network access
+    └── ui.html     Hidden iframe — relays I/O for code.js
 
-code.js  →  ui.html  →  localhost:4000/api/figma/scan-components
-                     →  localhost:4000/api/figma/patch-tokens
-                     →  https://api.github.com
+code.js → ui.html → localhost:4000/api/inkbridge/scan-components
+                  → localhost:4000/api/inkbridge/patch-tokens
+                  → https://api.github.com
 ```
 
-All network I/O is relayed through the UI iframe via `postMessage` due to the Figma sandbox restriction.
+All network I/O is relayed through the UI iframe via `postMessage`
+because the Figma plugin sandbox can't make requests directly.
 
 ---