diff --git a/README.md b/README.md index 494ad7f273..98cb96d5d7 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,37 @@ Explore the components in [Mistica storybook](https://mistica-web.vercel.app) Start prototyping interfaces with Mistica components in the [Mística playroom](https://mistica-web.vercel.app/playroom) +## AI / LLM Integration + +Mistica ships documentation optimised for AI coding assistants. The package includes a `doc/llms.md` file with +concise component references, critical rules, and links to detailed documentation — all inside `node_modules`. + +### Using the skill + +If you use any agent that supports skills, you can install the bundled Mistica skill so the agent +automatically reads the right documentation before generating UI code: + +```terminal +npx skills add telefonica/mistica-web +``` + +Once installed, your agent should load the skill whenever you ask it to build Mistica UIs and will consult the +documentation automatically. + +### For LLMs reading this file + +If you are an AI assistant and `node_modules/@telefonica/mistica` is available in the project: + +1. Read `node_modules/@telefonica/mistica/doc/llms.md` — start here, it has critical rules and an overview. +2. Read the specific doc files referenced inside `llms.md` based on the task at hand. + +If `node_modules/@telefonica/mistica` is **not** available, fall back to the GitHub repository: + +- Main LLM reference: `https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md` +- Components: `https://github.com/Telefonica/mistica-web/blob/master/doc/components.md` +- Layout: `https://github.com/Telefonica/mistica-web/blob/master/doc/layout.md` +- Patterns: `https://github.com/Telefonica/mistica-web/blob/master/doc/patterns.md` + ## More docs - [Examples](https://github.com/Telefonica/mistica-web/tree/master/examples) diff --git a/doc/components.md b/doc/components.md new file mode 100644 index 0000000000..155f108d4e --- /dev/null +++ b/doc/components.md @@ -0,0 +1,730 @@ +# Components Reference + +All components are imported from `@telefonica/mistica`. + +```tsx +import {ButtonPrimary, Stack, Text2, ...} from '@telefonica/mistica'; +``` + +## Buttons + +### Button variants + +| Component | Usage | +| ------------------ | ------------------------- | +| `ButtonPrimary` | Primary action | +| `ButtonSecondary` | Secondary action | +| `ButtonDanger` | Destructive action | +| `ButtonLink` | Link-styled button | +| `ButtonLinkDanger` | Danger link-styled button | + +### Button interaction props (mutually exclusive) + +- `onPress={() => {}}` -- click handler +- `href="https://..."` -- external link (add `newTab` for target blank) +- `to="/path"` -- client-side navigation (uses configured Link component) +- `submit` -- form submit button (use inside `
`) + +### Button common props + +- `small` -- smaller size +- `disabled` -- disabled state +- `showSpinner` / `loadingText` -- loading state +- `StartIcon` / `EndIcon` -- icon components +- `trackingEvent` -- analytics event +- `trackEvent` -- default analytics tracking + +```tsx + console.log('clicked')}>Action +Open link +Submit form + {}}>Search +``` + +### ButtonGroup + +Groups up to 3 buttons (primary + secondary + link): + +```tsx + {}}>Primary} + secondaryButton={ {}}>Secondary} + link={ {}}>Link} +/> +``` + +### ButtonLayout + +Positions a primary and optional secondary button: + +```tsx + {}}>Continue} + secondaryButton={ {}}>Cancel} +/> +``` + +### IconButton / ToggleIconButton + +```tsx + {}} + Icon={IconSearchRegular} +/> + + +``` + +## Text and Titles + +### Text components + +`Text1` through `Text10` render text at progressively larger sizes. `Text1`-`Text4` accept a `weight` prop. + +Common props: `color`, `truncate`, `textAlign`, `as` (HTML tag), `wordBreak`, `decoration`, `transform`. + +```tsx +Regular body text +Medium body text +Light secondary text +Large display text +``` + +### Title components + +`Title1` through `Title4`. Accept `as` (heading level), `right` (right-side content), `id`. + +```tsx +Page Title + {}}>See all}>Section +``` + +### TextLink + +```tsx +External link +Internal link + {}}>Clickable text +``` + +## Cards + +All cards support touchable props (`onPress`, `href`, `to`), buttons (`buttonPrimary`, `buttonSecondary`, +`buttonLink`), and content props (`headline`, `pretitle`, `title`, `subtitle`, `description`, `slot`). + +### DataCard + +General-purpose card for data display. Supports `size`: `'default'`, `'snap'`, `'display'`. + +```tsx + + + + } + headline={Promo} + title="Card title" + subtitle="Subtitle" + description="Description text" + buttonPrimary={ + {}}> + Action + + } + buttonLink={ + {}}> + Link + + } +/> +``` + +### MediaCard + +Card with image or video media. Supports `mediaPosition`: `'top'`, `'left'`, `'right'`. + +```tsx +Active} + pretitle="Pretitle" + title="Media card title" + description="Description" + buttonPrimary={ + {}}> + Action + + } +/> +``` + +### CoverCard + +Full-bleed image/video background card. Supports `size`: `'default'`, `'display'`. + +```tsx +Featured} + title="Cover card title" + description="Description" + buttonPrimary={ + {}}> + Action + + } +/> +``` + +### NakedCard + +Card without container background. Supports `size`: `'default'`, `'snap'`. + +```tsx + +``` + +### Card in carousels and grids + +```tsx +, + , + , + ]} +/> +``` + +## Lists + +### RowList / Row (unbounded) + +```tsx + + + + + } + title="Row title" + description="Description" + onPress={() => {}} + /> + + {}} /> + +``` + +### BoxedRowList / BoxedRow (boxed container) + +Same API as RowList/Row but rendered inside a boxed container. + +```tsx + + {}} /> + +``` + +### Row variants + +Rows support different right-side controls: + +```tsx + {}}} /> + {}}} /> + {/* Inside RadioGroup */} + {}} /> {/* Auto chevron on press/href/to */} + {}, 'aria-label': 'Delete'}} /> +Detail} /> +``` + +### UnorderedList / OrderedList + +```tsx + + First item + Second item + +``` + +## Navigation + +### MainNavigationBar + +Full app navigation with logo, sections, burger menu on mobile: + +```tsx + {}}, + { + title: 'Products', + onPress: () => {}, + menu: { + columns: [{title: 'Category', items: [{title: 'Item 1', onPress: () => {}}]}], + }, + }, + ]} + right={ + + {}}> + + + + } +/> +``` + +### NavigationBar + +Simple navigation bar with back button: + +```tsx + navigate(-1)} + title="Page Title" + right={ + + {}}> + + + + } +/> +``` + +### FunnelNavigationBar + +For step-by-step flows: + +```tsx + + {}}> + + + + } +/> +``` + +### Tabs + +```tsx +const [selectedIndex, setSelectedIndex] = React.useState(0); + +; +``` + +### NavigationBreadcrumbs + +```tsx + +``` + +## Headers + +### Header + HeaderLayout + +```tsx +} + header={ +
New} + pretitle="Section" + title="Page Title" + description="Page description text" + /> + } + extra={} + sideBySideExtraOnDesktop +/> +``` + +### MainSectionHeader + MainSectionHeaderLayout + +```tsx + + {}}>Action} + /> + +``` + +## Feedback + +### FeedbackScreen variants + +```tsx + {}}>Continue} +/> + + {}}>Retry} +/> + + {}}>Got it} +/> +``` + +### Dialogs (imperative) + +```tsx +import {alert, confirm, useDialog} from '@telefonica/mistica'; + +// Simple alert +alert({title: 'Title', message: 'Message', acceptText: 'OK'}); + +// Confirm dialog +confirm({title: 'Confirm?', message: 'Are you sure?', acceptText: 'Yes', cancelText: 'No'}); + +// Rich dialog via hook +const {dialog} = useDialog(); +dialog({ + title: 'Title', + subtitle: 'Subtitle', + message: 'Message', + extra: , + acceptText: 'Accept', + cancelText: 'Cancel', +}); +``` + +### Snackbar + +```tsx +const {openSnackbar} = useSnackbar(); + +openSnackbar({ + message: 'Item saved', + type: 'INFORMATIVE', + buttonText: 'Undo', + withDismiss: true, +}); +``` + +## Empty states + +```tsx + {}}>Search again} +/> + +} + title="Empty section" + description="Nothing here yet" + button={ {}}>Add item} +/> +``` + +## Loading states + +### Skeletons + +```tsx + {/* Single line placeholder */} + {/* Multi-line paragraph placeholder */} + {/* Circle placeholder (avatar) */} + {/* Circle + line (list item) */} + {/* Rectangle placeholder */} +``` + +### LoadingScreen / BrandLoadingScreen + +```tsx + + +``` + +### Spinner + +```tsx + +``` + +## Other components + +### Tag + +```tsx +Promo +Success +Error +``` + +Types: `'promo'`, `'info'`, `'active'`, `'inactive'`, `'success'`, `'warning'`, `'error'`. + +### Chip + +```tsx + {}}>Closeable chip +Active toggle + {}}>Filter +``` + +### Badge + +```tsx + + + +``` + +### Callout + +```tsx +} + button={ + {}}> + Action + + } + onClose={() => {}} +/> +``` + +### Hero + +```tsx +} + headline={New} + pretitle="Welcome" + title="Hero Title" + description="Hero description" + button={ {}}>Get started} + desktopMediaPosition="right" +/> +``` + +### Carousel / Slideshow + +```tsx + )} +/> + + +``` + +### Avatar + +```tsx + + + +``` + +### Image / Video + +```tsx + + +