Skip to content

Commit 2cfcb63

Browse files
MarcosldMarcosld
committed
WEB-2413: Improvements
1 parent 23be5f0 commit 2cfcb63

6 files changed

Lines changed: 156 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,37 @@ Explore the components in [Mistica storybook](https://mistica-web.vercel.app)
105105
Start prototyping interfaces with Mistica components in the
106106
[Mística playroom](https://mistica-web.vercel.app/playroom)
107107

108+
## AI / LLM Integration
109+
110+
Mistica ships documentation optimised for AI coding assistants. The package includes a `doc/llms.md` file with
111+
concise component references, critical rules, and links to detailed documentation — all inside `node_modules`.
112+
113+
### Using the skill
114+
115+
If you use any agent that supports skills, you can install the bundled Mistica skill so the agent
116+
automatically reads the right documentation before generating UI code:
117+
118+
```terminal
119+
npx skills add telefonica/mistica-web
120+
```
121+
122+
Once installed, your agent should load the skill whenever you ask it to build Mistica UIs and will consult the
123+
documentation automatically.
124+
125+
### For LLMs reading this file
126+
127+
If you are an AI assistant and `node_modules/@telefonica/mistica` is available in the project:
128+
129+
1. Read `node_modules/@telefonica/mistica/doc/llms.md` — start here, it has critical rules and an overview.
130+
2. Read the specific doc files referenced inside `llms.md` based on the task at hand.
131+
132+
If `node_modules/@telefonica/mistica` is **not** available, fall back to the GitHub repository:
133+
134+
- Main LLM reference: `https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md`
135+
- Components: `https://github.com/Telefonica/mistica-web/blob/master/doc/components.md`
136+
- Layout: `https://github.com/Telefonica/mistica-web/blob/master/doc/layout.md`
137+
- Patterns: `https://github.com/Telefonica/mistica-web/blob/master/doc/patterns.md`
138+
108139
## More docs
109140

110141
- [Examples](https://github.com/Telefonica/mistica-web/tree/master/examples)

‎doc/layout.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,40 @@ The `HeaderLayout` is responsible for render the page header and related compone
325325
|-|-|-|
326326
|<img src="./images/layout/header-layout-mobile.svg" />|<img src="./images/layout/header-layout-tablet.svg" />|<img src="./images/layout/header-layout-desktop.svg" />|
327327

328+
## Components that include ResponsiveLayout internally
329+
330+
The following components manage their own `ResponsiveLayout` internally. **Do not wrap them inside a
331+
`ResponsiveLayout`** — that would create a double-nested layout that breaks spacing and alignment.
332+
333+
| Component | Reason |
334+
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
335+
| `HeaderLayout` | Wraps its header content in a responsive container |
336+
| `MainSectionHeaderLayout` | Contains its own responsive wrapper |
337+
| `Hero` | Manages internal responsive layout for content and media |
338+
| `CoverHero` | Applies responsive layout to its text content column |
339+
| `MasterDetailLayout` | Full-width responsive grid managed internally |
340+
| `ButtonFixedFooterLayout` | Footer buttons aligned via an internal responsive container |
341+
| `NavigationBar` | All navigation bar variants (including `MainNavigationBar` and `FunnelNavigationBar`) center content using an internal `ResponsiveLayout` |
342+
| `Tabs` | Tab list constrained with `ResponsiveLayout fullWidth` |
343+
| `SuccessFeedbackScreen` | All feedback screen variants contain their own page layout |
344+
| `LoadingScreen` | `BrandLoadingScreen` also uses an internal responsive text layout |
345+
346+
These components are placed **directly at the page level**, side by side with `ResponsiveLayout` blocks, not
347+
inside them:
348+
349+
```tsx
350+
<MainNavigationBar sections={[...]} selectedIndex={0} />
351+
<HeaderLayout header={<Header title="Page Title" />} />
352+
<Tabs selectedIndex={0} onChange={setTab} tabs={[{text: 'Tab 1'}, {text: 'Tab 2'}]} />
353+
<ResponsiveLayout>
354+
<Box paddingY={24}>
355+
<Stack space={16}>
356+
<Text2 regular>Content</Text2>
357+
</Stack>
358+
</Box>
359+
</ResponsiveLayout>
360+
```
361+
328362
## GridLayout
329363

330364
A 12-column grid with predefined templates for common page layouts. Must be used inside a `ResponsiveLayout`.

‎doc/llms.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,22 @@
44
> form fields, theming, analytics, and more for building web applications following Telefonica's design
55
> guidelines.
66
7+
## Documentation location
8+
9+
This file is the main entry point. All docs live at:
10+
11+
- **Installed package**: `node_modules/@telefonica/mistica/doc/`
12+
- **GitHub fallback** (use when node_modules is not available):
13+
`https://github.com/Telefonica/mistica-web/tree/master/doc`
14+
15+
If you cannot find a documentation file in `node_modules`, fetch the equivalent file from the GitHub
16+
repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/<filename>`.
17+
718
## Critical Rules
819

920
1. **NEVER hardcode colors.** Always use `skinVars.colors.*` design tokens from `@telefonica/mistica`.
10-
2. **NEVER use raw `<div>` for layout.** Use Mistica layout components: `Box`, `Stack`, `Inline`, `Align`,
11-
`ResponsiveLayout`, `GridLayout`, `Grid`.
21+
2. **Try not to use raw `<div>` for layout.** Use Mistica layout components: `Box`, `Stack`, `Inline`,
22+
`Align`, `ResponsiveLayout`, `GridLayout`, `Grid`.
1223
3. **NEVER set font sizes manually.** Use text components: `Text1`-`Text10`, `Title1`-`Title4`.
1324
4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or Mistica components that handle it
1425
automatically.

‎doc/patterns.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,66 @@ const [selectedId, setSelectedId] = React.useState(null);
236236
</ButtonFixedFooterLayout>
237237
```
238238

239+
## Carousel patterns
240+
241+
`Carousel`, `CenteredCarousel`, and `Slideshow` are **horizontal-scroll** components. Use them when content
242+
needs to be navigated left-to-right (e.g. product cards, promotional banners, image galleries).
243+
244+
### Carousel vs CenteredCarousel vs Slideshow
245+
246+
| Component | Best for | Visible items |
247+
| ------------------ | -------------------------------------------------- | --------------------------- |
248+
| `Carousel` | Card collections, product grids | Configurable per breakpoint |
249+
| `CenteredCarousel` | Featured/highlighted items with neighbour peek | 1 on mobile, 3 on desktop |
250+
| `Slideshow` | Full-width hero banners, autoplay image slideshows | 1 at a time |
251+
252+
### Placement rules
253+
254+
- **`Carousel` and `CenteredCarousel`**: place inside `ResponsiveLayout` so they respect the page grid.
255+
- **`Slideshow`**: place **outside** `ResponsiveLayout` — it bleeds full-width on mobile and tablet
256+
automatically.
257+
258+
```tsx
259+
{
260+
/* Carousel inside ResponsiveLayout */
261+
}
262+
<ResponsiveLayout>
263+
<Box paddingY={24}>
264+
<Stack space={16}>
265+
<Title2 as="h2">Featured products</Title2>
266+
<Carousel
267+
itemsPerPage={{mobile: 1, tablet: 2, desktop: 3}}
268+
withBullets
269+
items={products.map((p, i) => (
270+
<DataCard
271+
key={i}
272+
title={p.name}
273+
description={p.description}
274+
buttonPrimary={
275+
<ButtonPrimary small onPress={() => navigate(p.url)}>
276+
View
277+
</ButtonPrimary>
278+
}
279+
/>
280+
))}
281+
/>
282+
</Stack>
283+
</Box>
284+
</ResponsiveLayout>;
285+
286+
{
287+
/* Slideshow at page level (outside ResponsiveLayout) */
288+
}
289+
<Slideshow
290+
withBullets
291+
autoplay={{time: 5000, loop: true}}
292+
items={[
293+
<CoverCard key="1" imageSrc="/banner1.jpg" title="Offer 1" />,
294+
<CoverCard key="2" imageSrc="/banner2.jpg" title="Offer 2" />,
295+
]}
296+
/>;
297+
```
298+
239299
## Card patterns
240300

241301
### Asset pattern for cards and rows

‎package.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414
"dist-es/**",
1515
"css/**",
1616
"doc/**",
17-
"skills/**",
1817
"community.d.ts",
1918
"community.js"
2019
],

‎skills/mistica/SKILL.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ node_modules/@telefonica/mistica/doc/llms.md
4949
This file contains the critical rules, quick start guide, component categories, design token overview, and
5050
links to all other documentation files.
5151

52+
> **Fallback**: If `node_modules/@telefonica/mistica` is not available, read the equivalent files directly
53+
> from the GitHub repository: `https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md`
54+
5255
### Step 2: Read specific docs based on the task
5356

5457
Based on what the user needs, read the appropriate documentation files:
@@ -105,17 +108,32 @@ These rules MUST be followed in ALL generated code:
105108

106109
10. **Use `small` prop on buttons** inside cards and `EmptyStateCard`.
107110

111+
11. **Do NOT wrap these components in `ResponsiveLayout`** — they already contain one internally:
112+
`HeaderLayout`, `MainSectionHeaderLayout`, `Hero`, `CoverHero`, `MasterDetailLayout`,
113+
`ButtonFixedFooterLayout`, `NavigationBar`, `MainNavigationBar`, `FunnelNavigationBar`, `Tabs`,
114+
`SuccessFeedbackScreen`, `ErrorFeedbackScreen`, `InfoFeedbackScreen`, `LoadingScreen`,
115+
`BrandLoadingScreen`. Place them at page level, side by side with `ResponsiveLayout` blocks.
116+
117+
12. **Use carousels only for horizontal content.** `Carousel` and `CenteredCarousel` are horizontal-scroll
118+
components — always place them **inside** `ResponsiveLayout`. `Slideshow` bleeds full-width automatically
119+
and should be placed **outside** `ResponsiveLayout`.
120+
108121
## Quick Reference
109122

110123
### Standard page structure
111124

112125
```tsx
126+
{/* These components have their own internal ResponsiveLayout — place them at page level */}
113127
<MainNavigationBar sections={[...]} />
114128
<HeaderLayout header={<Header title="Page Title" />} />
129+
{/* Slideshow goes outside ResponsiveLayout — it bleeds full-width automatically */}
130+
<Slideshow items={[...]} />
115131
<ResponsiveLayout>
116132
<Box paddingY={24}>
117133
<Stack space={32}>
118134
<Stack space={16}>{/* section elements */}</Stack>
135+
{/* Carousel and CenteredCarousel go INSIDE ResponsiveLayout */}
136+
<Carousel itemsPerPage={{mobile: 1, tablet: 2, desktop: 3}} items={[...]} />
119137
</Stack>
120138
</Box>
121139
</ResponsiveLayout>

0 commit comments

Comments
 (0)