Button

Example

<button type="button" data-slean="button">Save</button>
<button type="button" data-slean="button" data-variant="outline">Cancel</button>
<button type="button" data-slean="button" data-variant="soft">Duplicate</button>
<button type="button" data-slean="button" data-variant="ghost">Rename</button>
<button type="button" data-slean="button" data-variant="danger">Delete</button>
<a href="/docs" data-slean="button" data-variant="link">Documentation</a>

<script lang="ts">
	// Nothing to import: the browser owns the button. The stylesheet is optional.
	import '@svelte-lean/styles/button.css';
</script>

<button type="button" data-slean="button">Save</button>
<button type="button" data-slean="button" data-variant="outline">Cancel</button>
<button type="button" data-slean="button" data-variant="soft">Duplicate</button>
<button type="button" data-slean="button" data-variant="ghost">Rename</button>
<button type="button" data-slean="button" data-variant="danger">Delete</button>
<a href="/docs" data-slean="button" data-variant="link">Documentation</a>

Sizes and states

<button type="button" data-slean="button" data-size="sm">Small</button>
<button type="button" data-slean="button" data-size="lg">Large</button>
<button type="button" data-slean="button" disabled>Disabled</button>
<button type="button" data-slean="button" aria-disabled="true">Unavailable</button>
<button type="button" data-slean="button" aria-busy="true">Saving</button>
<button
	type="button"
	data-slean="button"
	data-variant="outline"
	data-icon-only
	aria-label="Close"
>
	<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
</button>

<script lang="ts">
	import '@svelte-lean/styles/button.css';
</script>

<button type="button" data-slean="button" data-size="sm">Small</button>
<button type="button" data-slean="button" data-size="lg">Large</button>
<button type="button" data-slean="button" disabled>Disabled</button>
<button type="button" data-slean="button" aria-disabled="true">Unavailable</button>
<button type="button" data-slean="button" aria-busy="true">Saving</button>
<button
	type="button"
	data-slean="button"
	data-variant="outline"
	data-icon-only
	aria-label="Close"
>
	<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
</button>

Why this implementation exists

The platform's button is complete: it is focusable, Enter and Space activate it, it takes part in forms, and it exposes :disabled, :active and :focus-visible. A <div role="button"> would have to re-create every one of those in JavaScript and would still miss form participation. Svelte Lean therefore adds nothing to the behavior; what it adds is a stylesheet with variants and states, a contract that says when to use disabled and when aria-disabled, and the rule that navigation is a link.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet and @svelte-lean/primitives when you want the typed contract; neither adds runtime JavaScript for a button.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '@svelte-lean/styles/button.css';

Use a button for an action on the current page: submit, open, toggle, delete. Use an <a href> for navigation and give it data-slean="button" when it should look like one. Inside a <form> the default type is submit; write type="button" for anything that does not submit.

Anatomy

Runtime profile

The runtime block reads the tier and the events from the contract and the bytes from the native-only consumer fixture: a production Vite build of a page with button, dialog and popover markup and the Vite plugin, whose module graph contains no @svelte-lean/core or @svelte-lean/primitives module. The primitives size script asserts the same for a bundle that imports the root entry and a Tier 0 contract. Nothing is attached at hydration: there is no listener, no state object and no observer for a button. The listeners the proof page counts belong to the Tier 1 and Tier 2 behaviors (tabs, menu, listbox, combobox).

Accessibility contract

• A <button> element, never <div role="button"> and never an <a> without href.
• Icon-only buttons carry aria-label. Buttons that toggle something not driven by popovertarget or commandfor carry aria-expanded and aria-controls; those two attributes establish the relationship natively.
• disabled: not focusable, receives no events, excluded from form submission. aria-disabled="true": focusable and announced as disabled; the application must ignore the activation. Use it only when the control must stay reachable by keyboard.
• A busy button (aria-busy="true") stays focusable so focus is not lost while an action runs.
• Focus rules, text direction and the focus ring are native; the styles use logical properties.

Keyboard

Platform features

Without JavaScript

Fully functional for form submission and reset. Only application click handlers are missing, which is true of any button on any page. The playground's native page is exercised with page JavaScript disabled.

Server rendering

Plain HTML. The server renders the button, its type, its disabled state and its label; nothing is generated on the client and no id is required.

Before hydration

The button is interactive as soon as the document is parsed. The delayed-hydration test holds every script for several seconds and asserts that the native page's dialog invoker, a button, opens the dialog before any script has loaded.

Styling

button.css styles [data-slean="button"] with variants and sizes chosen through data-variant and data-size, all inside the slean.components layer and wrapped in :where(), so any unlayered rule of yours wins. The tokens it reads and the states it targets:

State selectors the stylesheet targets, all from the platform or ARIA: :active, :disabled, :hover, [aria-busy="true"], [aria-disabled="true"].

Variant attributes: data-variant (outline, secondary, soft, ghost, danger, link); data-size (sm, lg); data-icon-only.

Controlled integration

There is nothing to control: a button has no state beyond what the platform holds. The application attaches its own click handler and, while an action runs, sets aria-busy rather than disabled so focus stays put. No adapter, store or event of the package is involved.

<script lang="ts">
	let busy = $state(false);

	async function save() {
		busy = true;
		try {
			await fetch('/api/save', { method: 'POST' });
		} finally {
			busy = false;
		}
	}
</script>

<!-- aria-busy keeps the button focusable while the request runs; disabled would drop focus. -->
<button type="button" data-slean="button" aria-busy={busy || undefined} onclick={save}>
	Save
</button>

Compatibility notes

<button> and :focus-visible are Baseline widely available; the button itself has no fallback case. Invoker commands (command, commandfor) are a property of the dialog and popover it opens and are documented on those pages and on Browser support. Where the stylesheet uses color-mix() for hover states, browsers without it keep the base color.

Testing

• apps/playground/tests/primitives/native.spec.ts Playwright, with page JavaScript enabled and disabled
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)
• fixtures/native-only consumer build asserting that no behavior runtime ships (invariant A)
• packages/primitives/scripts/size.mjs the native-only build that must contain no runtime

Source

• packages/primitives/src/button/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/button/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/button.css the optional stylesheet