npm package: @synap-core/ui-system
Description: Synap design system built with Tamagui
Author: Synap Labs
Latest version: 1.3.1

# @synap/ui-system

Synap's comprehensive design system built with [Tamagui 1.141.5](https://tamagui.dev).

**A universal UI system for web and native** featuring shadow-based depth, dual theme identity (Amber/Cyan), glassmorphism, and tactile interactions.

---

## Features

- **Dual Theme System** - Light mode (Amber/warm) and Dark mode (Cyan/cool)
- **Shadow-Based Depth** - Physical, tactile UI with elevation
- **Glassmorphism** - Translucent overlays with backdrop blur
- **Spring Animations** - Natural, physics-based interactions
- **Fully Typed** - Complete TypeScript support with autocomplete
- **Responsive** - Mobile-first with breakpoint system
- **Accessible** - WCAG 2.1 AA compliant
- **Source Package** - No build step, transpiled by Next.js

---

## Installation

This is a private workspace package. Import from within the monorepo:

```typescript
import {
  Button,
  Card,
  YStack,
  XStack,
  Text,
  useTheme,
  useThemeMode,
} from '@synap/ui-system';
```

---

## Quick Start

### Basic Components

```typescript
import { Button, Card, YStack, Text } from '@synap/ui-system';

export function MyComponent() {
  return (
    <Card elevation="md" padding="$6">
      <YStack gap="$4">
        <Text fontSize="$6" fontWeight="600">
          Welcome to Synap
        </Text>
        <Button variant="primary" size="md">
          Get Started
        </Button>
      </YStack>
    </Card>
  );
}
```

### Theme-Aware Styling

```typescript
import { YStack, Text, useTheme } from '@synap/ui-system';

export function ThemedComponent() {
  const theme = useTheme();

  return (
    <YStack backgroundColor="$background" padding="$4">
      <Text color="$color">This text adapts to theme</Text>
      <Text color="$primary">Primary color (Amber in light, Cyan in dark)</Text>
    </YStack>
  );
}
```

### Responsive Design

```typescript
<YStack
  padding="$4"
  $gtMd={{ padding: '$8' }}
  $gtLg={{ padding: '$12' }}
>
  Responsive padding
</YStack>
```

---

## Design Tokens

### Colors

```typescript
// Semantic colors (theme-aware)
$primary        // Amber (light) / Cyan (dark)
$secondary      // Cyan (light) / Amber (dark)
$ai             // Emerald (constant across modes)
$success        // Emerald
$error          // Red
$warning        // Amber
$info           // Cyan

// UI colors
$color          // Text color
$background     // Background color
$muted          // Secondary text
$borderColor    // Border color
```

### Spacing

```typescript
$1: 4px    $2: 8px    $3: 12px   $4: 16px
$5: 20px   $6: 24px   $8: 32px   $12: 48px
```

### Typography

```typescript
// Font sizes
$4: 14px   $5: 16px   $6: 18px   $7: 20px

// Fonts
$heading   // Fraunces (serif)
$body      // DM Sans (sans-serif)
```

---

## Components

### Layout
- **YStack** - Vertical stack (flex column)
- **XStack** - Horizontal stack (flex row)
- **Panel** - Workspace panel with header/content/footer

### Form Controls
- **Button** - 6 variants: primary, secondary, neutral, ghost, outline, danger
- **ModernInput** - Elevated input with shadow and focus states
- **SearchBar** - Glassmorphism search with gradient glow
- **Checkbox** - Styled checkbox
- **Radio** - Styled radio button
- **Switch** - Toggle switch

### Display
- **Card** - Elevated card with shadow (5 elevation levels)
- **Badge** - Semantic badges for status/labels
- **AIInsightCard** - Floating AI suggestion cards with animations
- **Tooltip** - Contextual tooltips

---

## Theme System

### Using Themes

```typescript
import { TamaguiProvider, Theme } from '@synap/ui-system';
import config from '@synap/ui-system/config';

<TamaguiProvider config={config}>
  <Theme name="light"> {/* or "dark" */}
    <App />
  </Theme>
</TamaguiProvider>
```

### Detecting Theme

```typescript
import { useThemeMode } from '@synap/ui-system';

const isDark = useThemeMode();
const iconColor = isDark ? '#22D3EE' : '#D97706';
```

---

## Glassmorphism

For overlays, modals, command palette:

```typescript
<YStack
  backgroundColor="$glassBackground"
  borderWidth={1}
  borderColor="$glassBorder"
  borderRadius="$4"
  style={{
    backdropFilter: 'blur(20px)',
    WebkitBackdropFilter: 'blur(20px)',
  }}
>
  Glass content
</YStack>
```

---

## Best Practices

**DO:**
- Use design tokens (`$primary`, `$4`) instead of hard-coded values
- Test components in both light and dark modes
- Follow the 4px spacing scale
- Use semantic color names

**DON'T:**
- Hard-code colors or spacing values
- Mix external UI libraries
- Skip accessibility attributes

---

## Documentation

- **[Design System (Full Documentation)](../../../DESIGN_SYSTEM.md)** - Complete design system guide
- **[Architecture (CLAUDE.md)](../../../CLAUDE.md)** - Codebase architecture overview
- **[Tamagui Docs](https://tamagui.dev/docs/intro)** - Tamagui framework documentation

---

## Structure

```
packages/core/ui-system/
├── src/
│   ├── components/          # Component implementations
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Input.tsx
│   │   ├── ModernInput.tsx
│   │   ├── SearchBar.tsx
│   │   ├── AIInsightCard.tsx
│   │   ├── Badge.tsx
│   │   ├── Checkbox.tsx
│   │   ├── Radio.tsx
│   │   ├── Switch.tsx
│   │   └── ...
│   ├── layout/              # Layout components
│   │   ├── Panel.tsx
│   │   ├── Resizable.tsx
│   │   └── Stack.tsx
│   ├── hooks/               # Custom hooks
│   │   └── useThemeMode.ts
│   ├── tamagui.config.ts    # Tamagui configuration
│   ├── themes.ts            # Theme definitions
│   └── index.ts             # Main exports
├── package.json
└── README.md
```

---

## Development

This is a **source package** (no build step). TypeScript source is exported directly and transpiled by Next.js.

```json
{
  "exports": {
    ".": "./src/index.ts"
  }
}
```

### Type Checking

```bash
cd packages/core/ui-system
pnpm type-check
```

---

## Dependencies

- **Tamagui 1.141.5** - Universal design system
- **Framer Motion 12** - Animation library
- **Lucide React 0.555** - Icon library
- **React 19** - UI library

---

## License

Private - Synap Monorepo

---

## Support

For questions or issues:
- Check [DESIGN_SYSTEM.md](../../../DESIGN_SYSTEM.md)
- Review component source in `src/components/`
- See [Tamagui documentation](https://tamagui.dev)