@dorsk/tsumikit 0.50.0 → 0.51.0

package/README.md

@@ -154,6 +154,60 @@ for a light theme (`:root` defaults to dark, so dark themes may omit it).
 - Adding a built-in theme to the kit = one entry in `THEMES`
   (`stores/theme.svelte.ts`) + one block in `styles/themes.css`.
 
+### Styling a component from outside
+
+A Svelte consumer's **scoped** CSS cannot reach a child component's markup — the
+scoping attribute is only added to elements the consumer itself renders. `class`
+passthrough therefore only helps for layout hooks (margin, flex, grid placement).
+CSS custom properties *do* cross the component boundary, so they are the
+sanctioned escape hatch for everything else.
+
+- **Naming:** `--<prefix>-<axis>`, where `<prefix>` is the component's short
+  prefix (`btn`, `badge`, `txt`, `select`, `input`, `textarea`, `card`, `md`, …)
+  and `<axis>` is one of `bg`, `fg`, `border`, `size`, `radius`, plus a few
+  component-specific ones (`--btn-tone`, `--badge-max-width`, `--gauge-w`).
+  `Text` uses `txt` because `--text*` is already the theme's foreground token.
+- **Setting them:** per instance via `style`, or on any ancestor for a subtree.
+
+```svelte
+<Button style="--btn-bg: var(--c-violet); --btn-fg: #fff; --btn-radius: 0">Ship</Button>
+
+<div class="danger-zone">
+  <Button>Delete</Button>   <!-- inherits the block below -->
+</div>
+
+<style>
+  .danger-zone { --btn-border: var(--danger); --btn-fg: var(--danger); }
+</style>
+```
+
+- Every property is read as `var(--x, <default>)`, so leaving it unset renders
+  exactly as before.
+- **`:global()` into kit internals is unsupported.** Class names like `.btn`,
+  `.badge`, `.select-wrap` or `.textarea` are private and change without a major
+  bump. If an axis you need is missing, open an issue — do not reach in.
+
+| component | published properties |
+| --- | --- |
+| `Button` | `--btn-bg`, `--btn-fg`, `--btn-border`, `--btn-size`, `--btn-radius`, `--btn-tone`, `--btn-on`, `--btn-box` |
+| `Badge` | `--badge-bg`, `--badge-fg`, `--badge-border`, `--badge-radius`, `--badge-tone`, `--badge-max-width` |
+| `Text` | `--txt-fg`, `--txt-size` |
+| `Select` | `--select-bg`, `--select-fg`, `--select-border`, `--select-size`, `--select-radius` |
+| `Input` | `--input-bg`, `--input-fg`, `--input-border`, `--input-size`, `--input-radius` |
+| `Textarea` | `--textarea-bg`, `--textarea-fg`, `--textarea-border`, `--textarea-size`, `--textarea-radius` |
+| `Card` | `--card-pad`, `--card-gap`, `--card-border-style` |
+| `Divider` | `--divider-color`, `--divider-spacing` |
+| `Gauge` | `--gauge-w`, `--gauge-h`, `--gauge-fill` |
+| `MasterDetail` | `--md-list-w`, `--md-gap`, `--md-divider` |
+| `NavBar` | `--navbar-max` |
+| `Callout` | `--callout-tone` |
+| `Fieldset` | `--fieldset-pad`, `--fieldset-border` |
+| `GitRef` | `--git-ref-tone`, `--git-ref-max-width` |
+| `EmptyState` | `--empty-tone` |
+
+`tests/css-custom-property-contract.test.js` reads this table and fails if a
+listed property is not actually read by its component, so the docs cannot drift.
+
 ## Components
 
 **Atoms:** Text, Heading, Button, Input (`icon` inset leading glyph,

package/dist/components/atoms/Badge.svelte

@@ -166,13 +166,13 @@
 		align-items: center;
 		gap: var(--sp-1);
 		padding: 0.15rem var(--sp-2);
-		border-radius: var(--r-pill);
+		border-radius: var(--badge-radius, var(--r-pill));
 		font-size: var(--fs-xs);
 		font-weight: var(--fw-medium);
 		line-height: 1.4;
-		background: var(--bg-elevated-2);
-		color: var(--text-muted);
-		border: 1px solid var(--border);
+		background: var(--badge-bg, var(--bg-elevated-2));
+		color: var(--badge-fg, var(--text-muted));
+		border: 1px solid var(--badge-border, var(--border));
 		white-space: nowrap;
 		max-width: var(--badge-max-width, 100%);
 	}
@@ -188,9 +188,9 @@
 		padding: 0.05rem var(--sp-2);
 	}
 	.toned {
-		color: var(--badge-tone);
-		border-color: color-mix(in srgb, var(--badge-tone) 40%, transparent);
-		background: color-mix(in srgb, var(--badge-tone) 12%, transparent);
+		color: var(--badge-fg, var(--badge-tone));
+		border-color: var(--badge-border, color-mix(in srgb, var(--badge-tone) 40%, transparent));
+		background: var(--badge-bg, color-mix(in srgb, var(--badge-tone) 12%, transparent));
 	}
 	.text {
 		padding: 0;

package/dist/components/atoms/Button.svelte

@@ -165,11 +165,11 @@
 		justify-content: center;
 		gap: var(--sp-2);
 		padding: var(--sp-2) var(--sp-4);
-		min-height: var(--control-height-default);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		background: var(--surface);
-		color: var(--text);
+		min-height: var(--btn-size, var(--control-height-default));
+		border: 1px solid var(--btn-border, var(--border-strong));
+		border-radius: var(--btn-radius, var(--r-md));
+		background: var(--btn-bg, var(--surface));
+		color: var(--btn-fg, var(--text));
 		font-weight: var(--fw-medium);
 		font-size: var(--fs-sm);
 		line-height: 1;
@@ -188,9 +188,9 @@
 		cursor: not-allowed;
 	}
 	.btn-primary {
-		background: var(--accent);
-		border-color: var(--accent);
-		color: var(--text-on-accent);
+		background: var(--btn-bg, var(--accent));
+		border-color: var(--btn-border, var(--accent));
+		color: var(--btn-fg, var(--text-on-accent));
 		font-weight: var(--fw-semibold);
 	}
 	.btn-primary:hover:not(:disabled) {
@@ -205,21 +205,21 @@
 		border-color: var(--danger);
 	}
 	.btn-ghost {
-		background: transparent;
-		border-color: transparent;
+		background: var(--btn-bg, transparent);
+		border-color: var(--btn-border, transparent);
 	}
 	.btn-ghost:hover:not(:disabled) {
 		background: var(--bg-elevated-2);
 		border-color: transparent;
 	}
 	.btn-sm {
-		height: var(--control-height-compact);
-		min-height: var(--control-height-compact);
+		height: var(--btn-size, var(--control-height-compact));
+		min-height: var(--btn-size, var(--control-height-compact));
 		padding: var(--sp-1) var(--sp-3);
 		font-size: var(--fs-xs);
 	}
 	.btn-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--btn-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-5);
 		font-size: var(--fs-base);
 	}
@@ -298,13 +298,13 @@
 		align-items: center;
 		justify-content: center;
 		gap: var(--sp-2);
-		height: var(--control-height);
-		min-height: var(--control-height);
+		height: var(--btn-size, var(--control-height));
+		min-height: var(--btn-size, var(--control-height));
 		padding: 0 var(--sp-3);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		background: var(--surface);
-		color: var(--text);
+		border: 1px solid var(--btn-border, var(--border-strong));
+		border-radius: var(--btn-radius, var(--r-md));
+		background: var(--btn-bg, var(--surface));
+		color: var(--btn-fg, var(--text));
 		font-weight: var(--fw-medium);
 		font-size: var(--fs-sm);
 		line-height: 1;
@@ -326,9 +326,9 @@
 	   the primary action with the neutral --surface; restore the accent fill when
 	   both are present. */
 	.btn-control.btn-primary {
-		background: var(--accent);
-		border-color: var(--accent);
-		color: var(--text-on-accent);
+		background: var(--btn-bg, var(--accent));
+		border-color: var(--btn-border, var(--accent));
+		color: var(--btn-fg, var(--text-on-accent));
 	}
 	.btn-control.btn-primary:hover:not(:disabled) {
 		border-color: var(--accent);
@@ -389,7 +389,7 @@
 		align-self: flex-start;
 	}
 	.btn-pill {
-		border-radius: var(--r-pill);
+		border-radius: var(--btn-radius, var(--r-pill));
 	}
 	/* Link variant: no box, inherits the surrounding text size. Placed after the
 	   size rules so their min-height doesn't reapply; a tone wins over --link. */
@@ -419,23 +419,23 @@
 	}
 	/* `square`: side = the height contract in force (size tier or control). */
 	.btn-square {
-		width: var(--control-height-default);
-		min-width: var(--control-height-default);
+		width: var(--btn-size, var(--control-height-default));
+		min-width: var(--btn-size, var(--control-height-default));
 		padding: 0;
 		flex: none;
 	}
 	.btn-square.btn-sm {
-		width: var(--control-height-compact);
-		min-width: var(--control-height-compact);
+		width: var(--btn-size, var(--control-height-compact));
+		min-width: var(--btn-size, var(--control-height-compact));
 	}
 	.btn-square.btn-lg {
-		width: var(--control-height-large);
-		min-width: var(--control-height-large);
-		height: var(--control-height-large);
+		width: var(--btn-size, var(--control-height-large));
+		min-width: var(--btn-size, var(--control-height-large));
+		height: var(--btn-size, var(--control-height-large));
 	}
 	.btn-square.btn-control {
-		width: var(--control-height);
-		min-width: var(--control-height);
+		width: var(--btn-size, var(--control-height));
+		min-width: var(--btn-size, var(--control-height));
 	}
 	/* `box`: explicit square scale, wins over icon/chip/square/size sizing. */
 	.btn-box {

package/dist/components/atoms/Input.svelte

@@ -130,13 +130,13 @@
 <style>
 	.input {
 		width: 100%;
-		min-height: var(--control-height-default);
+		min-height: var(--input-size, var(--control-height-default));
 		padding: var(--sp-2) var(--sp-3);
 		line-height: var(--lh-tight);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--input-bg, var(--bg));
+		border: 1px solid var(--input-border, var(--border-strong));
+		border-radius: var(--input-radius, var(--r-md));
+		color: var(--input-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 	}
 	.input:focus {
@@ -148,12 +148,12 @@
 		outline-offset: var(--focus-ring-offset);
 	}
 	.input-sm {
-		min-height: var(--control-height-compact);
+		min-height: var(--input-size, var(--control-height-compact));
 		padding: var(--sp-1) var(--sp-2);
 		font-size: var(--fs-sm);
 	}
 	.input-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--input-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
 	}
@@ -166,7 +166,7 @@
 		flex: none;
 	}
 	.input-pill {
-		border-radius: var(--r-pill);
+		border-radius: var(--input-radius, var(--r-pill));
 		padding-inline: var(--sp-4);
 	}
 	.input[aria-invalid='true'] {

package/dist/components/atoms/Select.svelte

@@ -205,13 +205,13 @@
 	}
 	.select {
 		width: 100%;
-		min-height: var(--control-height-default);
+		min-height: var(--select-size, var(--control-height-default));
 		padding: var(--sp-2) var(--sp-3);
 		line-height: var(--lh-tight);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--select-bg, var(--bg));
+		border: 1px solid var(--select-border, var(--border-strong));
+		border-radius: var(--select-radius, var(--r-md));
+		color: var(--select-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 	}
 	/* Default variant: drop the OS chevron, reserve room for our own. */
@@ -226,7 +226,7 @@
 	}
 	/* Compact inline form for dense headers/toolbars. */
 	.select.select-lg {
-		min-height: var(--control-height-large);
+		min-height: var(--select-size, var(--control-height-large));
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
 	}
@@ -240,15 +240,15 @@
 	/* Toolbar contract: size="sm" shares the compact control height so it lines up
 	   with Button size="sm", Popover size="sm" and SegmentedControl size="sm". */
 	.select.select-sm {
-		height: var(--control-height-compact);
+		height: var(--select-size, var(--control-height-compact));
 	}
 	.select.w-auto {
 		width: auto;
 	}
 	.select.embedded {
-		background: var(--bg-elevated-2);
+		background: var(--select-bg, var(--bg-elevated-2));
 		border: none;
-		border-radius: var(--r-sm);
+		border-radius: var(--select-radius, var(--r-sm));
 	}
 	.select:focus {
 		outline: none;
@@ -281,7 +281,7 @@
 		gap: var(--sp-2);
 		padding: 0 var(--sp-3);
 		padding-right: calc(var(--sp-3) + 1.25rem);
-		color: var(--text);
+		color: var(--select-fg, var(--text));
 		pointer-events: none;
 		overflow: hidden;
 	}

package/dist/components/atoms/Text.svelte

@@ -95,29 +95,31 @@
 	/* Base: inherit everything — a bare <Text> renders like a plain span. */
 	.text {
 		margin: 0;
+		color: var(--txt-fg, inherit);
+		font-size: var(--txt-size, inherit);
 	}
 	/* Variants (presets) — listed before tone/weight/size so those override. */
 	.v-body {
-		font-size: var(--fs-base);
+		font-size: var(--txt-size, var(--fs-base));
 		line-height: var(--lh-normal);
-		color: var(--text);
+		color: var(--txt-fg, var(--text));
 	}
 	.v-label {
-		font-size: var(--fs-sm);
+		font-size: var(--txt-size, var(--fs-sm));
 		font-weight: var(--fw-medium);
-		color: var(--text-muted);
+		color: var(--txt-fg, var(--text-muted));
 	}
 	.v-caption {
-		font-size: var(--fs-xs);
-		color: var(--text-faint);
+		font-size: var(--txt-size, var(--fs-xs));
+		color: var(--txt-fg, var(--text-faint));
 	}
 	.v-code {
 		font-family: var(--font-mono);
-		font-size: 0.92em;
+		font-size: var(--txt-size, 0.92em);
 	}
 	.v-eyebrow {
-		font-size: var(--fs-xs);
-		color: var(--text-muted);
+		font-size: var(--txt-size, var(--fs-xs));
+		color: var(--txt-fg, var(--text-muted));
 		font-weight: var(--fw-medium);
 		text-transform: uppercase;
 		letter-spacing: 0.04em;
@@ -127,28 +129,28 @@
 		font-family: var(--font-mono);
 	}
 	.tone-default {
-		color: var(--text);
+		color: var(--txt-fg, var(--text));
 	}
 	.tone-muted {
-		color: var(--text-muted);
+		color: var(--txt-fg, var(--text-muted));
 	}
 	.tone-faint {
-		color: var(--text-faint);
+		color: var(--txt-fg, var(--text-faint));
 	}
 	.tone-success {
-		color: var(--ok);
+		color: var(--txt-fg, var(--ok));
 	}
 	.tone-warn {
-		color: var(--warn);
+		color: var(--txt-fg, var(--warn));
 	}
 	.tone-danger {
-		color: var(--danger);
+		color: var(--txt-fg, var(--danger));
 	}
 	.tone-info {
-		color: var(--info);
+		color: var(--txt-fg, var(--info));
 	}
 	.tone-accent {
-		color: var(--accent);
+		color: var(--txt-fg, var(--accent));
 	}
 	/* Weight — overrides variant weight. */
 	.fw-normal {
@@ -165,46 +167,46 @@
 	}
 	/* Size — overrides variant size (listed last so it wins). */
 	.fs-xs {
-		font-size: var(--fs-xs);
+		font-size: var(--txt-size, var(--fs-xs));
 	}
 	.fs-sm {
-		font-size: var(--fs-sm);
+		font-size: var(--txt-size, var(--fs-sm));
 	}
 	.fs-base {
-		font-size: var(--fs-base);
+		font-size: var(--txt-size, var(--fs-base));
 	}
 	.fs-md {
-		font-size: var(--fs-md);
+		font-size: var(--txt-size, var(--fs-md));
 	}
 	.fs-lg {
-		font-size: var(--fs-lg);
+		font-size: var(--txt-size, var(--fs-lg));
 	}
 	.fs-xl {
-		font-size: var(--fs-xl);
+		font-size: var(--txt-size, var(--fs-xl));
 	}
 	.fs-2xl {
-		font-size: var(--fs-2xl);
+		font-size: var(--txt-size, var(--fs-2xl));
 	}
 	.noscale.fs-xs {
-		font-size: 12px;
+		font-size: var(--txt-size, 12px);
 	}
 	.noscale.fs-sm {
-		font-size: 13px;
+		font-size: var(--txt-size, 13px);
 	}
 	.noscale.fs-base {
-		font-size: 15px;
+		font-size: var(--txt-size, 15px);
 	}
 	.noscale.fs-md {
-		font-size: 16px;
+		font-size: var(--txt-size, 16px);
 	}
 	.noscale.fs-lg {
-		font-size: 18px;
+		font-size: var(--txt-size, 18px);
 	}
 	.noscale.fs-xl {
-		font-size: 22px;
+		font-size: var(--txt-size, 22px);
 	}
 	.noscale.fs-2xl {
-		font-size: 28px;
+		font-size: var(--txt-size, 28px);
 	}
 	.italic {
 		font-style: italic;

package/dist/components/atoms/Textarea.svelte

@@ -223,16 +223,16 @@
 		   --sp-3 top+bottom would overshoot it and a `rows={1}` textarea would
 		   render taller than the buttons it sits beside. */
 		padding: var(--sp-2) var(--sp-3);
-		background: var(--bg);
-		border: 1px solid var(--border-strong);
-		border-radius: var(--r-md);
-		color: var(--text);
+		background: var(--textarea-bg, var(--bg));
+		border: 1px solid var(--textarea-border, var(--border-strong));
+		border-radius: var(--textarea-radius, var(--r-md));
+		color: var(--textarea-fg, var(--text));
 		transition: border-color 0.12s var(--ease);
 		/* Custom handle replaces the native grip; never show the native one. */
 		resize: none;
 		/* Match the single-row height of Button/Input so a `rows={1}` textarea
 		   lines up with them; the native `rows` attribute grows it from here. */
-		min-height: 2.5rem;
+		min-height: var(--textarea-size, 2.5rem);
 		line-height: var(--lh-tight);
 		font-family: inherit;
 	}
@@ -250,12 +250,12 @@
 	.textarea-sm {
 		padding: var(--sp-1) var(--sp-2);
 		font-size: var(--fs-sm);
-		min-height: 2rem;
+		min-height: var(--textarea-size, 2rem);
 	}
 	.textarea-lg {
 		padding: var(--sp-3) var(--sp-4);
 		font-size: var(--fs-base);
-		min-height: var(--control-height-large);
+		min-height: var(--textarea-size, var(--control-height-large));
 	}
 	.textarea[aria-invalid='true'],
 	.textarea[aria-invalid='true']:focus {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",