@flowdrop/flowdrop 2.0.0-beta.2 → 2.0.0-beta.4

package/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0-beta.4] - 2026-06-13
+
+Fourth 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). `latest` remains 1.15.0 until 2.0.0 GA. This release is mostly an internal design-system consolidation pass — new shared `Button` / `IconButton` / `Input` / `Select` / `Textarea` primitives route every control through the `base.css` class system as the single source of truth, so themes (including Drafter) style fields and buttons consistently. User-visible changes are a navbar `end` snippet for embedding custom trailing controls, a new `--fd-control-radius` theming token, a range-slider fill fix, and opaque Drafter buttons. The archived Astro docs site is retired in favor of the Mintlify docs at `flowdrop.mintlify.app`.
+
+### Added
+
+- **`end` snippet on the navbar.** A new `end` snippet prop renders custom trailing content in the navbar (before the settings gear), letting consuming apps inject their own controls — e.g. a theme toggle — without forking the navbar.
+- **`--fd-control-radius` theming token.** Form controls (inputs, selects, textareas, the array action buttons, fieldset/checkbox-group/config-form borders) now read their corner radius from `--fd-control-radius`, so themes can tighten field corners independently of cards and panels. Drafter sets it to `2px` for its crisp blueprint look; other themes inherit the existing radius.
+
+### Fixed
+
+- **Range slider fill now tracks the thumb center.** The colored fill measured 0–100% of the raw track width while the browser keeps the thumb inside the track, so the fill and thumb drifted apart — worst at the extremes and visible on load. The fill now mirrors the thumb's actual travel (`thumb/2` to `100% − thumb/2`) via a new `--fd-range-fill` calc, with the thumb size tokenized.
+- **Drafter buttons are opaque and flat.** Several buttons in the Drafter skin (file-upload node config, canvas toggles) rendered with translucent backgrounds and read as see-through; they are now flat and opaque.
+
+### Changed (internal — no API change)
+
+- **Shared form-control and button primitives.** New typed `Button`, `IconButton`, `Input`, `Select`, and `Textarea` wrappers sit over the existing `.flowdrop-btn*` / `.flowdrop-input*` / `.flowdrop-btn--icon*` classes in `base.css`, making it the single source for control look (`:disabled` is the only muted state). `ThemeToggle`, the config form, sidebar search, the node swap picker, `FormArray` move/delete buttons, `InputCollector`, and the playground inputs were migrated onto them, dropping their hand-rolled, duplicated CSS. The primitives are internal (not exported), so their APIs aren't frozen before GA; public component prop APIs (e.g. `ThemeToggle`) are unchanged.
+- **`EditorStatusBar` extracted onto the shared button system.** The endpoint-error banner — previously inline in `App.svelte` with its own button CSS and a centered `80rem` layout — is now an `EditorStatusBar` component that routes actions through the `Button` primitive, spans the editor chrome flush, and uses a proper `CloseIcon` for dismissal. Added Storybook stories for `Button` and `EditorStatusBar`.
+- **Navbar control heights from one token.** Three hardcoded `height: 2.5rem` rules now use `var(--fd-size-btn-min)`, sharing a single source of truth with `.flowdrop-btn`.
+- **Extracted shared logic flagged by the duplication review.** `connections.ts` gains a shared `detectCycles()` (used by both `hasCycles` / `hasInvalidCycles`); `svelte-app.ts` extracts a `configureInstance()` shared by `mountFlowDropApp` / `mountWorkflowEditor`; and `FormField` / `FormFieldLight` share a `resolveBaseFieldType()` for the basic-type switch (with a unit test pinning resolution order) while keeping the deliberate full/light rendering split for the bundle-guard contract. No behavioral change.
+
+### Docs
+
+- **Retired the archived Astro/Starlight docs site (`apps/docs`)** and its docker-publish workflow; the Mintlify site at `flowdrop.mintlify.app` is canonical. All live documentation links (README, AGENTS, quick-start, i18n guide, API README, dev playground navbar, docker-playground landing, interrupt-feature doc) were repointed there. `apps/api-docs` is kept only to back the `api:lint` / `api:bundle` tooling and CI. Corrected the local dev-server port reference to the recommended Express demo.
+
+## [2.0.0-beta.3] - 2026-06-12
+
+Third 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). `latest` remains 1.15.0 until 2.0.0 GA. This release finishes the navbar/theme defaults pass started in beta.2 (navbar opt-in everywhere, light as the default theme, the FlowDrop wordmark in the header), adds the **Drafter** blueprint theme with per-theme canvas grids, and lands a keyboard-navigation and focus-ring overhaul alongside the 20px node-grid alignment.
+
+### Breaking Changes
+
+- **`mountPlaygroundApp` / `<PlaygroundApp>` no longer render the navbar by default.** `showNavbar` now defaults to `false`, matching `mountFlowDropApp` / `<App>` — so every mount path is navbar-off by default and embedding FlowDrop into a page that already has its own header never double-stacks a header. Pass `showNavbar: true` to opt back into the FlowDrop navbar (logo, branding, settings modal) when FlowDrop owns the whole page.
+
+### Added
+
+- **Drafter blueprint theme.** A third built-in editor theme (`'drafter'`), shipping light + dark variants: a blueprint aesthetic with a soft mint canvas, a subtle emerald line grid, and translucent green-tinted flat nodes. Data-type port colors and category icon colors are left untouched so they keep popping against the muted draft surface. Selectable from the Settings → UI Theme picker; the `FlowDropSkinName` / theme / skin name unions gain `'drafter'`.
+- **Per-theme canvas grid.** A new `FlowDropGridVariant` type (`'dots' | 'lines' | 'cross'`) and `themeConfig.canvas.grid` config let any theme drive the editor's background grid (previously hardcoded to dots). The grid pattern color is the `--fd-grid-pattern-color` token, whose default matches xyflow's dot color, so the default/minimal themes render unchanged. `resolveTheme` now merges `config.canvas` alongside `config.sidebar`.
+- **`features.builtinEditors` opt-out.** The built-in markdown/code/template editors are batteries-included in the full editor by default. Pass `features: { builtinEditors: false }` to `mountFlowDropApp` (or `builtinEditors: false` to `mountWorkflowEditor` / `<WorkflowEditor>`) to skip registering them — keeping the textarea fallback or leaving room to register your own field components via `instance.fields.register(...)`. The corrected fallback hint now points at the registry-scoped API (`registerMarkdownEditorField(instance.fields)`).
+- **FlowDrop wordmark logo in the navbar.** The header now renders the FlowDrop wordmark in place of the plain text title.
+
+### Changed
+
+- **The default theme preference is now `'light'` (was `'dark'`).** `DEFAULT_THEME_SETTINGS.preference` was hardcoded to `'dark'`, so any embed with no persisted theme choice rendered dark. Embeds now default to light; hosts that want dark by default should set the preference explicitly.
+- **Editor / node / chrome surface tokens are scoped per surface,** refining how themes (including Drafter) tint the canvas, nodes, and surrounding chrome independently.
+
+### Fixed
+
+- **Nodes are a single tab stop again.** The node config (gear) button sat in the tab order, so leaving a node required a second `Tab` press. The gear button is removed from the tab order (it stays mouse/Enter-activatable), and node focus defers to xyflow's own node focus — Tab now moves one node per press. `nodesFocusable` redundancy was removed to eliminate the duplicate stop.
+- **The full editor renders markdown/code/config editors out of the box again.** The beta.2 light-entry split made the heavy form editors opt-in everywhere, which inadvertently left `<WorkflowEditor>` / `<App>` / the playground showing the "Editor component not registered" textarea fallback for node config fields with `format: 'markdown' | 'code' | 'template'`. The full editor now registers the built-in editors on its own instance's field registry on mount. Registration uses a dynamic `import()`, so the chunks stay code-split (loaded lazily) and the light `/editor` static bundle is unaffected — the bundle guard still passes. The standalone `@flowdrop/flowdrop/form` primitive is unchanged and remains opt-in.
+- **`<App navbarActions>` accepts the full `NavbarAction` shape.** The component prop was typed with an inline subset that silently dropped `external` and `group`, even though the underlying `<Navbar>` (and the `mountFlowDropApp` option) already supported them. It now uses the canonical `NavbarAction` type, so external-link and grouped actions type-check through the component as they always did through the mount API.
+- **The node header no longer shows a top-accent line.**
+
+### Changed (internal — no API change)
+
+- **One centralized focus ring across the whole component library.** New `--fd-ring-width` / `--fd-ring-offset` tokens and a single `.flowdrop-root :focus-visible` rule in `base.css` replace ~200 lines of component-local focus CSS (mismatched outlines, hardcoded `rgba(59,130,246)` box-shadow glows, `color-mix` rings) removed across 41 files. CodeMirror editors in `overflow:hidden` containers use a `:focus-within` ring (outline paints outside the box and would clip); range-input thumbs ring on the parent.
+- **Extracted shared `NodeConfigButton` and `CanvasIconButton` components,** replacing per-node config-button and per-canvas floating-button duplication (including an inline-SVG cog) with one keyboard-correct implementation each.
+- **Node geometry converted from `rem` to `px` and snapped to a 20px grid** across all eight node types — header, port rows (fixed 60px), icon sizes, paddings, gaps, and font sizes — so nodes stay aligned to the canvas coordinate grid regardless of the host's root font-size.
+- **The code / markdown / template editors now rest on the shared input surface** instead of carrying their own background.
+
 ## [2.0.0-beta.2] - 2026-06-09
 
 Second 2.0 beta, published under the npm `beta` dist-tag (`npm install @flowdrop/flowdrop@beta`). This release tightens the 2.0 package boundaries, finishes `AuthProvider` propagation across the editor and playground runtime surfaces, and adds a regression guard for light-entry bundle size.

package/MIGRATION-2.0.md

@@ -295,6 +295,19 @@ import { getInstance } from '@flowdrop/flowdrop/editor';
 registerCodeEditorField(getInstance().fields);
 ```
 
+**You only need this for the standalone `@flowdrop/flowdrop/form` primitive.**
+The full editor is batteries-included: `<WorkflowEditor>` / `<App>` and the
+playground register the built-in markdown, code, and template editors on their
+own instance's `fields` registry on mount, so node config fields with
+`format: 'markdown' | 'code' | 'template'` render real editors out of the box —
+no host call required. Registration is a dynamic `import()`, so the CodeMirror /
+`marked` chunks stay code-split (the light `/editor` static bundle is
+unaffected) and load lazily on first use. To strip them, pass
+`features: { builtinEditors: false }` to `mountFlowDropApp` (or
+`builtinEditors: false` to `mountWorkflowEditor` / `<WorkflowEditor>`) and either
+accept the textarea fallback or register your own field components via
+`instance.fields.register(...)`.
+
 Category color/icon helpers likewise take a `CategoriesStore` as an explicit
 parameter — the last global-instance fallback in `utils` is gone.
 

package/README.md

@@ -23,10 +23,10 @@
 </p>
 
 <p align="center">
-  <a href="https://docs.flowdrop.io/getting-started/installation">Quickstart</a> •
+  <a href="https://flowdrop.mintlify.app/docs/quickstart">Quickstart</a> •
   <a href="#features">Features</a> •
   <a href="#integration">Integration</a> •
-  <a href="https://docs.flowdrop.io">Docs</a>
+  <a href="https://flowdrop.mintlify.app">Docs</a>
 </p>
 
 <p align="center">
@@ -139,7 +139,7 @@ Every user-facing string flows through a typed `Messages` tree. Pass a callback
 <App messages={() => ({ form: { schema: { save: 'Apply' } } })} />
 ```
 
-Wire the callback to your i18n library (paraglide-js, sveltekit-i18n, etc.) — locale changes propagate automatically. See the [i18n & Custom Messages guide](https://docs.flowdrop.io/guides/i18n) for the full shape and a paraglide-js worked example.
+Wire the callback to your i18n library (paraglide-js, sveltekit-i18n, etc.) — locale changes propagate automatically. See the [i18n & Custom Messages guide](https://flowdrop.mintlify.app/guides/i18n) for the full shape and a paraglide-js worked example.
 
 ## Sub-Module Exports
 
@@ -283,8 +283,8 @@ Runtime configuration means you build once and deploy to staging, production, or
 
 | Resource                                                                                     | Description              |
 | -------------------------------------------------------------------------------------------- | ------------------------ |
-| [QUICK_START.md](https://docs.flowdrop.io/getting-started/installation/)                     | Get running in 5 minutes |
-| [API Documentation](https://api.flowdrop.io/v1/)                                             | REST API specification   |
+| [QUICK_START.md](https://flowdrop.mintlify.app/docs/quickstart)                              | Get running in 5 minutes |
+| [API Documentation](https://flowdrop.mintlify.app/api-reference/introduction)                | REST API specification   |
 | [CHANGELOG.md](https://github.com/flowdrop-io/flowdrop/blob/main/libs/flowdrop/CHANGELOG.md) | Version history          |
 
 ## Development

package/dist/components/App.svelte

@@ -9,7 +9,10 @@
   import MainLayout from './layouts/MainLayout.svelte';
   import WorkflowEditor from './WorkflowEditor.svelte';
   import NodeSidebar from './NodeSidebar.svelte';
-  import Icon from '@iconify/svelte';
+  import CanvasIconButton from './CanvasIconButton.svelte';
+  import EditorStatusBar from './EditorStatusBar.svelte';
+  import MenuIcon from './icons/MenuIcon.svelte';
+  import MenuOpenIcon from './icons/MenuOpenIcon.svelte';
   import ConfigForm from './ConfigForm.svelte';
   import ConfigPanel from './ConfigPanel.svelte';
   import CommandConsole from './console/CommandConsole.svelte';
@@ -18,6 +21,7 @@
   import NodeSwapPicker from './NodeSwapPicker.svelte';
   import SwapMappingEditor from './SwapMappingEditor.svelte';
   import Navbar from './Navbar.svelte';
+  import type { NavbarAction } from '../types/navbar.js';
   import type { NodeMetadata, Workflow, WorkflowNode, ConfigSchema } from '../types/index.js';
   import type { InteractiveSwapState, SwapEventContext } from '../utils/nodeSwap.js';
   import {
@@ -98,13 +102,7 @@
     /** Custom navbar title */
     navbarTitle?: string;
     /** Custom navbar actions */
-    navbarActions?: Array<{
-      label: string;
-      href: string;
-      icon?: string;
-      variant?: 'primary' | 'secondary' | 'outline';
-      onclick?: (event: Event) => void;
-    }>;
+    navbarActions?: NavbarAction[];
     /** Show settings gear icon in navbar */
     showSettings?: boolean;
     /** Show the "Connected" status indicator in the navbar (default: true) */
@@ -1215,53 +1213,21 @@
     {/snippet}
 
     <!-- Main Content: Workflow Editor with Error Status -->
-    <!-- Status Display: aria-live announces API errors dynamically without requiring focus -->
     {#if error}
-      <div class="flowdrop-status flowdrop-status--error" aria-live="polite" aria-atomic="true">
-        <div class="flowdrop-status__content">
-          <div class="flowdrop-flex flowdrop-gap--3">
-            <div class="flowdrop-status__indicator flowdrop-status__indicator--error"></div>
-            <span class="flowdrop-text--sm flowdrop-font--medium">Error: {error}</span>
-          </div>
-          <div class="flowdrop-flex flowdrop-gap--2">
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--primary"
-              onclick={retryLoad}
-              type="button"
-            >
-              Retry
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--outline"
-              onclick={() => {
-                const defaultUrl = '/api/flowdrop';
-                const newUrl = prompt('Enter Backend API URL:', defaultUrl);
-                if (newUrl) {
-                  configureApi(createEndpointConfig(newUrl));
-                  fetchNodeTypes();
-                }
-              }}
-              type="button"
-            >
-              Set API URL
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--sm flowdrop-btn--outline"
-              onclick={testApiConnection}
-              type="button"
-            >
-              Test API
-            </button>
-            <button
-              class="flowdrop-btn flowdrop-btn--ghost flowdrop-btn--sm"
-              onclick={() => (error = null)}
-              type="button"
-            >
-              ✕
-            </button>
-          </div>
-        </div>
-      </div>
+      <EditorStatusBar
+        {error}
+        onRetry={retryLoad}
+        onSetApiUrl={() => {
+          const defaultUrl = '/api/flowdrop';
+          const newUrl = prompt('Enter Backend API URL:', defaultUrl);
+          if (newUrl) {
+            configureApi(createEndpointConfig(newUrl));
+            fetchNodeTypes();
+          }
+        }}
+        onTestApi={testApiConnection}
+        onDismiss={() => (error = null)}
+      />
     {/if}
 
     <!-- Main Editor Area -->
@@ -1278,18 +1244,22 @@
     >
       <!-- Floating sidebar toggle — always visible on the canvas top-left -->
       {#if !disableSidebar}
-        <button
+        <CanvasIconButton
           class="flowdrop-sidebar-fab"
-          onclick={toggleSidebar}
-          aria-label={isSidebarCollapsed
-            ? mergedMessages.layout.expandSidebar
-            : mergedMessages.layout.collapseSidebar}
-          title={isSidebarCollapsed
+          label={isSidebarCollapsed
             ? mergedMessages.layout.expandSidebar
             : mergedMessages.layout.collapseSidebar}
+          active={!isSidebarCollapsed}
+          onclick={toggleSidebar}
         >
-          <Icon icon={isSidebarCollapsed ? 'mdi:menu' : 'mdi:menu-open'} />
-        </button>
+          {#snippet icon()}
+            {#if isSidebarCollapsed}
+              <MenuIcon />
+            {:else}
+              <MenuOpenIcon />
+            {/if}
+          {/snippet}
+        </CanvasIconButton>
       {/if}
 
       <WorkflowEditor
@@ -1300,6 +1270,8 @@
         {mode}
         {pipelineId}
         {refreshTrigger}
+        builtinEditors={features.builtinEditors}
+        gridVariant={themeConfig?.canvas?.grid ?? 'dots'}
         consoleOpen={getUiSettings().consoleOpen}
         onToggleConsole={toggleConsole}
       />
@@ -1311,139 +1283,12 @@
   .flowdrop-root {
     display: contents;
   }
-  /* Status bar styles */
-  .flowdrop-status {
-    background-color: var(--fd-info-muted);
-    border-bottom: 1px solid var(--fd-info);
-    padding: 1rem;
-  }
-
-  .flowdrop-status--error {
-    background-color: var(--fd-error-muted);
-    border-bottom: 1px solid var(--fd-error);
-  }
-
-  .flowdrop-status__content {
-    max-width: 80rem;
-    margin: 0 auto;
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-  }
-
-  .flowdrop-status__indicator {
-    width: 0.5rem;
-    height: 0.5rem;
-    border-radius: 50%;
-  }
-
-  .flowdrop-status__indicator--error {
-    background-color: var(--fd-error);
-  }
-
-  /* Button styles */
-  .flowdrop-btn {
-    padding: 0.375rem 0.75rem;
-    border-radius: var(--fd-radius-md);
-    font-size: 0.75rem;
-    font-weight: 500;
-    cursor: pointer;
-    border: 1px solid transparent;
-    transition: all var(--fd-transition-fast);
-  }
-
-  .flowdrop-btn--sm {
-    padding: 0.25rem 0.5rem;
-    font-size: 0.625rem;
-  }
-
-  .flowdrop-btn--outline {
-    background-color: transparent;
-    border-color: var(--fd-border);
-    color: var(--fd-foreground);
-  }
 
-  .flowdrop-btn--outline:hover {
-    background-color: var(--fd-muted);
-    border-color: var(--fd-border-strong);
-  }
-
-  .flowdrop-btn--primary {
-    background-color: var(--fd-primary);
-    border-color: var(--fd-primary);
-    color: var(--fd-primary-foreground);
-  }
-
-  .flowdrop-btn--primary:hover {
-    background-color: var(--fd-primary-hover);
-    border-color: var(--fd-primary-hover);
-  }
-
-  .flowdrop-btn--ghost {
-    background-color: transparent;
-    border-color: transparent;
-    color: var(--fd-muted-foreground);
-  }
-
-  .flowdrop-btn--ghost:hover {
-    background-color: var(--fd-muted);
-    color: var(--fd-foreground);
-  }
-
-  /* Utility classes */
-  .flowdrop-flex {
-    display: flex;
-  }
-
-  .flowdrop-gap--2 {
-    gap: 0.5rem;
-  }
-
-  .flowdrop-gap--3 {
-    gap: 0.75rem;
-  }
-
-  .flowdrop-text--sm {
-    font-size: 0.875rem;
-    line-height: 1.25rem;
-  }
-
-  .flowdrop-font--medium {
-    font-weight: 500;
-  }
-
-  /* Floating sidebar toggle button */
-  .flowdrop-sidebar-fab {
-    position: absolute;
+  /* Floating sidebar toggle button — placement only; visuals live in CanvasIconButton */
+  :global(.flowdrop-sidebar-fab) {
     top: 12px;
     left: 12px;
     z-index: 50;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 2.25rem;
-    height: 2.25rem;
-    border: 1px solid var(--fd-border);
-    border-radius: var(--fd-radius-md);
-    background-color: var(--fd-background);
-    color: var(--fd-muted-foreground);
-    cursor: pointer;
-    box-shadow: var(--fd-shadow-md);
-    transition:
-      color var(--fd-transition-fast),
-      background-color var(--fd-transition-fast),
-      box-shadow var(--fd-transition-fast);
-  }
-
-  .flowdrop-sidebar-fab:hover {
-    color: var(--fd-foreground);
-    background-color: var(--fd-subtle);
-    box-shadow: var(--fd-shadow-lg);
-  }
-
-  .flowdrop-sidebar-fab:focus {
-    outline: none;
-    box-shadow: 0 0 0 2px var(--fd-ring);
   }
 
   /* Main editor area */

package/dist/components/App.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { NavbarAction } from '../types/navbar.js';
 import type { NodeMetadata, Workflow, ConfigSchema } from '../types/index.js';
 import type { SwapStrategy } from '../utils/nodeSwap.js';
 import type { EndpointConfig } from '../config/endpoints.js';
@@ -53,13 +54,7 @@ interface Props {
     /** Custom navbar title */
     navbarTitle?: string;
     /** Custom navbar actions */
-    navbarActions?: Array<{
-        label: string;
-        href: string;
-        icon?: string;
-        variant?: 'primary' | 'secondary' | 'outline';
-        onclick?: (event: Event) => void;
-    }>;
+    navbarActions?: NavbarAction[];
     /** Show settings gear icon in navbar */
     showSettings?: boolean;
     /** Show the "Connected" status indicator in the navbar (default: true) */

package/dist/components/Button.stories.svelte

@@ -0,0 +1,65 @@
+<script module lang="ts">
+  import type { ComponentProps } from 'svelte';
+  import { defineMeta } from '@storybook/addon-svelte-csf';
+  import Button from './Button.svelte';
+  import { fn } from 'storybook/test';
+
+  const { Story } = defineMeta({
+    title: 'Display/Button',
+    component: Button,
+    tags: ['autodocs'],
+    parameters: {
+      layout: 'centered'
+    },
+    argTypes: {
+      variant: {
+        control: { type: 'select' },
+        options: ['primary', 'secondary', 'outline', 'ghost']
+      },
+      size: {
+        control: { type: 'select' },
+        options: ['sm', 'md', 'lg']
+      },
+      disabled: { control: 'boolean' }
+    },
+    args: {
+      variant: 'secondary',
+      size: 'md',
+      disabled: false,
+      onclick: fn()
+    }
+  });
+</script>
+
+<!-- Arg-driven template so the Controls panel can tweak variant/size/disabled live. -->
+{#snippet template(args: Omit<ComponentProps<typeof Button>, 'children'>)}
+  <Button {...args}>Button</Button>
+{/snippet}
+
+<Story name="Primary" args={{ variant: 'primary' }} {template} />
+
+<Story name="Secondary" args={{ variant: 'secondary' }} {template} />
+
+<Story name="Outline" args={{ variant: 'outline' }} {template} />
+
+<Story name="Ghost" args={{ variant: 'ghost' }} {template} />
+
+<Story name="Disabled" args={{ variant: 'primary', disabled: true }} {template} />
+
+<!-- Static showcases comparing every variant / size side by side. -->
+<Story name="Variants" asChild>
+  <div style="display: flex; gap: 0.75rem; align-items: center;">
+    <Button variant="primary">Primary</Button>
+    <Button variant="secondary">Secondary</Button>
+    <Button variant="outline">Outline</Button>
+    <Button variant="ghost">Ghost</Button>
+  </div>
+</Story>
+
+<Story name="Sizes" asChild>
+  <div style="display: flex; gap: 0.75rem; align-items: center;">
+    <Button variant="primary" size="sm">Small</Button>
+    <Button variant="primary" size="md">Medium</Button>
+    <Button variant="primary" size="lg">Large</Button>
+  </div>
+</Story>

package/dist/components/Button.stories.svelte.d.ts

@@ -0,0 +1,19 @@
+import Button from './Button.svelte';
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const Button: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type Button = InstanceType<typeof Button>;
+export default Button;

package/dist/components/Button.svelte

@@ -0,0 +1,62 @@
+<!--
+  Button — typed wrapper over the shared `.flowdrop-btn` system (base.css).
+
+  All button styling (variants, sizes, the --fd-size-btn-min height token and the
+  centralized focus ring) lives in base.css. This component is the ergonomic,
+  type-safe entry point so callers pick `variant`/`size` instead of hand-writing
+  class strings — the single place new buttons should route through.
+
+  Internal for now (not exported from any public entry) so the API isn't frozen
+  before GA. Existing hand-rolled buttons migrate onto it incrementally.
+-->
+
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    /** Visual style — maps to `.flowdrop-btn--{variant}` in base.css */
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+    /** Size — `md` is the base `.flowdrop-btn`; `sm`/`lg` add a modifier */
+    size?: 'sm' | 'md' | 'lg';
+    /** Native button type */
+    type?: 'button' | 'submit' | 'reset';
+    /** Tooltip text */
+    title?: string;
+    /** Accessible label (use when the button is icon-only) */
+    ariaLabel?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Extra classes appended to the root button */
+    class?: string;
+    /** Click handler */
+    onclick?: (event: MouseEvent) => void;
+    /** Button contents (icon, label, or both) */
+    children: Snippet;
+  }
+
+  let {
+    variant = 'secondary',
+    size = 'md',
+    type = 'button',
+    title,
+    ariaLabel,
+    disabled = false,
+    class: className = '',
+    onclick,
+    children
+  }: Props = $props();
+
+  // 'md' is the unmodified base class; only 'sm'/'lg' need a size modifier.
+  const sizeClass = $derived(size === 'md' ? '' : `flowdrop-btn--${size}`);
+</script>
+
+<button
+  class="flowdrop-btn flowdrop-btn--{variant} {sizeClass} {className}"
+  {type}
+  {title}
+  {disabled}
+  aria-label={ariaLabel}
+  {onclick}
+>
+  {@render children()}
+</button>

package/dist/components/Button.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** Visual style — maps to `.flowdrop-btn--{variant}` in base.css */
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+    /** Size — `md` is the base `.flowdrop-btn`; `sm`/`lg` add a modifier */
+    size?: 'sm' | 'md' | 'lg';
+    /** Native button type */
+    type?: 'button' | 'submit' | 'reset';
+    /** Tooltip text */
+    title?: string;
+    /** Accessible label (use when the button is icon-only) */
+    ariaLabel?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Extra classes appended to the root button */
+    class?: string;
+    /** Click handler */
+    onclick?: (event: MouseEvent) => void;
+    /** Button contents (icon, label, or both) */
+    children: Snippet;
+}
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;