@hegemonart/get-design-done 1.42.0 → 1.43.0

package/reference/data-visualization.md

@@ -1,12 +1,12 @@
-# Data Visualization — Chart Selection and Best Practices
+# Data Visualization - Chart Selection and Best Practices
 
-Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/charts.csv
+Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) - data/charts.csv
 
-Charts are not decorations — they are arguments. Every chart type encodes a specific analytical claim, and choosing the wrong encoding forces the reader to decode the wrong claim. This reference provides decision rules for selecting chart types, configuring them accessibly, and avoiding the most common misuses.
+Charts are not decorations - they are arguments. Every chart type encodes a specific analytical claim, and choosing the wrong encoding forces the reader to decode the wrong claim. This reference provides decision rules for selecting chart types, configuring them accessibly, and avoiding the most common misuses.
 
 ---
 
-## 1. Chart-Choice Matrix — Decision Framework
+## 1. Chart-Choice Matrix - Decision Framework
 
 Every chart serves one of six analytical purposes: **comparison** (how do values rank against each other?), **composition** (how does a whole break into parts?), **distribution** (how are values spread?), **relationship** (do two or more variables correlate or influence each other?), **trend** (how does a value change over time?), or **geographic** (how does a value vary by location?). Identifying the purpose before choosing a chart eliminates most bad chart decisions.
 
@@ -14,10 +14,10 @@ Every chart serves one of six analytical purposes: **comparison** (how do values
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Bar (vertical) | Comparing discrete categories; up to ~15 categories | When category labels are long — they collide |
-| Bar (horizontal) | Long category labels; ranked lists; > 8 categories | When comparing time series — use line instead |
+| Bar (vertical) | Comparing discrete categories; up to ~15 categories | When category labels are long - they collide |
+| Bar (horizontal) | Long category labels; ranked lists; > 8 categories | When comparing time series - use line instead |
 | Bullet | Comparing a value against a target range (KPI context) | For more than ~8 metrics on one screen |
-| Slope | Showing how two time points changed relative to each other; showing rank reversal | More than two time points — use a line chart |
+| Slope | Showing how two time points changed relative to each other; showing rank reversal | More than two time points - use a line chart |
 
 ### Composition
 
@@ -25,7 +25,7 @@ Every chart serves one of six analytical purposes: **comparison** (how do values
 |---|---|---|
 | Pie | Part-of-whole with ≤ 5 slices; slices differ substantially in size | > 5 categories; comparing slice sizes precisely |
 | Donut | Same as pie; center space holds a summary number (total, %) | Any context where the center number distracts from part-whole reading |
-| Stacked Bar | Part-of-whole across multiple categories or time points | When the interior segments (not just the bottom) need to be compared — interior comparison is unreliable |
+| Stacked Bar | Part-of-whole across multiple categories or time points | When the interior segments (not just the bottom) need to be compared - interior comparison is unreliable |
 | Treemap | Hierarchical part-of-whole; sizes span orders of magnitude | Showing change over time; fewer than ~8 leaf nodes (bar is clearer) |
 | Sunburst | Hierarchical part-of-whole when hierarchy depth matters (2-3 levels) | More than 3 hierarchy levels; when labels must be legible for all segments |
 | Waterfall | How a starting value reaches an ending value through additions and subtractions | Non-sequential cumulative data; when intermediate steps have no story value |
@@ -34,52 +34,52 @@ Every chart serves one of six analytical purposes: **comparison** (how do values
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Histogram | Shape of a single continuous variable's distribution | Comparing two distributions directly — use overlaid density or faceted charts |
-| Box Plot | Comparing distributions across groups; showing median, IQR, outliers | Audiences unfamiliar with statistical notation — explain quartiles in the chart subtitle |
-| Violin Plot | Same as box plot, but when the shape of the distribution matters (bimodal, skewed) | Small samples (n < 30) — the smoothed density curve is misleading |
-| Heatmap | Distribution of a value across two categorical dimensions; calendar patterns | When precise values matter — heatmap encodes value via color, which is imprecise |
+| Histogram | Shape of a single continuous variable's distribution | Comparing two distributions directly - use overlaid density or faceted charts |
+| Box Plot | Comparing distributions across groups; showing median, IQR, outliers | Audiences unfamiliar with statistical notation - explain quartiles in the chart subtitle |
+| Violin Plot | Same as box plot, but when the shape of the distribution matters (bimodal, skewed) | Small samples (n < 30) - the smoothed density curve is misleading |
+| Heatmap | Distribution of a value across two categorical dimensions; calendar patterns | When precise values matter - heatmap encodes value via color, which is imprecise |
 
 ### Relationship
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Scatter | Correlation between two continuous variables | Overplotting with > 5,000 points — use hexbin or density contours instead |
-| Bubble | Three-variable relationship where the third variable is proportional in magnitude | When bubble areas differ < 2× — the size difference is imperceptible |
-| Chord | Flows or relationships between the same set of entities (e.g., trade between countries) | Directed flows where magnitude matters — Sankey is clearer |
+| Scatter | Correlation between two continuous variables | Overplotting with > 5,000 points - use hexbin or density contours instead |
+| Bubble | Three-variable relationship where the third variable is proportional in magnitude | When bubble areas differ < 2× - the size difference is imperceptible |
+| Chord | Flows or relationships between the same set of entities (e.g., trade between countries) | Directed flows where magnitude matters - Sankey is clearer |
 | Sankey | Directed flows between nodes; volume is encoded in link width | Cyclic flows; more than ~10 nodes (hairball effect) |
-| Network/Force-directed | Topology of connections between nodes; cluster detection | Quantifying relationships — edge weight is visually unreliable |
+| Network/Force-directed | Topology of connections between nodes; cluster detection | Quantifying relationships - edge weight is visually unreliable |
 
 ### Trend
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Line | Single or multiple continuous values over time | Unordered categorical data — use bar |
-| Area | Cumulative volume over time; emphasis on magnitude not rate of change | Multiple series with overlapping areas — use line chart with fills instead |
+| Line | Single or multiple continuous values over time | Unordered categorical data - use bar |
+| Area | Cumulative volume over time; emphasis on magnitude not rate of change | Multiple series with overlapping areas - use line chart with fills instead |
 | Sparkline | Compact trend indicator embedded in a table or KPI card | Any context requiring axis labels or precise value reading |
-| Candlestick | OHLC financial data; price range and direction per period | Non-financial time series — the OHLC convention is opaque to general audiences |
+| Candlestick | OHLC financial data; price range and direction per period | Non-financial time series - the OHLC convention is opaque to general audiences |
 
 ### Progress/Goal
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Gauge | Single KPI versus a target or threshold; dashboard hero metric | Multiple gauges side by side — comparison is very hard with radial encodings |
+| Gauge | Single KPI versus a target or threshold; dashboard hero metric | Multiple gauges side by side - comparison is very hard with radial encodings |
 | Funnel | Conversion or attrition across sequential stages | Stages that are not strictly sequential or mutually exclusive |
 
 ### Geographic
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Geographic / Choropleth | Value distribution across geographic regions; regional comparison | When region size distorts perception — large low-population regions dominate (use cartogram instead) |
+| Geographic / Choropleth | Value distribution across geographic regions; regional comparison | When region size distorts perception - large low-population regions dominate (use cartogram instead) |
 
 ### Project Timelines
 
 | Chart type | When to use | When to avoid |
 |---|---|---|
-| Gantt | Task scheduling, duration, and dependency visualization over time | Real-time progress tracking without frequent data updates — stale Gantt charts mislead |
+| Gantt | Task scheduling, duration, and dependency visualization over time | Real-time progress tracking without frequent data updates - stale Gantt charts mislead |
 
 ---
 
-## 2. Complete Chart Catalog (25 Types — GDD Decision Format)
+## 2. Complete Chart Catalog (25 Types - GDD Decision Format)
 
 ### Comparison
 
@@ -87,13 +87,13 @@ Every chart serves one of six analytical purposes: **comparison** (how do values
 Use a vertical bar chart when comparing discrete, unordered categories and the category labels fit horizontally beneath each bar. It is the default choice for most categorical comparison tasks because readers compare bar heights intuitively from a shared baseline. Recommended library: Recharts `<BarChart>` for React. Never use when you have more than 15 categories or when the chart width cannot accommodate all labels without rotation.
 
 **Bar (Horizontal)**
-Use a horizontal bar chart when category labels are long (> 15 characters), when rankings are the story, or when you have more than 8 categories. Horizontal orientation gives labels room to breathe and makes rank order easy to read top-to-bottom. Recommended library: Recharts `<BarChart layout="vertical">` for React. Never use when your data represents a time series — line charts handle ordered time data far better.
+Use a horizontal bar chart when category labels are long (> 15 characters), when rankings are the story, or when you have more than 8 categories. Horizontal orientation gives labels room to breathe and makes rank order easy to read top-to-bottom. Recommended library: Recharts `<BarChart layout="vertical">` for React. Never use when your data represents a time series - line charts handle ordered time data far better.
 
 **Bullet Chart**
-Use a bullet chart when you need to show a single measure against one or more qualitative thresholds (poor / satisfactory / good) and a target marker, typically in a KPI or performance dashboard. It was designed by Stephen Few as a compact replacement for gauges and meter charts. Recommended library: Nivo `@nivo/bullet` for React. Never use when the audience needs to compare more than eight metrics simultaneously — the encoding becomes too dense.
+Use a bullet chart when you need to show a single measure against one or more qualitative thresholds (poor / satisfactory / good) and a target marker, typically in a KPI or performance dashboard. It was designed by Stephen Few as a compact replacement for gauges and meter charts. Recommended library: Nivo `@nivo/bullet` for React. Never use when the audience needs to compare more than eight metrics simultaneously - the encoding becomes too dense.
 
 **Slope Chart**
-Use a slope chart when you want to show how values changed between exactly two time points and which entities rose, fell, or crossed each other. The crossing lines make rank reversal immediately visible. Recommended library: D3 with a custom `line` generator in React. Never use when you have more than two time points or more than ~10 entities — the chart becomes unreadable.
+Use a slope chart when you want to show how values changed between exactly two time points and which entities rose, fell, or crossed each other. The crossing lines make rank reversal immediately visible. Recommended library: D3 with a custom `line` generator in React. Never use when you have more than two time points or more than ~10 entities - the chart becomes unreadable.
 
 ---
 
@@ -106,91 +106,91 @@ Use a pie chart when showing how a whole divides into parts, the parts are mutua
 Use a donut chart in the same scenarios as a pie chart, with the added benefit that the hollow center can display a summary value (total, percentage of the largest segment, or a label). The reduced ink in the center slightly improves the legibility of the arc. Recommended library: Recharts `<PieChart>` with `innerRadius` set for React. Never use when the center callout number would distract from the part-whole message or when the chart is very small.
 
 **Stacked Bar Chart**
-Use a stacked bar chart when you need to show both total magnitude and part-of-whole composition across multiple groups or time points simultaneously. The bottom segment is comparable across groups; interior segments are not — readers cannot align them to a common baseline. Recommended library: Recharts `<BarChart>` with `stackId` for React. Never use when comparing the sizes of interior stack segments is the primary analytical task.
+Use a stacked bar chart when you need to show both total magnitude and part-of-whole composition across multiple groups or time points simultaneously. The bottom segment is comparable across groups; interior segments are not - readers cannot align them to a common baseline. Recommended library: Recharts `<BarChart>` with `stackId` for React. Never use when comparing the sizes of interior stack segments is the primary analytical task.
 
 **Treemap**
-Use a treemap when showing hierarchical composition and sizes span a wide range — the nested rectangles make relative size comparisons across magnitudes legible at a glance. Treemaps handle dozens to hundreds of leaf nodes without becoming unreadable, provided the labels are sized to fit. Recommended library: Nivo `@nivo/treemap` for React. Never use when the data has fewer than eight leaf nodes (a bar chart communicates the same information with less decoding effort) or when showing change over time.
+Use a treemap when showing hierarchical composition and sizes span a wide range - the nested rectangles make relative size comparisons across magnitudes legible at a glance. Treemaps handle dozens to hundreds of leaf nodes without becoming unreadable, provided the labels are sized to fit. Recommended library: Nivo `@nivo/treemap` for React. Never use when the data has fewer than eight leaf nodes (a bar chart communicates the same information with less decoding effort) or when showing change over time.
 
 **Sunburst**
 Use a sunburst chart when hierarchical part-of-whole data has two or three meaningful levels and the reader needs to trace the contribution of sub-categories to their parent. Each ring represents one level of the hierarchy. Recommended library: Nivo `@nivo/sunburst` for React. Never use when hierarchy depth exceeds three levels, as inner rings become too small to label legibly and the chart degrades into an art object.
 
 **Waterfall Chart**
-Use a waterfall chart when explaining how an initial value reaches a final value through a series of positive and negative contributions — profit-and-loss bridges, budget variance analysis, and step-by-step change attribution are the canonical use cases. Each bar floats from the accumulated prior value. Recommended library: Recharts with custom `<Bar>` using transparent bottom segments to create the floating effect, or Nivo `@nivo/bar` for React. Never use when the intermediate steps are not sequentially meaningful or when the audience cannot tolerate the decoding effort of floating bars.
+Use a waterfall chart when explaining how an initial value reaches a final value through a series of positive and negative contributions - profit-and-loss bridges, budget variance analysis, and step-by-step change attribution are the canonical use cases. Each bar floats from the accumulated prior value. Recommended library: Recharts with custom `<Bar>` using transparent bottom segments to create the floating effect, or Nivo `@nivo/bar` for React. Never use when the intermediate steps are not sequentially meaningful or when the audience cannot tolerate the decoding effort of floating bars.
 
 ---
 
 ### Distribution
 
 **Histogram**
-Use a histogram when revealing the shape of a single continuous variable's distribution — whether it is normal, skewed, bimodal, or has outliers. The key design choice is bin width: too few bins hides structure; too many bins creates noise. Recommended library: Nivo `@nivo/bar` with manually computed bins, or Victory `<VictoryHistogram>` for React. Never use when comparing two distributions on the same axis — overlapping histograms are hard to read; use a ridgeline or faceted approach instead.
+Use a histogram when revealing the shape of a single continuous variable's distribution - whether it is normal, skewed, bimodal, or has outliers. The key design choice is bin width: too few bins hides structure; too many bins creates noise. Recommended library: Nivo `@nivo/bar` with manually computed bins, or Victory `<VictoryHistogram>` for React. Never use when comparing two distributions on the same axis - overlapping histograms are hard to read; use a ridgeline or faceted approach instead.
 
 **Box Plot**
-Use a box plot (box-and-whisker) when comparing the distribution of a continuous variable across multiple groups. It summarizes median, interquartile range (IQR), and outliers in a compact glyph that scales to dozens of groups. Recommended library: Victory `<VictoryBoxPlot>` for React. Never use with audiences unfamiliar with statistical notation — always include a subtitle that explains that the box spans the middle 50% of values.
+Use a box plot (box-and-whisker) when comparing the distribution of a continuous variable across multiple groups. It summarizes median, interquartile range (IQR), and outliers in a compact glyph that scales to dozens of groups. Recommended library: Victory `<VictoryBoxPlot>` for React. Never use with audiences unfamiliar with statistical notation - always include a subtitle that explains that the box spans the middle 50% of values.
 
 **Violin Plot**
-Treat a violin plot as an enhanced box plot that additionally shows the full density shape of the distribution via a mirrored kernel density estimate. Use it when the distribution shape is the analytical point — bimodality, heavy tails, or gaps in the data that a box plot's five-number summary would hide. Recommended library: D3 with a custom density estimate rendered as a `<path>` in React. Never use with samples smaller than 30 observations — the smoothed curve implies precision the data does not support.
+Treat a violin plot as an enhanced box plot that additionally shows the full density shape of the distribution via a mirrored kernel density estimate. Use it when the distribution shape is the analytical point - bimodality, heavy tails, or gaps in the data that a box plot's five-number summary would hide. Recommended library: D3 with a custom density estimate rendered as a `<path>` in React. Never use with samples smaller than 30 observations - the smoothed curve implies precision the data does not support.
 
 **Heatmap**
-Use a heatmap when showing the distribution of a value across two categorical dimensions simultaneously — website traffic by hour and day of week, gene expression across samples and conditions, or feature correlation matrices. Color encodes the value; spatial position encodes the two categories. Recommended library: Nivo `@nivo/heatmap` for React. Never use when the audience needs to read precise values — color is an imprecise channel; pair with tooltips or an adjacent data table.
+Use a heatmap when showing the distribution of a value across two categorical dimensions simultaneously - website traffic by hour and day of week, gene expression across samples and conditions, or feature correlation matrices. Color encodes the value; spatial position encodes the two categories. Recommended library: Nivo `@nivo/heatmap` for React. Never use when the audience needs to read precise values - color is an imprecise channel; pair with tooltips or an adjacent data table.
 
 ---
 
 ### Relationship
 
 **Scatter Plot**
-Use a scatter plot when investigating correlation, clustering, or outliers between two continuous variables. Each point represents one observation; position encodes both values against shared axes. Recommended library: Recharts `<ScatterChart>` for React. Never use when overplotting obscures the pattern — with more than 5,000 points, switch to a hexbin aggregation or 2D density contour chart.
+Use a scatter plot when investigating correlation, clustering, or outliers between two continuous variables. Each point represents one observation; position encodes both values against shared axes. Recommended library: Recharts `<ScatterChart>` for React. Never use when overplotting obscures the pattern - with more than 5,000 points, switch to a hexbin aggregation or 2D density contour chart.
 
 **Bubble Chart**
-Use a bubble chart when a third continuous variable can be meaningfully encoded as the area of each scatter point — market share plus revenue plus growth rate, for example. Area encoding is less precise than position, so the third variable should be the least precise claim in the story. Recommended library: Recharts `<ScatterChart>` with a custom dot renderer for React. Never use when the range of the third variable is less than 2× — the size difference is imperceptible and the extra encoding adds confusion without insight.
+Use a bubble chart when a third continuous variable can be meaningfully encoded as the area of each scatter point - market share plus revenue plus growth rate, for example. Area encoding is less precise than position, so the third variable should be the least precise claim in the story. Recommended library: Recharts `<ScatterChart>` with a custom dot renderer for React. Never use when the range of the third variable is less than 2× - the size difference is imperceptible and the extra encoding adds confusion without insight.
 
 **Chord Diagram**
-Use a chord diagram when showing bidirectional flows or relationships between members of the same set — migration between cities, trade flows between countries, or co-occurrence between categories. The arc length encodes the total flow for each node; the chord width encodes the flow between two specific nodes. Recommended library: D3 `d3-chord` with custom React SVG rendering. Never use when the flows are directed and their asymmetry is the story — Sankey handles directed flows with visible volume much more clearly.
+Use a chord diagram when showing bidirectional flows or relationships between members of the same set - migration between cities, trade flows between countries, or co-occurrence between categories. The arc length encodes the total flow for each node; the chord width encodes the flow between two specific nodes. Recommended library: D3 `d3-chord` with custom React SVG rendering. Never use when the flows are directed and their asymmetry is the story - Sankey handles directed flows with visible volume much more clearly.
 
 **Sankey Diagram**
-Use a Sankey diagram when showing directed flows with volume through a network of nodes — user journey funnels, energy systems, budget allocations, and supply chain flows are classic cases. Link width is proportional to flow volume. Recommended library: Nivo `@nivo/sankey` for React. Never use with cyclic flows or more than approximately ten nodes — the diagram quickly becomes a hairball that defeats the purpose of the visualization.
+Use a Sankey diagram when showing directed flows with volume through a network of nodes - user journey funnels, energy systems, budget allocations, and supply chain flows are classic cases. Link width is proportional to flow volume. Recommended library: Nivo `@nivo/sankey` for React. Never use with cyclic flows or more than approximately ten nodes - the diagram quickly becomes a hairball that defeats the purpose of the visualization.
 
 **Network / Force-Directed Graph**
-Use a force-directed network graph when the topology of connections between entities is the story — who is connected to whom, cluster structure, centrality, and isolated nodes. Force simulation positions densely connected clusters near each other. Recommended library: D3 `d3-force` with custom React SVG for full control. Never use when you need to compare edge weights or node values precisely — quantitative encoding via edge thickness or node size is unreliable in a force layout.
+Use a force-directed network graph when the topology of connections between entities is the story - who is connected to whom, cluster structure, centrality, and isolated nodes. Force simulation positions densely connected clusters near each other. Recommended library: D3 `d3-force` with custom React SVG for full control. Never use when you need to compare edge weights or node values precisely - quantitative encoding via edge thickness or node size is unreliable in a force layout.
 
 ---
 
 ### Trend
 
 **Line Chart**
-Use a line chart when showing how one or more continuous values change over an ordered time series. The connecting line implies continuity between measurements, so only use it when intermediate values would logically exist. Recommended library: Recharts `<LineChart>` for React. Never use for unordered categorical data — a bar chart is correct when there is no meaningful order between data points.
+Use a line chart when showing how one or more continuous values change over an ordered time series. The connecting line implies continuity between measurements, so only use it when intermediate values would logically exist. Recommended library: Recharts `<LineChart>` for React. Never use for unordered categorical data - a bar chart is correct when there is no meaningful order between data points.
 
 **Area Chart**
-Use an area chart when the cumulative volume or magnitude beneath the line is part of the story — total revenue over time, cumulative downloads, or stacked contribution of multiple series. Filling the area below the line emphasizes quantity more than rate of change. Recommended library: Recharts `<AreaChart>` for React. Never use with multiple overlapping series that share the same baseline — the overlaps become confusing; use a line chart with area fills per series that do not overlap, or switch to a stacked area.
+Use an area chart when the cumulative volume or magnitude beneath the line is part of the story - total revenue over time, cumulative downloads, or stacked contribution of multiple series. Filling the area below the line emphasizes quantity more than rate of change. Recommended library: Recharts `<AreaChart>` for React. Never use with multiple overlapping series that share the same baseline - the overlaps become confusing; use a line chart with area fills per series that do not overlap, or switch to a stacked area.
 
 **Sparkline**
-Use a sparkline as a compact inline trend indicator embedded within a table cell, a KPI card, or dense prose — the shape of the trend is the signal, not individual values. They are designed to be read without axes or labels. Recommended library: Recharts `<LineChart>` at very small dimensions with all axes and padding removed, or Victory `<VictoryLine>` for React. Never use when the reader needs to identify specific values, compare two sparklines precisely, or understand the scale of the change.
+Use a sparkline as a compact inline trend indicator embedded within a table cell, a KPI card, or dense prose - the shape of the trend is the signal, not individual values. They are designed to be read without axes or labels. Recommended library: Recharts `<LineChart>` at very small dimensions with all axes and padding removed, or Victory `<VictoryLine>` for React. Never use when the reader needs to identify specific values, compare two sparklines precisely, or understand the scale of the change.
 
 **Candlestick Chart**
-Use a candlestick chart for financial OHLC (open, high, low, close) data where the price range and direction within each period are both meaningful — daily stock prices, hourly crypto trades, and options expiry analysis. The body color (typically green/red) encodes whether the close was above or below the open. Recommended library: a specialized financial library such as `lightweight-charts` (TradingView), or D3 with custom React SVG for full control. Never use for non-financial time series where the OHLC convention would confuse general audiences who do not know the encoding.
+Use a candlestick chart for financial OHLC (open, high, low, close) data where the price range and direction within each period are both meaningful - daily stock prices, hourly crypto trades, and options expiry analysis. The body color (typically green/red) encodes whether the close was above or below the open. Recommended library: a specialized financial library such as `lightweight-charts` (TradingView), or D3 with custom React SVG for full control. Never use for non-financial time series where the OHLC convention would confuse general audiences who do not know the encoding.
 
 ---
 
 ### Progress / Goal
 
 **Gauge Chart**
-Use a gauge (also called a dial or speedometer chart) for a single KPI that has a meaningful threshold or target — CPU usage, customer satisfaction score, or a completion percentage. The radial encoding is immediately legible to general audiences as a progress metaphor. Recommended library: Nivo `@nivo/pie` with a semi-circle clipping mask, or a custom D3 arc in React. Never use for multiple gauges displayed side by side — radial comparison is cognitively expensive; use a bullet chart array instead.
+Use a gauge (also called a dial or speedometer chart) for a single KPI that has a meaningful threshold or target - CPU usage, customer satisfaction score, or a completion percentage. The radial encoding is immediately legible to general audiences as a progress metaphor. Recommended library: Nivo `@nivo/pie` with a semi-circle clipping mask, or a custom D3 arc in React. Never use for multiple gauges displayed side by side - radial comparison is cognitively expensive; use a bullet chart array instead.
 
 **Funnel Chart**
-Use a funnel chart when showing attrition or conversion across a fixed sequence of stages — e-commerce checkout steps, sales pipeline stages, or onboarding flows. Each stage is narrower than the previous, encoding drop-off volume. Recommended library: Nivo `@nivo/funnel` for React. Never use when the stages are not strictly sequential, not mutually exclusive, or when users can re-enter earlier stages — the funnel metaphor implies a one-way flow and will mislead.
+Use a funnel chart when showing attrition or conversion across a fixed sequence of stages - e-commerce checkout steps, sales pipeline stages, or onboarding flows. Each stage is narrower than the previous, encoding drop-off volume. Recommended library: Nivo `@nivo/funnel` for React. Never use when the stages are not strictly sequential, not mutually exclusive, or when users can re-enter earlier stages - the funnel metaphor implies a one-way flow and will mislead.
 
 ---
 
 ### Geographic
 
 **Geographic / Choropleth Map**
-Use a choropleth map when comparing a statistical variable across geographic regions — unemployment by county, election results by state, or population density by country. Color encodes the variable; spatial position provides geographic context. Recommended library: D3 with `d3-geo` projections and TopoJSON boundary data, or Nivo `@nivo/geo` for React. Never use when large low-population regions visually dominate the map while small high-population regions are barely visible — this is a known perceptual bias of choropleths; consider a cartogram or a bar chart with a small map inset.
+Use a choropleth map when comparing a statistical variable across geographic regions - unemployment by county, election results by state, or population density by country. Color encodes the variable; spatial position provides geographic context. Recommended library: D3 with `d3-geo` projections and TopoJSON boundary data, or Nivo `@nivo/geo` for React. Never use when large low-population regions visually dominate the map while small high-population regions are barely visible - this is a known perceptual bias of choropleths; consider a cartogram or a bar chart with a small map inset.
 
 ---
 
 ### Project Timelines
 
 **Gantt Chart**
-Use a Gantt chart when visualizing task scheduling, durations, dependencies, and resource allocation across a project timeline. Horizontal bars represent task duration; vertical position groups tasks by resource or phase. Recommended library: custom D3 rendering or specialized libraries such as `react-google-charts` (Gantt type) for React. Never use when the underlying data is not kept current — a stale Gantt chart actively misleads stakeholders about project status.
+Use a Gantt chart when visualizing task scheduling, durations, dependencies, and resource allocation across a project timeline. Horizontal bars represent task duration; vertical position groups tasks by resource or phase. Recommended library: custom D3 rendering or specialized libraries such as `react-google-charts` (Gantt type) for React. Never use when the underlying data is not kept current - a stale Gantt chart actively misleads stakeholders about project status.
 
 ---
 
@@ -198,7 +198,7 @@ Use a Gantt chart when visualizing task scheduling, durations, dependencies, and
 
 Approximately 8% of males and 0.5% of females have some form of color vision deficiency. Using a color-blind-safe palette is not optional for any chart that reaches a general audience.
 
-### Okabe-Ito (Categorical — 8 colors)
+### Okabe-Ito (Categorical - 8 colors)
 
 Developed by Masataka Okabe and Kei Ito and published in "Color Universal Design (CUD): How to make figures and presentations that are friendly to colorblind people" (J-Stage, 2008). This palette is distinguishable under all major types of color vision deficiency: deuteranopia, protanopia, tritanopia, and achromatopsia.
 
@@ -215,19 +215,19 @@ Developed by Masataka Okabe and Kei Ito and published in "Color Universal Design
 
 Use Okabe-Ito as the default categorical palette for all new charts unless a client brand palette takes precedence. When brand colors are required, simulate deuteranopia using tools such as Coblis or Viz Palette before shipping.
 
-### Viridis (Sequential — Continuous)
+### Viridis (Sequential - Continuous)
 
-Viridis is a perceptually uniform sequential colormap developed by Nathaniel Smith and Stefan van der Walt for matplotlib (SciPy 2015). It is safe for deuteranopia and protanopia, prints legibly in greyscale, and is monotonically increasing in perceived brightness — meaning that higher values are always visually distinct from lower values. Use Viridis for heatmaps, choropleths, and any continuous sequential data.
+Viridis is a perceptually uniform sequential colormap developed by Nathaniel Smith and Stefan van der Walt for matplotlib (SciPy 2015). It is safe for deuteranopia and protanopia, prints legibly in greyscale, and is monotonically increasing in perceived brightness - meaning that higher values are always visually distinct from lower values. Use Viridis for heatmaps, choropleths, and any continuous sequential data.
 
-CSS custom property suggestion: use the `viridis` scale from the `d3-scale-chromatic` package — `d3.scaleSequential(d3.interpolateViridis)`.
+CSS custom property suggestion: use the `viridis` scale from the `d3-scale-chromatic` package - `d3.scaleSequential(d3.interpolateViridis)`.
 
-### Cividis (Sequential — Blue-Yellow Optimized)
+### Cividis (Sequential - Blue-Yellow Optimized)
 
 Cividis is a variant of Viridis specifically optimized for blue-yellow (tritanopia) color blindness, developed by Jamie Nuñez, Christopher Anderton, and Ryan Renslow (PLOS ONE, 2018). It transitions from dark blue through grey to yellow and is designed to appear nearly identical to individuals with and without color vision deficiency. Use Cividis when your audience includes users with tritanopia, or as a general-purpose alternative to Viridis.
 
 CSS: `d3.scaleSequential(d3.interpolateCividis)` from `d3-scale-chromatic`.
 
-### Plasma (Sequential — High Contrast)
+### Plasma (Sequential - High Contrast)
 
 Plasma is a high-contrast perceptually uniform sequential palette that transitions from dark purple through bright orange-yellow. Use Plasma for sequential data where Viridis reads as too green-dominant or where high contrast between low and high values is needed in print. It is safe for deuteranopia and protanopia.
 
@@ -244,9 +244,9 @@ CSS: `d3.scaleSequential(d3.interpolatePlasma)` from `d3-scale-chromatic`.
 The pie chart is the most misused chart type in business contexts. These rules are non-negotiable.
 
 - **Use pie only for part-of-whole data with five or fewer slices.** The human visual system is reliable at reading pie slices only when the slices are few and substantially different in size. Beyond five slices, switch to a horizontal bar chart sorted by value.
-- **Never use 3D pie charts.** The perspective projection warps the apparent size of slices — a slice in the foreground appears larger than an identical slice in the background. A 3D pie chart is not a stylistic choice; it is a lie about the data. Remove it from any design system component library.
+- **Never use 3D pie charts.** The perspective projection warps the apparent size of slices - a slice in the foreground appears larger than an identical slice in the background. A 3D pie chart is not a stylistic choice; it is a lie about the data. Remove it from any design system component library.
 - **For more than five categories, use a bar chart or treemap.** A horizontal bar chart sorted descending gives every category a position on a shared baseline and is orders of magnitude more readable than a twelve-slice pie.
-- **Label slices directly when there are five or fewer slices.** Place the label and value inside or adjacent to each slice. Legends force the reader to shuttle their eyes back and forth between the legend and the chart — this is cognitive overhead that direct labeling eliminates. When slices are too small to label directly, use a leader line.
+- **Label slices directly when there are five or fewer slices.** Place the label and value inside or adjacent to each slice. Legends force the reader to shuttle their eyes back and forth between the legend and the chart - this is cognitive overhead that direct labeling eliminates. When slices are too small to label directly, use a leader line.
 
 ---
 
@@ -256,25 +256,25 @@ Axes are the scaffolding of interpretation. Misusing them is one of the most com
 
 ### Zero Baseline
 
-Always start bar chart and area chart Y-axes at zero. A bar whose height encodes a value depends entirely on that bar's length relative to the baseline — truncating the baseline inflates the visual difference between bars. A chart showing two bars of 98 and 99 that is truncated to start at 97 makes them appear vastly different; starting at zero makes them appear nearly identical, which is the truth. This rule is absolute for bar and area charts.
+Always start bar chart and area chart Y-axes at zero. A bar whose height encodes a value depends entirely on that bar's length relative to the baseline - truncating the baseline inflates the visual difference between bars. A chart showing two bars of 98 and 99 that is truncated to start at 97 makes them appear vastly different; starting at zero makes them appear nearly identical, which is the truth. This rule is absolute for bar and area charts.
 
 ### Line Chart Truncation Exception
 
-Line charts showing change over time may truncate the Y axis when the absolute values are large but the change is small and meaningful — for example, a body temperature chart ranging from 36.0°C to 38.5°C is more useful than one ranging from 0°C to 40°C. **When you truncate a line chart Y-axis, you must include a break indicator (⁃⁃) on the axis to signal that the baseline is not zero.** Without the break indicator, the chart misleads.
+Line charts showing change over time may truncate the Y axis when the absolute values are large but the change is small and meaningful - for example, a body temperature chart ranging from 36.0°C to 38.5°C is more useful than one ranging from 0°C to 40°C. **When you truncate a line chart Y-axis, you must include a break indicator (⁃⁃) on the axis to signal that the baseline is not zero.** Without the break indicator, the chart misleads.
 
 ### Dual Y-Axis
 
-Avoid dual Y-axis charts. A dual Y-axis allows the designer to manipulate the apparent correlation between two variables by independently scaling each axis — any two unrelated trends can be made to appear correlated. There is almost always a better alternative: separate charts sharing an X-axis (small multiples), an index chart normalizing both series to 100 at a common start point, or a scatter plot if correlation is what you are trying to show.
+Avoid dual Y-axis charts. A dual Y-axis allows the designer to manipulate the apparent correlation between two variables by independently scaling each axis - any two unrelated trends can be made to appear correlated. There is almost always a better alternative: separate charts sharing an X-axis (small multiples), an index chart normalizing both series to 100 at a common start point, or a scatter plot if correlation is what you are trying to show.
 
 ### Log Scale
 
-A logarithmic scale is valid and appropriate when data spans multiple orders of magnitude — population by country, income distribution, or exponential growth curves. A log scale compresses the high end and expands the low end, making growth rates comparable across the full range. **Always label a log-scale axis explicitly as "log scale."** Readers who do not notice they are looking at a log axis will dramatically misread the rate of change between data points.
+A logarithmic scale is valid and appropriate when data spans multiple orders of magnitude - population by country, income distribution, or exponential growth curves. A log scale compresses the high end and expands the low end, making growth rates comparable across the full range. **Always label a log-scale axis explicitly as "log scale."** Readers who do not notice they are looking at a log axis will dramatically misread the rate of change between data points.
 
 ---
 
 ## 6. Annotation Patterns
 
-Annotations are the editorial layer of a chart — they tell the reader which data points are most important and why.
+Annotations are the editorial layer of a chart - they tell the reader which data points are most important and why.
 
 ### Direct Labeling vs. Legend
 
@@ -282,7 +282,7 @@ Direct labeling on the chart is more readable than a legend when the chart has f
 
 ### Callouts for Notable Data Points
 
-Use callout annotations to mark data points with editorial significance — a record high or low, a policy change, an anomaly, a product launch, or an external event that explains a discontinuity. A callout typically consists of a small circle or dot on the data point, a leader line, and a text label. Callout text should be **one sentence maximum**, left-aligned on the callout, and written in plain language that states what happened, not what the reader can already see ("Revenue fell 22% in March after the supply chain disruption" is useful; "Value decreases here" is not).
+Use callout annotations to mark data points with editorial significance - a record high or low, a policy change, an anomaly, a product launch, or an external event that explains a discontinuity. A callout typically consists of a small circle or dot on the data point, a leader line, and a text label. Callout text should be **one sentence maximum**, left-aligned on the callout, and written in plain language that states what happened, not what the reader can already see ("Revenue fell 22% in March after the supply chain disruption" is useful; "Value decreases here" is not).
 
 ### Annotation Placement
 
@@ -296,11 +296,11 @@ Data visualizations present unique accessibility challenges because they communi
 
 ### Data Table Alternative
 
-Always provide a data table as an accessible alternative to complex charts. WCAG 1.1.1 (Level A) requires non-text content to have a text alternative that presents the same information. For a line chart, this means an HTML `<table>` with the same data used to generate the chart — it can be visually hidden and shown on demand, included below the chart, or linked as a download. The chart title and description should also be conveyed in the chart's `<title>` and `<desc>` SVG elements or in an `aria-label` on the chart container.
+Always provide a data table as an accessible alternative to complex charts. WCAG 1.1.1 (Level A) requires non-text content to have a text alternative that presents the same information. For a line chart, this means an HTML `<table>` with the same data used to generate the chart - it can be visually hidden and shown on demand, included below the chart, or linked as a download. The chart title and description should also be conveyed in the chart's `<title>` and `<desc>` SVG elements or in an `aria-label` on the chart container.
 
 ### ARIA Live Regions for Dynamic Charts
 
-Charts that update in real time — stock price tickers, live analytics dashboards, server monitoring — must use ARIA live regions to announce changes to screen reader users. Set `aria-live="polite"` on a visually hidden element that receives a text update each time the chart data changes. Use `aria-live="assertive"` only for urgent alerts (threshold breach, system failure). Avoid updating the live region more than once every few seconds, as rapid updates interrupt screen reader speech.
+Charts that update in real time - stock price tickers, live analytics dashboards, server monitoring - must use ARIA live regions to announce changes to screen reader users. Set `aria-live="polite"` on a visually hidden element that receives a text update each time the chart data changes. Use `aria-live="assertive"` only for urgent alerts (threshold breach, system failure). Avoid updating the live region more than once every few seconds, as rapid updates interrupt screen reader speech.
 
 ### Keyboard Navigation
 
@@ -308,17 +308,17 @@ Interactive charts that support brushing, zooming, or selecting data ranges must
 
 ### Sonification
 
-Sonification — encoding data as sound (pitch, tempo, or timbre) — is an experimental but promising alternative for screen reader users who cannot interpret visual charts even with text alternatives. Libraries such as Highcharts Sonification Studio and Astronify provide this capability. Sonification is not currently a WCAG requirement, but it is worth noting for products that serve visually impaired users as a primary audience. Do not substitute sonification for a data table; provide both.
+Sonification - encoding data as sound (pitch, tempo, or timbre) - is an experimental but promising alternative for screen reader users who cannot interpret visual charts even with text alternatives. Libraries such as Highcharts Sonification Studio and Astronify provide this capability. Sonification is not currently a WCAG requirement, but it is worth noting for products that serve visually impaired users as a primary audience. Do not substitute sonification for a data table; provide both.
 
 ---
 
 ## 8. Dashboard Patterns
 
-A dashboard is a collection of charts, and the design principles that apply to individual charts apply with compounding force to dashboards — bad individual chart choices become bad dashboard experiences.
+A dashboard is a collection of charts, and the design principles that apply to individual charts apply with compounding force to dashboards - bad individual chart choices become bad dashboard experiences.
 
 ### Overview First, Filter Late, Drill Down
 
-Follow Shneiderman's Visual Information-Seeking Mantra: **overview first, zoom and filter, then details on demand.** The dashboard's first view should give the reader the big picture — total performance, trend direction, anomalies. Filtering controls (date range, segment selector) narrow the overview. Drill-down links or expandable panels reveal underlying detail. Reversing this order — starting with granular data — overwhelms users and prevents them from forming a correct mental model of the system.
+Follow Shneiderman's Visual Information-Seeking Mantra: **overview first, zoom and filter, then details on demand.** The dashboard's first view should give the reader the big picture - total performance, trend direction, anomalies. Filtering controls (date range, segment selector) narrow the overview. Drill-down links or expandable panels reveal underlying detail. Reversing this order - starting with granular data - overwhelms users and prevents them from forming a correct mental model of the system.
 
 ### KPI Cards Above the Fold
 
@@ -326,8 +326,8 @@ The most important single number belongs above the fold as a KPI card. A well-de
 
 ### Progressive Disclosure
 
-Structure dashboard information in three layers: **summary** (KPI cards and headline charts above the fold), **detail** (supporting charts visible on scroll), and **raw data** (accessible via a link, export, or drill-down table). This mirrors how users actually read dashboards — most users stop at the summary layer most of the time; power users drill into detail; analysts need the raw data. Putting all three layers on the same screen simultaneously creates visual noise for the majority of users.
+Structure dashboard information in three layers: **summary** (KPI cards and headline charts above the fold), **detail** (supporting charts visible on scroll), and **raw data** (accessible via a link, export, or drill-down table). This mirrors how users actually read dashboards - most users stop at the summary layer most of the time; power users drill into detail; analysts need the raw data. Putting all three layers on the same screen simultaneously creates visual noise for the majority of users.
 
 ### Cognitive Load Budget
 
-Apply a strict cognitive load budget above the fold: **no more than five distinct visual elements** (KPI cards, charts, filter controls) should compete for attention in the initial viewport. Every additional element above five increases cognitive load non-linearly — users experience "dashboard blindness" and stop reading the dashboard at all. If you have eight KPIs, group them into two rows of four with clear visual hierarchy that directs attention to the top two. If you have twelve charts, use tabs or sections to reveal them progressively rather than displaying them simultaneously.
+Apply a strict cognitive load budget above the fold: **no more than five distinct visual elements** (KPI cards, charts, filter controls) should compete for attention in the initial viewport. Every additional element above five increases cognitive load non-linearly - users experience "dashboard blindness" and stop reading the dashboard at all. If you have eight KPIs, group them into two rows of four with clear visual hierarchy that directs attention to the top two. If you have twelve charts, use tabs or sections to reveal them progressively rather than displaying them simultaneously.

package/reference/debugger-philosophy.md

@@ -8,7 +8,7 @@ A design bug is a gap between what the design says (DESIGN-PLAN.md goals, D-XX d
 
 2. **One variable at a time.** Change one thing, re-measure. Multiple simultaneous changes make causation impossible to determine and usually bury the true culprit.
 
-3. **Persistent state.** Write findings to `.design/DEBUG.md` after each investigation step. A killed debug session resumes from the last checkpoint — your future self should be able to read the file and pick up mid-thought.
+3. **Persistent state.** Write findings to `.design/DEBUG.md` after each investigation step. A killed debug session resumes from the last checkpoint - your future self should be able to read the file and pick up mid-thought.
 
 4. **Design decisions are ground truth.** If D-XX says "primary = #3B82F6" and the rendered color is #000, that is a bug regardless of intent, aesthetics, or taste. The decision trail is the spec.
 
@@ -26,7 +26,7 @@ Written to `.design/DEBUG.md` with one `##` section per session. Each section co
 
 ## Red Flags
 
-- "It works for me" without a measurement — no. Measure.
-- Fixing a symptom without isolating the cause — the bug will return somewhere else.
-- Editing a global token to fix one component — blast radius.
-- Skipping the DEBUG.md write-up because "it's obvious now" — future-you will disagree.
+- "It works for me" without a measurement - no. Measure.
+- Fixing a symptom without isolating the cause - the bug will return somewhere else.
+- Editing a global token to fix one component - blast radius.
+- Skipping the DEBUG.md write-up because "it's obvious now" - future-you will disagree.

package/reference/design-system-guidance.md

@@ -6,21 +6,21 @@ A design system is not a component library. A component library is a collection
 
 ## Token Versioning and Deprecation Policy
 
-Design tokens are an API. Like any API, they must be versioned, because the components and applications that consume them will break if tokens are renamed or removed without notice. Treating tokens as implementation details — things that can be changed quietly — is the single most common cause of unexpected visual regressions in design systems.
+Design tokens are an API. Like any API, they must be versioned, because the components and applications that consume them will break if tokens are renamed or removed without notice. Treating tokens as implementation details - things that can be changed quietly - is the single most common cause of unexpected visual regressions in design systems.
 
 **Semantic versioning for token APIs:** Token changes should follow SemVer semantics. Adding a new token is a minor release. Changing a token's value (e.g., updating `--color-brand-primary` from `#1a73e8` to `#1557b0`) is a minor release if the semantic meaning is preserved, or a major release if it changes the intent. Renaming or removing a token is always a major release.
 
 **Deprecation warnings before removal:** A token should never be removed without a deprecation period of at least one major version. During the deprecation period, the old token continues to work but emits a warning in development mode (or in Figma via variable mode annotation). The deprecation notice must include the replacement token and a migration date. Consumers who are warned well in advance can migrate on their own timeline; consumers who are surprised by breakage lose trust in the system.
 
-**Migration guides required:** Every major release that removes or renames tokens must include a migration guide. The guide must list every changed token, its old name, its new name, and a search-and-replace pattern that can be applied programmatically. A migration that requires consumers to manually discover what changed is not a migration — it is a breakage.
+**Migration guides required:** Every major release that removes or renames tokens must include a migration guide. The guide must list every changed token, its old name, its new name, and a search-and-replace pattern that can be applied programmatically. A migration that requires consumers to manually discover what changed is not a migration - it is a breakage.
 
-**Never rename without aliasing:** When a token must be renamed — because the original name violated naming conventions, was ambiguous, or referred to a value rather than a purpose — the old name must be preserved as an alias pointing to the new name. The alias is deprecated and removed in the next major release after a documented migration window. This rule exists because token names propagate into codebases at scale: a rename without aliasing breaks every downstream consumer simultaneously.
+**Never rename without aliasing:** When a token must be renamed - because the original name violated naming conventions, was ambiguous, or referred to a value rather than a purpose - the old name must be preserved as an alias pointing to the new name. The alias is deprecated and removed in the next major release after a documented migration window. This rule exists because token names propagate into codebases at scale: a rename without aliasing breaks every downstream consumer simultaneously.
 
 ---
 
 ## Multi-Brand Token Architecture
 
-A multi-brand token architecture allows a single component library to support multiple brand expressions — different color palettes, typography scales, and spacing densities — without forking the component code. The architecture achieves this through three distinct token layers, each with a specific responsibility.
+A multi-brand token architecture allows a single component library to support multiple brand expressions - different color palettes, typography scales, and spacing densities - without forking the component code. The architecture achieves this through three distinct token layers, each with a specific responsibility.
 
 ### Base Layer (Primitives)
 
@@ -33,7 +33,7 @@ Examples:
 - `--space-8: 8px`
 - `--font-size-16: 16px`
 
-**See:** [`./proportion-systems.md`](./proportion-systems.md) for the whole-UI proportion system covering 4pt/8pt/√2 baseline grids, baseline-grid lock, vertical rhythm, and modular relationships across type / spacing / sizing / radius scales — the primitive tokens above are the codified output of that system.
+**See:** [`./proportion-systems.md`](./proportion-systems.md) for the whole-UI proportion system covering 4pt/8pt/√2 baseline grids, baseline-grid lock, vertical rhythm, and modular relationships across type / spacing / sizing / radius scales - the primitive tokens above are the codified output of that system.
 
 Primitive tokens should never be used directly in component code. They exist only to feed the semantic layer. This constraint is essential: if components reference primitive tokens directly, you lose the ability to theme them without modifying component code.
 
@@ -51,7 +51,7 @@ Theme switching works by replacing the semantic layer. In practice, each brand d
 
 ### Component Layer (Scoped Tokens)
 
-The component layer scopes semantic tokens to specific component contexts. Component-layer tokens exist because some components need values that differ from their semantic parents in specific states, variants, or sizes — but those differences should still be expressed as token relationships, not hardcoded values.
+The component layer scopes semantic tokens to specific component contexts. Component-layer tokens exist because some components need values that differ from their semantic parents in specific states, variants, or sizes - but those differences should still be expressed as token relationships, not hardcoded values.
 
 Examples:
 - `--button-bg-primary: var(--color-interactive-default)`
@@ -69,7 +69,7 @@ The token architecture is only valuable if it can be consumed by all the platfor
 
 **Style Dictionary** is the standard open-source tool for token transformation. It reads a JSON or YAML token definition and transforms it into CSS custom properties, iOS Swift constants, Android XML resources, or any other format through a configurable pipeline. Style Dictionary is the right choice for most organizations because it is well-documented, widely adopted, and extensible. The transform pipeline should be version-controlled alongside the token definitions.
 
-**Tokens Studio (Figma plugin)** enables the design-to-code handoff by syncing Figma variables and styles to a JSON format that Style Dictionary can consume. When Tokens Studio is integrated with the CI pipeline — so that token changes in Figma trigger a transform and publish cycle — the design-to-code gap closes. Designers change tokens in Figma; engineers receive the updated CSS variables in the next publish. Without this integration, token values diverge between design and code, which is the root cause of most "the design says one thing but the code does another" defects.
+**Tokens Studio (Figma plugin)** enables the design-to-code handoff by syncing Figma variables and styles to a JSON format that Style Dictionary can consume. When Tokens Studio is integrated with the CI pipeline - so that token changes in Figma trigger a transform and publish cycle - the design-to-code gap closes. Designers change tokens in Figma; engineers receive the updated CSS variables in the next publish. Without this integration, token values diverge between design and code, which is the root cause of most "the design says one thing but the code does another" defects.
 
 **Terrazzo** provides advanced token transform capabilities for organizations with complex multi-platform, multi-brand requirements. It handles cases that Style Dictionary handles awkwardly: mathematically derived scales (e.g., a spacing scale generated from a base value), conditional token resolution (different values for different contexts), and schema validation at the token definition level.
 
@@ -77,17 +77,17 @@ The token architecture is only valuable if it can be consumed by all the platfor
 
 ## Semantic-Layer Design
 
-The semantic layer is the design system's most consequential architectural decision. Naming tokens by value — `--color-red`, `--color-blue-700`, `--font-size-14` — produces a token API that is fragile under theming and misleading to consumers. Naming tokens by purpose produces an API that survives brand evolution, makes component intent explicit, and is safe to search and audit.
+The semantic layer is the design system's most consequential architectural decision. Naming tokens by value - `--color-red`, `--color-blue-700`, `--font-size-14` - produces a token API that is fragile under theming and misleading to consumers. Naming tokens by purpose produces an API that survives brand evolution, makes component intent explicit, and is safe to search and audit.
 
 **The cardinal rule:** Name tokens by PURPOSE, not by VALUE.
 
-Wrong: `--color-red` (a value name — breaks if the brand switches to orange for danger)  
-Right: `--color-surface-danger` (a purpose name — survives any palette change)
+Wrong: `--color-red` (a value name - breaks if the brand switches to orange for danger)  
+Right: `--color-surface-danger` (a purpose name - survives any palette change)
 
-Wrong: `--font-size-14` (a value name — breaks if the scale changes)  
-Right: `--font-size-caption` (a purpose name — survives a scale adjustment)
+Wrong: `--font-size-14` (a value name - breaks if the scale changes)  
+Right: `--font-size-caption` (a purpose name - survives a scale adjustment)
 
-**Tokens should survive theme changes without rename.** A token that must be renamed every time the palette changes is not a semantic token — it is a named value. The test: if you change the value of `--color-surface-danger` from red to orange, does the name still accurately describe its purpose? If yes, the name is semantic. If no, the name was value-based.
+**Tokens should survive theme changes without rename.** A token that must be renamed every time the palette changes is not a semantic token - it is a named value. The test: if you change the value of `--color-surface-danger` from red to orange, does the name still accurately describe its purpose? If yes, the name is semantic. If no, the name was value-based.
 
 **Hierarchical naming:** Semantic tokens should follow a consistent naming convention that expresses category, role, and variant:
 
@@ -112,11 +112,11 @@ This convention makes the token vocabulary predictable: anyone who knows the con
 
 Component APIs are the contract between the design system and its consumers. An inconsistent or poorly designed API creates confusion, increases adoption friction, and makes migration painful. These conventions should be enforced in code review and documented in every component's API reference.
 
-**The `size` prop:** Always use named sizes — `sm`, `md`, `lg` — never raw pixel values. Pixel values expose implementation details and break the abstraction. Named sizes allow the design system to change the underlying pixel values across a version without requiring component consumers to update their code. `xs` and `xl` are acceptable additions when genuinely needed; avoid open-ended numeric scales that invite inconsistency.
+**The `size` prop:** Always use named sizes - `sm`, `md`, `lg` - never raw pixel values. Pixel values expose implementation details and break the abstraction. Named sizes allow the design system to change the underlying pixel values across a version without requiring component consumers to update their code. `xs` and `xl` are acceptable additions when genuinely needed; avoid open-ended numeric scales that invite inconsistency.
 
-**The `variant` prop:** Use a fixed vocabulary: `primary`, `secondary`, `ghost`, `destructive`. Additional variants should be exceptional and documented with rationale. Never create variants that duplicate semantic roles (e.g., `danger` alongside `destructive`) — this fragments the vocabulary and creates consumer confusion about which to use.
+**The `variant` prop:** Use a fixed vocabulary: `primary`, `secondary`, `ghost`, `destructive`. Additional variants should be exceptional and documented with rationale. Never create variants that duplicate semantic roles (e.g., `danger` alongside `destructive`) - this fragments the vocabulary and creates consumer confusion about which to use.
 
-**Never expose internal implementation details as props.** A component whose API includes `backgroundColor`, `borderRadius`, or `fontWeight` props is not a component — it is a styled div. Internal visual properties should be determined by the component's variant and size, expressed through tokens. If a consumer needs visual customization beyond the declared variants, the appropriate tool is either a new variant (with a contribution RFC) or composition, not an escape hatch prop.
+**Never expose internal implementation details as props.** A component whose API includes `backgroundColor`, `borderRadius`, or `fontWeight` props is not a component - it is a styled div. Internal visual properties should be determined by the component's variant and size, expressed through tokens. If a consumer needs visual customization beyond the declared variants, the appropriate tool is either a new variant (with a contribution RFC) or composition, not an escape hatch prop.
 
 ---
 
@@ -128,9 +128,9 @@ A design system without governance is a suggestion library. Governance is what t
 
 **Voting quorum for breaking changes:** Changes that remove or rename tokens, alter component API signatures, or change default visual behavior require a minimum quorum of token stakeholders (typically design leads and engineering leads from all consuming products) to review and approve. The quorum threshold and voting period should be documented and consistent. This prevents one team's urgency from creating breakage for other teams.
 
-**Single-owner per component:** Every component must have a named owner — a person who is responsible for its API, its documentation, its accessibility compliance, and its migration support. Ownerless components decay: they accumulate inconsistencies, miss accessibility regressions, and fall behind the token system evolution. Ownership should transfer explicitly when team members change roles.
+**Single-owner per component:** Every component must have a named owner - a person who is responsible for its API, its documentation, its accessibility compliance, and its migration support. Ownerless components decay: they accumulate inconsistencies, miss accessibility regressions, and fall behind the token system evolution. Ownership should transfer explicitly when team members change roles.
 
-**Design and engineering sign-off both required:** No component ships without explicit sign-off from both the design lead (verifying that it matches the designed spec and has appropriate variant coverage) and the engineering lead (verifying that the API is correct, the implementation is idiomatic, and the tests cover the declared states). This dual sign-off is not bureaucracy — it is the minimal process that prevents the design-code gap from re-opening on every release.
+**Design and engineering sign-off both required:** No component ships without explicit sign-off from both the design lead (verifying that it matches the designed spec and has appropriate variant coverage) and the engineering lead (verifying that the API is correct, the implementation is idiomatic, and the tests cover the declared states). This dual sign-off is not bureaucracy - it is the minimal process that prevents the design-code gap from re-opening on every release.
 
 ---
 
@@ -152,7 +152,7 @@ The documentation standard for every component requires all of the following:
 
 **Code example:** A minimal, copy-paste-ready code example for the most common usage. Consumers should be able to get to a correct implementation in under two minutes.
 
-**Accessibility notes:** The ARIA role, relevant ARIA attributes, keyboard interaction pattern, and focus management behavior. This section is not optional — every interactive component has accessibility requirements that cannot be inferred from the visual design alone.
+**Accessibility notes:** The ARIA role, relevant ARIA attributes, keyboard interaction pattern, and focus management behavior. This section is not optional - every interactive component has accessibility requirements that cannot be inferred from the visual design alone.
 
 ---
 
@@ -164,10 +164,10 @@ Design systems evolve through recognizable maturity stages. Understanding where
 Components are built per project with no shared library. Each application makes its own visual decisions about color, typography, and spacing. There is no coordination mechanism, no shared vocabulary, and no reuse. Visual inconsistency across products is structural, not accidental. The cost of this level is paid in designer and engineer time spent rediscovering the same decisions on every project.
 
 ### Level 1: Shared UI Kit
-A Figma component library exists and is used by designers. Components have documented variants and states in Figma. There is no code counterpart — developers implement from designs directly. The design-to-code gap is the defining problem at this level: the Figma library and the code diverge over time because there is no synchronization mechanism.
+A Figma component library exists and is used by designers. Components have documented variants and states in Figma. There is no code counterpart - developers implement from designs directly. The design-to-code gap is the defining problem at this level: the Figma library and the code diverge over time because there is no synchronization mechanism.
 
 ### Level 2: Component Library
-Coded components exist and are shared across applications as a package. The library has basic documentation. There are no design tokens — visual values are hardcoded in component styles. Theming is not possible without forking the library. The code-to-design gap is still present because Figma and code are not synchronized.
+Coded components exist and are shared across applications as a package. The library has basic documentation. There are no design tokens - visual values are hardcoded in component styles. Theming is not possible without forking the library. The code-to-design gap is still present because Figma and code are not synchronized.
 
 ### Level 3: Token-Driven
 Design tokens exist in both Figma and code, synchronized through an automated pipeline (Tokens Studio + Style Dictionary). A semantic layer separates component implementations from raw values. Basic theming is possible by swapping the semantic layer. This is the first level where multi-brand support becomes practical. Most organizations that have invested in a design system are at Level 2 or approaching Level 3.