npm package: @parithys/upstreamai-design-system-library
Description: UpstreamAI Design System Library
Latest version: 1.0.5

# Design System Library Publisher

A Figma plugin that analyses a design file and extracts **every key design system asset** — variables, color styles, typography, effects, grids, spacing, and components — then generates ready-to-publish output in multiple formats.

## What it extracts

| Category | Details |
|---|---|
| **Variables** | All Figma variable collections (color, float/spacing, string, boolean) with every mode value |
| **Color styles** | Solid fills, gradients (linear, radial, angular, diamond) and image paints |
| **Typography styles** | Font family, weight, size, line-height, letter-spacing, text decoration, case |
| **Effect styles** | Drop shadows, inner shadows, layer blurs, background blurs |
| **Grid styles** | Column grids, row grids, fixed grids with gutter and count |
| **Components** | Component sets (multi-variant), standalone components with all property definitions |

## Export formats

| Format | Output |
|---|---|
| **Tokens (JSON)** | [W3C DTCG](https://design-tokens.github.io/community-group/format/) — nested `$value`/`$type` tokens |
| **CSS** | `:root` custom properties (`--prefix-token-name: value`) |
| **SCSS** | Variable declarations (`$prefix-token-name: value`) + SCSS maps |
| **JavaScript** | Nested `const tokens = { … }` object + `module.exports` |
| **TypeScript** | Same as JS with `as const` and `export type Tokens` |

## Prerequisites

- [Node.js](https://nodejs.org) ≥ 18
- Figma Desktop (plugins require the desktop app)

## Setup

```bash
# Install dependencies
npm install

# Build for production (outputs to dist/)
npm run build

# Watch mode during development
npm run dev
```

## Installing in Figma

1. Run `npm run build`
2. Open Figma Desktop → **Plugins** → **Development** → **Import plugin from manifest…**
3. Select `manifest.json` from this directory
4. Open any file that contains a design system → run the plugin from **Plugins → Development → Design System Library Publisher**

## Architecture

```
src/
├── code.ts                  # Figma sandbox — orchestrates extraction
├── types.ts                 # Shared TypeScript interfaces
├── ui.html                  # Plugin window HTML template
├── ui.ts                    # Plugin window JS (runs in iframe)
├── extractors/
│   ├── variables.ts         # Figma Variables API
│   ├── styles.ts            # Paint / Text / Effect / Grid styles
│   └── components.ts        # Component sets & standalone components
└── formatters/
    ├── utils.ts             # Color helpers, name converters, shared utils
    ├── tokens.ts            # W3C DTCG JSON
    ├── css.ts               # CSS custom properties
    ├── scss.ts              # SCSS variables + maps
    └── js.ts                # JS / TS module exports
```

The plugin runs in two isolated contexts:

- **`code.ts` (Figma sandbox)** — has full Figma API access, no DOM.  Extracts all data and sends it to the UI via `figma.ui.postMessage`.
- **`ui.ts` (iframe / browser)** — receives the data, renders the inspector UI, runs the formatters, and handles copy/download.

## Name conversion

Figma token paths (`Color/Primary/500`) are converted consistently:

| Target | Result |
|---|---|
| Token path | `color.primary.500` |
| CSS var | `--color-primary-500` |
| SCSS var | `$color-primary-500` |
| JS key | `colorPrimary500` |

## License

MIT