@llodev/bi-dashboard 0.0.0-stage → 0.0.0

package/references/echarts.md

@@ -0,0 +1,124 @@
+### 9.2 ECharts — TypeScript (React, Vue, Angular, or vanilla)
+
+The ECharts canvas does not understand `var(--…)` nor, in every operation, `oklch()`. Resolve the tokens to `rgb` first:
+
+```ts
+import type { EChartsOption } from "echarts";
+
+/** Converts any CSS color (including var(--x) and oklch) into rgb(a) the canvas can read. */
+export function resolveColor(css: string, el: HTMLElement = document.documentElement): string {
+  const probe = document.createElement("span");
+  probe.style.color = css;
+  el.appendChild(probe);
+  const computed = getComputedStyle(probe).color;
+  probe.remove();
+  const ctx = document.createElement("canvas").getContext("2d")!;
+  ctx.fillStyle = computed;
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+  return a === 255 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${(a / 255).toFixed(3)})`;
+}
+
+export type Roles = {
+  ink: string;
+  muted: string;
+  context: string;
+  highlight: string;
+  highlightText: string;
+  font: string;
+};
+
+export const readRoles = (): Roles => ({
+  ink: resolveColor("var(--foreground)"),
+  muted: resolveColor("var(--muted-foreground)"),
+  context: resolveColor("color-mix(in oklab, var(--muted-foreground) 35%, transparent)"),
+  highlight: resolveColor("var(--chart-1)"),
+  highlightText: resolveColor("var(--chart-1)"),
+  font: getComputedStyle(document.body).fontFamily, // the canvas does not accept "inherit"
+});
+
+export function peakBarsOption(
+  dates: string[],
+  values: number[],
+  s: {
+    title: string;
+    subtitle: string;
+    baseline: number;
+    baselineLabel: string;
+    peakIndex: number;
+    peakValue: string;
+    peakNote: string;
+  },
+  c: Roles,
+  month: (iso: string) => string,
+  money: (v: number) => string,
+): EChartsOption {
+  return {
+    animation: false,
+    textStyle: { fontFamily: c.font },
+    title: {
+      left: 0,
+      text: s.title,
+      subtext: s.subtitle,
+      textStyle: { fontSize: 20, fontWeight: 800, color: c.ink },
+      subtextStyle: { fontSize: 12, color: c.muted },
+    },
+    grid: { left: 8, right: 8, top: 88, bottom: 28, containLabel: true },
+    tooltip: { trigger: "axis", valueFormatter: (v) => money(Number(v)) },
+    xAxis: {
+      type: "category",
+      data: dates,
+      axisLine: { show: false },
+      axisTick: { show: false },
+      splitLine: { show: false },
+      axisLabel: {
+        color: c.muted,
+        fontSize: 11,
+        interval: (_i: number, v: string) => v.endsWith("-01"),
+        formatter: month,
+      },
+    },
+    yAxis: { type: "value", show: false },
+    series: [
+      {
+        type: "bar",
+        barCategoryGap: "35%",
+        data: values.map((v, i) => ({
+          value: v,
+          itemStyle: { color: i === s.peakIndex ? c.highlight : c.context },
+        })),
+        markLine: {
+          symbol: "none",
+          silent: true,
+          lineStyle: { type: "dashed", width: 1, color: c.muted },
+          label: {
+            position: "insideStartTop",
+            color: c.muted,
+            fontSize: 11,
+            formatter: s.baselineLabel,
+          },
+          data: [{ yAxis: s.baseline }],
+        },
+        markPoint: {
+          symbol: "rect",
+          symbolSize: 1,
+          itemStyle: { color: "transparent" },
+          label: {
+            show: true,
+            position: "left",
+            align: "right",
+            formatter: `{v|${s.peakValue}}\n{d|${s.peakNote}}`,
+            rich: {
+              v: { fontSize: 22, fontWeight: 800, color: c.highlightText },
+              d: { fontSize: 12, color: c.highlightText },
+            },
+          },
+          data: [{ name: "peak", coord: [s.peakIndex, values[s.peakIndex]] }],
+        },
+      },
+    ],
+  };
+}
+```
+
+Use: `chart.setOption(peakBarsOption(...))`; when the theme changes (the `.dark` class or `prefers-color-scheme`), call `readRoles()` again and reapply the option. With many points, `large: true` and `sampling: "lttb"` (lines).

package/references/explore.md

@@ -0,0 +1,71 @@
+## 1. Phase 0 — Explore the project
+
+Before writing code, find out what already exists. The precedence rule is:
+
+**explicit user direction > the project's design system > libraries/patterns already used in the project > this skill's patterns.**
+
+### 1.1 Stack and where the dashboard lives
+
+Search and read (when they exist):
+
+- **JS/TS**: `package.json` (React, Next.js, Vue, Svelte, Angular; chart libs: `recharts`, `echarts`, `@nivo/*`, `chart.js`, `highcharts`, `@visx/*`, `vega-lite`, `plotly.js`), `components.json` (shadcn/ui), `tsconfig.json` (aliases such as `@/`), the `components/ui/` folder (is there a `chart.tsx`? a `card.tsx`?).
+- **Python**: `pyproject.toml`, `requirements*.txt`, notebooks (`plotly`, `matplotlib`, `seaborn`, `altair`, `streamlit`, `dash`, `panel`), `.streamlit/config.toml`, `matplotlibrc`.
+- **R**: `DESCRIPTION`, `renv.lock`, `*.Rmd`/`*.qmd` (`ggplot2`, `shiny`, `plotly`).
+- **BI**: `.pbix`/`.pbip`/TMDL files (Power BI), exported dashboards from Metabase, Superset, Looker Studio, Grafana (JSON).
+- **Data**: where it comes from (SQL directly, ORM, API, CSV/Parquet, warehouse), SQL dialect, granularity, time zone, currency.
+- **Conventions**: folder structure, naming, lint/format, existing tests, i18n (`next-intl`, `i18next`, `locale` in config).
+
+Use the chart library **the project already uses**. Introduce a new one only if there is none or the user asks; in that case, choose by stack ([`references/capability-map.md`](capability-map.md)) and justify it in one line.
+
+### 1.2 Design system → token map
+
+Find the visual sources of truth:
+
+| Ecosystem                    | Where to look                                                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| shadcn/ui + Tailwind v4      | `globals.css`/`app.css`: `:root` and `.dark` with `--background`, `--foreground`, `--card`, `--muted`, `--muted-foreground`, `--border`, `--primary`, `--chart-1…5`, `--radius`; `@theme inline` |
+| Tailwind v3                  | `tailwind.config.*` (`theme.extend.colors`, `fontFamily`, `borderRadius`) + HSL variables in CSS (`hsl(var(--chart-1))`)                                                                         |
+| MUI / Chakra / Mantine / Ant | theme object (`createTheme`, `extendTheme`, `MantineProvider`, `ConfigProvider`)                                                                                                                 |
+| Dedicated tokens             | `tokens.json`, Style Dictionary, Figma tokens, `design-tokens/`                                                                                                                                  |
+| Python/R                     | Plotly theme (`pio.templates`), `matplotlibrc`/styles, ggplot `theme_*()`, Streamlit `config.toml`                                                                                               |
+| BI                           | Power BI JSON theme, Metabase/Superset theme, corporate palette                                                                                                                                  |
+
+Also identify: the dark-theme mechanism (`.dark` class, `data-theme`, `prefers-color-scheme`), the interface font and whether it has tabular numerals, the default radius and spacing, and existing card/table/filter components.
+
+Translate what you found into **roles**. Chart code uses the roles, never the raw colors:
+
+| Role                    | What it is                             | How to infer                                                                                                                                            |
+| ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ink`                   | titles and values                      | project foreground                                                                                                                                      |
+| `muted`                 | subtitles, axes, context labels        | muted-foreground / secondary text                                                                                                                       |
+| `context`               | marks that serve as comparison         | a system gray (or `muted-foreground` at 30–45% opacity)                                                                                                 |
+| `reference`             | median/target lines                    | `muted` with a dashed stroke                                                                                                                            |
+| `highlight`             | the protagonist mark                   | a **saturated** brand color: `--chart-1` or `--primary` if it is chromatic; if the primary is neutral (black/gray), use the first saturated chart color |
+| `highlight-text`        | annotation text in the highlight color | `highlight` if it has contrast ≥ 4.5:1 against the card background; otherwise a darker variant (light theme) or a lighter one (dark theme)              |
+| `highlight-soft`        | shaded bands, areas                    | `highlight` at 10–15% opacity                                                                                                                           |
+| `positive` / `negative` | unambiguous good/bad signal            | system semantic tokens (success/destructive)                                                                                                            |
+| `surface` / `page`      | card and page background               | card / background                                                                                                                                       |
+
+Map rules:
+
+- `highlight` **must not** be the semantic error color (red) unless the highlight is something bad. If the brand is red, say so and prefer another system color or the less semantic brand tone.
+- Validate contrast: text ≥ 4.5:1 (≥ 3:1 if large/bold), essential graphical marks ≥ 3:1 against the background. `context` may have low contrast on purpose, as long as the essential information is in the highlight and the annotations.
+- Do not assume `--chart-1` (or the first chart token) is the best highlight color: in several themes it is a light, low-contrast tone. Choose the saturated chart token that passes contrast.
+- Validate both themes if the project has a dark theme.
+- **Fallback** (only if there is no design system and no user direction): `ink #1A1A1A`, `muted #6B6B6B`, `context #C4C4C4`, `reference #8A8A8A`, `highlight #E8590C`, `highlight-text #C2410C`, `surface #FFFFFF`, `page #F4F4F2`; dark: `ink #F2F2F2`, `muted #A0A3A8`, `context #4A4D52`, `highlight #FF7A1A`, `surface #1C1E22`, `page #0F1115`. Font: the system sans-serif (`Inter`, `system-ui`).
+
+### 1.3 Exploration output
+
+Record a few lines (in the chat or in the PR) before implementing:
+
+```
+Stack: Next.js 15 + shadcn/ui (Tailwind v4) + Recharts 3 — use components/ui/chart.tsx
+Data: Postgres via Drizzle; daily sales in orders.amount (BRL, America/Sao_Paulo)
+Tokens: highlight=var(--chart-1) · context=var(--muted-foreground)/35% · surface=var(--card) · dark via .dark
+Locale: pt-BR · currency BRL · Geist font (tabular-nums available)
+Decisions: reuse <Card>; filters in components/filters/date-range.tsx
+```
+
+If something essential cannot be discovered (audience, main question, data source), ask **once**, concretely. Assume the rest and state the assumption.
+
+---

package/references/form.md

@@ -0,0 +1,32 @@
+## 5. Choose the form from the data and the question
+
+| Data / question                                       | Form                                                           | How to highlight                                                                |
+| ----------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Long time series: "did any period break from normal?" | Thin bars per period                                           | Event bar in `highlight`, dashed median, annotation                             |
+| Time series: "how did it evolve? who passed whom?"    | Line (2–5 series)                                              | Colored protagonist, the rest `context`, label at the end, mark at the crossing |
+| Series with many entities (years, stores, SKUs)       | Thin `context` lines + 1 highlighted + dotted average          | Direct labels on the highlighted series and on the average                      |
+| Categories (≤ 12): "which one stood out?"             | Sorted bars (horizontal if the names are long)                 | Protagonist bar and its label in `highlight`, values on the bars                |
+| Before × after by category                            | Bars with a marker for the previous period, slope, or dumbbell | Annotated change (`+203%`)                                                      |
+| Part of a whole                                       | Sorted bars or a unit chart (each square = 1%)                 | Protagonist category colored; avoid a pie with > 3 slices                       |
+| Distribution                                          | Histogram, density, boxplot, strip                             | Band or group of interest colored                                               |
+| Relationship between measures                         | Scatter                                                        | Group/quadrant in `highlight-soft` (shaded area), labels on the relevant points |
+| Time × group matrix (cohorts, hour × day)             | Single-color sequential heatmap                                | Relevant cell/row with an outline or annotation                                 |
+| Funnel                                                | Cascading horizontal bars with the pass-through rate           | Stage with the largest loss in `highlight`                                      |
+| Geographic                                            | Monochrome choropleth or symbol map                            | Protagonist region in `highlight`, the rest neutral                             |
+| Exact values for lookup                               | Compact table with inline bars and a highlighted row           | Column sorted by the story metric                                               |
+| One number matters                                    | KPI card                                                       | Delta with an explicit baseline                                                 |
+
+Avoid: pie/donut with many slices, 3D, dual axes (use two aligned charts), radar, gauges, stacked area with many layers, a giant table as the main visual.
+
+---
+
+## 6. Perception principles in practice
+
+- **Closure**: the reader completes incomplete shapes; that is why the axis, frame, separators, and grid can go without hurting reading.
+- **Common region**: what sits inside the same area is one group. Group related KPIs on the same background (instead of a border per number); shade the part of the chart that matters (forecast period, campaign window, quadrant). Borders on every element fragment the dashboard.
+- **Continuity**: the eye follows lines and alignments. Align charts that share time on the same axis and scale; let the reference line run across the chart.
+- **Proximity**: the label sits against the mark; the title sits against the chart; more space **between** groups than **inside** them.
+- **Similarity**: same color/shape = the same thing across the whole dashboard.
+- **Preattentive processing (figure and ground)**: one element that differs in color, size, or weight pops out before conscious reading — and the effect disappears when everything is different.
+
+---

package/references/ggplot2.md

@@ -0,0 +1,37 @@
+### 9.5 R — ggplot2
+
+```r
+library(ggplot2)
+library(dplyr)
+
+roles  <- c(ink = "#1A1A1A", muted = "#6B6B6B", context = "#C4C4C4", highlight = "#E8590C", highlight_text = "#C2410C")
+months <- c("JAN","FEV","MAR","ABR","MAI","JUN","JUL","AGO","SET","OUT","NOV","DEZ")
+money  <- function(v) paste0("R$ ", format(round(v / 1e3, 1), big.mark = ".", decimal.mark = ",", nsmall = 1), " mil")
+
+baseline <- median(df$value)
+peak     <- slice_max(df, value, n = 1, with_ties = FALSE)
+factor   <- peak$value / baseline
+
+ggplot(df, aes(date, value)) +
+  geom_col(aes(fill = date == peak$date), width = 0.7) +
+  scale_fill_manual(values = c(`FALSE` = roles[["context"]], `TRUE` = roles[["highlight"]]), guide = "none") +
+  geom_hline(yintercept = baseline, linetype = "dashed", linewidth = 0.3, colour = roles[["muted"]]) +
+  annotate("label", x = min(df$date), y = baseline, label = paste("normal day (median) ·", money(baseline)),
+           hjust = 0, vjust = -0.3, size = 3, colour = roles[["muted"]], label.size = 0, fill = "white") +
+  annotate("text", x = peak$date - 3, y = peak$value, hjust = 1, vjust = 1, lineheight = 0.95,
+           label = paste0(toupper(money(peak$value)), "\n", round(factor), " times a normal day"),
+           colour = roles[["highlight_text"]], fontface = "bold", size = 4.5) +
+  scale_x_date(date_breaks = "1 month", labels = function(d) months[as.integer(format(d, "%m"))],
+               expand = expansion(mult = 0.01)) +
+  labs(title = "Black Friday sold 5 times more than a normal day",
+       subtitle = "Daily sales in 2025 · each bar is one day", caption = "SOURCE: SALES.CSV", x = NULL, y = NULL) +
+  theme_minimal(base_size = 11) +
+  theme(panel.grid = element_blank(), axis.text.y = element_blank(),
+        axis.text.x = element_text(colour = roles[["muted"]]),
+        plot.title.position = "plot", plot.caption.position = "plot",
+        plot.title = element_text(face = "bold", size = 18, colour = roles[["ink"]]),
+        plot.subtitle = element_text(colour = roles[["muted"]]),
+        plot.caption = element_text(colour = roles[["muted"]], size = 8, hjust = 0))
+```
+
+In production, generate the title with the same logic as `peak_story` (factor ≥ 1.5, honest rounding). In Shiny, wrap it in `renderPlot` and recompute `baseline`/`peak` from the filtered slice.

package/references/layout.md

@@ -0,0 +1,44 @@
+## 7. Dashboard layout and components
+
+### 7.1 Page hierarchy
+
+1. **Header**: the dashboard's conclusion title ("Revenue grew 18% in 2025, driven by the app"), subtitle (period, slice, refresh), discreet global filters.
+2. **KPI band**: 3–5 numbers that answer the main question, grouped by theme.
+3. **Protagonist chart**: proves the dashboard title; full width or 2/3.
+4. **Supporting charts**: 2–4, each with its own conclusion title, explaining the why.
+5. **Detail** (optional): a table for checking.
+
+A 12-column grid with the design system's spacing; ~6–9 visuals per screen at most; charts that share a time axis stay aligned; on narrow screens, stack them in hierarchy order.
+
+### 7.2 KPI card
+
+```
+REVENUE 2025                ← label (muted, small)
+R$ 18,4 mi                  ← value (ink, large, tabular-nums)
++18% vs. 2024               ← delta WITH an explicit baseline
+▁▂▂▃▂▃▄▃▄▅▆█                ← optional sparkline: context, last point in highlight
+```
+
+Delta neutral by default; `positive`/`negative` only when good/bad is unambiguous, always with a sign. Optionally, a short sentence in place of the delta ("best month of the year").
+
+### 7.3 Chart card
+
+Use the project's card component. Inside: title → subtitle → chart → footer, all on the same left margin. No extra border when the card background already separates it from the page.
+
+### 7.4 Interaction and states
+
+- **Dynamic titles and highlights**: recomputed on every filter by the [`references/story.md`](story.md) functions.
+- The **tooltip** carries the exact detail; the essential is already annotated.
+- Hover/selection emphasizes the entity and dims the others (the same highlight logic).
+- Filters with a visible state ("2025 · All channels").
+- Loading (a skeleton in the card's shape), empty (a sentence explaining why), and error (message + action) states.
+- A short animation (≤ 300 ms) only on transitions; no decorative animation on load.
+
+### 7.5 Accessibility
+
+- `aria-label`/`<figcaption>` with the title's conclusion and the key value; offer the data table (or a download) as an alternative.
+- Meaning never by color alone: the highlight also uses a label, weight, or position.
+- Keyboard focus on the controls; accessible tooltips when the library allows (e.g. `accessibilityLayer` in Recharts).
+- Respect `prefers-reduced-motion`.
+
+---

package/references/python.md

@@ -0,0 +1,103 @@
+### 9.4 Python — Plotly (also Streamlit and Dash) and matplotlib
+
+Story layer and formatting (pt-BR, without depending on the system locale):
+
+```python
+import pandas as pd
+
+MONTHS = ["JAN", "FEV", "MAR", "ABR", "MAI", "JUN", "JUL", "AGO", "SET", "OUT", "NOV", "DEZ"]
+ROLES = {  # fill in from the project design system
+    "ink": "#1A1A1A", "muted": "#6B6B6B", "context": "#C4C4C4",
+    "highlight": "#E8590C", "highlight_text": "#C2410C", "surface": "#FFFFFF",
+}
+
+def num_br(v: float, digits: int = 1) -> str:
+    return f"{v:,.{digits}f}".replace(",", "X").replace(".", ",").replace("X", ".")
+
+def money(v: float, digits: int = 1) -> str:
+    if abs(v) >= 1e6:
+        return f"R$ {num_br(v / 1e6, digits)} mi"
+    if abs(v) >= 1e3:
+        return f"R$ {num_br(v / 1e3, digits)} mil"
+    return f"R$ {num_br(v, 0)}"
+
+def times(f: float) -> str:
+    return f"{round(f)} times" if abs(f - round(f)) < 0.15 else f"{num_br(f, 1)} times"
+
+def short_day(d: pd.Timestamp) -> str:
+    return f"{d.day} {MONTHS[d.month - 1].lower()}"
+
+def peak_story(df: pd.DataFrame, event: str | None = None) -> dict:
+    """df: columns 'date' (datetime) and 'value'; complete series, no gaps."""
+    baseline = df["value"].median()
+    peak = df.loc[df["value"].idxmax()]
+    factor = peak["value"] / baseline
+    title = (f"{event or 'The peak'} sold {times(factor)} more than a normal day"
+             if factor >= 1.5 else "Daily sales stayed flat over the period")
+    return {"baseline": baseline, "peak": peak, "factor": factor, "title": title,
+            "colors": [ROLES["highlight"] if d == peak["date"] else ROLES["context"] for d in df["date"]]}
+```
+
+Plotly:
+
+```python
+import plotly.graph_objects as go
+
+def peak_bars_plotly(df: pd.DataFrame, s: dict, subtitle: str, source: str) -> go.Figure:
+    months = pd.date_range(df["date"].min().replace(day=1), df["date"].max(), freq="MS")
+    p = s["peak"]
+    fig = go.Figure(go.Bar(x=df["date"], y=df["value"], marker_color=s["colors"], marker_line_width=0,
+                           hovertemplate="%{x|%d/%m/%Y}<br>R$ %{y:,.0f}<extra></extra>"))
+    fig.update_layout(
+        title=dict(x=0, xref="paper", xanchor="left", text=f"<b>{s['title']}</b><br><span style='font-size:13px;color:{ROLES['muted']}'>{subtitle}</span>"),
+        font=dict(family="Inter, system-ui, sans-serif", color=ROLES["ink"], size=12),
+        plot_bgcolor=ROLES["surface"], paper_bgcolor=ROLES["surface"], separators=",.",
+        bargap=0.35, showlegend=False, margin=dict(l=24, r=24, t=96, b=56))
+    fig.update_yaxes(visible=False)
+    fig.update_xaxes(showgrid=False, showline=False, ticks="", tickvals=months,
+                     ticktext=[MONTHS[m.month - 1] for m in months], tickfont=dict(color=ROLES["muted"], size=11))
+    fig.add_hline(y=s["baseline"], line_dash="dot", line_width=1, line_color=ROLES["muted"],
+                  annotation_text=f"normal day (median) · {money(s['baseline'])}", annotation_position="top left",
+                  annotation_font=dict(size=11, color=ROLES["muted"]))
+    fig.add_annotation(x=p["date"], y=p["value"], showarrow=False, xanchor="right", yanchor="top", xshift=-6, align="right",
+                       text=f"<b><span style='font-size:22px'>{money(p['value']).upper()}</span></b><br>"
+                            f"{short_day(p['date'])} · {times(s['factor'])} a normal day",
+                       font=dict(color=ROLES["highlight_text"], size=12))
+    fig.add_annotation(x=0, y=-0.16, xref="paper", yref="paper", showarrow=False, xanchor="left",
+                       text=source, font=dict(size=10, color=ROLES["muted"]))
+    return fig
+```
+
+In Streamlit: `st.plotly_chart(fig, use_container_width=True, config={"displayModeBar": False})`. In Dash: `dcc.Graph(figure=fig, config={"displayModeBar": False})`. For a dark theme, swap `ROLES` for the project's dark tokens.
+
+matplotlib (static reports, PDFs, emails):
+
+```python
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+from matplotlib.ticker import FuncFormatter
+
+def peak_bars_mpl(df: pd.DataFrame, s: dict, subtitle: str, source: str):
+    p = s["peak"]
+    fig, ax = plt.subplots(figsize=(10, 4.6), dpi=200)
+    fig.patch.set_facecolor(ROLES["surface"]); ax.set_facecolor(ROLES["surface"])
+    ax.bar(df["date"], df["value"], width=0.7, color=s["colors"], linewidth=0)
+    ax.axhline(s["baseline"], ls=(0, (2, 3)), lw=1, color=ROLES["muted"])
+    ax.text(df["date"].iloc[0], s["baseline"], f"normal day (median) · {money(s['baseline'])}", va="bottom",
+            fontsize=9, color=ROLES["muted"], bbox=dict(facecolor=ROLES["surface"], edgecolor="none", pad=1.5))
+    ax.annotate(f"{money(p['value']).upper()}\n{short_day(p['date'])} · {times(s['factor'])} a normal day",
+                xy=(p["date"], p["value"]), xytext=(-8, 0), textcoords="offset points",
+                ha="right", va="top", color=ROLES["highlight_text"], fontsize=13, fontweight="bold")
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    ax.yaxis.set_visible(False)
+    ax.tick_params(axis="x", length=0, colors=ROLES["muted"], labelsize=9)
+    ax.set_xlim(df["date"].min() - pd.Timedelta(days=2), df["date"].max() + pd.Timedelta(days=2))
+    ax.xaxis.set_major_locator(mdates.MonthLocator())
+    ax.xaxis.set_major_formatter(FuncFormatter(lambda x, _: MONTHS[mdates.num2date(x).month - 1]))
+    fig.text(0.02, 0.97, s["title"], fontsize=17, fontweight="bold", color=ROLES["ink"], va="top")
+    fig.text(0.02, 0.89, subtitle, fontsize=10, color=ROLES["muted"], va="top")
+    fig.text(0.02, 0.01, source, fontsize=8, color=ROLES["muted"])
+    fig.subplots_adjust(top=0.80, left=0.03, right=0.98, bottom=0.10)
+    return fig
+```