一页组件文档至少回答六个问题：它解决什么任务、有哪些结构和状态、内容怎么写、何时不该用、如何满足可访问性、变更后怎么迁移。把这六项放入设计系统方法的交付流程，团队才不会把组件库当成图片仓库。
先写用途和边界
按钮用于触发动作，不用于导航链接；主要按钮承载当前页面最重要的一步，次要按钮和文字链接处理替代路径。文档先写任务和限制，使用者才能判断“这个组件是否适合”，而不是只看外观。
把不该用的场景写成反例。例如删除不可逆数据时，若只用一个普通主按钮，用户可能忽略风险；文档应指出需要确认、说明或更安全的替代。
状态用同一套字段解释
默认、悬停、聚焦、按下、加载、禁用和错误状态要用同一组文案和尺寸说明。状态之间的差异要能从图和文字同时读出，不能只靠颜色。
每个状态附一个真实使用场景和验收条件：加载时不可重复提交，禁用时说明原因，焦点时在键盘路径上可见。这样研发测试和设计评审使用同一套判断。
把内容当成组件的一部分
按钮文案用动作动词，必要时补对象；“提交”“保存草稿”“导出当前画板”承诺不同结果。文档列出最长可接受文案、换行规则和多语言注意事项，但不编造一个全站统一字符数。
示例和反例最好使用同一场景，读者能直接比较。图文之外，把关键信息写成可复制文本，避免组件只有一张图片而搜索和辅助技术读不到。
让变更可以迁移
组件增加状态或修改默认间距时，文档记录变更原因、受影响实例、迁移步骤和预计失效时间。变更说明应该靠近版本入口，不能只发一条没有上下文的通知。
把组件、变体、示例和文档字段放在同一个 Pixso 文件中，研发可以核对结构，设计可以回看用法，评审人可以从反例定位边界。发布前检查链接、状态和当前版本，避免示例指向旧组件。
文档应把示例与组件版本绑定。示例更新时记录修改原因和影响实例，组件弃用时给出替代组件和迁移顺序；如果某个行为依赖业务规则，标注“由业务决定”的位置，不把示例写成全站强制规范。
上线前让三类人各走一遍：设计师按任务挑组件，研发按状态实现，内容或测试按文档写验收。若三方在同一字段上得出不同理解，先改文档和例子，再扩大组件使用范围。
组件文档的示例与说明结构可参考Storybook 文档编写指南；本文不代表 Pixso 与该工具存在集成关系。
