@spacetrev/design-system

Enterprise design system for all Space products — Built with TypeScript, Emotion, and React. Optimized for tree-shaking, accessible, and LLM-ready.

✨ Features

• 🎨 Three Professional Palettes — Artisan (warm/earthy), Modern (cool/contemporary), Classic (traditional/premium)
• 🎨 Custom Palette Generator — LAB color interpolation with WCAG contrast helpers
• 🧩 Primitive Components — Button, Card, Badge, Input, Textarea, Checkbox, Modal, Drawer
• 📐 Complete Token System — Colors, spacing, typography, shadows, radius, motion, breakpoints, z-index
• 🎭 Theme System — Preset themes + custom theme factory with Emotion integration
• 🔤 Icon System — Lucide React integration with theme-aware sizing/coloring
• 📱 Tree-Shakeable — ESM + CJS builds, optimized bundle size (~42KB CJS)
• ♿ Accessible — WCAG AA compliant colors, keyboard navigation, ARIA attributes
• 🤖 LLM-Ready — MCP integration for AI-assisted development (coming soon)
• 📚 Storybook — Interactive component gallery (coming soon)

📦 Installation

npm install @spacetrev/design-system @emotion/react @emotion/styled
# or
pnpm add @spacetrev/design-system @emotion/react @emotion/styled
# or
yarn add @spacetrev/design-system @emotion/react @emotion/styled

Peer Dependencies:

• react@^18.0.0
• react-dom@^18.0.0
• @emotion/react@^11.0.0
• @emotion/styled@^11.0.0

🚀 Quick Start

Basic Theme Setup

import { ThemeProvider, GlobalStyles } from '@spacetrev/design-system';
import { Button } from '@spacetrev/design-system/components';

function App() {
  return (
    <ThemeProvider theme="artisan">
      <GlobalStyles />
      <Button variant="primary">Hello World</Button>
    </ThemeProvider>
  );
}

Custom Palette

import { ThemeProvider, createCustomPalette } from '@spacetrev/design-system/theme';

const customPalette = createCustomPalette({
  primary: '#D4744A',
  secondary: '#8B9D83',
  accent: '#E6A855',
  neutral: '#8B8680',
});

function App() {
  return (
    <ThemeProvider theme={{ palette: customPalette, name: 'MyBrand' }}>
      {/* Your app */}
    </ThemeProvider>
  );
}

Component Examples

import {
  Button,
  Card,
  Badge,
  Input,
  Textarea,
  Checkbox,
  Modal,
  Drawer,
} from '@spacetrev/design-system/components';
import { Search, Mail } from '@spacetrev/design-system/icons/ui-icons';

// Buttons
<Button variant="primary" size="lg" leftIcon={Mail}>
  Contact Us
</Button>

// Cards
<Card variant="elevated" padding="lg" hoverable>
  <h3>Card Title</h3>
  <p>Card content goes here...</p>
</Card>

// Badges
<Badge variant="success" size="md">Active</Badge>

// Inputs
<Input
  label="Email"
  type="email"
  placeholder="you@example.com"
  leftIcon={Mail}
  required
/>

// Textarea
<Textarea
  label="Message"
  placeholder="Type your message..."
  rows={4}
  resize="vertical"
/>

// Checkbox
<Checkbox label="I agree to the terms" required />

// Modal
const [open, setOpen] = useState(false);
<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Modal Title"
  size="md"
  footer={
    <>
      <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
      <Button variant="primary">Confirm</Button>
    </>
  }
>
  <p>Modal content here...</p>
</Modal>

// Drawer
<Drawer
  open={open}
  onClose={() => setOpen(false)}
  title="Settings"
  position="right"
  size="md"
>
  <p>Drawer content here...</p>
</Drawer>

📖 Component API

Primitive Components (8)

• Button — 5 variants (primary, secondary, outline, ghost, danger), 3 sizes, loading state, icons
• Card — 3 variants (default, elevated, outlined), 4 padding sizes, hoverable/clickable
• Badge — 6 variants (primary, secondary, success, warning, error, neutral), 3 sizes
• Input — 3 variants, 4 states, icons, addons, validation
• Textarea — Same variants as Input, configurable resize behavior
• Checkbox — 3 sizes, indeterminate state, error state
• Modal — 5 sizes (sm, md, lg, xl, full), animations, keyboard navigation
• Drawer — 4 positions (left, right, top, bottom), 4 sizes, animations

Theme System

• ThemeProvider — Emotion theme wrapper with preset/custom theme support
• createTheme — Factory for creating themes from preset or custom palette
• createCustomPalette — Generate full palette from 4 base colors with LAB interpolation
• useTheme — React hook for accessing theme in components
• GlobalStyles — CSS reset + base styles

Icon System

• Icon — Lucide wrapper with theme-aware sizing/coloring
• category-icons — Commerce category icons (beef, chicken, fish, pork, etc.)
• ui-icons — Common UI icons from Lucide (Search, Mail, Settings, etc.)

Design Tokens

All tokens available via @spacetrev/design-system/tokens:

• colors — 3 preset palettes with 50-950 scales + semantic colors
• spacing — 4px base scale (2xs to 5xl) + semantic aliases
• typography — Font sizes, weights, semantic typography
• shadows — 6-level elevation + colored shadow generator
• radius — Border radius scale (sm to full)
• motion — Durations (100-500ms), easing curves, transition helpers
• breakpoints — Mobile-first responsive breakpoints + media query helpers
• zIndex — Stacking context values (dropdown to toast)

🎨 Theme Presets

Artisan (Warm & Earthy)

Perfect for boutique shops, artisanal products, organic brands.

• Primary: Terracotta (#D4744A)
• Secondary: Sage (#8B9D83)
• Accent: Amber (#E6A855)
• Neutral: Cream-to-Charcoal

Modern (Cool & Contemporary)

Ideal for tech products, SaaS apps, modern startups.

• Primary: Slate (#64748B)
• Secondary: Teal (#14B8A6)
• Accent: Blush (#E879F9)
• Neutral: Cool Gray

Classic (Traditional & Premium)

Great for luxury brands, professional services, established businesses.

• Primary: Burgundy (#7C2D3A)
• Secondary: Forest (#2D5016)
• Accent: Tan (#C19A6B)
• Neutral: Warm Beige

🛠️ Development

# Install dependencies
pnpm install

# Start dev mode (watch + rebuild on changes)
pnpm dev

# Build for production
pnpm build

# Run linter
pnpm lint

# Type check
pnpm typecheck

# Run tests (coming soon)
pnpm test

# Start Storybook (coming soon)
pnpm storybook

📚 Documentation (Coming Soon)

• Storybook — Interactive component gallery
• MCP Integration — LLM-assisted development guide
• Migration Guide — Upgrading from existing design systems
• Contribution Guide — How to contribute

🗺️ Roadmap

• Complete token system (8 token files)
• Theme system with LAB interpolation
• Icon system with Lucide integration
• 8 primitive components
• Storybook setup with theme switching
• MCP JSON generation (ts-morph script)
• Component extraction from tres-raices-site and space-trading
• Additional primitives (Select, Radio, Switch, Tooltip, Toast)
• Composite components (Form, Table, Tabs, Accordion)
• Animation components (FadeIn, SlideIn, etc.)
• npm publishing + GitHub releases
• Comprehensive unit tests

📄 License

MIT © SpaceTrev