diff --git a/.github/workflows/deploy-master.yml b/.github/workflows/deploy-master.yml index 175ca3a67c..19aa0f286d 100644 --- a/.github/workflows/deploy-master.yml +++ b/.github/workflows/deploy-master.yml @@ -19,7 +19,7 @@ jobs: with: persist-credentials: false - - uses: amondnet/vercel-action@master + - uses: amondnet/vercel-action@v41.1.4 # Pinned because v42 fails with "Error: Provided path ./ is not absolute" with: github-token: ${{ secrets.GITHUB_TOKEN }} # needed to allow comments on prs vercel-token: ${{ secrets.VERCEL_TOKEN }} # Required diff --git a/.github/workflows/deploy-pull-requests.yml b/.github/workflows/deploy-pull-requests.yml index bd80c44479..098d8149fd 100644 --- a/.github/workflows/deploy-pull-requests.yml +++ b/.github/workflows/deploy-pull-requests.yml @@ -24,7 +24,7 @@ jobs: - run: sed -i 's/yarn vercel-build/yarn vercel-preview-build/' vercel.json shell: bash - - uses: amondnet/vercel-action@master + - uses: amondnet/vercel-action@v41.1.4 # Pinned because v42 fails with "Error: Provided path ./ is not absolute" id: vercel-deploy # identifier to reference this step with: github-token: ${{ secrets.GITHUB_TOKEN }} # needed to allow comments on prs diff --git a/doc/llms.md b/doc/llms.md index 67da26a037..dff26f7598 100644 --- a/doc/llms.md +++ b/doc/llms.md @@ -279,7 +279,42 @@ All tokens via `skinVars` from `@telefonica/mistica`: - **Spacing**: `skinVars.spacing.*` (button, card, input, tag, feedback, hero, header, drawer padding tokens) - **Text presets**: Handled by text components, not accessed directly -## Docs +## How to use this documentation + +Follow these steps before writing any code. + +### Step 1: Read the minimum required docs (ALWAYS required) + +**You MUST always read these four files before doing anything else**, regardless of the task. They provide the +foundational knowledge needed to use the library correctly: + +| File | Why it is required | +| ---------------------------------- | ------------------------------------------------------------------- | +| `doc/patterns.md` (**start here**) | Page composition, layout rules, color rules, and common UI patterns | +| `doc/components.md` | Full component catalog with props and usage examples | +| `doc/layout.md` | All layout primitives and page layout components | +| `doc/design-tokens.md` | skinVars colors, rawColors, border radii, spacing, text presets | + +Do not skip any of these four files and do not read them partially — **always read each one in full**. They +are the minimum required context for every task. + +### Step 2: Read additional docs based on the task + +After reading the minimum set, read any further files that apply to your specific task: + +| Task | Read this file | +| ------------------------------------------------- | ------------------------ | +| **Forms** | `doc/forms.md` | +| **Theme configuration (customize skin)** | `doc/theme-config.md` | +| **Sheets / bottom sheets** | `doc/sheet.md` | +| **Analytics tracking** | `doc/analytics.md` | +| **Fonts setup** | `doc/fonts.md` | +| **Custom text tokens** | `doc/texts.md` | +| **Testing (read if you have to implement tests)** | `doc/testing.md` | +| **Migrating from older versions** | `doc/migration-guide.md` | +| **Optimizing bundle size with lottie** | `doc/lottie.md` | + +## Docs reference - [Components reference](./components.md): full component catalog with props and usage examples - [Design tokens](./design-tokens.md): skinVars colors, rawColors, applyAlpha, border radii, spacing tokens, diff --git a/doc/patterns.md b/doc/patterns.md index c4d9638539..e42bcd8dd2 100644 --- a/doc/patterns.md +++ b/doc/patterns.md @@ -6,8 +6,8 @@ `@telefonica/mistica`. For skins and theme-level customization, see [theme-config.md](./theme-config.md). 2. **NEVER use raw `
` for layout.** Use `Box`, `Stack`, `Inline`, `ResponsiveLayout`, `GridLayout`, `Grid`. -3. **NEVER set font sizes manually.** Use text components (`Text1`-`Text10`, `Title1`-`Title4`). If those don't - cover your necessities you can set custom sizes with `Text` component. +3. **NEVER set font sizes manually.** Use text components (`Text1`-`Text10`, `Title1`-`Title4`). If those + don't cover your necessities you can set custom sizes with `Text` component. 4. **NEVER set border radius manually.** Use `skinVars.borderRadii.*` or components that handle it (`Boxed`, cards, etc.). For theme-level visual customization without a dedicated component prop, use a custom skin. 5. **Always wrap your app** with `ThemeContextProvider` and import `@telefonica/mistica/css/mistica.css`. @@ -488,24 +488,26 @@ return ( ## Funnel / step-by-step flow ```tsx - - - - - - } -/> - - - - {currentStep === 0 && } - {currentStep === 1 && } - {currentStep === 2 && } - {currentStep === 3 && } - - + + + + + + + } + /> + + + + {currentStep === 0 && } + {currentStep === 1 && } + {currentStep === 2 && } + {currentStep === 3 && } + + + ``` ## Next.js integration diff --git a/skills/mistica-react/SKILL.md b/skills/mistica-react/SKILL.md index 87444fb7f8..8b9ecbf1cc 100644 --- a/skills/mistica-react/SKILL.md +++ b/skills/mistica-react/SKILL.md @@ -35,44 +35,12 @@ npm install @telefonica/mistica ## Documentation -All Mistica documentation is available in the installed package. **Before generating any UI code**, read the -relevant documentation files from `node_modules/@telefonica/mistica/doc/`. +**Before writing any code**, read `node_modules/@telefonica/mistica/doc/llms.md`. That file is the canonical +source of truth and contains critical rules, a quick start guide, component categories, design token overview, +and step-by-step instructions on which documentation files to read and in what order. -### Step 1: Read the main reference +> **Fallback**: If `node_modules/@telefonica/mistica/doc/llms.md` is not available, fetch the equivalent file from the +> GitHub repository: `https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md` -Always start by reading the main LLM documentation file: - -``` -node_modules/@telefonica/mistica/doc/llms.md -``` - -This file contains the critical rules, quick start guide, component categories, design token overview, and -links to all other documentation files. - -> **Fallback**: If `node_modules/@telefonica/mistica` is not available, read the equivalent files directly -> from the GitHub repository: `https://github.com/Telefonica/mistica-web/blob/master/doc/llms.md` - -### Step 2: Read specific docs based on the task - -Based on what the user needs, read the appropriate documentation files: - -| Task | Read this file | -| --------------------------------- | --------------------------------------------------------- | -| **Any UI task** (start here) | `node_modules/@telefonica/mistica/doc/patterns.md` | -| **Using specific components** | `node_modules/@telefonica/mistica/doc/components.md` | -| **Colors, tokens, theming** | `node_modules/@telefonica/mistica/doc/design-tokens.md` | -| **Page layouts** | `node_modules/@telefonica/mistica/doc/layout.md` | -| **Forms** | `node_modules/@telefonica/mistica/doc/forms.md` | -| **Theme configuration** | `node_modules/@telefonica/mistica/doc/theme-config.md` | -| **Sheets / bottom sheets** | `node_modules/@telefonica/mistica/doc/sheet.md` | -| **Analytics tracking** | `node_modules/@telefonica/mistica/doc/analytics.md` | -| **Fonts setup** | `node_modules/@telefonica/mistica/doc/fonts.md` | -| **Custom text tokens** | `node_modules/@telefonica/mistica/doc/texts.md` | -| **Testing** | `node_modules/@telefonica/mistica/doc/testing.md` | -| **Migration from older versions** | `node_modules/@telefonica/mistica/doc/migration-guide.md` | -| **Lottie animations** | `node_modules/@telefonica/mistica/doc/lottie.md` | - -## Rules - -Treat `node_modules/@telefonica/mistica/doc/llms.md` as the canonical source of truth for critical rules, page -structure, and Mistica best practices. Do not rely on abbreviated rules here when `llms.md` is available. +Follow every instruction in `llms.md` exactly, including reading all minimum required docs before generating +any code.