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 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 for the full workflow and failure modes.

Consumer Import Pattern

Root layout in fudge-client:

<!-- 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):

<script>
  import '@fudge-me/design-system/tokens/color.css';
</script>

Component import:

<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:

<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 | Cross-repo consumption contract and public API surface |