Back to Details

bklit-ui-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bklit UI design

Bklit UI 设计

Map what people say ("a hatched backdrop that fades at the edges") to what Bklit has (
<Background />
), then make it look native to the app it lands in.
Bklit charts are installed as source with 
npx shadcn@latest add @bklit/<item>
(use the project's runner: 
pnpm dlx
, 
bunx --bun
, …) and imported from the project's alias, e.g. 
@/components/charts/background
. Never import from 
@bklitui/ui/charts
— that is the private monorepo package.
将人们用自然语言描述的需求（“边缘渐隐的阴影线背景”）映射到 Bklit 实际提供的组件（
<Background />
），再让它与落地应用自然融合。
Bklit 图表通过以下命令以源代码形式安装（使用项目采用的 runner：
pnpm dlx
、
bunx --bun
等）：
bash
npx shadcn@latest add @bklit/<item>
然后通过项目的 alias 导入，例如 
@/components/charts/background
。切勿从 
@bklitui/ui/charts
导入——那是私有 monorepo package。

Workflow

工作流

1. Detect the host design

1. 检测宿主设计

Run the bundled detector from the user's project root. 
<skill-dir>
is the folder containing this SKILL.md (commonly 
.claude/skills/bklit-ui-design
, 
.agents/skills/bklit-ui-design
or 
~/.claude/skills/bklit-ui-design
):
bash
node <skill-dir>/scripts/detect-design.mjs
Zero dependencies, Node ≥ 18, never throws. It prints JSON: 
tailwindVersion
, 
cssPath
, 
colorFormat
, 
darkMode
, 
tokens
(
--primary
, 
--radius
, …), 
chartVars
(light/dark 
--chart-*
), 
themeInline
, 
components
(from 
components.json
), 
primitives
, 
chartLibs
, 
bklit.installed
and 
warnings
. Agents without shell access: read 
components.json
, the global CSS file it names, and 
package.json
, and collect the same facts by hand.
Read 
warnings
first — they flag the problems that make charts look broken (gray default palette, Tailwind v3 bare-HSL tokens, missing 
@theme
mappings).
在用户项目根目录运行随附的检测器。
<skill-dir>
是包含此 SKILL.md 的文件夹（通常为 
.claude/skills/bklit-ui-design
、
.agents/skills/bklit-ui-design
或 
~/.claude/skills/bklit-ui-design
）：
bash
node <skill-dir>/scripts/detect-design.mjs
零依赖、Node ≥ 18，且永不抛出异常。它会输出 JSON：
tailwindVersion
、
cssPath
、
colorFormat
、
darkMode
、
tokens
（
--primary
、
--radius
等）、
chartVars
（浅色/深色 
--chart-*
）、
themeInline
、
components
（来自 
components.json
）、
primitives
、
chartLibs
、
bklit.installed
和 
warnings
。没有 shell 访问权限的 Agent：读取 
components.json
、其中指定的全局 CSS 文件和 
package.json
，手动收集相同信息。
先阅读 
warnings
——它们会标记导致图表显示异常的问题（灰色默认调色板、Tailwind v3 裸 HSL tokens、缺少 
@theme
映射）。

2. Parse the request into design intents

2. 将请求解析为设计意图

Split the sentence into intents (background, fade, shape, fill, line, markers, tooltip, grid, legend, loading, motion, annotation) and look each up in references/vocabulary.md. Example:
"squircle bars with a ghost track and a ring on hover" → shape: 
BarSquares squareRadius={0.5}
+ 
BarChart squareSnap
· track: 
BarColumnTrack
· tooltip: 
ChartTooltip dotVariant="ring" dotRadiusFraction={0.5}
"diagonal pattern background that fades out on all sides" → 
<Background />
(diagonal and 4-side fade are the defaults)
将句子拆分为多个 intent（背景、渐隐、形状、填充、线条、标记、tooltip、网格、图例、加载、动效、标注），并在 references/vocabulary.md 中逐一查找。示例：
“带 ghost track 且 hover 时显示 ring 的 squircle 柱状图” → 形状：
BarSquares squareRadius={0.5}
+ 
BarChart squareSnap
· 轨道：
BarColumnTrack
· tooltip：
ChartTooltip dotVariant="ring" dotRadiusFraction={0.5}
“四边渐隐的斜纹背景” → 
<Background />
（斜纹和四边渐隐均为默认效果）

3. Pick a recipe and adapt it

3. 选择 recipe 并进行适配

Start from the closest composition in references/recipes.md rather than assembling from scratch — those are the gallery's proven looks. Then adapt to the detection output:
  • colours → 
    var(--chart-1..5)
    / 
    chartCssVars
    , never literals;
  • corner style → host 
    --radius
    (rules/taste.md §4);
  • density → fewer grid rows / no background in small dashboard cards;
  • palette, dark mode, Tailwind v3 quirks → rules/theming.md.
从 references/recipes.md 中最接近的 composition 开始，而不是从零开始拼装——这些是图库中经过验证的视觉效果。 然后根据检测结果进行调整：
  • 颜色 → 
    var(--chart-1..5)
    / 
    chartCssVars
    ，不要使用字面量；
  • 圆角样式 → 宿主的 
    --radius
    （rules/taste.md §4）；
  • 密度 → 更少的 grid rows / 小型 dashboard card 中不使用背景；
  • 调色板、dark mode、Tailwind v3 兼容性问题 → rules/theming.md。

4. Install the registry items

4. 安装 registry 项

Install every item the composition touches (the vocabulary's import table lists which slug provides each export), e.g.:
bash
npx shadcn@latest add @bklit/bar-chart @bklit/bar-depth @bklit/chart-tooltip
shadcn adds missing CSS variables without overwriting the host's existing ones. If 
@bklit
does not resolve, see the 
bklit-ui
skill's installation notes.
安装 composition 涉及的所有项（vocabulary 的导入表列出了提供每个 export 的 slug），例如：
bash
npx shadcn@latest add @bklit/bar-chart @bklit/bar-depth @bklit/chart-tooltip
shadcn 会补充缺失的 CSS variables，但不会覆盖宿主已有的变量。 如果 
@bklit
无法解析，请参阅 
bklit-ui
skill 的安装说明。

5. Confirm props against the installed source

5. 根据已安装的源码确认 props

Open the installed files (
components/charts/<file>.tsx
) and check every prop you plan to use exists with the expected type. The registry source is the contract; this skill can lag behind it.
打开已安装的文件（
components/charts/<file>.tsx
），检查计划使用的每个 prop 是否存在且类型符合预期。registry 源码才是契约；此 skill 可能落后于源码。

6. Apply the taste rules

6. 应用审美规则

Run through rules/taste.md: one decorative layer, subtle backgrounds, no stacked effects, corners matching 
--radius
, rings with squares, tokens only, dark mode verified, unique pattern ids.
逐项检查 rules/taste.md：只使用一个装饰层、背景保持克制、不堆叠特效、圆角与 
--radius
一致、square 使用 ring、仅使用 tokens、验证 dark mode、确保 pattern id 唯一。

7. Be honest about gaps

7. 如实说明能力缺口

If the request needs something Bklit lacks (see "Not supported" in the vocabulary — e.g. hexagon 
Background
preset, glow on lines, stacked areas, labels on bars), say so plainly, then offer the nearest supported look or a small custom composition (recipe 15 shows the pattern). Never invent props such as 
pattern="hexagons"
or 
glow
.
如果请求需要 Bklit 不具备的能力（见 vocabulary 中的“Not supported”，例如六边形 
Background
preset、线条 glow、堆叠 area、柱状图 labels），请直接说明，然后提供最接近的受支持效果或小型自定义 composition（recipe 15 展示了该 pattern）。切勿杜撰 
pattern="hexagons"
或 
glow
等 props。

Output checklist

输出检查清单

  • Install command(s) with the exact 
    @bklit/<item>
    slugs.
  • Complete JSX with imports from the project alias.
  • Any CSS token changes, in the host's colour format, for light and dark.
  • One line per honest gap or trade-off.
  • Links when useful: 
    https://bklit.com/docs/components/<slug>
    , 
    https://bklit.com/charts/<slug>
    , 
    https://bklit.com/studio?chart=<slug>
    .
  • 安装命令，包含准确的 
    @bklit/<item>
    slug。
  • 完整的 JSX，并从项目 alias 导入。
  • 所有 CSS token 更改，使用宿主的 color format，同时覆盖浅色和深色模式。
  • 每项能力缺口或取舍各占一行，并如实说明。
  • 在有帮助时提供链接：
    https://bklit.com/docs/components/<slug>
    、
    https://bklit.com/charts/<slug>
    、
    https://bklit.com/studio?chart=<slug>
    。

Files

文件

FileUse
references/vocabulary.mdPhrase → JSX/props → registry slug; import map; unsupported list
references/recipes.md15 complete compositions for named looks
rules/taste.mdDesign rules with incorrect/correct pairs
rules/theming.mdHost signals → chart token overrides (v4, v3, dark mode)
scripts/detect-design.mjsDesign detection (JSON)
evals/evals.jsonBehaviour checks for this skill
文件用途
references/vocabulary.md描述短语 → JSX/props → registry slug；导入映射；不支持项列表
references/recipes.md15 种针对指定视觉效果的完整 composition
rules/taste.md包含错误/正确示例对照的设计规则
rules/theming.md宿主环境信号 → chart token 覆盖配置（v4、v3、dark mode）
scripts/detect-design.mjs设计检测（JSON）
evals/evals.json此 skill 的行为检查