chore(Skill): read Mística Figma grid layouts into GridLayout/ResponsiveLayout

[aweell]

Summary

Teaches the mistica-react skill to read the layouts the updated mistica-figma skill produces, so a design built with the new Figma conventions is implemented with GridLayout / ResponsiveLayout instead of raw Grid/flex divs.

The mistica-figma skill builds sections as native 12-column GRID frames (column spans + template naming) and full-width padded ResponsiveLayout frames. The reading path (doc/llms/figma-mcp.md) predates this and was written against the older flex/Tailwind MCP output — it had no GridLayout row and no guidance for the grid/section conventions. The mapping rules here are grounded in the real Figma MCP DOM (grid grid-cols-[repeat(12,minmax(0,1fr))] + col-[start/span_N]) and verified against the @telefonica/mistica source (GridLayout templates, the Variant enum, the ResponsiveLayout wrap requirement).

Changes

• doc/llms/figma-mcp.md — mapping-table rows for the plain ResponsiveLayout section, the grid grid-cols-[repeat(12,…)] section, and col-[S/span_N] children; a "Reading grid sections" subsection with a child-span → template lookup (6+6, 8+4, 4+6, 3+9, 5+4, 10, 8), the wrap rule (ResponsiveLayout = side margins only, GridLayout = columns), px→margin / py→Box, background→variant, mobile collapse, and a worked 3+9 example.
• doc/llms/agents/figma-verifier.md — flag raw grid/flex/Grid/spacers used instead of a span-matched GridLayout, an unwrapped GridLayout, a padded section without ResponsiveLayout, and double-wrapped nav/tabs.

Validation (A/B test per TESTING-MISTICA-SKILL.md)

claude-opus-4-8, 3 runs/arm, isolated workspaces differing only in these two files, same byte-for-byte prompt against a Figma frame with a 6+6 hero and a 3+9 sidebar+table.

Dimension	Baseline	Modified
Correct GridLayout template usage	2/3 runs	3/3 runs
Primitive compliance / pixel parity / tokens / time	100% / faithful / —	100% / faithful / no meaningful change

The baseline failure run hand-built the split with low-level Grid/GridItem + non-responsive hardcoded paddingX={48} (still "Mistica primitives", so compliance and the desktop screenshot did not flag it). The modified arm reliably used the semantic GridLayout templates. No regression in tokens, cost, latency, or fidelity.

🤖 Generated with Claude Code

[github-actions]

Size stats

	master	this branch	diff
Total JS	17 MB	17 MB	0 B
JS without icons	2.07 MB	2.07 MB	0 B
Lib overhead	96.3 kB	96.3 kB	0 B
Lib overhead (gzip)	21.1 kB	21.1 kB	0 B

[Copilot]

Pull request overview

Updates the LLM-facing Figma→Mistica reading guidance so that 12-column GRID sections produced by the newer mistica-figma conventions are implemented with semantic ResponsiveLayout + GridLayout (including template selection) rather than low-level grid/flex constructs.

Changes:

• Extends doc/llms/figma-mcp.md with explicit mapping rules for full-width padded sections, 12-col grid sections, and col-[start/span_N] children, plus a “Reading grid sections” template-lookup and worked example.
• Extends doc/llms/agents/figma-verifier.md with new verification checks that enforce using GridLayout templates and correct ResponsiveLayout wrapping (and avoiding double wrapping for components that embed it).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
doc/llms/figma-mcp.md	Adds updated mapping table + detailed guidance for reading 12-col grid sections into ResponsiveLayout/GridLayout.
doc/llms/agents/figma-verifier.md	Adds verifier rules to flag incorrect layout primitive usage and missing/extra ResponsiveLayout wrapping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aweell]

A/B test report — mistica-react skill: Figma grid-layout reading

Date: 2026-06-30. Methodology: TESTING-MISTICA-SKILL.md (PR #1574).
Figma reference: https://www.figma.com/design/MwDPGBvhUkRlYlrcDo1PT1/Mistica-figma-skill-layout-test?node-id=300-867&t=9D4gUDcbShuaETVO-1

TL;DR verdict

Dimension	Baseline (no-*)	Modified (with-*)	Verdict
Grid-structure correctness	2/3 runs used GridLayout templates; 1/3 hand-built the split with low-level Grid/GridItem + hardcoded paddingX={48}	3/3 runs used GridLayout template="6+6" (Hero) and "3+9" (Data Section)	Modified win
GridLayout JSX usages (mean, range)	1.33 (0–2)	2.0 (2–2)	Modified win (consistency)
template= props (mean, range)	1.33 (0–2)	2.0 (2–2)	Modified win
Mistica primitive compliance ratio	1.000	1.000	Tie (both perfect)
Raw HTML / hex / inline-style / raw-px	0 / 0 / 0 / 0	0 / 0 / 0 / 0	Tie (both clean)
Pixel parity @1440 (1–5, subjective)	~5	~5	Tie
Input-side tokens (mean)	2,060,591	2,046,436	Tie (−0.7%, noise)
Output tokens (mean, range)	17,184 (10,896–22,876)	17,666 (16,884–18,786)	Tie; modified far tighter
Cost USD (mean, range)	$2.77 ($2.26–3.34)	$2.59 ($2.44–2.70)	Tie; modified tighter
Wall-clock s (mean, range)	275 (177–364)	280 (277–284)	Tie; modified tighter

Headline: the change improves grid-structure correctness and run-to-run consistency — it eliminates the
observed failure mode of hand-building the 12-column split at the wrong altitude — at no measurable cost
in tokens, time, or visual parity.

Methodology

• Single variable under test: the two files of the Part A skill change overlaid into the modified arm's
  node_modules/@telefonica/mistica/doc/llms/ — figma-mcp.md (grid-reading table rows + "Reading grid
  sections" subsection) and agents/figma-verifier.md (layout structural checks). Baseline = the published
  16.68.0 docs (identical to repo HEAD; confirmed INSTALLED==HEAD). Single-variable check: diff -rq
  between a baseline and a modified workspace's doc/llms reported only those two files differing;
  baseline contains 0 occurrences of "Reading grid sections", modified contains it.
• Task prompt (byte-for-byte identical, all 6 runs): see prompt.txt — implement the Figma frame
  MwDPGBvhUkRlYlrcDo1PT1 node 300:867 ("Dashboard/Desktop") into src/App.tsx, build must pass, skip any
  optional verifier loop (constant applied to both arms).
• Model (fixed): claude-opus-4-8 (1M context) for every run.
• n: 3 runs per arm, 6 total. Arms interleaved (no-1, with-1, no-2, with-2, no-3, with-3) to spread any
  API-load drift across both arms.
• Isolation: 6 APFS copy-on-write clones of one base Vite + React + TS app (@telefonica/mistica@16.68.0,
  skill mounted at .claude/skills/mistica-react). Outside the developer repo. Figma plugin/MCP is globally
  enabled, so headless claude -p inherits it (verified via a smoke test returning the correct frame name).
• Measurement: run-level metrics from the terminal result event of each persisted stream-json
  (runs/<ws>.jsonl); static analysis of generated src/*.tsx (excluding main.tsx boilerplate) via
  measure.mjs; wall-clock from driver timestamps (runs/<ws>.meta).
• Reproduction artefacts: setup_workspaces.sh, prompt.txt, run_ab.sh, measure.mjs,
  render_shots.sh, metrics.json, runs/, shots/.

Per-run data

Baseline (no-*)

run	input	cache read	cache create	output	cost	wall	GridLayout	template=	ResponsiveLayout	compliance
no-1	11,252	2,536,055	144,712	22,876	$3.34	364s	2	2	5	1.0
no-2	28,097	1,387,652	114,741	10,896	$2.26	177s	2	2	5	1.0
no-3	21,859	1,812,181	125,223	17,781	$2.71	285s	0	0	3	1.0

Modified (with-*)

run	input	cache read	cache create	output	cost	wall	GridLayout	template=	ResponsiveLayout	compliance
with-1	18,563	1,953,772	116,442	18,786	$2.70	280s	2	2	5	1.0
with-2	11,246	2,111,962	107,311	17,329	$2.62	284s	2	2	5	1.0
with-3	18,562	1,693,485	107,964	16,884	$2.44	277s	2	2	5	1.0

Token volume is overwhelmingly cache reads on the input side (>98%); the "fewer tokens" question is a wash
once decomposed, consistent with the methodology's caution.

The baseline failure mode (no-3)

Instead of the semantic GridLayout template, no-3 reproduced the Figma grid-cols-12 / col-span DOM
literally with the low-level primitive and hardcoded responsive padding:

<ResponsiveLayout fullWidth>
  <Box paddingX={48} paddingY={32}>
    <Grid columns={12} gap={24}>
      <GridItem columnSpan={3}><FilterPanel /></GridItem>
      <GridItem columnSpan={9}><Table … /></GridItem>
    </Grid>
  </Box>
</ResponsiveLayout>

This still scores compliance = 1.0 (Grid/GridItem are Mistica components), and at desktop 1440 it
renders pixel-equivalent — so neither the compliance metric nor the screenshot flags it. The defect is
altitude and responsiveness: the hardcoded paddingX={48} does not shrink to 16 px on mobile the way
ResponsiveLayout margins do, and the template name (3+9) is lost. All three modified runs avoided this.

Screenshot gallery

	baseline	modified
run 1
run 2
run 3

All six faithfully reproduce the reference layout (6+6 hero with four KPI cards, 3+9 filter-sidebar + table,
nav, footer). Cosmetic-only variation: invented vs. literal (HRow cell) table data, KPI-card vertical gap,
and with-3 adding nav sections — none attributable to the variable under test.

Interpretation

• Measured effect: the change makes correct GridLayout template usage reliable (3/3 vs 2/3) and removes
  the hand-built-grid failure path. It also tightened output-token, cost, and wall-clock variance.
• Artefact, not effect: the baseline already used GridLayout in 2/3 runs because layout.md (read in
  every run) documents the templates. So this change raises reliability, not capability from zero. With
  n=3 the failure-rate reduction (1/3 → 0/3) is suggestive, not statistically tight.
• No regression: tokens, cost, time, and pixel parity are ties; the modified arm is never worse.

[github-actions]

Deploy preview for mistica-web ready!

Project:	mistica-web
Status:	✅  Deploy successful!
Preview URL:	https://mistica-auj6bdglm-flows-projects-65bb050e.vercel.app
Latest Commit:	54b92c7

Deployed with vercel-action

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[github-actions]

Accessibility report
✔️ No issues found

ℹ️ You can run this locally by executing yarn audit-accessibility.