jfs-components 0.1.50 → 0.1.54

package/.cursor/D2C-FLOW.md

@@ -0,0 +1,94 @@
+# D2C multi-screen orchestration
+
+Load only when scope discovery finds two or more `ScreenSpec`s. The main agent
+is the orchestrator: it owns contracts, shared files, integration, and
+end-to-end QA. Each implementation agent owns exactly one screen family.
+
+## 1. Prepare conflict-free contracts
+
+Before launching agents:
+
+1. Define the transition graph and typed step model.
+2. Define shared props/callbacks, fake data, validation, timing, and persistence.
+3. Create the minimum scaffold: host/navigator, shared types, placeholders.
+4. Assign each family:
+   - one screen file;
+   - uniquely named mode file(s);
+   - `assets/<screen-key>/`.
+5. Only the orchestrator edits the host/shared types. Agents cannot edit other
+   screens or clear shared directories.
+
+Typical recording-demo layout:
+
+```text
+RecordingDemoScreen.tsx    # orchestrator
+types.ts                   # orchestrator
+SignInScreen.tsx           # Sign In agent
+signInModes.json
+assets/sign-in/
+OtpScreen.tsx              # OTP agent
+otpModes.json
+assets/otp/
+```
+
+## 2. Launch one agent per family
+
+After shared ambiguities are resolved and the scaffold exists, launch all
+independent agents in one parallel batch when possible; honor configured model
+preferences. Do not create one agent per state or combine unrelated screens.
+
+Each prompt is self-contained:
+
+```text
+absolute repo path; platform/stack; recording-demo placement
+owned files/directories + explicit do-not-edit list
+original flow URL + parent node
+primary node URL + all variant URLs/state meanings
+purpose + relationship to preceding/following screens
+shared TypeScript contract; input/output/persistence
+resolved fake-data, validation, navigation, timing behavior
+exact jfs-extract-modes commands + output paths
+files/rules/examples to read, including .cursor/D2C-SCREEN.md
+acceptance criteria + required completion summary
+STOP-BEFORE-EDIT rule for material ambiguity
+```
+
+Each agent independently executes `.cursor/D2C-SCREEN.md`, implements only its
+family/local states, runs focused checks, and returns its report.
+
+## 3. Integrate actual deliverables
+
+After all agents finish, inspect files—not only summaries:
+
+1. Confirm all placeholders are replaced and imports/modes/assets exist.
+2. Resolve conflicts, duplicates, missing assets, invalid props, and inconsistent
+   mode merging.
+3. Wire every transition and thread shared data/persistence.
+4. Keep variant states local to the correct family.
+5. Verify Back/Skip/Cancel/retry/resend, CTA states, and terminal paths.
+6. Keep fake flows local; do not add network/server dependencies.
+7. Re-run typecheck/lint/build; separate new failures from existing ones.
+
+## 4. End-to-end QA
+
+Render the complete journey on the target platform:
+
+- reach every terminal path from the intended start;
+- test all forward, Back, Skip, and Cancel branches;
+- test cross-screen validation, persistence, retry/resend, disabled/enabled
+  actions, transient timing, and repeated presses;
+- capture every real screen and materially different state;
+- verify keyboard/numpad, scrolling, sticky footers, and safe areas.
+
+One successful screen is not proof of the flow. Fix integration differences and
+recapture. If tooling is unavailable, report the exact remaining manual QA.
+
+## Completion report
+
+Report briefly:
+
+- detected families and grouped variants;
+- final transition graph and shared/fake-data behavior;
+- files, assets, and mode outputs per screen;
+- checks, paths, and edge cases exercised;
+- per-screen visual status and blockers.

package/.cursor/D2C-SCREEN.md

@@ -0,0 +1,119 @@
+# D2C per-screen execution
+
+Load only after scope discovery provides a `ScreenSpec`. Applies to direct
+single-screen work and each screen agent in a flow.
+
+## 1. Gather evidence
+
+Read the Figma design-to-code skill before Figma calls.
+
+1. `get_design_context` for the primary node and variants needed to understand
+   visual/interactive differences.
+2. `get_screenshot` for the primary and materially different variants; retain
+   them for QA.
+3. `get_metadata` when hierarchy, visibility, assets, or duplicate names need
+   disambiguation.
+4. Follow Code Connect, component docs, annotations, and hidden-layer metadata.
+5. Use exact exported images/icons. Download them into the repository; never
+   commit expiring/localhost URLs, placeholders, hand-authored SVGs, or a new
+   icon package.
+
+If MCP cannot read a required node, report the blocker and stop.
+
+## 2. Extract modes through Figma REST
+
+From the consuming repository:
+
+```bash
+npx jfs-extract-modes "<node-specific-figma-url>" --out "<unique-output>.json"
+```
+
+Fallback:
+
+```bash
+node node_modules/jfs-components/scripts/extract-figma-modes.js \
+  "<node-specific-figma-url>" --out "<unique-output>.json"
+```
+
+Extract a variant separately if selected modes differ from the primary. The CLI
+reads `FIGMA_ACCESS_TOKEN` from root `.env` (exported env wins). Never print it
+or ask the user to paste it into chat. Required scope: `file_content:read`.
+
+If missing, direct the user to `[Open .env](.env)` and add
+`FIGMA_ACCESS_TOKEN=`. Creation path: Figma file browser → account menu →
+Settings → Security → Personal access tokens → Generate; choose expiry and only
+`file_content:read`; copy once into `.env`. Never create/overwrite it yourself.
+[Official PAT docs](https://developers.figma.com/docs/rest-api/personal-access-tokens/).
+
+Resolve modes:
+
+1. Start with `inheritedFromAncestors`.
+2. Collect entries for the component path and its ancestors.
+3. Merge root → leaf; deeper entries override.
+4. Match name/position; use `nodeId` for duplicates.
+
+If `unresolved` exists, report every item/reason and stop:
+
+- `local collection`: packaged data cannot resolve a file-local collection.
+- `key not in variables JSON` / `mode not in collection`: packaged tokens stale.
+
+## 3. Implement
+
+Inspect actual `jfs-components` exports/types and nearby project examples first.
+
+- Implement one screen family; variants are local component state.
+- Use user-specified fake data, validation, navigation, timing, and persistence.
+- Prefer mapped components; primitives only for necessary layout.
+- Apply modes to the closest represented component/subtree. Preserve parent
+  inheritance and child overrides; never flatten, move, substitute, or omit
+  selected modes.
+- Match content, order, visibility, variants, spacing, and assets; omit hidden
+  layers.
+- Never invent a component, prop, or icon.
+
+Component contracts:
+
+- Titles: reproduce line count with `numberOfLines`/`disableTruncation`.
+- SubPage `AppBar`: trailing actions in a Fragment so action gaps apply.
+- Consent + CTA `ActionFooter`: one column child:
+  `<View style={{ flexGrow: 1, minWidth: 0, gap: 8 }}>`.
+- Multiple IMAGE fills: last fill is visually topmost.
+- Icons: exact registry `ic_*` glyph when available; otherwise exact exported
+  asset. Use a packaged substitute only when it clearly matches.
+
+Run focused type/lint checks.
+
+## 4. Visual and interaction QA
+
+Render on the target platform. Recording-demo boots directly into its host.
+Prefer `npm run simulator`, then capture device screenshots.
+
+For the primary and every materially different variant, compare:
+
+- component size, variant, emphasis, color, spacing, and alignment;
+- text content, wrapping, and truncation;
+- icons/images and visibility;
+- AppBar safe area/actions;
+- scrolling/below-fold content;
+- keyboard/numpad and sticky footer/home-indicator clearance.
+
+Exercise applicable behavior:
+
+- empty/partial/complete inputs and validation boundaries;
+- immutable formatting and disabled/enabled CTA;
+- selection, retry/resend, persistence, transient timing, rapid presses;
+- incoming/outgoing navigation callbacks.
+
+Fix differences and recapture. If render tooling is unavailable, do not claim
+visual completion; report the blocker and exact manual verification.
+
+## Return to orchestrator / completion report
+
+Report briefly:
+
+- files, mode outputs, and assets;
+- effective modes;
+- local states and behavior;
+- navigation callbacks/data contract;
+- checks and edge cases exercised;
+- visual status and blockers.

package/.cursor/commands/D2C.md

@@ -0,0 +1,101 @@
+# D2C — Figma to jfs-components
+
+Build the supplied Figma node with `jfs-components`. The link may represent one
+screen, states of one screen, or a complete flow. **Discover scope before
+implementation.**
+
+## Invariants
+
+- User-stated behavior is authoritative. Figma defines visuals and designed
+  states, not unspecified product logic.
+- Use Figma MCP. Never recreate an unreadable design from assumptions.
+- Use real package exports/props and extracted modes. Stop on unresolved modes.
+- Fake demos stay local unless the user explicitly requests a service.
+- This may be recorded: present a clean first implementation. Never mention
+  prior attempts, cached knowledge, mistakes, or “fixes.” Be concise:
+  discover → clarify → execute → verify.
+
+## 0. Input and placement
+
+Use the Figma URL after `/D2C` or in the latest prompt; ask for it if absent.
+
+On mobile, each root must be <Screen> wrapped in in `SafeAreaView`
+(from `react-native-safe-area-context` when the project already uses it,
+otherwise `react-native`) so notches and home indicators are respected — do not
+rely on the host to add it.
+
+## 1. Discover screen families
+
+On the linked node:
+
+1. Read the Figma design-to-code skill; call `get_design_context` with its
+   required skill logging parameter.
+2. Call `get_screenshot` for the complete overview.
+3. Call `get_metadata` to inventory visible screen-sized frames: IDs, names,
+   hierarchy, dimensions, order, and visibility.
+4. Inspect prototype links, annotations, titles, actions, repeated structure,
+   and spatial order. Never infer flow from left-to-right placement alone.
+
+Group every frame into a **screen family**:
+
+- Same family: same user goal/step, major layout, and data model; differences
+  are state (empty/filled/focused/disabled, selected, loading/success/error,
+  OTP progress/resend/invalid, expanded, toast/keyboard, scroll position).
+- Different family: different goal/step, content model, primary interaction,
+  destination, or substantially different layout.
+- If uncertain, inspect children/prototype links; frame names are weak evidence.
+
+Create one internal `ScreenSpec` per family:
+
+```text
+key + purpose
+primary node ID + exact URL
+variant node IDs/URLs + state meaning
+incoming/outgoing transitions (Back/Skip/Cancel/retry included)f
+input/output/shared data
+user-specified behavior
+material unknowns
+```
+
+Before coding, briefly report the family count and grouped variants.
+
+## 2. Clarify once
+
+Ask one consolidated question set only for material behavior not answered by
+Figma, the prompt, or project conventions:
+
+- validation/formatting/immutable prefixes/lengths;
+- fake operation success/failure and error states;
+- initial/terminal screens and Back/Skip/Cancel destinations;
+- backward-navigation persistence;
+- splash/loading/toast/resend/auto-advance timing;
+- platform-specific behavior.
+
+Default cosmetic details only; never invent product logic.
+
+## 3. Route
+
+### One family
+
+Variants are local state, never separate routes.
+
+1. Read `.cursor/D2C-SCREEN.md`.
+2. Execute it directly for the `ScreenSpec`.
+
+### Two or more families
+
+The linked node is a flow.
+
+1. Resolve shared material unknowns before implementation.
+2. Read `.cursor/D2C-FLOW.md`.
+3. Orchestrate one implementation agent per `ScreenSpec`.
+4. Every screen agent must read and execute `.cursor/D2C-SCREEN.md`.
+5. The orchestrator integrates and verifies the entire transition graph.
+
+If a screen agent finds a material unknown, it stops before editing and reports
+the precise question; the orchestrator asks the user and resumes it.
+
+## Completion
+
+Follow the reporting contract in the loaded reference file(s). Keep the final
+report factual and brief.

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.54] - 2026-07-27
+
+- Token / mode resolution pass against Figma Code Connect + Coin Variables:
+  - Tooltip / Slider — `tooltip/radius` / `tooltip/maxWidth` → bound `radius` / `maxWidth`
+  - Nudge — `nudge/radius` → `nudge/borderRadius` (repaired alias target in Coin Variables)
+  - Badge — System intent label color uses published Emphasis tokens; size mode `Badge / Size` → `Badge Size`
+  - Remapped invalid mode keys across Accordion, ActionTile, Button, ButtonGroup, IconButton, IconCapsule, ListItem, PortfolioHero, Avatar consumers, and story Theme leftovers
+- CategoryCard updates (stories / MDX / assets)
+
+---
+
+## [0.1.51] - 2026-07-26
+
+- Packages the Cursor D2C playbooks with the npm release: `.cursor/commands/D2C.md`, `.cursor/D2C-FLOW.md`, and `.cursor/D2C-SCREEN.md` (replacing the removed root `D2C.md` entry in `package.json` `files`).
+- D2C command — mobile roots must wrap `<Screen>` in `SafeAreaView` (no longer assumes a recording-demo host provides it).
+
+---
+
 ## [0.1.50] - 2026-07-25
 
 - Token resolution pass — remapped unresolved `getVariableByName` refs and bad mode keys against Figma Code Connect / Coin Variables (CardCTA, CategoryCard, Checkbox, CircularProgressBarDoted, DonutChartSummary, ProductMerchandisingCard, ProductOverview, Radio, SavingsGoalSummary, SegmentedControl, SegmentedTrack, Slider, Tooltip, StatusHero, CardFeedback).