@llodev/bi-dashboard 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @llodev/bi-dashboard
+
+## 0.1.0
+
+### Minor Changes
+
+- [#121](https://github.com/llodev/skills/pull/121) [`f55b646`](https://github.com/llodev/skills/commit/f55b646f38d0959f503c79c2e45fc943332f5421) Thanks [@lloliveiradev](https://github.com/lloliveiradev)! - feat(bi-dashboard): first release of the bi-dashboard skill
+
+  New `bi-*` family. `@llodev/bi-dashboard` designs dashboards and charts that
+  state one conclusion before the reader checks an axis. `@llodev/bi` installs
+  the family. No MCP, no runtime.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLDev Information Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+<!-- readme-selector:start -->
+<p align="center">
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
+</p>
+<!-- readme-selector:end -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @llodev/bi-dashboard
+
+> Design dashboards and charts that state one conclusion before the reader checks an axis.
+
+[![npm](https://img.shields.io/npm/v/@llodev/bi-dashboard?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@llodev/bi-dashboard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Agent Skills spec](https://img.shields.io/badge/Agent_Skills-spec-7c5cff)](https://agentskills.io)
+
+Part of the `@llodev/bi` family.
+
+## Install
+
+```bash
+# npm (with skillpm or Claude Code marketplace)
+npm i @llodev/bi-dashboard
+
+# Vercel CLI
+npx skills add llodev/skills/skills/bi-dashboard
+```
+
+No MCP, no config, no init — it's a pure knowledge skill. Once installed it activates on prompts like the ones below.
+
+## Use
+
+| Prompt example                           | What the agent does                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------- |
+| `"build the revenue dashboard"`          | Explores the project, computes one ChartStory per chart, then implements  |
+| `"review this dashboard"`                | Runs exploration and the final checklist, then proposes prioritized edits |
+| `"this chart title just names the axis"` | Rewrites the title as the conclusion and annotates the highlight          |
+
+## Contents
+
+| File                           | Content                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `SKILL.md`                     | Phase order, the four chart rules, and when to read each file.             |
+| `references/explore.md`        | Stack discovery and the token-role map.                                    |
+| `references/story.md`          | `ChartStory`, story functions, locale formatting, titles, SQL.             |
+| `references/form.md`           | Which mark answers which question.                                         |
+| `references/layout.md`         | Page hierarchy, KPI card, states, accessibility.                           |
+| `references/capability-map.md` | The five capabilities, and which library to add when the project has none. |
+| `references/react-recharts.md` | Recharts / shadcn recipe.                                                  |
+| `references/echarts.md`        | ECharts recipe.                                                            |
+| `references/vega-lite.md`      | Vega-Lite / Altair recipe.                                                 |
+| `references/python.md`         | Plotly and matplotlib recipe.                                              |
+| `references/ggplot2.md`        | ggplot2 recipe.                                                            |
+| `references/bi-tools.md`       | Power BI, Looker Studio, Metabase, Superset, Grafana.                      |
+| `anti-patterns/charts.md`      | Titles, color, grid, and untested story logic.                             |
+| `references/verify.md`         | Render, number check, and the final checklist.                             |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: bi-dashboard
+description: >-
+  Designs dashboards, charts, and KPI cards that state one conclusion in
+  seconds: a conclusion title, a single highlight, and the explanation
+  written on the mark. Use when creating, refactoring, or reviewing
+  dashboards and charts in any stack — React and shadcn, Recharts, ECharts,
+  Vega-Lite, Altair, Plotly, matplotlib, ggplot2, SQL, Power BI, Looker
+  Studio, Metabase, Superset, or Grafana. Discover the project design
+  system before picking a color. Triggers include dashboard, chart, KPI,
+  gráfico, storytelling, conclusion title, annotation, and BI.
+license: MIT
+metadata:
+  version: 0.1.0
+  tags:
+    - agent-skill
+    - bi
+    - dashboard
+    - chart
+  family: bi
+  role: skill
+compatibility:
+  agents:
+    - claude-code
+    - cursor
+    - codex
+    - windsurf
+    - cline
+    - roo-code
+---
+
+# Dashboards that explain themselves
+
+This skill guides the design and implementation of dashboards and charts that communicate **one conclusion in seconds**. The quality bar is: a glance reads the title, sees the highlight, and understands the message before reading a single axis.
+
+It applies to any project and stack. The visual (colors, fonts, radii, light/dark theme, components) **is not fixed**: it comes from the project's design system, discovered during exploration, or from the direction of whoever invoked the skill. What is fixed are the communication principles and the process.
+
+## How to use this skill
+
+Follow the phases in order. Do not skip exploration or the story calculation.
+
+| Phase                  | Output                                          | Read                                                                                                                                  |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| 0. Project exploration | Technical context + token map                   | [`references/explore.md`](references/explore.md)                                                                                      |
+| 1. Brief               | Question, audience, decisions, metrics          | this file                                                                                                                             |
+| 2. Story calculation   | Verified numbers and one `ChartStory` per chart | [`references/story.md`](references/story.md)                                                                                          |
+| 3. Design              | Form of each chart + page layout                | [`references/form.md`](references/form.md), then [`references/layout.md`](references/layout.md) when the page has more than one chart |
+| 4. Implementation      | Code in the project's pattern                   | one stack recipe                                                                                                                      |
+| 5. Verification        | Real render + tests + checklist                 | [`references/verify.md`](references/verify.md)                                                                                        |
+
+If the user asks for only one chart, the phases shrink, but they stay in the same order. If they ask for a review of an existing dashboard, read `references/explore.md`, `references/verify.md`, and `anti-patterns/charts.md`, then propose prioritized changes. Do not load a stack recipe for a review that does not ask for an implementation.
+
+## Phase 0 — Explore the project
+
+**MANDATORY — READ ENTIRE FILE**: [`references/explore.md`](references/explore.md).
+
+**Do NOT load** a stack recipe during exploration.
+
+Precedence, copied from that file so it is in force before the read returns: **explicit user direction > the project's design system > libraries/patterns already used in the project > this skill's patterns.**
+
+## Phase 1 — Brief
+
+Answer before choosing charts:
+
+1. **What decision or question** does the dashboard support? (e.g. "was the November campaign worth the investment?")
+2. **Who reads it** and how often? (weekly leadership, real-time operations, end customer)
+3. **Which metrics** answer the question, with an exact definition (formula, filter, time zone, currency).
+4. **What is the comparison baseline** for each metric (period median, target, same period last year, peer average).
+5. **Granularity and period** (day/week/month; last 12 months; closed year).
+6. **Required interactions** (filters, drill-down, export) — only those that change a decision.
+
+A dashboard answers **one main question**. Different questions become different pages or tabs.
+
+## Phase 2 — Compute the story
+
+**MANDATORY — READ ENTIRE FILE**: [`references/story.md`](references/story.md) before writing a title, an annotation, or a SQL query.
+
+**MANDATORY — READ ENTIRE FILE**: [`anti-patterns/charts.md`](anti-patterns/charts.md) before writing a title or an annotation.
+
+**Do NOT load** a stack recipe until the `ChartStory` values exist.
+
+## The four rules of every chart
+
+### Rule 1 — The title is the conclusion
+
+| Descriptive (avoid) | Conclusion (use)                                      |
+| ------------------- | ----------------------------------------------------- |
+| Daily sales         | Black Friday sold 5 times more than a normal day      |
+| Monthly sales       | March sold 51% above a normal month                   |
+| Revenue by channel  | The app tripled and accounted for 84% of the growth   |
+| Users by plan       | Pro grew 5.7 times and passed Basic in week 26        |
+| Costs by category   | Payroll consumes 42% of everything the company spends |
+
+Three text layers, left-aligned on the same margin:
+
+1. **Title** — the conclusion, 1–2 lines, strong weight.
+2. **Subtitle** — what is measured + how to read it: "Daily sales in 2025 · each bar is one day"; "Costs by category · each square = 1% of the R$ 3 mi total".
+3. **Footer** — source and notes, small, discreet.
+
+### Rule 2 — Color leads the eye
+
+- Everything that is context goes in `context` (gray). The title's protagonist goes in `highlight`.
+- **One** protagonist per chart. A second highlight is allowed only for the case in Decisions; otherwise split the chart.
+- The highlight is consistent: the bar, the category label, the annotated value, and (optionally) the title keyword use the same color.
+- The same entity has the same color across the whole dashboard.
+- Never one color per series "just because". Many series: all of them thin in `context`, the protagonist in `highlight` with a direct label.
+- Semantic colors (`positive`/`negative`) only for unambiguous good/bad, always with a sign or text alongside.
+
+### Rule 3 — Remove what does not help the reader
+
+- No background grid. At most the zero line or a reference line that means something.
+- Hide the Y axis when the key values are annotated; keep it when the reader needs to read arbitrary values (operations, analysis).
+- Minimal ticks: abbreviated months instead of full dates; few values on the axis when it exists.
+- No legend when you can label directly; a long legend is a sign to redesign.
+- No 3D, gradients, heavy shadows, borders on every element, markers on every point.
+- **The form can be noise too**: a noisy daily series as a line becomes a scribble; thin bars (one per day) show each day's volume and make the peak pop. Change the form when it does not answer the question ([`references/form.md`](references/form.md)).
+
+### Rule 4 — Write the explanation on the chart
+
+- An important value **beside** the important point, in `highlight-text`: a large value (`R$ 78,4 MIL`) + one line of context (`28 nov · 5 times a normal day`).
+- A reference line labeled on the line itself: `normal day (median) · R$ 15,4 mil` — that is what gives meaning to the "5 times".
+- A direct label at the end of the lines (`Pro 8.550`), values on the bars when there are ≤ 12 categories.
+- Annotate crossings and events at the exact point (`week 26 · Pro passes Basic`).
+- Annotations of ≤ 2 lines, close to the element, without covering data.
+
+## Decisions
+
+Refuse a second highlight unless the conclusion names two subjects the reader must compare in one glance: a crossing, or a before/after pair. A second "also important" series is another chart. If the title needs a second finding, split it.
+
+When a filter can change a number, entity, rank, or comparison cited in the title, subtitle, highlight, or annotation, recompute all four from the filtered slice before render. An empty slice replaces the title with the empty-state sentence. Never leave the unfiltered conclusion on screen.
+
+## Phase 3 — Design
+
+**MANDATORY — READ ENTIRE FILE**: [`references/form.md`](references/form.md) before choosing a mark.
+
+Read [`references/layout.md`](references/layout.md) entire when the page has a KPI row or more than one chart.
+
+**Do NOT load** `references/layout.md` for a single chart with no page around it.
+
+## Phase 4 — Implement in the project
+
+Every recipe implements the same story: daily bars in `context`, the peak in `highlight`, a labeled dashed median, an annotation beside the peak, no grid and no Y axis. Adapt the names and the tokens to the project.
+
+1. **Data layer**: a query/endpoint that already returns the complete series (no gaps), at the right granularity, aggregated in the database when the volume is large.
+2. **Story layer**: pure functions ([`references/story.md`](references/story.md)) that produce the `ChartStory`. They stay testable and reusable (e.g. `lib/chart-story.ts`, `analytics/story.py`).
+3. **Visual layer**: components that receive `data` + `story` + formatters and only draw. No business rule inside the component.
+4. **Tokens**: components read the roles ([`references/explore.md`](references/explore.md)) through CSS variables, the library theme, or project constants — never a loose hex in the component.
+5. **Composition**: build the page with the existing layout components (grid, card, filters).
+6. **Tests**: test the story functions (peak, median, crossing, title with fallback) with edge cases (empty series, zero baseline, tie, filter with no data).
+
+Typical structure in a React app:
+
+```
+lib/chart-story.ts            ← median, peakVsBaseline, shares, growth, firstCrossing, makeFormat, titles
+components/charts/peak-bars.tsx
+components/charts/highlight-line.tsx
+components/charts/ranked-bars.tsx
+components/dashboard/kpi-card.tsx
+app/(dashboard)/sales/page.tsx
+```
+
+**MANDATORY**: read [`references/capability-map.md`](references/capability-map.md) entire when the project has no chart library, or when the library is not one of the recipes below.
+
+**MANDATORY**: read exactly one recipe, the library the project already uses.
+
+| Signal                                                  | Read                                                           |
+| ------------------------------------------------------- | -------------------------------------------------------------- |
+| React, shadcn/ui, or Recharts                           | [`references/react-recharts.md`](references/react-recharts.md) |
+| ECharts                                                 | [`references/echarts.md`](references/echarts.md)               |
+| Vega-Lite or Altair                                     | [`references/vega-lite.md`](references/vega-lite.md)           |
+| Plotly, matplotlib, Streamlit, or Dash                  | [`references/python.md`](references/python.md)                 |
+| ggplot2 or R                                            | [`references/ggplot2.md`](references/ggplot2.md)               |
+| Power BI, Looker Studio, Metabase, Superset, or Grafana | [`references/bi-tools.md`](references/bi-tools.md)             |
+
+**Do NOT load** the other recipes for the same chart.
+
+## Phase 5 — Verify
+
+**MANDATORY — READ ENTIRE FILE**: [`references/verify.md`](references/verify.md).
+
+## Before a chart title, and before handing off a review
+
+**MANDATORY — read [`anti-patterns/charts.md`](anti-patterns/charts.md) entire.**
+
+## References
+
+| File                           | Load when                                            |
+| ------------------------------ | ---------------------------------------------------- |
+| `references/explore.md`        | Phase 0, and any review                              |
+| `references/story.md`          | Phase 2, before any title or annotation              |
+| `references/form.md`           | Choosing a mark                                      |
+| `references/layout.md`         | A page with more than one chart or a KPI row         |
+| `references/verify.md`         | Phase 5, and any review                              |
+| `references/capability-map.md` | No chart library yet, or a library with no recipe    |
+| `references/react-recharts.md` | React / shadcn / Recharts                            |
+| `references/echarts.md`        | ECharts                                              |
+| `references/vega-lite.md`      | Vega-Lite or Altair                                  |
+| `references/python.md`         | Plotly, matplotlib, Streamlit, Dash                  |
+| `references/ggplot2.md`        | ggplot2 or R                                         |
+| `references/bi-tools.md`       | Power BI, Looker Studio, Metabase, Superset, Grafana |
+| `anti-patterns/charts.md`      | Before a title, and before a review handoff          |

package/anti-patterns/charts.md

@@ -0,0 +1,14 @@
+## 12. Anti-patterns
+
+NEVER ship these. Each one looks finished and still makes the chart lie or go unread.
+
+- NEVER use a generic title ("Chart Title", "Daily sales") or one that only repeats the axes. The title is also the accessible name. A reader trained by restated axes stops reading titles, so the conclusion on the next chart is skipped, and a screen-reader user never hears the finding.
+- NEVER use the library's default palette, a rainbow, or one color per series for no reason. Default categorical palettes put red beside green, so a region is decoded as good or bad. Neighboring hues also collapse under deuteranopia, and the series you meant as the protagonist is not the one that remains distinct.
+- NEVER draw a spaghetti chart with no protagonist, or a long legend far from the marks. Matching a legend swatch back to a thin line is a second fixation. Once hues sit next to each other, that saccade lands on the wrong series and the argument proceeds about the wrong trend. Labels on all twelve lines collide; one highlighted series is the fix.
+- NEVER keep a heavy grid, an axis with dozens of ticks, or full dates on every tick. A grid at the same stroke width as the series creates crossings that read as data points. A full date on every tick is a unique string, so the eye cannot group month starts, and the date in the annotation stops being the only date on the chart.
+- NEVER use a line for a noisy daily series when the question is "which day was different". A line asserts a slope. Tuesday-to-Wednesday is the difference of two noisy totals, not a rate anyone should act on. The peak is then a vertex with no area, so "how much bigger than normal" is harder to see than a bar against the median bar.
+- NEVER show a KPI with no comparison baseline, or red/green with no sign or text. A bare total invites a baseline from memory, and that memory is the wrong period. Color without a sign dies in a screenshot or a chat paste. Red is also unstable across one KPI row: up is bad for cost and not bad for revenue.
+- NEVER put a border and a shadow on every card and every chart, and never use 3D or decorative gradients. People judge a bar's height by its darker edge, so a shadow adds phantom height. Perspective shrinks the back of a 3D chart, and a smaller category drawn behind a larger one can look bigger. A border on every card is a common-region cue, so twelve cards read as twelve unrelated facts.
+- NEVER hardcode colors that ignore the design system, and never ship a broken dark theme. The failure is not "off brand." A hex that cleared 4.5:1 on white drops under 3:1, or matches the context gray, once the surface flips dark, so the protagonist stops popping for the theme you did not open. A second chart that picks its own orange also splits one entity into two.
+- NEVER leave a fixed title that a filter makes false. The title is believed first and checked never. Bars that move feel like the page updated, which makes the stale sentence more trusted, not less. An empty slice is the sharp case: the marks disappear and the title still reports the peak.
+- NEVER hide business logic (median, peak, titles) inside the visual component, untested. The query title and the component median disagree on zeros, nulls, gap-fill, and filter context, so the annotation names a different day than the title. Logic that lives only in the render path never gets imported by a unit test, and the honest fallback ships unexecuted.

package/docs/i18n/README.es-ES.md

@@ -0,0 +1,61 @@
+<!-- readme-selector:start -->
+<p align="center">
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
+</p>
+<!-- readme-selector:end -->
+
+# @llodev/bi-dashboard
+
+> Diseña dashboards y gráficos que afirman una conclusión antes de que el lector consulte un eje.
+
+[![npm](https://img.shields.io/npm/v/@llodev/bi-dashboard?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@llodev/bi-dashboard)
+[![Licencia: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Agent Skills spec](https://img.shields.io/badge/Agent_Skills-spec-7c5cff)](https://agentskills.io)
+
+Parte de la familia `@llodev/bi`.
+
+## Instalación
+
+```bash
+# npm (con skillpm o el marketplace de Claude Code)
+npm i @llodev/bi-dashboard
+
+# Vercel CLI
+npx skills add llodev/skills/skills/bi-dashboard
+```
+
+Sin MCP, sin configuración, sin init — es una skill de conocimiento puro. Tras instalarla, se activa con prompts como los de abajo.
+
+## Uso
+
+| Ejemplo de prompt                        | Qué hace el agente                                                          |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| `"build the revenue dashboard"`          | Explora el proyecto, calcula un ChartStory por gráfico y luego implementa   |
+| `"review this dashboard"`                | Ejecuta la exploración y el checklist final y propone ediciones priorizadas |
+| `"this chart title just names the axis"` | Reescribe el título como la conclusión y anota el destacado                 |
+
+## Contenido
+
+| Archivo                        | Contenido                                                                          |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `SKILL.md`                     | Orden de las fases, las cuatro reglas de gráfico y cuándo leer cada archivo.       |
+| `references/explore.md`        | Descubrimiento del stack y el mapa de roles de los tokens.                         |
+| `references/story.md`          | `ChartStory`, funciones de la historia, formato de locale, títulos, SQL.           |
+| `references/form.md`           | Qué marca responde a qué pregunta.                                                 |
+| `references/layout.md`         | Jerarquía de la página, tarjeta de KPI, estados, accesibilidad.                    |
+| `references/capability-map.md` | Las cinco capacidades y qué biblioteca añadir cuando el proyecto no tiene ninguna. |
+| `references/react-recharts.md` | Receta de Recharts / shadcn.                                                       |
+| `references/echarts.md`        | Receta de ECharts.                                                                 |
+| `references/vega-lite.md`      | Receta de Vega-Lite / Altair.                                                      |
+| `references/python.md`         | Receta de Plotly y matplotlib.                                                     |
+| `references/ggplot2.md`        | Receta de ggplot2.                                                                 |
+| `references/bi-tools.md`       | Power BI, Looker Studio, Metabase, Superset, Grafana.                              |
+| `anti-patterns/charts.md`      | Títulos, color, cuadrícula y lógica de historia sin pruebas.                       |
+| `references/verify.md`         | Renderizado, comprobación de números y el checklist final.                         |
+
+## Licencia
+
+MIT — consulta [LICENSE](../../LICENSE).

package/docs/i18n/README.pt-BR.md

@@ -0,0 +1,61 @@
+<!-- readme-selector:start -->
+<p align="center">
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/skills/bi-dashboard/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
+</p>
+<!-- readme-selector:end -->
+
+# @llodev/bi-dashboard
+
+> Projete dashboards e gráficos que afirmam uma conclusão antes de o leitor conferir um eixo.
+
+[![npm](https://img.shields.io/npm/v/@llodev/bi-dashboard?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@llodev/bi-dashboard)
+[![Licença: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Agent Skills spec](https://img.shields.io/badge/Agent_Skills-spec-7c5cff)](https://agentskills.io)
+
+Parte da família `@llodev/bi`.
+
+## Instalação
+
+```bash
+# npm (com skillpm ou marketplace do Claude Code)
+npm i @llodev/bi-dashboard
+
+# Vercel CLI
+npx skills add llodev/skills/skills/bi-dashboard
+```
+
+Sem MCP, sem config, sem init — é uma skill de conhecimento puro. Após instalar, ela é ativada por prompts como os abaixo.
+
+## Uso
+
+| Exemplo de prompt                        | O que o agente faz                                                      |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `"build the revenue dashboard"`          | Explora o projeto, calcula um ChartStory por gráfico e então implementa |
+| `"review this dashboard"`                | Roda a exploração e o checklist final e propõe edições priorizadas      |
+| `"this chart title just names the axis"` | Reescreve o título como a conclusão e anota o destaque                  |
+
+## Conteúdo
+
+| Arquivo                        | Conteúdo                                                                           |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `SKILL.md`                     | Ordem das fases, as quatro regras de gráfico e quando ler cada arquivo.            |
+| `references/explore.md`        | Descoberta da stack e o mapa de papéis dos tokens.                                 |
+| `references/story.md`          | `ChartStory`, funções da história, formatação de locale, títulos, SQL.             |
+| `references/form.md`           | Qual marca responde a qual pergunta.                                               |
+| `references/layout.md`         | Hierarquia da página, card de KPI, estados, acessibilidade.                        |
+| `references/capability-map.md` | As cinco capacidades e qual biblioteca adicionar quando o projeto não tem nenhuma. |
+| `references/react-recharts.md` | Receita de Recharts / shadcn.                                                      |
+| `references/echarts.md`        | Receita de ECharts.                                                                |
+| `references/vega-lite.md`      | Receita de Vega-Lite / Altair.                                                     |
+| `references/python.md`         | Receita de Plotly e matplotlib.                                                    |
+| `references/ggplot2.md`        | Receita de ggplot2.                                                                |
+| `references/bi-tools.md`       | Power BI, Looker Studio, Metabase, Superset, Grafana.                              |
+| `anti-patterns/charts.md`      | Títulos, cor, grade e lógica de história sem testes.                               |
+| `references/verify.md`         | Renderização, checagem de números e o checklist final.                             |
+
+## Licença
+
+MIT — veja [LICENSE](../../LICENSE).

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@llodev/bi-dashboard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Design dashboards and charts that state one conclusion before the reader checks an axis.",
+  "license": "MIT",
+  "homepage": "https://github.com/llodev/skills/tree/main/skills/bi-dashboard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llodev/skills.git",
+    "directory": "skills/bi-dashboard"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "anti-patterns",
+    "references",
+    "docs"
+  ],
+  "keywords": [
+    "agent-skill",
+    "bi",
+    "dashboard",
+    "chart"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }

package/references/bi-tools.md

@@ -0,0 +1,34 @@
+### 9.6 BI tools (Power BI, Looker Studio, Metabase, Superset, Grafana)
+
+The same principles, with each tool's native features:
+
+- **Dynamic conclusion title**: a measure or calculated field that generates the sentence, bound to the visual title through conditional formatting.
+- **Highlight**: conditional color formatting by rule (is it the maximum? is it the selected category?) with the highlight color and gray for the rest.
+- **Reference line**: a constant or median line from the visual itself or a dedicated measure, with a data label.
+- **Cleanup**: turn off the grid, axis titles, the Y axis, and the legend; data labels only on the highlight.
+
+Power BI (DAX) — measures for the title and the color:
+
+```dax
+Daily Median =
+MEDIANX ( ALLSELECTED ( 'Calendar'[Date] ), [Sales] )
+
+Daily Peak =
+MAXX ( ALLSELECTED ( 'Calendar'[Date] ), [Sales] )
+
+Daily Sales Title =
+VAR factor = DIVIDE ( [Daily Peak], [Daily Median] )
+RETURN
+    IF (
+        factor >= 1.5,
+        "The peak sold " & FORMAT ( factor, "0" ) & " times more than a normal day",
+        "Daily sales stayed flat over the period"
+    )
+
+Sales Bar Color =
+IF ( [Sales] = [Daily Peak], "#E8590C", "#C4C4C4" )
+```
+
+Apply `Daily Sales Title` in _Title → fx_ and `Sales Bar Color` in _Columns → Color → fx (field value)_; replace the hex values with the report theme's. Adjust the `FORMAT` rounding rule to follow [`references/story.md`](story.md) when the factor is not close to an integer.
+
+---

package/references/capability-map.md

@@ -0,0 +1,17 @@
+## 9. Recipes by stack
+
+Every recipe implements the same story: daily bars in `context`, the peak in `highlight`, a labeled dashed median, an annotation beside the peak, no grid and no Y axis. Adapt the names and the tokens to the project.
+
+### 9.0 Capability map (for any library)
+
+Every library has to do five things. If the project's library is not below, look up the equivalent:
+
+| Capability     | Recharts / shadcn                      | ECharts                                    | Vega-Lite / Altair          | Plotly                            | matplotlib                     | ggplot2                               | Chart.js                | Highcharts              |
+| -------------- | -------------------------------------- | ------------------------------------------ | --------------------------- | --------------------------------- | ------------------------------ | ------------------------------------- | ----------------------- | ----------------------- |
+| Color per item | `<Cell fill>`                          | `itemStyle` per datum                      | `color` with `condition`    | `marker_color` list               | `color=` list                  | `fill` + `scale_fill_manual`          | `backgroundColor` array | `point.color` / `zones` |
+| Reference line | `<ReferenceLine>`                      | `markLine`                                 | `rule` layer                | `add_hline`                       | `axhline`                      | `geom_hline`                          | annotation plugin       | `plotLines`             |
+| Annotated text | `<ReferenceDot label>` / `<LabelList>` | `markPoint.label`                          | `text` layer                | `add_annotation`                  | `annotate`                     | `annotate("text")`                    | annotation plugin       | annotations module      |
+| Shaded band    | `<ReferenceArea>`                      | `markArea`                                 | `rect`                      | `add_vrect`                       | `axvspan`                      | `annotate("rect")`                    | annotation plugin (box) | `plotBands`             |
+| No grid / axis | omit `<CartesianGrid>`, `<YAxis hide>` | `splitLine.show=false`, `yAxis.show=false` | `axis: null`, `grid: false` | `showgrid=False`, `visible=False` | `spines`, `set_visible(False)` | `theme(panel.grid = element_blank())` | `grid.display=false`    | `gridLineWidth: 0`      |
+
+Choosing a library when the project has none: React + shadcn/ui → **shadcn charts (Recharts)**; web with many points (>10 thousand) or heavy interaction → **ECharts**; a portable spec or notebooks → **Vega-Lite/Altair**; analytical Python → **Plotly** (interactive) or **matplotlib** (static); R → **ggplot2**.