SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbklit-ui-migrate

bklit-ui-migrate

Frontend & websites

View repository

Updated 10-17 04:35

About this skill

Recharts → Bklit UI migration

Bklit charts are shadcn registry components: npx shadcn@latest add @bklit/<slug> copies source into the user's project and the code imports it from their own alias, e.g. @/components/charts/line-chart. Never import from @bklitui/ui/charts — that is bklit's private monorepo package.

Work through the steps in order. Do not start rewriting before the inventory (step 1) and classification (step 2) have been shown to the user.

References

File Use it for
references/component-map.md Recharts component → bklit export, registry slug, import path
references/prop-map.md Prop-by-prop mapping, units, defaults
references/shadcn-chart.md ChartContainer / ChartConfig / ChartTooltipContent / ChartLegendContent, var(--color-*), full before/after
references/examples.md Verified before/after: multi-line, stacked bar, horizontal bar, donut, radar, gradient area
rules/gaps.md Features with no bklit prop — workaround or keep Recharts (Incorrect/Correct)
scripts/detect-recharts.mjs Zero-dependency inventory + classification

Docs for each chart: https://bklit.com/docs/components/<slug>.

Ground rules

  1. Never invent props. If a Recharts prop has no row in prop-map.md, it is a gap — read rules/gaps.md. bklit has no tickFormatter on XAxis, no domain on YAxis, no stackId, no layout, no connectNulls, no syncId.
  2. Line / Area / Composed / Scatter are time-series charts. x values must be Dates (or ISO strings / epoch ms). Categorical x → BarChart or a workaround.
  3. Preserve data, colours and labels. Same series, same colours (resolved from ChartConfig), same human labels in tooltip and legend.
  4. One file at a time, typecheck after each.
  5. Ask before any "needs workaround" conversion — it changes how the chart looks or reads.
  6. Leave "keep Recharts" charts untouched. A partial migration is a valid outcome.

Step 1 — Detect and inventory

Run the detector from the project root (Node ≥ 18, no install):

node <skill-dir>/scripts/detect-recharts.mjs . --format=table   # human table
node <skill-dir>/scripts/detect-recharts.mjs .                  # full JSON

It walks source files (skipping node_modules, .next, dist, build, dot-dirs), finds recharts imports (named or import * as RechartsPrimitive) and shadcn wrapper imports, and reports per file: components used, each chart root with line number, notable props (stackId, layout="vertical", syncId, XAxis type="number", Treemap, LabelList, ErrorBar, custom shape/content, Brush, …), the proposed bklit target, slugs to install, and a classification. shadcnWrappers[].importedBy lists who still imports components/ui/chart.tsx. It never throws; unreadable paths go in errors.

The script is a heuristic (it cannot see data values or axes built in helper functions). Open every listed file and confirm before presenting. Show the user a table:

File Recharts / shadcn components Chart type bklit target Class
components/chart-area-interactive.tsx:51 AreaChart, Area, CartesianGrid, XAxis, ChartContainer, ChartTooltip(Content), ChartLegend(Content) Area (stacked) AreaChart needs workaround
components/storage-treemap.tsx:25 Treemap, Tooltip, ResponsiveContainer Treemap — keep Recharts

Also check components.json: confirm the @bklit registry ("registries": { "@bklit": "https://ui.bklit.com/r/{name}.json" }) and note aliases.components — it decides the import prefix (default @/components → files land in components/charts/).

Step 2 — Classify and confirm

For every chart, state one of:

  • Clean — every component and prop maps (see component-map.md, prop-map.md). Data may still need a reshape (pie, radar, radial, ring).
  • Needs workaround — convertible with a compromise. Typical: categorical or numeric x on a time-series chart, Area stackId, multiple bar stack groups, fixed YAxis domain, negative bar values, x tickFormatter/angled ticks, LabelList, syncId, Brush (bklit's brush is not shipped in any registry item), ReferenceLine/ReferenceDot, null gaps, nested pies.
  • Keep on Recharts — Treemap, ErrorBar, Customized, custom shape/node renderers, ZAxis bubbles, layout="vertical" on non-bar charts.

Give the reason for each non-clean chart (quote the prop) and the proposed workaround from rules/gaps.md. Ask the user which workaround charts to convert and how (e.g. overlap vs cumulative areas). Convert clean charts without further questions unless the user asked to review each.

Step 3 — Install the bklit items

Install only what the confirmed charts need, using the project's package runner:

npx shadcn@latest add @bklit/line-chart @bklit/bar-chart @bklit/y-axis @bklit/legend
# pnpm dlx shadcn@latest add …   |   bunx --bun shadcn@latest add …
Needed for Slug
LineChart / AreaChart / BarChart / ComposedChart / ScatterChart line-chart / area-chart / bar-chart / composed-chart / scatter-chart (each brings grid, chart-tooltip; time charts bring x-axis; bar brings BarXAxis/BarYAxis)
PieChart / RadarChart / ring (RadialBarChart) / one-value gauge pie-chart / radar-chart / ring-chart / gauge-chart
FunnelChart / Sankey / SunburstChart funnel-chart / sankey-chart / sunburst-chart
any visible value YAxis y-axis (not bundled with line/area/bar)
Legend legend
ReferenceArea reference-area
ReferenceDot / event markers markers

shadcn adds bklit's CSS variables (--chart-line-primary, --chart-grid, --chart-crosshair, tooltip colours, …) to the global stylesheet but does not overwrite existing variables, so the user's --chart-1 … --chart-5 stay as they are. Confirm the files landed where aliases.components says before writing imports.

Step 4 — Convert one file at a time

For each chart:

  1. Reshape data.
    • Time charts: make row[xDataKey] a Date. Bare "2024-04-01" strings parse as UTC midnight (shows the previous day west of UTC) → new Date(\${d}T00:00:00`). Sort by x. Set xDataKeywhen the key is not"date"(bar default"name"`).
    • Series-level data (<Scatter data>, <Line data>) → merge into the root data.
    • Pie: { label, value, color? }[]. Radar: metrics {key,label}[] + data {label, color?, values}[] normalised 0–100. Ring: { label, value, maxValue, color? }[]. Funnel: { label, value, color? }[]. Sankey: unchanged.
  2. Map components and props with component-map.md and prop-map.md. Highlights that are easy to get wrong:
    • ResponsiveContainer → delete; size with aspectRatio (default "2 / 1") or className="h-[300px]".
    • layout="vertical" → BarChart orientation="horizontal" (inverted naming) + BarYAxis.
    • All bars share one stackId → root stacked.
    • type="monotone" → curve={curveMonotoneX} from @visx/curve. Recharts' default curve is linear; bklit Line defaults to curveNatural, Area to curveMonotoneX.
    • dot → showMarkers/markers; activeDot → ChartTooltip showDots/dotSize.
    • isAnimationActive={false} → animate={false} on the series (root animationDuration, default 1100 ms).
    • Bar radius → lineCap (default "round"; "butt" for square Recharts bars; a number for px).
    • paddingAngle (deg) → padAngle (rad); pie angles: rad = (90 − deg) · π / 180.
    • YAxis tickFormatter → formatValue; domain → none.
    • Tooltip → ChartTooltip with rows={(point) => [...]} for labels/formatting (row order = series child order), content={({ point, index }) => …} for full control, cursor={false} → showCrosshair={false}.
    • Legend → <Legend items> from @/components/charts/legend, rendered outside the chart root.
    • margin: same shape, but bklit defaults to 40 on every side because axis labels live in the margin.
  3. Preserve colours and labels from ChartConfig (shadcn). Every var(--color-<key>) must become the config's colour (e.g. var(--chart-1)) — those variables only exist inside ChartContainer. Labels go to rows and Legend items. Details: shadcn-chart.md.
  4. Keep the component's public API (name, props, exports) so call sites do not change.
  5. Add "use client" if the file passes functions (rows, content, formatValue) and is not already a client component.

Step 5 — Rewrite imports (watch for collisions)

Import each piece from the file the registry installed:

import { Line, LineChart } from "@/components/charts/line-chart";
import { Grid } from "@/components/charts/grid";
import { XAxis } from "@/components/charts/x-axis";
import { YAxis } from "@/components/charts/y-axis";
import { ChartTooltip } from "@/components/charts/tooltip";
import { Legend, LegendItem, LegendLabel, LegendMarker } from "@/components/charts/legend";

Remove the file's recharts and @/components/ui/chart imports once nothing in it uses them. Names collide across libraries — ChartTooltip, ChartLegend (shadcn wrapper) and LineChart, Line, Area, Bar, XAxis, YAxis, Legend, ReferenceArea, PieChart, … (Recharts). In a file that still renders a kept Recharts chart, alias one side:

import { Treemap, Tooltip as RechartsTooltip } from "recharts";
import { ChartTooltip as BklitChartTooltip } from "@/components/charts/tooltip";

The registry's legend item export is LegendItem (the docs' LegendItemComponent alias exists only in bklit's monorepo barrel).

Step 6 — Remove the old code only when unused

  • Delete components/ui/chart.tsx only when no file imports it: re-run the detector (shadcnWrappers[].importedBy empty) and search the repo (rg "ui/chart"), including stories, tests and docs.
  • Remove the recharts dependency only when the detector reports no recharts imports left (no kept charts) and rg "from ['\"]recharts" is empty. Use the project's package manager (npm uninstall recharts, pnpm remove recharts, …).
  • If any chart is kept on Recharts, keep both and say so in the summary.

Step 7 — Verify

  1. Typecheck and lint after each file, then build: npx tsc --noEmit (or the project's typecheck script), the project's lint script, then build.
  2. Visual comparison: run the dev server and compare each converted chart with the original (screenshots before/after, light and dark mode). Check: series count and colours, labels in tooltip and legend, x labels/dates (UTC shift), y range, stacking, sizing, hover, empty state.
  3. Expected, acceptable differences to call out: bklit's enter animation, dashed/edge-faded grid, crosshair + date pill tooltip, fixed "MMM d" x labels, rounded bars by default.
  4. Re-run the detector and report what is left on Recharts and why.

Finish

Summarise for the user: charts converted (file → bklit chart), workarounds applied, charts kept on Recharts with reasons, items installed, files/dependencies removed, and verification results.

For restyling the migrated charts (palette, tokens, typography, motion), hand off to the bklit-ui-design skill; for general bklit composition questions use the bklit-ui skill.