From 8b26669a95b9c8d08280d85eca81f31680db9a8d Mon Sep 17 00:00:00 2001 From: Marcos Luis Delgado Date: Mon, 13 Apr 2026 12:55:29 +0100 Subject: [PATCH 1/3] feat(skill): Include source code in published bundle Ship src/** in the npm tarball (excluding tests, stories, generated files) and document its location in doc/llms.md so LLMs can read the real component source as a complement to the docs and type defs. Refs WEB-2431 --- doc/llms.md | 24 ++++++++++++++++++++++++ package.json | 12 ++++++++++++ 2 files changed, 36 insertions(+) diff --git a/doc/llms.md b/doc/llms.md index dff26f7598..82347944f2 100644 --- a/doc/llms.md +++ b/doc/llms.md @@ -15,6 +15,30 @@ This file is the main entry point. All docs live at: If you cannot find a documentation file in `node_modules`, fetch the equivalent file from the GitHub repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/`. +## Source code location + +The full TypeScript/TSX source of this package is shipped inside the published tarball and is available +alongside the compiled output and type definitions. Use it as a **complementary** reference whenever the docs +or `.d.ts` files don't fully answer a question about a component's real behavior, props, or internals. + +- **Installed package**: `node_modules/@telefonica/mistica/src/` +- **GitHub fallback**: `https://github.com/Telefonica/mistica-web/tree/master/src` + +What you'll find there: + +- `src/**/*.tsx`, `src/**/*.ts` — production component source +- `src/**/*.css.ts` — vanilla-extract style definitions +- `src/index.tsx` and `src/community/index.tsx` — public entry points; start here to map an import to a file + +Recommended lookup workflow: + +1. Resolve the import path the consumer uses (e.g. `import {Button} from '@telefonica/mistica'` or + `'@telefonica/mistica/community'`). +2. Open `node_modules/@telefonica/mistica/src/index.tsx` (or `src/community/index.tsx`) to find which file the + symbol is re-exported from. +3. Read that source file (and its `*.css.ts` sibling, if any) for real props, types, default values, and + behavior. + ## Critical Rules 1. **NEVER hardcode colors in app/component UI code.** Always use `skinVars.colors.*` design tokens from diff --git a/package.json b/package.json index 8684a484ab..413911726a 100644 --- a/package.json +++ b/package.json @@ -14,6 +14,18 @@ "dist-es/**", "css/**", "doc/**", + "src/**", + "!src/generated/**", + "!src/**/__tests__/**", + "!src/**/__acceptance_tests__/**", + "!src/**/__screenshot_tests__/**", + "!src/**/__type_tests__/**", + "!src/**/__stories__/**", + "!src/**/__private_stories__/**", + "!src/**/*-test.ts", + "!src/**/*-test.tsx", + "!src/**/*-story.ts", + "!src/**/*-story.tsx", "community.d.ts", "community.js" ], From aec5f20e993a364b522e8a33ffed3327930087fa Mon Sep 17 00:00:00 2001 From: Marcos Luis Delgado Date: Thu, 16 Apr 2026 08:11:49 +0100 Subject: [PATCH 2/3] docs(llms): slim down source-code section to minimum guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the broad "Source code location" section with a concise "Source code" section that tells LLMs where source lives and when to read it (debugging layout/CSS, event handling, skin authoring) — and when not to (greenfield UI work). Research across 9 A/B iterations showed that verbose source-reading instructions pull agents toward low-level escape hatches when documented composite components would produce simpler code. Co-Authored-By: Claude Opus 4.6 (1M context) --- doc/llms.md | 29 ++++++++--------------------- 1 file changed, 8 insertions(+), 21 deletions(-) diff --git a/doc/llms.md b/doc/llms.md index 82347944f2..ac2c68965b 100644 --- a/doc/llms.md +++ b/doc/llms.md @@ -15,29 +15,16 @@ This file is the main entry point. All docs live at: If you cannot find a documentation file in `node_modules`, fetch the equivalent file from the GitHub repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/`. -## Source code location +## Source code -The full TypeScript/TSX source of this package is shipped inside the published tarball and is available -alongside the compiled output and type definitions. Use it as a **complementary** reference whenever the docs -or `.d.ts` files don't fully answer a question about a component's real behavior, props, or internals. +Source is available at `node_modules/@telefonica/mistica/src/` (fallback: +`https://github.com/Telefonica/mistica-web/tree/master/src`). Use `src/index.tsx` to map imports to files. -- **Installed package**: `node_modules/@telefonica/mistica/src/` -- **GitHub fallback**: `https://github.com/Telefonica/mistica-web/tree/master/src` - -What you'll find there: - -- `src/**/*.tsx`, `src/**/*.ts` — production component source -- `src/**/*.css.ts` — vanilla-extract style definitions -- `src/index.tsx` and `src/community/index.tsx` — public entry points; start here to map an import to a file - -Recommended lookup workflow: - -1. Resolve the import path the consumer uses (e.g. `import {Button} from '@telefonica/mistica'` or - `'@telefonica/mistica/community'`). -2. Open `node_modules/@telefonica/mistica/src/index.tsx` (or `src/community/index.tsx`) to find which file the - symbol is re-exported from. -3. Read that source file (and its `*.css.ts` sibling, if any) for real props, types, default values, and - behavior. +Read source only when you need to understand internal behavior that docs and types don't cover — for example +debugging layout/CSS issues (`*.css.ts` files), understanding event handling, or authoring a custom skin (read +a real skin in `src/skins/` to see canonical token patterns). Do not read source for greenfield UI work — the +docs already cover that, and reading source tends to pull toward low-level APIs when a documented composite +component would be simpler. ## Critical Rules From 9086deb588fcc2bb1f3c90dd95b0604c7d7a3e16 Mon Sep 17 00:00:00 2001 From: Marcos Luis Delgado Date: Thu, 16 Apr 2026 09:01:56 +0100 Subject: [PATCH 3/3] WEB-2431: Little fix --- doc/llms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/llms.md b/doc/llms.md index ac2c68965b..a098d2ab0c 100644 --- a/doc/llms.md +++ b/doc/llms.md @@ -22,9 +22,9 @@ Source is available at `node_modules/@telefonica/mistica/src/` (fallback: Read source only when you need to understand internal behavior that docs and types don't cover — for example debugging layout/CSS issues (`*.css.ts` files), understanding event handling, or authoring a custom skin (read -a real skin in `src/skins/` to see canonical token patterns). Do not read source for greenfield UI work — the -docs already cover that, and reading source tends to pull toward low-level APIs when a documented composite -component would be simpler. +a real skin in `src/skins/` to see canonical token patterns). Normally you shouldn't read source for +greenfield UI work — the docs already cover that, and reading source tends to pull toward low-level APIs when +a documented composite component would be simpler. ## Critical Rules