Conversation
|
Size stats
|
|
Deploy preview for mistica-web ready!
Deployed with vercel-action |
|
Accessibility report ℹ️ You can run this locally by executing |
Marcosld
requested review from
AlexandraGallipoliRodrigues,
atabel,
aweell,
ieduardogf and
yceballost
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Mistica’s documentation (patterns/layout/components) to improve LLM-generated React code, specifically by encouraging idiomatic layout composition using Inline expand and avoiding raw flexbox/style workarounds.
Changes:
- Added
Inline expandguidance and “common mistakes” explanations to steer models away from flexbox div wrappers. - Documented
Box widthas a fixed-width sibling pattern alongsideInline expand. - Updated the components reference with a rule to consult
.d.tsdefinitions before using components.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| doc/patterns.md | Adds DO/DON’T guidance for using Inline expand instead of raw flexbox/style hacks. |
| doc/layout.md | Expands layout docs with Box width example and a new Inline “Grow” section describing expand usage and pitfalls. |
| doc/components.md | Adds a new rule instructing readers/agents to consult .d.ts files for prop/JSDoc context. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### DO: Fill remaining horizontal space with `Inline` `expand` | ||
|
|
||
| To make a row child grow into the leftover width next to a fixed-width sibling , use `Inline`'s `expand` prop |
Comment on lines
+116
to
+120
| // ❌ raw flexbox div — breaks; Inline already wraps each child in a div | ||
| <div style={{display: 'flex'}}> | ||
| <div style={{flex: 1}}>...</div> | ||
| <div style={{flex: '0 0 394px'}}>...</div> | ||
| </div> |
Comment on lines
+170
to
+172
| ### Grow | ||
|
|
||
| Use the `expand` prop to make one or more children of an `Inline` grow to fill the remaining horizontal space. |
Comment on lines
+173
to
+175
| It takes the index (or an array of indexes) of the children that should grow. Indexes follow | ||
| `React.Children.toArray` order, so empty nodes (`null`, `false`) are skipped but rendered elements always | ||
| count. You don't wrap the growing child in anything — `Inline` already wraps every child in its own element: |
Comment on lines
+201
to
+203
| `<div style={{flex: 1}}>` (or `flex-grow`) does nothing useful. Neither does `<Box style={{...}}>` — `Box` has | ||
| no `style` prop, so a flex or width passed that way is silently dropped and the row collapses or overflows its | ||
| container. Reach for `expand` (and `<Box width={N}>` for any fixed sibling) instead. |
| # Components Reference | ||
|
|
||
| All components are imported from `@telefonica/mistica`. | ||
| All components are imported from `@telefonica/mistica`. Before using any component, you should **always** read the definition .d.ts files located in `node_modules` so you have all the props and JSDoc context. |
ieduardogf
approved these changes
May 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduction
The objective of this task was investigating if we needed new doc to cover the Inline new prop
expanded. In order to do so we added some new rules to the doc and tested it against the pristine mistica version with JSDoc only.We tested a single Figma design (iPhone 14 product detail page) 6 times: 3 runs with the MODIFIED doc folder live and 3 runs with the PRISTINE published
@telefonica/mistica@16.63.1doc folder swapped in. All 6 iterations were independent freshclaude -p --permission-mode auto --model claude-opus-4-7processes of the same prompt — each one read themistica-reactskill, called Figma MCP on the root frame and its sub-sections, then wrote a single React component. Auto-memory was permanently deleted before the runs (a prior pass was discarded after we found the user's auto-memory already encoded the same rules — that's a confounder).Summary
Across 6 runs on the same design, MOD docs produced consistent, idiomatic Mistica layout code; PRI docs produced inconsistent results — half the time correct, half the time the
<div style={{flex:1}}>anti-pattern the new rules target. The differentiator was specifically theInline expandAPI usage and the avoidance of raw flex/style fallbacks, not visual fidelity (both arms render the page faithfully).Patterns
MainNavigationBar,NavigationBreadcrumbs,ResponsiveLayout,GridLayout,Slideshow,Image,Tag,Title1/4,Text2/3/7,InfoRating,RadioGroup,BoxedRow/BoxedRowList,Chip,ButtonPrimary,TextLink,MediaCard,Tabs,Accordion/AccordionItem,ProgressBar,Box,Stack,Inline,skinVars, plus the same set of icons.Inline expandadoption is the cleanest discriminating signal — 3/3 MOD, 1/3 PRI. All three MOD runs used<Inline … expand={N}>for the rating-distribution rows. Only one of three PRI runs did; the other two fell back to<div style={{flex:1, …}}>/<div style={{flexGrow:1}}>nested inside anInline— exactly the silent-no-op the newlayout.md"common mistakes" call-out warns about.<Box width={N}>is only triggered by the docs — 6 sites across MOD, 0 sites across PRI. Every MOD run used<Box width={80}>(orwidth={90}) for the fixed label column next to aProgressBar. No PRI run used aBox widthanywhere — they either inlined<div style={{width:80, flexShrink:0}}>or fell back tospace="between"and let the layout breathe.expandexists (it's indist/inline.d.ts: expand?: number | ReadonlyArray<number>, and Mistica is public on GitHub). So PRI isn't a "no knowledge" baseline — the prop is in the typed API surface. The docs aren't teaching the prop; they're putting it (and the worked example) in front of the agent during the task, which is what makes adoption reliable.Random failures
Despite identical prompts and identical context, the iterations fail in different places:
Slideshow, one pickedCarousel(per its own justification of containment). Both are valid Mistica primitives.Methodology
claude -psubprocesses with the MODIFIED doc folder live innode_modules/@telefonica/mistica/doc/. Each independently:mistica-reactskill and called Figma MCP on the root frame and sub-sections.node_modules/.../doc/with the PRISTINE published@telefonica/mistica@16.63.1docs. Repeated with 3 fresh subprocesses. Restored the modified docs afterwards.ProductPage.tsxwas mounted in a wrapperThemeContextProvider(Movistar New skin), built with Vite (base: './', no dev server), served on a unique localhost port, and captured by Playwright/Chromium at 1368 px wide, full page, 2× DPR.<Inline,expand=, raw flex-div lines (<div … flex/flexGrow/flexShrink/flex:N),<Box width={, and inline-style layout hacks (style={{…}}excludingcursor:'pointer').Iterations
Pair 1 — MOD_1 vs PRI_1
<Inline expand={N}>for rating rowsexpandprobably from.d.ts)<div … flex/flexGrow/flexShrink>lines<Box width={N}>for fixed label columnstyle={{…}}Box width)Net. Visual tie, both clean code-wise. PRI1 is the one PRI run that reached for
expandon its own — likely from the typed API indist/inline.d.ts. It still skipped<Box width={N}>for the fixed label column (handled the fixed width implicitly viaInline space=…), which only the docs trigger. This pair is the _best case for PRI: when the model happens to spelunk the.d.ts, it gets close to MOD.Pair 2 — MOD_2 vs PRI_2
<Inline expand={N}>for rating rows<div style={{flex:1}}>anti-pattern<div … flex/flexGrow/flexShrink>lines<div style={{width:80, flexShrink:0}}>,<div style={{flexGrow:1, minWidth:0}}>,<div style={{width:40, flexShrink:0}}>on the rating-distribution rows<Box width={N}>for fixed label columnstyle={{…}}Net. In the rating-distribution row, MOD_2 wrote
<Inline … expand={1}><Box width={80}>…<ProgressBar/></Inline>and PRI_2 wrote three raw<div style={{…}}>wrappers nested inside anInline— the canonical anti-pattern the newpatterns.mdDO/DON'T documents. This is the headline contrast.Pair 3 — MOD_3 vs PRI_3
<Inline expand={N}>for rating rows<div … flex/flexGrow/flexShrink>lines<Box width={N}>for fixed label columnstyle={{…}}Net. PRI_3 reached for raw flex divs and inline width styles for the rating rows; MOD_3 used the documented
Inline expand+Box widthpattern. Visually MOD_3 is slightly worse (its images didn't bundle)Results
Rule-adherence at a glance
Counts across the 6 runs' main
ProductPage.tsx(PRI_1is structured as a full vite app, so its main file is atsrc/ProductPage.tsx):<Inlineexpand=<Box width={<Inline … expand={N}>for growing children<div … flex/flexGrow/flexShrink><Box width={N}>for fixed-width siblingsstyle={{…}}layout hacksRun metadata
Conclusions
expandis — it's in the typed API surface (dist/inline.d.ts), but sometimes agents don't read that files. This effect seems to be especially strong when there's doc available through a skill like in mistica.expandprop when doc is available (3/3 MOD vs 1/3 PRI forexpand, 0 layout style hacks for MOD vs 7 for PRI), and small-to-zero on visual fidelity (both arms render the page faithfully). The benefit is code quality and maintainability, not what an end user sees.<Box width={N}>is only used when documented. 6 sites across MOD, 0 across PRI. Thelayout.mdfixed-width example is the trigger. When not documented agents tend to use divs..d.tsfirst" rule is the structural lever. It's the one that explains why PRI_1 succeeded — the agent independently spelunked the type definitions and discoveredexpand. Codifying that as default behaviour (which the modifiedcomponents.mddoes) is what would make PRI behave like MOD. Worth keeping in the docs even though we can't score it from artifacts.