token-counter

Token Counter 是一个 UX 模式，核心用途是展示 token 使用量与限制。它解决的问题是：帮助团队建立一种可靠方式，在用户触及硬性上限之前，让提示词大小、响应预算以及成本或截断风险变得可见。该模式在有硬性限制的提示词编写场景中最有用。与相邻模式相比，它应在不隐藏用户持续操作所需的状态、规则或恢复路径的前提下减少摩擦。

适用场景

有硬性限制的提示词编写
对成本敏感的 AI 工具
调试截断和上下文溢出

应避免的场景

当标准非 AI 工作流更清晰、更可靠时，避免添加 AI 专属 UI。
除非用户确实能从中受益，否则不要暴露高级控件。
不要仅靠精致的视觉来掩盖模型的不确定性。

实现流程

在复制示例之前，确认该模式与问题和约束相匹配。
从 references/pattern.md 中的结构和示例开始，然后选择最小可行的变体。
在叠加视觉打磨之前，先应用无障碍、性能和交互护栏。
使用测试指南验证键盘、屏幕阅读器、响应式和失败场景下的行为。

无障碍护栏

键盘交互

验证 token counter 可以仅用键盘完成操作。
当模式打开、更新或显示额外 UI 时，保持焦点顺序合乎逻辑。
保持可见的焦点状态，且在高倍缩放时仍然可读。

屏幕阅读器支持

优先使用语义元素，仅在语义本身不足时才添加 ARIA。
在正确的位置、以正确的礼貌程度播报错误、加载或完成等状态变化。
在有用时，用 aria-describedby 或结构化标题连接标签、提示和状态文本。

视觉无障碍

不要仅依赖颜色来传达严重程度、完成或选中状态。

性能护栏

将网络延迟、token 使用量和长响应的客户端渲染作为一个整体来预算，而不是分开考虑。
当有助于提升首次价值时间时，可流式或分块输出内容，但要稳定布局，避免阅读时抖动。
跟踪长提示词、模型切换和重试等昂贵状态，以便用证据来调优体验。

常见错误

隐藏系统状态

问题：用户无法判断模型是在等待、流式输出、重试还是已完成。修复方式：暴露清晰的请求生命周期状态，并让它们保持在所影响内容附近可见。

把失败当作标准表单错误处理

问题：AI 失败包括安全拦截、上下文限制、模型可用性和部分输出，而不仅仅是请求失败。修复方式：区分不同失败模式，并给出与每种模式匹配的恢复操作。

忽略 token 和延迟预算

问题：当响应变慢、变短或变贵却没有解释时，体验会显得不可预测。修复方式：从一开始就把 token、延迟和提供商约束设计进界面。

技能介绍