Integration

The design system — tokens, Svelte components, and brand assets — lives in this repository at packages/. The YotoShelf frontend consumes these via a git submodule at frontend/design, which points to a tagged release of this repo.

Consuming as a submodule

The YotoShelf frontend already has this configured. For a new project:

# Add the submodule pointing at this repo
git submodule add https://gitlab.com/yotoshelf/yotoshelf.dev.git design
git submodule update --init

This creates a design/ directory. Your project then imports from design/packages/.

Importing design tokens

In your project's global CSS file (e.g., src/styles/global.css):

/* Import Google Fonts — Fraunces (display), Literata (body), IBM Plex Mono (mono) */
@import url('https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..900;1,9..144,300..900&family=Literata:ital,opsz,wght@0,7..72,300..700;1,7..72,300..700&family=IBM+Plex+Mono:wght@400;500&display=swap');

/* Import the Tailwind theme (which imports tokens.css internally) */
@import '../design/packages/tokens/tailwind-theme.css';

/* Import Tailwind */
@import 'tailwindcss';

The Tailwind theme file imports tokens.css automatically — you get both CSS custom properties and Tailwind utility classes from a single import.

Using design tokens directly

All tokens are available as CSS custom properties:

.my-element {
  color: var(--color-foreground);
  font-family: var(--font-body);
  padding: var(--spacing-4);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
  transition: all var(--transition-base);
}

Using Tailwind utilities

The theme maps tokens to Tailwind classes:

<div class="bg-background text-foreground p-4 rounded-lg shadow-md">
  <h2 class="font-display text-2xl font-semibold">Heading</h2>
  <p class="font-body text-sm text-muted-foreground">Body text</p>
</div>

Importing shared Svelte components

<script>
  import { Button, Card, Badge, Input, Dialog, Callout, Carousel }
    from '../design/packages/components/index.js';
</script>

<Button variant="primary" size="md">Save Card</Button>

<Card>
  <h3>My Collection</h3>
  <p>12 cards</p>
</Card>

<!-- Chips / section badges: use pastel families -->
<Badge variant="sage">Stories</Badge>
<Badge variant="dusty-blue">Music</Badge>
<Badge variant="butter">Learning</Badge>
<Badge variant="blush">Favourites</Badge>

<!-- Status badges -->
<Badge variant="success">Ready</Badge>
<Badge variant="warning">Draft</Badge>

<!-- Callout variants -->
<Callout variant="note" title="Tip">
  Tap a card to preview before syncing.
</Callout>
<Callout variant="warning">
  Refresh tokens are single-use.
</Callout>
<Callout variant="quirk">
  Yoto cards are identified by NFC UID — duplicates share a slot.
</Callout>

Chip and badge usage pattern

Use the four pastel variants (sage, dusty-blue, butter, blush) as section chips — they map to the --color-sage, --color-dusty-blue, --color-butter, and --color-blush token families respectively. These are additive identities for content categories; they are not semantic status signals. Keep status signals (ready/draft/error) on the semantic variants.

Chips render as pill badges (border-radius: var(--radius-full)) with the pastel background, the paired foreground token for text, and a 1px border from the *-border token. This gives them legible contrast without needing full opacity fills.

Component props reference

Component	Key Props
Button	variant (primary/secondary/destructive/ghost/outline), size (sm/md/lg), disabled, href
Card	href (makes clickable), padding (boolean)
Badge	variant (default/success/warning/destructive/outline/sage/dusty-blue/butter/blush), pill shape by default
Input	label, placeholder, value (bindable), type, disabled, error
Dialog	open (bindable), title, slots: default + footer
Callout	variant (note/warning/quirk), title (optional) — rounded corners, soft background tint
Carousel	slides ({ src, alt, caption? }[]) — picture-book plate layout; omit for placeholder state

Updating the submodule pointer

# Pull latest from this repo's main branch
git submodule update --remote design

# Commit the pointer update
git add design
git commit -m "update: design system to latest"

Dark mode

Add data-theme="dark" or class dark to your <html> element. All color and shadow tokens automatically adjust.

<html data-theme="dark">

Project structure

your-project/
├── design/                  ← git submodule → yotoshelf.dev
│   ├── packages/
│   │   ├── tokens/
│   │   │   ├── tokens.css          ← CSS custom properties
│   │   │   └── tailwind-theme.css  ← Tailwind v4 @theme
│   │   └── components/
│   │       ├── Button.svelte
│   │       ├── Card.svelte
│   │       ├── Badge.svelte
│   │       ├── Input.svelte
│   │       ├── Dialog.svelte
│   │       ├── Callout.svelte
│   │       ├── Carousel.svelte
│   │       └── index.js            ← barrel export
│   └── public/
│       └── logo/                   ← hero.svg, mark.svg
├── src/
│   └── styles/
│       └── global.css              ← imports from design/packages/
└── ...