Skip to content

Commit aec5f20

Browse files
Marcosldclaude
andcommitted
docs(llms): slim down source-code section to minimum guidance
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) <noreply@anthropic.com>
1 parent 8b26669 commit aec5f20

1 file changed

Lines changed: 8 additions & 21 deletions

File tree

doc/llms.md

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,29 +15,16 @@ This file is the main entry point. All docs live at:
1515
If you cannot find a documentation file in `node_modules`, fetch the equivalent file from the GitHub
1616
repository at `https://github.com/Telefonica/mistica-web/blob/master/doc/<filename>`.
1717

18-
## Source code location
18+
## Source code
1919

20-
The full TypeScript/TSX source of this package is shipped inside the published tarball and is available
21-
alongside the compiled output and type definitions. Use it as a **complementary** reference whenever the docs
22-
or `.d.ts` files don't fully answer a question about a component's real behavior, props, or internals.
20+
Source is available at `node_modules/@telefonica/mistica/src/` (fallback:
21+
`https://github.com/Telefonica/mistica-web/tree/master/src`). Use `src/index.tsx` to map imports to files.
2322

24-
- **Installed package**: `node_modules/@telefonica/mistica/src/`
25-
- **GitHub fallback**: `https://github.com/Telefonica/mistica-web/tree/master/src`
26-
27-
What you'll find there:
28-
29-
- `src/**/*.tsx`, `src/**/*.ts` — production component source
30-
- `src/**/*.css.ts` — vanilla-extract style definitions
31-
- `src/index.tsx` and `src/community/index.tsx` — public entry points; start here to map an import to a file
32-
33-
Recommended lookup workflow:
34-
35-
1. Resolve the import path the consumer uses (e.g. `import {Button} from '@telefonica/mistica'` or
36-
`'@telefonica/mistica/community'`).
37-
2. Open `node_modules/@telefonica/mistica/src/index.tsx` (or `src/community/index.tsx`) to find which file the
38-
symbol is re-exported from.
39-
3. Read that source file (and its `*.css.ts` sibling, if any) for real props, types, default values, and
40-
behavior.
23+
Read source only when you need to understand internal behavior that docs and types don't cover — for example
24+
debugging layout/CSS issues (`*.css.ts` files), understanding event handling, or authoring a custom skin (read
25+
a real skin in `src/skins/` to see canonical token patterns). Do not read source for greenfield UI work — the
26+
docs already cover that, and reading source tends to pull toward low-level APIs when a documented composite
27+
component would be simpler.
4128

4229
## Critical Rules
4330

0 commit comments

Comments
 (0)