dashtaste 0.0.0-stage → 0.0.2

package/skills/dashtaste-cn/references/numbers.md

@@ -0,0 +1,93 @@
+# Numbers and dates
+
+## Compact amounts
+
+Use 万 at 10,000 and 亿 at 100,000,000.
+Use `1.23万`, with no internal space.
+Fix a column to 万 when comparing rows or charts near a unit threshold.
+For example, 9,800 and 12,300 become 0.98万 and 1.23万 in that column.
+Use auto units for isolated KPIs with very different scales.
+Auto examples: 12,300 → 1.23万; 230,000,000 → 2.3亿.
+The formatter API uses auto units; fixed 万 is a local display calculation.
+
+Use at most two decimals for Chinese compact units and one for global units.
+Omit trailing zeroes on isolated compact amounts; use consistent decimals within a list or column.
+Use `minimumFractionDigits: 2` for monetary lists and `compactFrom: 10000` for grouped full counts below 10,000.
+Use integers for counts unless the measure is an average.
+Use two decimals for monetary detail when required by the measure.
+Use tabular numerals and right alignment for numeric columns.
+Do not mix automatic unit switches within a shared chart axis.
+Scale values before using a literal axis formatter; templates do not divide data.
+A series value of 1.23 with axis name Orders (万) represents 12,300 orders.
+
+## Percentages
+
+Store rates as fractions in application data: 0.123 means 12.3%.
+`formatPercent(0.123)` returns `12.3%`.
+Use one decimal by default and zero for coarse whole-number shares.
+Use two decimals only when changes at that scale matter.
+Keep no space before `%`.
+Distinguish a relative percent change from a percentage-point difference.
+A move from 20% to 25% is +5 percentage points and +25% relative.
+
+## Deltas
+
+Compute (current − previous) / abs(previous).
+Show ▲ for positive and ▼ for negative, always together with colour.
+Zero is flat: `0.0%`, muted colour, no arrow.
+Invalid values and a zero previous value display `–`.
+Do not infer good or bad solely from direction; name the measure clearly.
+Apply one page-wide delta convention, including tables and tooltips.
+Default: red up, green down regardless of metric polarity, preserving the market
+涨跌 convention. A deliberate green-up override must cover the page.
+Set page `deltaColors: 'by-polarity'` (HTML `data-delta-colors="by-polarity"`)
+to use green for improvement and red for deterioration. `polarity` defaults to
+`higher-is-better`; `lower-is-better` makes rising churn, expenses, or refunds red
+and falling values green. Arrows always follow the sign. Mark delta elements or
+ancestors with `data-polarity="lower-is-better"` for extraction and DT013.
+同比 compares the same period in the previous year.
+环比 compares the immediately preceding period of the same length.
+日环比 compares today with yesterday at the same elapsed cutoff.
+周同比 compares with the same weekday of the previous week.
+For incomplete periods compare equal elapsed durations, not full prior periods.
+Label each comparison explicitly; never use a bare second percentage.
+
+## Dates and shortcuts
+
+Display dates as `2026-10-21`; use 24-hour times such as `14:30`.
+Date shortcuts: 今天 / 昨天 / 近7天 / 近30天 / 本月 / 自定义。
+Define 近7天 and 近30天 as inclusive calendar windows ending today.
+本月 starts on day 1 and ends at the selected cutoff today.
+今天 and 昨天 use the dashboard timezone, not the viewer's implicit timezone.
+Use full-width punctuation in Chinese prose and spaces around Latin text or digits.
+Keep compact values such as `1.23万` and percentages such as `12%` intact.
+
+## Format API
+
+```ts
+import { formatCompact, formatPercent, formatDelta, formatDate } from 'dashtaste/format';
+
+const amount = formatCompact(12300, 'cn');
+const rate = formatPercent(0.123, 1);
+const delta = formatDelta(110, 100, 'cn', { label: '环比' });
+// Render delta.text and delta.color together; preserve the returned direction.
+const date = formatDate(new Date(2026, 9, 21), 'cn');
+const fixedWan = `${Number((12300 / 10000).toFixed(2))}万`;
+const longDate = new Intl.DateTimeFormat('en-US', {
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric',
+}).format(new Date(2026, 9, 21));
+```
+
+Set timezone handling before formatting server timestamps.
+Never parse a display string back into analytical data.
+Keep raw amounts, units, and comparison periods as separate fields.
+
+## Numeral typography
+
+Use "Instrument Sans" with "PingFang SC", "Noto Sans CJK SC", sans-serif fallback.
+Set font-variant-numeric: tabular-nums on every number.
+Keep decimal precision consistent within each metric and table column.
+Use 500 for headings and values, 400 for body text; never exceed 600.
+Use one hero at 2.2 times the secondary KPI size or larger.

package/skills/dashtaste-cn/references/tokens.md

@@ -0,0 +1,72 @@
+# Tokens
+
+Ink and muted are text colours. Subtle and hairlines are decorative.
+
+## light
+
+| Token               | Hex     |
+| ------------------- | ------- |
+| light.page          | #F2F4F2 |
+| light.card          | #FFFFFF |
+| light.sunken        | #F7F8F7 |
+| light.ink           | #141414 |
+| light.muted         | #636261 |
+| light.subtle        | #7B7B76 |
+| light.hairline      | #E6E6E6 |
+| light.strong        | #DDDDDD |
+| light.primary       | #141414 |
+| light.brand         | #3E6A88 |
+| light.accent        | #C68A1C |
+| light.up            | #C8372F |
+| light.down          | #167D4F |
+| light.flat          | #636261 |
+| light.other         | #BCBBBA |
+| light.categorical.0 | #3E6A88 |
+| light.categorical.1 | #20293A |
+| light.categorical.2 | #8080F7 |
+| light.categorical.3 | #B4A85D |
+| light.categorical.4 | #77C4D6 |
+| light.sequential.0  | #EEF2F5 |
+| light.sequential.1  | #DDE4EA |
+| light.sequential.2  | #B3CADB |
+| light.sequential.3  | #74ABD0 |
+| light.sequential.4  | #3E6A88 |
+
+## dark
+
+| Token              | Hex     |
+| ------------------ | ------- |
+| dark.bg            | #121212 |
+| dark.panel         | #171716 |
+| dark.sunken        | #0A0B0A |
+| dark.ink           | #EEEEEB |
+| dark.muted         | #959590 |
+| dark.subtle        | #7B7B76 |
+| dark.hairline      | #2A2926 |
+| dark.strong        | #484843 |
+| dark.brand         | #74ABD0 |
+| dark.accent        | #E8B657 |
+| dark.up            | #DB655C |
+| dark.down          | #73B78E |
+| dark.flat          | #959590 |
+| dark.other         | #61615C |
+| dark.categorical.0 | #74ABD0 |
+| dark.categorical.1 | #E5B357 |
+| dark.categorical.2 | #9B7EF0 |
+| dark.categorical.3 | #466376 |
+| dark.categorical.4 | #4B8C9C |
+| dark.sequential.0  | #1F303B |
+| dark.sequential.1  | #2A4456 |
+| dark.sequential.2  | #3E6A88 |
+| dark.sequential.3  | #74ABD0 |
+| dark.sequential.4  | #B3CADB |
+
+Use the numeral face with tabular figures. Headings use weight 500; body uses 400.
+One hero anchors the page; all other numbers remain subordinate.
+
+Use the mono face for Latin ticks and table headers: 11px, 0.06em tracking.
+Keep CJK in the CJK face at 12px or larger, 16px on screens.
+The accent token marks only the latest point of the main trend and sparkline end dots.
+Its value label stays ink. The brand token supplies steel data strokes in light mode.
+Red and green are reserved for deltas.
+Paper and ink define the main surfaces and data strokes.

package/skills/dashtaste-global/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: dashtaste-global
+description: Build or review readable global-audience dashboards with concrete layout, chart, colour, and number defaults.
+---
+
+# Dashboard workflow
+
+Use for dashboard pages, chart options, KPI strips, rankings, and dashboard reviews.
+For a Chinese-market audience use dashtaste-cn.
+
+1. Pick the global pack and light or dark mode before choosing colours.
+2. Read [tokens](references/tokens.md) for exact colours and sizes.
+3. Read [layout](references/layout.md) for page structure and controls.
+4. Read [charts](references/charts.md) for the chart types you need.
+5. Read [numbers](references/numbers.md) for units, dates, and comparisons.
+6. Build the page with real data, explicit units, and clear hierarchy.
+7. Run `npx dashtaste check options.json --pack global --max-warnings 0`.
+   For a rendered page, check its URL with a browser available through `CHROME_PATH`.
+8. Fix errors and warnings; inspect informational findings. Recheck after edits.
+   Read [avoid](references/avoid.md) when replacing a flagged pattern.
+
+## Ten rules to apply first
+
+- DT001: Set explicit series colours from the selected pack.
+- DT002: Keep at most five categorical colours; group the tail as Other.
+- DT003: Draw straight line segments; smoothing invents intermediate values.
+- DT004: Hide line symbols above 12 points.
+- DT005: Use ranked bars for shares; no donuts in KPI boards.
+- DT007: Use flat two-dimensional marks.
+- DT009: Put units in value-axis names.
+- DT010: Start bar value axes at zero and disable scale.
+- DT013: Use green for improvement and red for deterioration; set lower-is-better polarity for churn and expenses.
+- DT015: Meet 4.5:1 text contrast, or 3:1 for large text.
+
+## Layout explains itself
+
+Use no helper labels, explanatory captions, or “this chart shows” text.
+Put units in axis names. Titles may state the finding, such as
+“Returns fell for three weeks”. Labels identify data and controls directly.
+Keep definitions in an accessible detail view when needed, outside chart captions.
+
+Use one hero metric, one sheet, hairlines, and direct labels.
+Use the measured defaults in the references for all KPI boards.

package/skills/dashtaste-global/references/avoid.md

@@ -0,0 +1,135 @@
+# Patterns to avoid
+
+Use this list when reviewing a page or replacing a flagged pattern.
+Rule checks cover observable facts; inspect layout and copy manually as well.
+
+## DT001: default-palette
+
+Multiple series need explicit colours. Any default palette colour is flagged.
+Replace it: set option.color to the pack palette (dashtaste tokens --pack <pack>).
+
+## DT002: rainbow-palette
+
+More than 6 distinct categorical colours or more than 5 saturated 60-degree hue buckets.
+Replace it: use the pack palette and group remaining categories as Other.
+
+## DT003: smooth-line
+
+Line smoothing greater than zero draws values that do not exist.
+Replace it: use straight segments: smooth: false.
+
+## DT004: symbols-everywhere
+
+Line symbols are noisy above 12 points; ECharts shows symbols by default.
+Replace it: set showSymbol: false.
+
+## DT005: pie-slices
+
+Maximum 5 slices; cn rose charts allow 8.
+Replace it: use horizontal bars or combine small parts into Other.
+
+## DT006: pie-overuse
+
+More than one pie per page or radius ratio above 0.75 warns. A global pie is informational.
+Replace it: prefer horizontal bars; keep donut radius ratio at most 0.75.
+
+## DT007: three-d
+
+3D series, axes, coordinates, and pseudo-3D pie decoration distort comparisons.
+Replace it: use flat 2D charts.
+
+## DT008: dual-axis
+
+Multiple value axes obscure comparisons, including mixed bar and line charts.
+Replace it: use one value axis or aligned small multiples.
+
+## DT009: missing-unit
+
+Value axes need a name, formatter, unit metadata, or units in rendered ticks.
+Replace it: put units in axis names, rendered ticks, or formatter metadata.
+
+## DT010: bar-baseline
+
+Bar value axes must start at zero; positive min and scale: true distort lengths.
+Replace it: set min: 0 and scale: false.
+
+## DT011: raw-large-numbers
+
+At data maximum magnitude 10000 or above, axis, visible data label, and tooltip channels need formatters.
+Replace it: format compact units: cn 万/亿; global K/M.
+
+## DT012: unit-system
+
+String formatter templates must use the selected compact unit system.
+Replace it: use cn 万/亿 or global K/M/B consistently.
+
+## DT013: delta-convention
+
+Directional deltas must follow one page convention: global green-up; cn red-up by default.
+Replace it: apply one deltaColors convention to the whole page.
+
+## DT014: delta-colour-only
+
+Directional colour must be accompanied by an arrow or signed number.
+Replace it: add ▲/▼ or an explicit sign.
+
+## DT015: low-contrast-text
+
+Text needs 4.5:1; at least 24px or 18.66px bold needs 3:1. Chart label defaults use 4.5:1.
+Replace it: increase text contrast against its background.
+
+## DT016: thin-line-contrast
+
+Line colours need at least 3:1 against the chart background.
+Replace it: darken light-mode lines or lighten dark-mode lines.
+
+## DT017: gradient-decoration
+
+Card/page gradients and linear or radial chart fills add decoration.
+Replace it: use solid backgrounds and fills.
+
+## DT018: glow
+
+Coloured CSS shadows with blur at least 12px, or chart shadowBlur at least 10, create glow.
+Replace it: remove glow and use hairline borders.
+
+## DT019: kpi-overload
+
+More than 6 global or 8 cn KPI tiles weakens priority.
+Replace it: keep only primary KPIs in the first view.
+
+## DT020: kpi-rainbow
+
+Three or more distinct accent colours on KPI values or tiles distract. Neutral greys and pack text/background tokens are excluded.
+Replace it: use ink for values and reserve colour for deltas.
+
+## DT021: emoji-icons
+
+Emoji in headings, KPI labels, and rankings add inconsistent iconography.
+Replace it: use plain text and plain numerals for rankings.
+
+## DT022: cjk-min-size
+
+CJK text must be at least 12px.
+Replace it: set CJK text to at least 12px.
+
+## DT023: legend-single-series
+
+An explicitly visible legend on one series repeats context.
+Replace it: hide the legend or label the series directly.
+
+## Manual layout review
+
+Helper labels and explanatory captions repeat visible structure; no automatic rule yet.
+Decorative icon tiles distract from values; no automatic rule yet.
+Repeated card boxes weaken the document hierarchy; no automatic rule yet.
+
+## Measured anti-patterns
+
+DT024: uncapped bars and bars wider than 24px (32px on screens).
+DT025: legends for two to four lines without direct end labels.
+DT026: decorative line strokes above 3px or below 1px.
+DT027: proportional numerals in KPI values.
+DT028: several equally sized KPIs without a clear hero.
+Avoid donuts on KPI boards, dual axes, repeated boxed cards, and empty quadrants.
+Avoid helper sentences, uppercase tracking, and in-flow shadows.

package/skills/dashtaste-global/references/charts.md

@@ -0,0 +1,122 @@
+# Chart defaults
+
+These complete light-mode options use small values so no compact formatter is needed.
+Copy an option into a JSON file and check with `--pack global`.
+For dark mode replace all foreground and surface colours using tokens.md; check with `--mode dark`.
+For large values, convert data to display units and name the unit in the axis.
+Keep raw values separately for accessible detail views.
+
+## Line
+
+Use for change over time. Keep straight segments. Use filled 3–4px dots on series of at most 31 points. A 240px plot is a useful starting height.
+
+<!-- prettier-ignore -->
+```json
+{"color": ["#1A1A18"], "xAxis": {"type": "category", "data": ["Mon", "Tue", "Wed"]}, "yAxis": {"type": "value", "name": "Orders"}, "series": [{"type": "line", "smooth": false, "showSymbol": true, "data": [12, 18, 16], "lineStyle": {"width": 1.5, "color": "#1A1A18"}, "symbol": "circle", "symbolSize": 4, "markPoint": {"symbol": "circle", "symbolSize": 7, "itemStyle": {"color": "#B65A08"}, "label": {"show": true, "position": "top", "formatter": "{c}"}, "data": [{"coord": [2, 16]}]}}]}
+```
+
+## Bar
+
+Compare amounts. Start at zero. Use horizontal bars for long category labels and at most 12px bar thickness on desktop.
+
+<!-- prettier-ignore -->
+```json
+{"color": ["#1A1A18"], "xAxis": {"type": "value", "name": "Orders", "min": 0, "scale": false}, "yAxis": {"type": "category", "data": ["East", "West", "North"]}, "series": [{"type": "bar", "barMaxWidth": 12, "data": [24, 18, 12]}]}
+```
+
+## Combo
+
+Use aligned panels for different units. Keep comparison series on one shared axis.
+
+<!-- prettier-ignore -->
+```json
+{"color": ["#1A1A18"], "xAxis": {"type": "category", "data": ["Mon", "Tue", "Wed"]}, "yAxis": {"type": "value", "name": "Orders", "min": 0}, "series": [{"name": "Orders", "type": "bar", "data": [24, 18, 12], "barMaxWidth": 12}, {"name": "Prior orders", "type": "line", "showSymbol": true, "smooth": false, "data": [12, 15, 18], "lineStyle": {"width": 1.5, "color": "#1A1A18"}, "symbol": "circle", "symbolSize": 4}]}
+```
+
+## Share / pie / donut
+
+No donuts or pies in KPI boards. Use a ranked bar list or a single 100% stacked bar with direct labels. The option below is for isolated composition analysis.
+
+<!-- prettier-ignore -->
+```json
+{"color": ["#1A1A18"], "series": [{"type": "pie", "radius": ["35%", "60%"], "label": {"show": true, "formatter": "{b}: {d}%"}, "data": [{"name": "New", "value": 60}, {"name": "Repeat", "value": 40}]}]}
+```
+
+## Funnel
+
+Use for ordered process stages with a shared population. Keep one colour, descending values, and visible stage labels.
+
+<!-- prettier-ignore -->
+```json
+{"color": ["#1A1A18"], "series": [{"type": "funnel", "sort": "descending", "label": {"show": true, "formatter": "{b}: {c}"}, "data": [{"name": "Started", "value": 90}, {"name": "Qualified", "value": 60}, {"name": "Completed", "value": 30}]}]}
+```
+
+## Table
+
+Use a semantic HTML table in production: left-align labels, right-align amounts, use 36px rows and hairline separators. This static ECharts graphic is a portable option example.
+
+<!-- prettier-ignore -->
+```json
+{"graphic": [{"type": "text", "left": 16, "top": 16, "style": {"text": "Region        Orders", "fill": "#1B1B18", "fontSize": 14}}, {"type": "text", "left": 16, "top": 52, "style": {"text": "East                 24", "fill": "#1B1B18", "fontSize": 14}}]}
+```
+
+## KPI
+
+Use real text with tabular figures. One 52–64px hero, 22–26px secondary values, 11px uppercase tracked mono labels for Latin, 13px CJK labels; weights 400 and 500.
+
+<!-- prettier-ignore -->
+```json
+{"graphic": [{"type": "text", "left": 16, "top": 16, "style": {"text": "Orders", "fill": "#6B6B63", "fontSize": 14}}, {"type": "text", "left": 16, "top": 44, "style": {"text": "124", "fill": "#1B1B18", "fontSize": 32}}]}
+```
+
+## Ranking / TOP N
+
+Sort descending. Default to TOP 5; use TOP 10 only with room. Use muted tabular ranks without medals. Show the cutoff in the title.
+
+<!-- prettier-ignore -->
+```json
+{"title": {"text": "Top 3 regions by orders"}, "color": ["#1A1A18"], "xAxis": {"type": "value", "name": "Orders", "min": 0}, "yAxis": {"type": "category", "inverse": true, "data": ["1 East", "2 West", "3 North"]}, "series": [{"type": "bar", "barMaxWidth": 12, "data": [24, 18, 12]}]}
+```
+
+## Map
+
+Use only for geographic questions, otherwise use ranking bars. Register a matching GeoJSON map as regions before setOption. Keep roam off and use a sequential scale with units.
+
+<!-- prettier-ignore -->
+```json
+{"visualMap": {"min": 0, "max": 100, "text": ["Orders", "0"], "inRange": {"color": ["#1A1A18"]}}, "series": [{"type": "map", "map": "regions", "roam": false, "data": [{"name": "East", "value": 24}, {"name": "West", "value": 18}]}]}
+```
+
+## Shared interaction defaults
+
+Use tooltip trigger axis for time series and item for isolated marks.
+Use one explicit colour for a single series; do not rely on theme defaults.
+Hide the legend for one series. For comparisons, hide legends and use short annotations with thin 1px leader lines.
+Do not use decorative gradients, shadows, 3D marks, or emoji in titles.
+Keep missing observations missing; do not replace them with zero.
+Use stable ordering for categories unless ranking is the question.
+Keep controls outside the plotting rectangle.
+Provide keyboard access and a table or textual data alternative.
+Use a finding title only when the data supports it after filtering.
+A unit belongs in the axis name, not in a helper caption.
+
+## Measured defaults
+
+Main lines use 1.5px ink; comparisons use 1px dashed mid-grey.
+Long series hide symbols. Short series use small ink dots; comparisons or incomplete values use hollow dots.
+Use straight segments, horizontal grid lines, and no y-axis line.
+Bars use at most 65% of their category band; keep value labels outside.
+Use one accent mark and neutral context; reserve red and green for deltas.
+Small multiples use 1.5px lines without axes and a shared scale per row.
+No area gradients, glow, or decorative heavy strokes.
+
+Exactly one accent mark per chart: a filled 7px latest or peak dot and its value label.
+Never use the accent on another chart element. Bars may highlight one bar instead.
+Only latest and extreme values may have labels.
+Use markLine, markPoint or graphic for leader-line annotations.
+Thin ink bars are at most 12px; negative bars are mid-grey.
+Inline table bars use ink at 20% opacity; the top row uses solid ink.
+
+Use story-bearing data in examples. Annotate one event per chart with a leader line, a hollow ink dot, and a short label in empty space. Keep the latest point as the single accent.
+
+Use one signature element per board. Place it alongside the main metric so it reinforces the data story.

package/skills/dashtaste-global/references/layout.md

@@ -0,0 +1,78 @@
+# Layout
+
+Use one hero to establish the reading order.
+The hero is 52–64px on desktop and 112–128px on a screen.
+The hero is at least 2.2 times the next KPI.
+Use weight 500 and letter spacing −0.02em for the hero.
+Secondary KPIs use 22–26px, or 32–40px on screens.
+Labels use 12–13px and weight 500.
+Use sentence case without uppercase tracking.
+Titles name the metric or state a supported finding.
+Do not add helper text or explanatory sentences.
+
+## Surface
+
+The white page is the single surface.
+Separate sections with hairlines and whitespace.
+Avoid repeated boxed cards.
+Inner radii are at most 6px.
+Do not use in-flow shadows, gradients, glow, or glass effects.
+Dark screens use hairlines rather than luminous panel borders.
+
+## Density
+
+Fill the viewport with relevant information.
+Size the plot after reserving space for titles and direct labels.
+Keep all content inside the viewport.
+Use a main trend and a compact right rail.
+Place categorical detail beneath the trend.
+Keep date ranges in the header.
+Align section headings and plot edges.
+Align numeric baselines across the rail.
+Reserve room for the longest label.
+Avoid empty quadrants and decorative whitespace.
+
+## Tables
+
+Use semantic tables with 13px text and 36px rows.
+Use 11px muted mono column headers for Latin; CJK headers stay at least 12px.
+Right-align numbers with tabular figures.
+Use hairline row separators.
+Do not use zebra stripes or vertical rules.
+Show share with a 4px inline bar.
+The maximum share uses the accent; context uses a tint.
+Use muted tabular ranks without medals.
+Keep row names left aligned.
+Show units consistently within a column.
+Keep decimal precision consistent.
+
+## Screen
+
+Use a 1920×1080 viewport.
+The minimum CJK size is 16px.
+Use a 112–128px hero and a secondary KPI strip.
+Use twelve regional small multiples instead of coloured tiles.
+Use the same scale across regional sparklines.
+Keep the current time visible in the header.
+Mark the current hour with a vertical hairline.
+Progress bars are 4px flat fills.
+Use ink for the numerator and muted for the denominator.
+
+## Checks
+
+Check overflow at the exact target viewport.
+Inspect every exported image for clipping and overlap.
+Wait for local fonts before rendering.
+Render at a device scale factor of two.
+Keep tooltips out of the captured state.
+Check contrast on every surface.
+Keep at most three font weights, never above 600.
+
+Header: a 20px, weight 500 title left and date range right.
+Omit breadcrumbs, identity lines, helper lines and footer captions.
+Use at most one hairline below the header.
+Create breathing room with margins; avoid half-empty panels.
+
+Use story-bearing data in examples. Annotate one event per chart with a leader line, a hollow ink dot, and a short label in empty space. Keep the latest point as the single accent.
+
+Use one signature element per board. Place it alongside the main metric so it reinforces the data story.

package/skills/dashtaste-global/references/numbers.md

@@ -0,0 +1,83 @@
+# Numbers and dates
+
+## Compact amounts
+
+Keep counts below 10,000 grouped in full. Use K from 10,000, M at 1,000,000, and B at 1,000,000,000.
+Auto examples: 12,300 → 12.3K; 2,300,000 → 2.3M.
+Fix one display unit across a comparison table or shared axis.
+Keep exact values in details when compact rounding hides a meaningful difference.
+The formatter API uses auto units; fixed units are a local display calculation.
+
+Use at most two decimals for Chinese compact units and one for global units.
+Omit trailing zeroes on isolated compact amounts; use consistent decimals within a list or column.
+Use `minimumFractionDigits: 2` for monetary lists and `compactFrom: 10000` for grouped full counts below 10,000.
+Use integers for counts unless the measure is an average.
+Use two decimals for monetary detail when required by the measure.
+Use tabular numerals and right alignment for numeric columns.
+Do not mix automatic unit switches within a shared chart axis.
+Scale values before using a literal axis formatter; templates do not divide data.
+A series value of 1.23 with axis name Orders (万) represents 12,300 orders.
+
+## Percentages
+
+Store rates as fractions in application data: 0.123 means 12.3%.
+`formatPercent(0.123)` returns `12.3%`.
+Use one decimal by default and zero for coarse whole-number shares.
+Use two decimals only when changes at that scale matter.
+Keep no space before `%`.
+Distinguish a relative percent change from a percentage-point difference.
+A move from 20% to 25% is +5 percentage points and +25% relative.
+
+## Deltas
+
+Compute (current − previous) / abs(previous).
+Show ▲ for positive and ▼ for negative, always together with colour.
+Zero is flat: `0.0%`, muted colour, no arrow.
+Invalid values and a zero previous value display `–`.
+Do not infer good or bad solely from direction; name the measure clearly.
+Apply one page-wide delta convention, including tables and tooltips.
+Default: green for improvement, red for deterioration. `polarity` defaults to
+`higher-is-better`; set `lower-is-better` for churn, expenses, and refunds.
+Arrows always follow the sign; rising churn is red. Mark deltas or ancestors with
+`data-polarity="lower-is-better"` for extraction and DT013.
+Explicit red-up or green-up conventions are page-wide directional overrides.
+Label comparisons as prior period or prior year, with equal time coverage.
+For incomplete periods compare equal elapsed durations.
+
+## Dates and shortcuts
+
+Display dates as `Oct 21, 2026`; use a consistent dashboard timezone.
+Use Today / Yesterday / Last 7 days / Last 30 days / This month / Custom.
+Define rolling calendar windows inclusively and show the selected range.
+`formatDate` currently returns `2026-10-21` for both packs.
+Use the explicit presentation adapter below for a global long date.
+
+## Format API
+
+```ts
+import { formatCompact, formatPercent, formatDelta, formatDate } from 'dashtaste/format';
+
+const amount = formatCompact(12300, 'global');
+const rate = formatPercent(0.123, 1);
+const delta = formatDelta(110, 100, 'global', { label: 'Prior period' });
+// Render delta.text and delta.color together; preserve the returned direction.
+const date = formatDate(new Date(2026, 9, 21), 'global');
+const fixedWan = `${Number((12300 / 10000).toFixed(2))}万`;
+const longDate = new Intl.DateTimeFormat('en-US', {
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric',
+}).format(new Date(2026, 9, 21));
+```
+
+Set timezone handling before formatting server timestamps.
+Never parse a display string back into analytical data.
+Keep raw amounts, units, and comparison periods as separate fields.
+
+## Numeral typography
+
+Use "Inter" with font-feature-settings "tnum", "cv11".
+Set font-variant-numeric: tabular-nums on every number.
+Keep decimal precision consistent within each metric and table column.
+Use 500 for headings and values, 400 for body text; never exceed 600.
+Use one hero at 2.2 times the secondary KPI size or larger.