基础
与 AI 协作
这个包把自己写了两遍文档。这是浏览器打不开的那一半。
这个包有两类读者，只有一类打得开浏览器。第二类通常已经把它装上了——也就是说，它正在写的那个版本就躺在 node_modules 里，而它本来要读的文档在一个已经往前走了的网站上。下面这些全部由同一个 tarball 里的源码生成，所以它描述的是你手上真正那个版本，而不是最近发布的那个。
这件事最要紧的地方，恰好是模型最自信的地方。有那么几处命名和 shadcn/ui 不一样，凭习惯写的模型每次都写错——是 CardBody 不是 CardContent，是 THead/TBody/TR/TH/TD 不是 TableHeader 那一套，是 DialogContent 上的 title 属性而不是一个 DialogTitle 子元素。猜的结果是根本不存在的 import，最快的修法是别猜。
接着读快速开始
在终端里
这个包带了一个可执行文件。docs <Component> 会把一个组件完整打印出来——每个属性连同它的类型和默认值、导出的联合类型、键盘约定、可访问性承诺，以及组件自己 JSDoc 上的 @example 块。
它解析的不只是组件，还有部件和类型：docs CardBody、docs TH 和 docs ButtonVariant 都会落到正确的文件上，而且它会说清楚，把你转过去的那个名字归哪个组件所有。这就是一次 import 刚失败时该伸手去拿的命令，因为你手上那个标识符通常是一个部件，而不是导出它的那个东西。
docs --installed 是这笔交易里便宜的那一半：解析出来的版本号，以及分好组的名字，不带属性表。它是该放在一次会话开头的东西。--json 把同样的内容给成机器可读的，其中包含那四个样式表 specifier。
npx @misoto22/folio docs Button # one component, in full npx @misoto22/folio docs CardBody # resolves a part to its owner npx @misoto22/folio docs ButtonVariant # …and an exported type npx @misoto22/folio docs --list # every component, one line each npx @misoto22/folio docs --installed # version + names, no prop tables npx @misoto22/folio docs --installed --json
装上这个 skill
这个包在 skills/folio-design/ 下带了一个 agent skill，init 会把它复制到你项目的 .claude/skills/folio-design/。--agents-md 还会往你的 AGENTS.md 里追加一小节指向它；如果那个文件已经提到了这个包，它就什么都不动。
这个 skill 是刻意做成渐进式的。在真正有东西碰到这个包之前，留在会话里的只有它的名字和描述；正文等工作推进到那里才加载，之后五个规则文件——tokens、composition、forms、accessibility、naming——再一个一个加载。它开头就是那张 shadcn/ui 命名对照表，而且只要其中任何一行不再成立，这个包自己的测试就会让构建失败。
升级之后重跑一次。这个 skill 是一份副本，不是一个链接，所以装过一次的项目手上拿着的，是当时那个版本说的话。
npx @misoto22/folio init # writes .claude/skills/folio-design/ npx @misoto22/folio init --agents-md # …and points AGENTS.md at it
在网上
同样的内容也由这个站点以纯文本提供，给那些能抓 URL、却什么都没装的 agent。三种形态，在它们之间做选择是一笔预算：索引是一页，单个组件是一页，而全部内联展开就是整套系统。
包已经装上了，就优先用 CLI。站点记录的是最近发布的那一版；node_modules 里放着的才是你的代码真正编译时对着的那一版，而这个分歧两边都看不见。
- ui.misoto22.com/llms.txt
- 索引——这套系统是什么、八条法则、主题轴，以及每个组件一行。
- ui.misoto22.com/components/<slug>/llms.txt
- 单个组件：属性、类型、键盘、可访问性、示例。一次抓取，一个组件。
- ui.misoto22.com/llms-full.txt
- 索引，后面内联跟着每一个组件。只有在你真的需要全部时才伸手去拿。
tarball 里有什么
生成出来的文档是构建产物，随发布的包一起发出去，所以其中没有一样需要网络。dist/agent/ 里每个组件一个 Markdown 文件，一个 index.md 给出名字和各一行说明，还有一个 catalog.json 供 CLI 把一个部件或一个类型解析回它的归属组件。CLI 只是这个目录上薄薄的一层读取器；在源码 checkout 里它由 pnpm build:agent 构建出来，没有构建时 CLI 会明说，而不是什么都不打印。
skills/folio-design/ 与它一同发布，那正是 init 复制的东西。两者都列在包的 files 字段里，所以 npm pack 会把它们带上。