@fudge-me/design-system 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# fudge-design-system
+
+Visual language and UI primitives for the fudge ecosystem. Product-agnostic — no application logic, no backend assumptions, no domain semantics.
+
+**Status:** v0.1.0-rc.1 — foundation complete.
+
+## Consumers
+
+- **fudge-client** (Tauri v2 + Svelte 5, desktop)
+- Future web clients
+- Future mobile clients
+
+## Stack
+
+Svelte 5 component library. Product repos depend on this; never the reverse.
+
+## Shell Model
+
+The target UI is canvas-first:
+
+| Slot | Position |
+|---|---|
+| Command bar | Top |
+| Sidebar | Left |
+| Canvas | Center |
+| AI panel | Right |
+| Status bar | Bottom |
+
+Layout primitives in this repo map directly to these slots.
+
+## What It Provides
+
+- **Tokens** — three-tier system (raw → semantic → component), exported as `--fds-*` CSS custom properties. Covers color, spacing, typography, radii, shadows
+- **Layout primitives** — AppShell, CommandBar, Sidebar, Canvas, AIPanel, StatusBar, Panel
+- **Core components** — Button, Input, Tooltip, Modal, Command Palette
+- **Themes** — light/dark switching via ThemeProvider
+
+See [ROADMAP.md](ROADMAP.md) for future plans (icons, motion, custom themes, platform variants).
+
+## What It Excludes
+
+- Product logic
+- API calls or backend assumptions
+- Workspace, comms, or any domain semantics
+
+## Local Development
+
+Run `pnpm run package:watch` in this repo while developing with fudge-client. See [`docs/ai/local-dev-fast-path.md`](docs/ai/local-dev-fast-path.md) for the full workflow and failure modes.
+
+## Consumer Import Pattern
+
+Root layout in fudge-client:
+
+```svelte
+<!-- 1. Tokens — import once at app root, establishes all --fds-* custom properties -->
+<script>
+  import '@fudge-me/design-system/tokens';
+
+  // 2. Theme CSS — both files needed so switching works
+  import '@fudge-me/design-system/themes/light.css';
+  import '@fudge-me/design-system/themes/dark.css';
+
+  // 3. Components — ThemeProvider, layout, UI primitives
+  import { ThemeProvider } from '@fudge-me/design-system/themes';
+  import { AppShell, Sidebar, Canvas, AIPanel, CommandBar, StatusBar } from '@fudge-me/design-system/layout';
+  import { Button } from '@fudge-me/design-system/components';
+</script>
+
+<!-- 4. ThemeProvider sets data-theme on root; consumer handles persistence -->
+<ThemeProvider theme="system">
+  <AppShell>
+    {#snippet commandbar()}<CommandBar>...</CommandBar>{/snippet}
+    {#snippet sidebar()}<Sidebar>...</Sidebar>{/snippet}
+    {#snippet canvas()}<Canvas>...</Canvas>{/snippet}
+    {#snippet aipanel()}<AIPanel>...</AIPanel>{/snippet}
+    {#snippet statusbar()}<StatusBar>...</StatusBar>{/snippet}
+  </AppShell>
+</ThemeProvider>
+```
+
+### Per-layer examples
+
+**Token cherry-pick** (individual CSS file):
+
+```svelte
+<script>
+  import '@fudge-me/design-system/tokens/color.css';
+</script>
+```
+
+**Component import**:
+
+```svelte
+<script>
+  import { Button } from '@fudge-me/design-system/components';
+  import { Modal } from '@fudge-me/design-system/components';
+</script>
+
+<Button variant="primary" size="md" onclick={save}>Save</Button>
+<Modal open={showDialog} onclose={() => showDialog = false}>
+  <p>Content here</p>
+</Modal>
+```
+
+**Theme usage**:
+
+```svelte
+<script>
+  import { ThemeProvider } from '@fudge-me/design-system/themes';
+</script>
+
+<!-- "system" follows prefers-color-scheme; "light"/"dark" force a theme -->
+<ThemeProvider theme="system">
+  <slot />
+</ThemeProvider>
+```
+
+## Consumer Responsibilities
+
+1. Import tokens once at the app root
+2. Import both theme CSS files so switching works
+3. Wrap app in `ThemeProvider` — consumer handles persistence
+4. Do not override component tokens with raw tokens
+5. Use subpath exports only — do not import internal DS paths
+6. Use layered entrypoints when CSS is needed (root re-export excludes tokens)
+7. Component token overrides use direct child combinators (`>`) to prevent leaking
+
+## Docs
+
+| File | Purpose |
+|---|---|
+| `docs/ai/contracts.md` | Repo boundaries and responsibilities |
+| `docs/ai/prd.json` | Task definitions |
+| `docs/ai/decisions.md` | Architectural decisions |
+| `ARCHITECTURE.md` | Technical architecture and design decisions |
+| `ROADMAP.md` | Versioned delivery plan |
+| `docs/ai/css-variable-scoping.md` | CSS selector-tier scoping rules and per-zone token table |
+| `docs/ai/component-theming-boundaries.md` | Component theming contract with allowed/forbidden patterns |
+| `docs/ai/local-dev-fast-path.md` | Dev workflow: package:watch, Vite config, failure modes |
+| [Ecosystem contract](../docs/ecosystem/contracts/fudge-design-system.md) | Cross-repo consumption contract and public API surface |

package/dist/components/Button.svelte

@@ -0,0 +1,118 @@
+<script lang="ts" module>
+  export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+  export type ButtonSize = 'sm' | 'md' | 'lg';
+</script>
+
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { HTMLButtonAttributes } from 'svelte/elements';
+
+  interface Props extends HTMLButtonAttributes {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    children?: Snippet;
+  }
+
+  let {
+    variant = 'primary',
+    size = 'md',
+    type = 'button',
+    disabled = false,
+    children,
+    ...rest
+  }: Props = $props();
+</script>
+
+<button
+  class="fds-button fds-button--{variant} fds-button--{size}"
+  {type}
+  {disabled}
+  {...rest}
+>
+  {#if children}{@render children()}{/if}
+</button>
+
+<style>
+  .fds-button {
+    font-family: var(--fds-button-font-family);
+    font-size: var(--fds-button-font-size);
+    font-weight: var(--fds-button-font-weight);
+    line-height: 1;
+    padding: var(--fds-button-padding-y) var(--fds-button-padding-x);
+    background: var(--fds-button-bg);
+    color: var(--fds-button-text);
+    border: 1px solid var(--fds-button-border-color);
+    border-radius: var(--fds-button-radius);
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    transition: background 0.15s ease, border-color 0.15s ease, opacity 0.15s ease;
+  }
+
+  .fds-button:hover:not(:disabled) {
+    background: var(--fds-button-bg-hover);
+  }
+
+  .fds-button:active:not(:disabled) {
+    background: var(--fds-button-bg-active);
+  }
+
+  .fds-button:focus-visible {
+    outline: 2px solid var(--fds-button-border-color-focus);
+    outline-offset: 2px;
+  }
+
+  .fds-button:disabled {
+    background: var(--fds-button-bg-disabled);
+    color: var(--fds-button-text-disabled);
+    border-color: var(--fds-button-bg-disabled);
+    cursor: not-allowed;
+  }
+
+  /* Variant: secondary */
+  .fds-button--secondary {
+    --fds-button-bg: var(--fds-color-surface);
+    --fds-button-text: var(--fds-color-text);
+    --fds-button-border-color: var(--fds-color-border);
+    --fds-button-bg-hover: var(--fds-color-interactive-hover);
+    --fds-button-bg-active: var(--fds-color-interactive-active);
+  }
+
+  /* Variant: ghost */
+  .fds-button--ghost {
+    --fds-button-bg: transparent;
+    --fds-button-border-color: transparent;
+    --fds-button-text: var(--fds-color-text);
+    --fds-button-bg-hover: var(--fds-color-interactive-hover);
+    --fds-button-bg-active: var(--fds-color-interactive-active);
+  }
+
+  /* Variant: destructive */
+  .fds-button--destructive {
+    --fds-button-bg: var(--fds-color-error);
+    --fds-button-border-color: var(--fds-color-error);
+    --fds-button-text: var(--fds-color-text-on-primary);
+  }
+
+  .fds-button--destructive:hover:not(:disabled) {
+    opacity: 0.9;
+  }
+
+  .fds-button--destructive:active:not(:disabled) {
+    opacity: 0.8;
+  }
+
+  /* Size: sm */
+  .fds-button--sm {
+    --fds-button-padding-x: var(--fds-spacing-element);
+    --fds-button-padding-y: var(--fds-spacing-element-xs);
+    --fds-button-font-size: var(--fds-font-label-size);
+  }
+
+  /* Size: lg */
+  .fds-button--lg {
+    --fds-button-padding-x: var(--fds-spacing-section);
+    --fds-button-padding-y: var(--fds-spacing-element);
+  }
+</style>

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

@@ -0,0 +1,12 @@
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+interface Props extends HTMLButtonAttributes {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    children?: Snippet;
+}
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/components/CommandPalette.svelte

@@ -0,0 +1,167 @@
+<script lang="ts" module>
+  export interface CommandPaletteItem {
+    id: string;
+    label: string;
+    description?: string;
+  }
+</script>
+
+<script lang="ts">
+  import Input from './Input.svelte';
+
+  interface Props {
+    items: CommandPaletteItem[];
+    placeholder?: string;
+    onselect?: (item: CommandPaletteItem) => void;
+    onclose?: () => void;
+    filter?: (item: CommandPaletteItem, query: string) => boolean;
+    emptyMessage?: string;
+  }
+
+  let {
+    items,
+    placeholder = 'Search...',
+    onselect,
+    onclose,
+    filter,
+    emptyMessage = 'No results',
+  }: Props = $props();
+
+  const instanceId = `fds-cp-${Math.random().toString(36).slice(2, 9)}`;
+  const listboxId = `${instanceId}-listbox`;
+
+  let query = $state('');
+  let activeIndex = $state(0);
+
+  function defaultFilter(item: CommandPaletteItem, q: string): boolean {
+    return item.label.toLowerCase().includes(q.toLowerCase());
+  }
+
+  let filteredItems = $derived(
+    query ? items.filter((item) => (filter ?? defaultFilter)(item, query)) : items
+  );
+
+  $effect(() => {
+    // Reset active index when filtered items change
+    filteredItems;
+    activeIndex = 0;
+  });
+
+  $effect(() => {
+    const el = document.getElementById(`${instanceId}-item-${activeIndex}`);
+    el?.scrollIntoView({ block: 'nearest' });
+  });
+
+  function handleKeydown(e: KeyboardEvent) {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        if (filteredItems.length > 0) {
+          activeIndex = (activeIndex + 1) % filteredItems.length;
+        }
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        if (filteredItems.length > 0) {
+          activeIndex = (activeIndex - 1 + filteredItems.length) % filteredItems.length;
+        }
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (filteredItems.length > 0 && activeIndex < filteredItems.length) {
+          onselect?.(filteredItems[activeIndex]);
+        }
+        break;
+      case 'Escape':
+        e.preventDefault();
+        onclose?.();
+        break;
+    }
+  }
+</script>
+
+<div class="fds-command-palette">
+  <div class="fds-command-palette__input">
+    <Input
+      type="search"
+      {placeholder}
+      bind:value={query}
+      role="combobox"
+      aria-expanded={true}
+      aria-controls={listboxId}
+      aria-activedescendant={activeIndex >= 0 && filteredItems.length > 0
+        ? `${instanceId}-item-${activeIndex}`
+        : undefined}
+      aria-autocomplete="list"
+      onkeydown={handleKeydown}
+    />
+  </div>
+  <ul class="fds-command-palette__list" role="listbox" id={listboxId}>
+    {#each filteredItems as item, i}
+      <!-- svelte-ignore a11y_click_events_have_key_events -->
+      <li
+        role="option"
+        id="{instanceId}-item-{i}"
+        aria-selected={i === activeIndex}
+        class="fds-command-palette__item"
+        class:fds-command-palette__item--active={i === activeIndex}
+        onclick={() => onselect?.(item)}
+      >
+        <span class="fds-command-palette__item-label">{item.label}</span>
+        {#if item.description}
+          <span class="fds-command-palette__item-description">{item.description}</span>
+        {/if}
+      </li>
+    {/each}
+    {#if filteredItems.length === 0}
+      <li class="fds-command-palette__empty">{emptyMessage}</li>
+    {/if}
+  </ul>
+</div>
+
+<style>
+  .fds-command-palette {
+    background: var(--fds-command-palette-bg);
+    border: 1px solid var(--fds-command-palette-border-color);
+    border-radius: var(--fds-command-palette-radius);
+    box-shadow: var(--fds-command-palette-shadow);
+    padding: var(--fds-command-palette-padding);
+    display: flex;
+    flex-direction: column;
+  }
+
+  .fds-command-palette__input {
+    padding-bottom: var(--fds-command-palette-padding);
+  }
+
+  .fds-command-palette__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    max-height: 16rem;
+    overflow-y: auto;
+  }
+
+  .fds-command-palette__item {
+    display: flex;
+    flex-direction: column;
+    padding: var(--fds-command-palette-item-padding-y) var(--fds-command-palette-item-padding-x);
+    border-radius: var(--fds-command-palette-item-radius);
+    color: var(--fds-command-palette-item-text);
+    cursor: pointer;
+  }
+
+  .fds-command-palette__item--active {
+    background: var(--fds-command-palette-item-bg-active);
+  }
+
+  .fds-command-palette__item-description {
+    font-size: var(--fds-command-palette-item-font-size-secondary);
+    color: var(--fds-command-palette-item-text-secondary);
+  }
+
+  .fds-command-palette__empty {
+    padding: var(--fds-command-palette-item-padding-y) var(--fds-command-palette-item-padding-x);
+    color: var(--fds-command-palette-empty-text);
+  }
+</style>

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

@@ -0,0 +1,16 @@
+export interface CommandPaletteItem {
+    id: string;
+    label: string;
+    description?: string;
+}
+interface Props {
+    items: CommandPaletteItem[];
+    placeholder?: string;
+    onselect?: (item: CommandPaletteItem) => void;
+    onclose?: () => void;
+    filter?: (item: CommandPaletteItem, query: string) => boolean;
+    emptyMessage?: string;
+}
+declare const CommandPalette: import("svelte").Component<Props, {}, "">;
+type CommandPalette = ReturnType<typeof CommandPalette>;
+export default CommandPalette;

package/dist/components/Input.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  import type { HTMLInputAttributes } from 'svelte/elements';
+
+  interface Props extends HTMLInputAttributes {
+    type?: 'text' | 'search';
+    error?: boolean;
+    value?: string;
+  }
+
+  let {
+    type = 'text',
+    error = false,
+    disabled = false,
+    value = $bindable(''),
+    ...rest
+  }: Props = $props();
+</script>
+
+<input
+  class="fds-input"
+  class:fds-input--error={error}
+  {type}
+  {disabled}
+  bind:value
+  {...rest}
+/>
+
+<style>
+  .fds-input {
+    width: 100%;
+    font-family: var(--fds-input-font-family);
+    font-size: var(--fds-input-font-size);
+    padding: var(--fds-input-padding-y) var(--fds-input-padding-x);
+    background: var(--fds-input-bg);
+    color: var(--fds-input-text);
+    border: 1px solid var(--fds-input-border-color);
+    border-radius: var(--fds-input-radius);
+    outline: none;
+    transition: border-color 0.15s ease;
+  }
+
+  .fds-input::placeholder {
+    color: var(--fds-input-placeholder);
+  }
+
+  .fds-input:hover:not(:disabled):not(.fds-input--error) {
+    border-color: var(--fds-input-border-color-hover);
+  }
+
+  .fds-input:focus-visible {
+    border-color: var(--fds-input-border-color-focus);
+    outline: 2px solid var(--fds-input-border-color-focus);
+    outline-offset: -1px;
+  }
+
+  .fds-input--error {
+    border-color: var(--fds-input-border-color-error);
+  }
+
+  .fds-input--error:focus-visible {
+    border-color: var(--fds-input-border-color-error);
+    outline-color: var(--fds-input-border-color-error);
+  }
+
+  .fds-input:disabled {
+    background: var(--fds-input-bg-disabled);
+    color: var(--fds-input-text-disabled);
+    cursor: not-allowed;
+  }
+</style>

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

@@ -0,0 +1,9 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+interface Props extends HTMLInputAttributes {
+    type?: 'text' | 'search';
+    error?: boolean;
+    value?: string;
+}
+declare const Input: import("svelte").Component<Props, {}, "value">;
+type Input = ReturnType<typeof Input>;
+export default Input;

package/dist/components/Modal.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { HTMLDialogAttributes } from 'svelte/elements';
+
+  interface Props extends HTMLDialogAttributes {
+    open?: boolean;
+    closeOnEscape?: boolean;
+    closeOnBackdrop?: boolean;
+    children?: Snippet;
+    onclose?: () => void;
+  }
+
+  let {
+    open = $bindable(false),
+    closeOnEscape = true,
+    closeOnBackdrop = true,
+    children,
+    onclose: onclosecb,
+    ...rest
+  }: Props = $props();
+
+  let dialogEl: HTMLDialogElement | undefined = $state();
+
+  $effect(() => {
+    if (!dialogEl) return;
+    if (open && !dialogEl.open) {
+      dialogEl.showModal();
+    } else if (!open && dialogEl.open) {
+      dialogEl.close();
+    }
+  });
+
+  function handleCancel(e: Event) {
+    if (!closeOnEscape) {
+      e.preventDefault();
+    }
+  }
+
+  function handleClose() {
+    open = false;
+    onclosecb?.();
+  }
+
+  function handleClick(e: MouseEvent) {
+    if (closeOnBackdrop && e.target === dialogEl) {
+      open = false;
+    }
+  }
+</script>
+
+<dialog
+  bind:this={dialogEl}
+  class="fds-modal"
+  oncancel={handleCancel}
+  onclose={handleClose}
+  onclick={handleClick}
+  {...rest}
+>
+  <div class="fds-modal__content">
+    {#if children}{@render children()}{/if}
+  </div>
+</dialog>
+
+<style>
+  .fds-modal {
+    border: 1px solid var(--fds-modal-border-color);
+    padding: 0;
+    margin: auto;
+    max-width: min(90vw, 32rem);
+    background: var(--fds-modal-bg);
+    color: var(--fds-modal-text);
+    border-radius: var(--fds-modal-radius);
+    box-shadow: var(--fds-modal-shadow);
+  }
+
+  .fds-modal::backdrop {
+    background: var(--fds-modal-backdrop);
+  }
+
+  .fds-modal__content {
+    padding: var(--fds-modal-padding);
+  }
+</style>

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

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+import type { HTMLDialogAttributes } from 'svelte/elements';
+interface Props extends HTMLDialogAttributes {
+    open?: boolean;
+    closeOnEscape?: boolean;
+    closeOnBackdrop?: boolean;
+    children?: Snippet;
+    onclose?: () => void;
+}
+declare const Modal: import("svelte").Component<Props, {}, "open">;
+type Modal = ReturnType<typeof Modal>;
+export default Modal;