jfs-components 0.1.35 → 0.1.36

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.34] - 2026-07-21
+
+- `jfs-extract-modes` now automatically loads `FIGMA_ACCESS_TOKEN` from the
+  consuming project's root `.env` without overriding a token exported in the
+  shell. `dotenv` is now an explicit runtime dependency.
+- Simplified `D2C.md` for use as a Cursor slash command: clearer input handling,
+  ancestor-mode inheritance (`inheritedFromAncestors` + path merges), accurate
+  `unresolved` reasons, verify-before-invent component APIs, and practical
+  visual QA (fix implementation diffs; report environment-only diffs).
+- Added focused tests for `.env` precedence and extracted mode diagnostics.
+- Ignore local `.env` / `.env.*` secrets in git (keep `.env.example` allowed).
+
+---
+
 ## [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.

package/D2C.md

@@ -1,118 +1,113 @@
-# D2C — Design to Code (jfs-components)
+# D2C — Design to Code with 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.
+Implement the supplied Figma design using the installed `jfs-components`
+package. Follow all four stages in order.
 
-## Step 1 — Pull the design through the Figma MCP
+## Input
 
-Extract `fileKey` and `nodeId` from the pasted URL
-(`https://www.figma.com/design/<fileKey>/...?node-id=<a>-<b>` → nodeId is
-`<a>:<b>`).
+Use the Figma URL supplied after `/D2C` or in the user's latest message. If no
+Figma URL was supplied, ask for one before doing anything else.
 
-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.
+## 1. Read the design
 
-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.
+1. Call the Figma MCP `get_design_context` for the linked node.
+2. Call `get_screenshot` for the same node. Keep it as the visual reference for
+   final QA.
+3. Follow Code Connect mappings, design annotations, and provided assets. If
+   Figma supplies an image or SVG URL, use it directly; do not create a
+   placeholder or install an icon package.
 
-## Step 2 — Extract the modes (mandatory, never skip)
+If the Figma MCP is unavailable or cannot read the node, report the blocker and
+stop. Do not recreate the design from the URL or from assumptions.
 
-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):
+## 2. Extract and resolve explicit modes
+
+From the consuming project's root, run:
 
 ```bash
-export FIGMA_ACCESS_TOKEN=figd_...
-npx jfs-extract-modes "<the pasted Figma URL>" --out modes.json
+npx jfs-extract-modes "<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:
+The CLI automatically loads `FIGMA_ACCESS_TOKEN` from the project-root `.env`.
+An already exported shell value takes precedence. The token only needs the
+Figma `file_content:read` scope. Never print, log, or ask the user to paste the
+token into chat.
 
-```bash
-node node_modules/jfs-components/scripts/extract-figma-modes.js "<figma-url>" --out modes.json
-```
+If the token is missing, stop and direct the user to `[Open .env](.env)` and
+add `FIGMA_ACCESS_TOKEN=` if needed. To create a token: in Figma's file browser,
+open the account menu → **Settings** → **Security** → **Personal access
+tokens** → **Generate new token**, choose an expiration, grant only
+`file_content:read`, generate it, and copy it immediately into `.env`. Figma
+shows the value only once. Use the
+[official PAT documentation](https://developers.figma.com/docs/rest-api/personal-access-tokens/)
+if the UI has changed. Never create or overwrite a token value yourself.
 
-The output is a flat list — one entry per layer that has explicit modes:
+If the bin is unavailable in a nonstandard monorepo, run:
 
-```json
-{
-  "modes": [
-    { "layer": "Icon Button", "nodeId": "1:10638",
-      "path": "CC / Unsub > AppBar > Slot 2 > Icon Button",
-      "modes": { "Button / Size": "S", "Emphasis": "Low", "AppearanceBrand": "Neutral" } }
-  ]
-}
+```bash
+node node_modules/jfs-components/scripts/extract-figma-modes.js "<figma-url>" --out modes.json
 ```
 
-Rules for using it:
+Resolve the effective modes for each represented component as follows:
 
-- 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.
+1. Start with `inheritedFromAncestors`, when present.
+2. Find every `modes` entry whose `path` is the component's path or an ancestor
+   of it.
+3. Merge those entries from root to leaf; deeper entries override inherited
+   values.
+4. Match by layer name and position, using `nodeId` to disambiguate duplicate
+   names.
 
-## Step 3 — Build the screen
+If `unresolved` is present, report every item and its exact `reason`, then stop
+before implementation because mode fidelity cannot be guaranteed:
 
-Implement with `jfs-components` components, mapping Figma component names to
-library exports.
+- `local collection` means the design uses a file-local collection that the
+  packaged library data cannot resolve.
+- `key not in variables JSON` or `mode not in collection` means the packaged
+  design-token JSON is out of date.
 
-**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 guess or silently omit an unresolved mode.
 
-- 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.
+## 3. Implement
 
-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.
+Before editing, inspect the installed package's exports/types and the consuming
+app's existing screens. Reuse its file placement, navigation, styling, and
+asset conventions. Never invent a `jfs-components` component or prop.
 
-## Step 4 — QA against the design (mandatory, never skip)
+- Prefer mapped `jfs-components` over rebuilding them from primitives.
+- Apply extracted collection/mode pairs exactly through each component's
+  `modes` prop.
+- Put a mode on the closest code component that represents the reported Figma
+  layer or subtree. Preserve parent inheritance and child overrides; never
+  flatten a child override into its parent.
+- Do not substitute similar-looking modes, remove apparently redundant modes,
+  or move modes between layers.
+- Match Figma content, order, visibility, variants, spacing, and assets.
 
-After the screen compiles and renders, you MUST verify it visually against the
-Step 1 screenshot:
+Run the consuming app's existing typecheck, tests, or build command relevant to
+the changed screen and fix implementation errors.
 
-- **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.
+## 4. Render and visually verify
 
-Compare your screenshot with the Figma screenshot side by side. Check:
+Render the implemented screen on the target platform and capture it with the
+available mobile or browser tooling. Compare it with the Figma screenshot for:
 
-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)
+1. component size, variant, and emphasis;
+2. color and appearance;
+3. spacing, padding, alignment, and gaps;
+4. text, wrapping, and truncation; and
+5. icons, imagery, and layer visibility.
 
-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.
+Fix every implementation-caused difference and capture the screen again.
+Platform or environment differences that cannot be fixed in code, such as a
+missing system font or renderer-specific antialiasing, must be identified
+explicitly rather than hidden.
 
-## Summary contract
+If no suitable render or screenshot tooling is available, do not claim visual
+completion. Report what remains to be checked and give the exact manual run and
+comparison steps.
 
-| 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 |
+## Completion report
 
-Report back to the user with: the screen file(s) created, the modes applied per
-layer, and the final QA screenshot comparison.
+Report the files changed, the effective modes applied to each component, the
+validation commands and results, and the final visual comparison status.