bklit/bklit-ui

Bklit UI

Composable chart components for React, distributed via the @bklit shadcn registry. Charts are installed as source into the user's project.

IMPORTANT: Run shadcn CLI commands with the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest.

Current Project Context

!`npx shadcn@latest info --json`

Use the JSON above for framework, aliases, Tailwind version, installed components, and resolved paths. Confirm the @bklit registry is configured before adding charts.

Principles

1. Install before inventing. Use npx shadcn@latest add @bklit/<chart> — charts are registry components, not hand-rolled SVG.
2. Compose, don't flatten. Root chart → Grid → series → axes → ChartTooltip. See composition.md.
3. Theme with tokens. Use chartCssVars and --chart-* variables — never hardcode one-off colors. See theming.md.
4. Read the doc page first. Each chart has props, data shape, and examples at https://ui.bklit.com/docs/components/<slug>.
5. Browse variants. Gallery: https://ui.bklit.com/charts/<slug> — Studio: https://ui.bklit.com/studio?chart=<slug>.

Critical Rules

These rules are always enforced. Each links to Incorrect/Correct examples.

Composition → composition.md

• Series and axes live inside the root chart — LineChart, BarChart, AreaChart, etc.
• One root per chart — use ComposedChart for mixed series types.
• Grid before series so lines/bars render above grid lines.
• ChartTooltip as a chart child — required for crosshair and hover context.

Theming → theming.md

• Use chartCssVars from @bklitui/ui/charts instead of raw "var(--chart-…)" strings.
• Series palette: --chart-1 … --chart-5 for multi-series charts.
• Tooltip surfaces: bg-popover text-popover-foreground — avoids white-on-white in light mode.

Animation → animation.md

• Default duration ~1100ms for cartesian enter animations unless the doc specifies otherwise.
• Replay: change revealSignature or remount with a new key.
• Live charts: use paused on LiveLineChart to debug without stopping the rAF loop manually.

Tooltips → tooltips.md

• Custom content via ChartTooltip content prop or children patterns from docs.
• indicatorColor function for candlestick / dynamic crosshair colors.
• Custom indicators: use useChart() — do not track mouse globally outside chart context.

Installation → installation.md

• Require @bklit registry in components.json.
• Install: npx shadcn@latest add @bklit/<slug>.
• Let the CLI install peer dependencies — do not pin @visx/* / motion manually unless resolving a conflict.

Chart Catalog

| Slug | Use when | Install | Docs | Gallery | |------|----------|---------|------|---------| | area-chart | Trends with filled regions under lines | @bklit/area-chart | /docs/components/area-chart | /charts/area-chart | | bar-chart | Category comparisons, stacked or grouped bars | @bklit/bar-chart | /docs/components/bar-chart | /charts/bar-chart | | line-chart | Time series, multi-line trends, markers | @bklit/line-chart | /docs/components/line-chart | /charts/line-chart | | live-line-chart | Streaming / real-time data | @bklit/live-line-chart | /docs/components/live-line-chart | /charts/live-line-chart | | composed-chart | Mixed bar + line (or similar) on one axis | @bklit/composed-chart | /docs/components/composed-chart | /charts/composed-chart | | scatter-chart | Correlation, distribution, bubble sizing | @bklit/scatter-chart | /docs/components/scatter-chart | /charts/scatter-chart | | candlestick-chart | OHLC financial data, brushes | @bklit/candlestick-chart | /docs/components/candlestick-chart | /charts/candlestick-chart | | pie-chart | Part-to-whole slices | @bklit/pie-chart | /docs/components/pie-chart | /charts/pie-chart | | ring-chart | Donut / ring KPIs | @bklit/ring-chart | /docs/components/ring-chart | /charts/ring-chart | | radar-chart | Multi-axis comparison | @bklit/radar-chart | /docs/components/radar-chart | /charts/radar-chart | | gauge-chart | Single-value KPI dial | @bklit/gauge-chart | /docs/components/gauge-chart | /charts/gauge-chart | | funnel-chart | Stage conversion funnels | @bklit/funnel-chart | /docs/components/funnel-chart | /charts/funnel-chart | | sankey-chart | Flow between nodes | @bklit/sankey-chart | /docs/components/sankey-chart | /charts/sankey-chart | | choropleth-chart | Geo regions colored by value | @bklit/choropleth-chart | /docs/components/choropleth-chart | /charts/choropleth-chart |

Workflow

1. Run npx shadcn@latest info --json — verify @bklit registry and aliases.
2. Pick a chart from the catalog (or ask the user what story the data tells).
3. Open the doc URL for data shape and props.
4. If not installed: npx shadcn@latest add @bklit/<slug>.
5. Compose with grid, series, axes, tooltip — apply theming tokens.
6. Point the user to the gallery or Studio URL for variant inspiration.

Quick Reference

# Project info
npx shadcn@latest info --json

# Add a chart
npx shadcn@latest add @bklit/line-chart

# Search registries (if configured)
npx shadcn@latest search @bklit

import { LineChart, Line, Grid, XAxis, ChartTooltip, chartCssVars } from "@bklitui/ui/charts";

<LineChart data={data} xDataKey="date">
  <Grid horizontal />
  <Line dataKey="users" stroke={chartCssVars.linePrimary} />
  <XAxis />
  <ChartTooltip />
</LineChart>

Utility docs

• Theming: https://ui.bklit.com/docs/theming
• Grid: https://ui.bklit.com/docs/utility/grid
• Legend: https://ui.bklit.com/docs/utility/legend
• Tooltip: https://ui.bklit.com/docs/utility/tooltip
• Custom indicator: https://ui.bklit.com/docs/utility/custom-indicator
• useChart: https://ui.bklit.com/docs/utility/use-chart

Detailed References

• composition.md
• theming.md
• animation.md
• tooltips.md
• installation.md