npm package: @pisodev/ui-common
Description: 웹과 React Native를 위한 공통 타입 및 테마
Author: Piso
Latest version: 0.0.13

# @pisodev/ui-common

Shared types, theme, and typography system for cross-platform UI components.

## Installation

```bash
npm install @pisodev/ui-common
```

> **Note**: This package is automatically installed as a dependency when you install `@pisodev/ui-web` or `@pisodev/ui-native`.

## Features

- **Theme System**: Light and dark color themes
- **Typography Presets**: Consistent typography across platforms
- **Type Definitions**: Shared TypeScript types
- **Color Scales**: Comprehensive color palette with alpha variants
- **Figma Integration**: Auto-generated from Figma design tokens

## Usage

### Colors

#### TypeScript (theme objects)

```typescript
import { lightColors, darkColors } from '@pisodev/ui-common';

const primaryColor = lightColors.colors.blue1['500'];
const grayScale = darkColors.colors.gray['200'];

// Available color groups:
// gray, grayAlpha, graySemantic, whiteAlpha
// blue1, blue1Alpha, blue2, blue2Alpha
// green, greenAlpha, purple, purpleAlpha
// yellow, yellowAlpha, red, redAlpha
```

#### SCSS (single entrypoint)

```scss
@use '@pisodev/ui-common/styles.scss' as ui;

.light-card {
  background-color: ui.$gray-00-light;
  border-color: ui.$gray-200-light;
  color: ui.$gray-800-light;
}

.dark-card {
  background-color: ui.$gray-900-dark;
  color: ui.$gray-00-dark;
}
```

> `styles.scss` also injects `colors.css` (CSS variables) and `typography.css` (utility classes) once per compilation.

### Typography

```typescript
import { typographyPresets } from '@pisodev/ui-common';

const heading = typographyPresets['title2-bold'];
// {
//   fontFamily: string;
//   fontSize: number;
//   fontWeight: number;
//   fontStyle: string;
//   lineHeight: number;
//   letterSpacing: number;
// }
```

### Types

```typescript
import type { Theme, TypographyPreset } from '@pisodev/ui-common';

const customTheme: Theme = {
  colors: {
    // ... your color definitions
  }
};
```

## Color System

The color system provides:
- **12-step scales**: From lightest to darkest
- **Light & Dark modes**: Full theme support
- **Alpha variants**: For transparency effects
- **Semantic colors**: Pre-defined semantic meanings

### Available Color Scales

**Scale Tokens** - Base color scales with light/dark mode variants
```typescript
grayScale, blue1Scale, blue2Scale, greenScale, purpleScale, yellowScale, redScale
```

**Alpha Tokens** - Transparent color variants
```typescript
grayAlpha, blue1Alpha, blue2Alpha, greenAlpha, purpleAlpha, yellowAlpha, redAlpha, whiteAlpha
```

**Semantic Tokens** - Purpose-based colors
```typescript
graySemantic, semanticPaper, semanticDivider, semanticOverlay, semanticBrand, semanticInformation
```

## Typography System

Typography presets are generated from design tokens and include:
- Font family
- Font size
- Font weight
- Line height
- Letter spacing

## Development

This package uses automated scripts to generate color and typography data from design tokens.

### Build

```bash
npm run build
```

This will:
1. Extract typography from design tokens
2. Extract and build color scales
3. Compile TypeScript to distributable format

### Updating Colors from Figma

When colors change in Figma:

1. **Export** Figma tokens as JSON to `tokens/` directory
2. **Extract** colors from tokens: `npm run build:colors`
3. **Build** the package: `npm run build`

```bash
npm run build:colors  # Parse JSON → colors.data.ts → CSS/SCSS
npm run build         # Full build with all steps
```

## File Structure

```
src/theme/
├── extract-colors.ts      # Parses Figma JSON → colors.data.ts
├── build-colors.ts        # Generates CSS/SCSS from colors.data.ts
├── colors.data.ts         # TypeScript exports (auto-generated)
├── colors.ts              # Theme exports
└── colors.types.ts        # Type definitions

src/typography/
├── extract-typography.ts  # Extracts typography from tokens
├── typography.data.ts     # Typography presets (auto-generated)
└── typography.ts          # Typography exports

tokens/
└── *.json                # Figma design token JSON files
```

## License

MIT © Piso