npm package: @fudge-me/design-system
Description: Visual language and UI primitives for the fudge ecosystem
Latest version: 0.2.0

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