radicle-design-system

v0.1.2

Published

8 days ago

A comprehensive Svelte 5 design system package providing design tokens, icons, and production-ready components for the Radicle ecosystem.

0High
0Medium
0Low

julienstudio

@radicle/design-system

A comprehensive Svelte 5 design system package providing design tokens, icons, and production-ready components for the Radicle ecosystem.

Features

🎨 Design Tokens - Colors, typography, spacing, radii, and elevation
🧩 UI Components - 9 production-ready Svelte 5 components with runes
🌗 Theme Support - Light and dark themes with automatic switching
🎯 Accent Colors - Configurable accent colors (blue for Desktop, green for Garden)
🔤 Booton Font - Custom font family with multiple weights
🎭 104+ Icons - Lightweight icon components using Svelte 5
📦 Type-Safe - Full TypeScript support throughout
♿ Accessible - Semantic HTML and proper ARIA attributes

Installation

npm install @radicle/design-system

Note: You'll need to add the Booton font files to src/fonts/ directory. See src/fonts/README.md for the list of required files.

Usage

Basic Setup

Import the CSS files in your app:

@import '@radicle/design-system/styles/fonts.css';
@import '@radicle/design-system/styles/tokens.css';

Or in your JavaScript/TypeScript:

import '@radicle/design-system/styles/fonts.css';
import '@radicle/design-system/styles/tokens.css';

Theme Configuration

Control theme and accent colors using data attributes on your root HTML element:

<!-- Light theme, blue accent (default) -->
<html>

<!-- Dark theme, blue accent -->
<html data-theme="dark">

<!-- Light theme, green accent (Radicle Garden) -->
<html data-accent="green">

<!-- Dark theme, green accent -->
<html data-theme="dark" data-accent="green">

Using Design Tokens in CSS

All tokens are available as CSS custom properties:

.card {
  /* Colors */
  background: var(--surface-subtle);
  border: 1px solid var(--border-subtle);
  color: var(--text-primary);

  /* Spacing */
  padding: var(--space-lg);
  gap: var(--space-md);

  /* Radii */
  border-radius: var(--radius-lg);

  /* Elevation */
  box-shadow: var(--shadow-md);
}

.title {
  /* Typography */
  font-family: var(--font-sans);
  font-size: var(--heading-m);
  line-height: var(--heading-m-leading);
  font-weight: var(--weight-semibold);
}

.button-primary {
  /* Brand colors */
  background: var(--brand-default);
  color: var(--text-on-brand);
}

.button-primary:hover {
  background: var(--brand-emphasised);
}

Using Tokens in TypeScript

Import and use tokens directly in your code:

import { colors, spacing, typography } from '@radicle/design-system/tokens';

// Access color values
const bgColor = colors.light.surfaceCanvas;
const textColor = colors.dark.textPrimary;

// Access spacing values
const padding = spacing.spaceLg;

// Access typography values
const headingSize = typography.headingXl;

Using Components

Import and use UI components:

<script>
  import {
    Button,
    IconButton,
    Input,
    TextForm,
    Checkbox,
    RadioButton,
    Dropdown,
    Banner,
    ButtonGroup
  } from 'radicle-design-system';
  import { IconPlus, IconEdit } from 'radicle-design-system/icons';

  let username = $state('');
  let email = $state('');
  let agreed = $state(false);
</script>

<!-- Buttons -->
<Button variant="primary" onclick={() => console.log('clicked')}>
  <IconPlus />
  Add Item
</Button>

<IconButton variant="secondary">
  <IconEdit />
</IconButton>

<!-- Button Group (tabs) -->
<ButtonGroup gap="sm">
  <Button variant="secondary">Active Tab</Button>
  <Button variant="quaternary">Inactive Tab</Button>
</ButtonGroup>

<!-- Form Fields -->
<TextForm
  label="Username"
  bind:value={username}
  placeholder="Enter your username"
/>

<TextForm
  label="Email"
  bind:value={email}
  errorMessage="Invalid email address"
  type="email"
/>

<Checkbox bind:checked={agreed}>
  I agree to the terms
</Checkbox>

<!-- Banner -->
<Banner style="warning">
  This is a warning message
</Banner>

See COMPONENTS.md for complete component documentation with all props, variants, and examples.

Using Icons

Import and use icon components:

<script>
  import { IconPlus, IconCheck, IconX, IconChevronDown } from 'radicle-design-system/icons';
</script>

<button>
  <IconPlus />
  Add item
</button>

<button>
  <IconCheck size="large" />
  Confirm
</button>

<button class="danger">
  <IconX />
  Delete
</button>

<style>
  button {
    display: flex;
    align-items: center;
    gap: var(--space-sm);
    color: var(--text-primary);
  }

  .danger {
    color: var(--error-text);
  }
</style>

Icon props:

size?: 'normal' | 'large' - Icon size (default: 'normal')
class?: string - Additional CSS classes

See ICONS.md for the complete icon list.

Design Tokens Reference

Colors

Surface Colors

--surface-sidebar, --surface-canvas, --surface-subtle, --surface-mid, --surface-strong
--surface-alpha-subtle, --surface-alpha-mid, --surface-alpha-strong
--surface-open, --surface-merged, --surface-archived
--surface-shadow - Shadow color for elevations

Text Colors

--text-primary, --text-secondary, --text-tertiary, --text-quartenary
--text-disabled, --text-on-brand

Border Colors

--border-subtle, --border-mid, --border-strong
--border-alpha-subtle, --border-alpha-mid

Brand Colors

--brand-default, --brand-emphasised, --brand-text, --brand-border

Feedback Colors

Success: --success-text, --success-border, --success-bg
Warning: --warning-text, --warning-border, --warning-bg
Error: --error-text, --error-border, --error-bg

Typography

Font Families

--font-sans: Booton with fallbacks
--font-mono: JetBrains Mono with fallbacks

Font Weights

--weight-regular: 400
--weight-medium: 500
--weight-semibold: 600

Heading Sizes

--heading-xxl (2rem), --heading-xxl-leading (2.25rem)
--heading-xl (1.75rem), --heading-xl-leading (2rem)
--heading-l (1.375rem), --heading-l-leading (1.75rem)
--heading-m (1.125rem), --heading-m-leading (1.5rem)
--heading-s (1rem), --heading-s-leading (1.25rem)
--heading-xs (0.875rem), --heading-xs-leading (1.25rem)
--heading-xxs (0.75rem), --heading-xxs-leading (1rem)

Body Sizes

--body-l (1rem), --body-l-leading (1.5rem)
--body-m (0.875rem), --body-m-leading (1.25rem)
--body-s (0.75rem), --body-s-leading (1rem)

Monospace Sizes

--mono-l, --mono-m, --mono-s (with corresponding -leading values)
--code (0.875rem), --code-leading (1.25rem)

Spacing

--space2xs (0.125rem)
--space-xs (0.25rem)
--space-sm (0.5rem)
--space-md (0.75rem)
--space-lg (1rem)
--space-xl (1.25rem)
--space2xl (1.5rem)
--space3xl (1.75rem)
--space4xl (2rem)
--space5xl (2.5rem)
--space6xl (3rem)
--space7xl (4rem)
--space8xl (5rem)
--space9xl (6rem)
--space10xl (8rem)

Radii

--radius-xs (0.0625rem)
--radius-sm (0.125rem)
--radius-md (0.25rem)
--radius-lg (0.5rem)
--radius-full (99rem)

Elevation

--shadow-none - No shadow
--shadow1 - Elevation 1: 0 2px 2px 0 rgba(0, 6, 15, 0.08)
--shadow2 - Elevation 2: 0 3px 4px 0 rgba(0, 6, 15, 0.08)
--shadow3 - Elevation 3: 0 4px 6px 0 rgba(0, 6, 15, 0.08)
--shadow4 - Elevation 4: 0 5px 8px 0 rgba(0, 6, 15, 0.08)

Note: Elevations should be used with:

border: 1px solid var(--border-subtle)
background: var(--surface-canvas)
border-radius: var(--radius-lg) (or appropriate radius)

Development

# Install dependencies
npm install

# Generate CSS tokens
npm run generate:css

# Build package
npm run build

# Type check
npm run check

Components

The design system includes 9 production-ready Svelte 5 components:

Button - Versatile button with 5 variants and 3 sizes
IconButton - Icon-only button matching Button styles
ButtonGroup - Groups buttons with optional spacing
Input - Text input with multiple states and sizes
TextForm - Complete form field with label and error message
Checkbox - Custom-styled checkbox
RadioButton - Custom-styled radio button
Dropdown - Select dropdown with custom styling
Banner - Informational banner with icon

All components:

Built with Svelte 5 runes ($state, $props, $derived)
Fully type-safe with TypeScript
Theme and accent aware
Accessible with semantic HTML and ARIA attributes

See COMPONENTS.md for detailed documentation.

Package Structure

radicle-design-system/
├── styles/
│   ├── fonts.css       # Font face declarations
│   └── tokens.css      # Generated CSS custom properties
├── tokens/
│   └── index.js        # Token values for JavaScript/TypeScript
├── icons/
│   └── index.js        # 104+ icon components
├── components/
│   └── *.svelte        # UI components
└── index.js            # Main entry point

Documentation

COMPONENTS.md - Complete component documentation with props and examples
ICONS.md - Icon system documentation with full icon list
QUICKSTART.md - Quick start guide
DEMO.md - Demo site documentation
ELEVATION.md - Elevation system guidelines

License

TBD

Contributing

TBD