jfs-components 0.1.32 → 0.1.33

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.1.33] - 2026-07-20
+
+- **Use [`D2C.md`](./D2C.md) for Design-to-Code.** This is the playbook we want agents and consumers to follow when implementing a Figma screen with `jfs-components`. It ships in the npm package (see `package.json` `files`) so it is available at `node_modules/jfs-components/D2C.md` after install. The workflow is mandatory end-to-end: Figma MCP (`get_design_context` + `get_screenshot`) → mode extraction via `npx jfs-extract-modes` (REST API; Dev seat / file-read token is enough) → build with exact modes → visual QA against the Figma screenshot. Point Cursor rules / agent instructions at this file rather than inventing a parallel D2C process.
+- Packages `D2C.md` alongside the `jfs-extract-modes` CLI so the guide and the tool travel together in every release.
+
+---
+
+## [0.1.32] - 2026-07-20
+
+- Added `jfs-extract-modes` — a CLI shipped with the npm package (`bin` + `scripts/extract-figma-modes.js`) that extracts explicit Figma variable modes per layer via the **Figma REST API** only (one `GET /v1/files/:key` call). No Plugin API, so it works with a **Dev seat** (or any token with file read access) — you do not need an edit / full design seat. After installing `jfs-components`, run `npx jfs-extract-modes <figma-url>` (or `npm run extract-modes` in this repo) with `FIGMA_ACCESS_TOKEN` set. Optional `--add-keys` patches collection keys into the packaged variables JSON for library maintainers.
+- Packaged `Coin Variables-variables-full.json` updated with collection keys so mode resolution is collection-key exact for consumers.
+- `ValueBackMetric` — new optional `onPress` / `disabled` props make the whole card pressable (`Pressable` + `accessibilityRole="button"`), independent of the bottom link’s `onLinkPress`.
+- Regenerated `figma-modes.generated.ts` (adds `HelloJioInput` modes) and icon registry timestamp.
+
+---
+
 ## [0.1.31] - 2026-07-15
 
 - Added `CategoryCard` — compact category rail tile (`categoryCard/*` tokens) with image (or `imageSlot`), optional overlapping `Badge`, fixed 60dp width (overridable via `width`), and `active` / `disabled` press states. Label truncation mirrors `Text` via `disableTruncation` / `singleLine`.

package/D2C.md

@@ -0,0 +1,118 @@
+# D2C — Design to Code (jfs-components)
+
+You are implementing a screen from a Figma design using the `jfs-components`
+library. The user has pasted a Figma link. Follow this workflow exactly, in
+order. Do not skip steps and do not improvise substitutes for them.
+
+## Step 1 — Pull the design through the Figma MCP
+
+Extract `fileKey` and `nodeId` from the pasted URL
+(`https://www.figma.com/design/<fileKey>/...?node-id=<a>-<b>` → nodeId is
+`<a>:<b>`).
+
+1. Call `get_design_context` for the node. This gives you the component
+   structure, layout, props, variants, text content, and Code Connect hints.
+2. Call `get_screenshot` for the same node and keep the image. This is the
+   visual ground truth you will QA against in Step 4.
+
+The Figma MCP gives you almost everything — except one thing: the **variable
+modes explicitly set on each layer**. Those are invisible to the MCP and they
+change how components render (size, emphasis, appearance, color mode, etc.).
+That is what Step 2 is for.
+
+## Step 2 — Extract the modes (mandatory, never skip)
+
+Run the mode extractor that ships with this package. It needs a Figma personal
+access token with plain file-read access (a view-only / Dev seat token works;
+no Enterprise scopes, no edit access):
+
+```bash
+export FIGMA_ACCESS_TOKEN=figd_...
+npx jfs-extract-modes "<the pasted Figma URL>" --out modes.json
+```
+
+If `npx` cannot find the bin (e.g. unusual monorepo setup), call the script by
+its path inside the installed package:
+
+```bash
+node node_modules/jfs-components/scripts/extract-figma-modes.js "<figma-url>" --out modes.json
+```
+
+The output is a flat list — one entry per layer that has explicit modes:
+
+```json
+{
+  "modes": [
+    { "layer": "Icon Button", "nodeId": "1:10638",
+      "path": "CC / Unsub > AppBar > Slot 2 > Icon Button",
+      "modes": { "Button / Size": "S", "Emphasis": "Low", "AppearanceBrand": "Neutral" } }
+  ]
+}
+```
+
+Rules for using it:
+
+- Children inherit ancestor modes unless they set their own. To get the
+  effective modes of any layer, merge every entry whose `path` is a prefix of
+  that layer's path, top-down.
+- Correlate entries with the Figma MCP structure by layer name and position;
+  use `nodeId` when two layers share a name.
+- If the output contains an `unresolved` array, STOP and report it to the user
+  before building. It means the packaged variables JSON is out of date and the
+  screen cannot be built faithfully. Do not guess missing modes.
+
+## Step 3 — Build the screen
+
+Implement with `jfs-components` components, mapping Figma component names to
+library exports.
+
+**Modes are non-negotiable.** Apply every extracted mode exactly as given —
+collection name → mode name, on exactly the layer (or subtree) the extractor
+reported. There is zero tolerance for inconsistency here:
+
+- Do not substitute a "close enough" mode (`Emphasis: Medium` is not
+  `Emphasis: Low`).
+- Do not drop modes that seem redundant — if the design sets
+  `AppearanceBrand: Neutral` on one Icon Button and `Appearance: Primary` on
+  another, those are different and intentional.
+- Do not apply a child's modes to its parent or vice versa.
+
+For everything else (spacing, order, text, icons, variants, props), follow the
+Figma MCP output one-to-one. Reuse existing screens in the consuming app as
+convention references for file placement, navigation registration, and asset
+handling.
+
+## Step 4 — QA against the design (mandatory, never skip)
+
+After the screen compiles and renders, you MUST verify it visually against the
+Step 1 screenshot:
+
+- **Native app:** use the mobile MCP — launch the app, navigate to the new
+  screen, and take a screenshot (`mobile_take_screenshot`).
+- **Web deployment:** use the browser tooling — navigate to the deployed/dev
+  URL and take a screenshot.
+
+Compare your screenshot with the Figma screenshot side by side. Check:
+
+1. Component sizes and emphasis levels (these are where wrong modes show up)
+2. Colors / appearance (brand vs neutral vs secondary treatments)
+3. Spacing, padding, and gaps
+4. Text content and truncation
+5. Icon choices and visibility (some layers in the design are hidden)
+
+If there is ANY visible difference, fix it and re-screenshot. Repeat until the
+implementation matches the design. Typical root causes, in order of
+likelihood: a mode applied to the wrong layer, a missing mode (falling back to
+the collection default), a wrong variant, a wrong icon.
+
+## Summary contract
+
+| Step | Tool | Skippable? |
+|---|---|---|
+| Design context + screenshot | Figma MCP | No |
+| Mode extraction | `npx jfs-extract-modes` | No |
+| Build | jfs-components | — |
+| Visual QA loop | Mobile MCP or browser | No |
+
+Report back to the user with: the screen file(s) created, the modes applied per
+layer, and the final QA screenshot comparison.