--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/SIZING.md	Wed Aug 05 05:25:40 2026 -0700
@@ -0,0 +1,65 @@
+# Zenbu UI sizing
+
+Zenbu UI uses one five-step scale everywhere:
+
+| Size | Intended use |
+| --- | --- |
+| `xs` | dense metadata and compact actions |
+| `sm` | secondary controls and toolbars |
+| `md` | default body text and controls |
+| `lg` | prominent actions and lead text |
+| `xl` | touch-forward actions and display text |
+
+## Tokens
+
+Each step defines:
+
+- `--zenbu-sys-font-size-*` and `--zenbu-sys-line-height-*`;
+- `--zenbu-sys-control-height-*`;
+- `--zenbu-sys-control-padding-block-*` and
+  `--zenbu-sys-control-padding-inline-*`;
+- `--zenbu-sys-control-gap-*`;
+- `--zenbu-sys-icon-size-*`;
+- `--zenbu-sys-padding-*` for containers.
+
+Component hosts expose the selected values through inherited variables:
+
+```css
+--zenbu-control-height
+--zenbu-control-padding-block
+--zenbu-control-padding-inline
+--zenbu-control-gap
+--zenbu-control-font-size
+--zenbu-control-line-height
+--zenbu-control-icon-size
+```
+
+Styled components consume these automatically:
+
+```html
+<zen-button size="lg"><button type="button">Publish</button></zen-button>
+<zen-input size="sm"><input aria-label="Filter" /></zen-input>
+```
+
+Plain components expose the same variables without styling the native control.
+Applications can preserve their visual identity while sharing the scale:
+
+```css
+zen-button[appearance="plain"] > button {
+  min-height: var(--zenbu-control-height);
+  padding:
+    var(--zenbu-control-padding-block)
+    var(--zenbu-control-padding-inline);
+  font-size: var(--zenbu-control-font-size);
+}
+```
+
+## Typography and containers
+
+Use native semantics inside the primitives:
+
+```html
+<zen-heading size="xl"><h2>Repository activity</h2></zen-heading>
+<zen-text size="sm"><p>Updated two minutes ago.</p></zen-text>
+<zen-box padding="lg">...</zen-box>
+```