-
Notifications
You must be signed in to change notification settings - Fork 27
/
README.md
516 lines (442 loc) · 32.8 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
# Figma Plugin DS Svelte
WORK IN PROGRESS—This is a Svelte version of the Figma Plugin DS specifically for use in creating Figma Plugins. I decided to create this because Svelte seems like a great lightweight approach well suited for creating Figma plugins, and also improves the developer experience when compared to my vanilla JS Figma Plugin DS due to simplified markup.
You can also get started with [Figsvelte](https://github.com/thomas-lowry/figsvelte), a boilerplate for Figma plugins that already has this library setup as a dependency.
## Installation
To install into your own Svelte project.
`npm i -D figma-plugin-ds-svelte`
## To use
```javascript
//import the global css which includes Figma color, spacing, and type vars
//also includes a basic set of utility classes
import { GlobalCSS } from 'figma-plugin-ds-svelte';
//import the desired components
import { Button, Input, SelectMenu } from 'figma-plugin-ds-svelte';
```
---
## Components
_All components can accept class props to add global or utility classes to each component_
* [Button](#Button)
* [Checkbox](#Checkbox)
* [Disclosure panel](#Disclosure)
* [Icon](#Icon)
* [Icon button](#Icon-button)
* [Input](#Input)
* [Labels and sections](#Labels-and-sections)
* [Onboarding tip](#Onboarding-tip)
* [Radio button](#Radio-button)
* [Select menu](#Select-menu)
* [Switch](#Switch)
* [Textarea](#Textarea)
* [Type](#Type)
* [Tokens](#Tokens)
---
### Button
```javascript
import { Button } from 'figma-plugin-ds-svelte';
```
```html
<Button on:click={funcName}>Label</Button>
<Button on:click={funcName} variant="secondary">Label</Button>
<Button on:click={funcName} variant="secondary" destructive>Label</Button>
<Button on:click={funcName} disabled>Label</Button>
```
**Props**
| Prop | Type | Options/notes |
|:---------------|:--------|:----------------------------------------------------------------|
| `on:click` | Func | Assign a function to execute on click. Ex: `on:click={funcName}`|
| `variant` | String | Default: `"primary"`, Options: `"secondary"`, `"tertiary"` |
| `disabled` | Boolean | Default: `false` |
| `destructive` | Boolean | Default: `false` |
---
### Checkbox
```javascript
import { Checkbox } from 'figma-plugin-ds-svelte';
```
```html
<Checkbox>Label</Checkbox>
<Checkbox checked>Label</Checkbox>
<Checkbox disabled>Label</Checkbox>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:-----------------------------------------------------------------------------------------|
| `on:change`| Func | Funtion to execute on change. Ex: `on:change={funcName}` |
| `value` | Boolean | Default: `false`; |
| `checked` | Boolean | Default: `false`; You can bind the value when checked to a var. `bind:checked={varName}` |
| `disabled` | Boolean | Default: `false` |
---
### Disclosure
```javascript
import { Disclosure, DisclosureItem } from 'figma-plugin-ds-svelte';
```
```html
<Disclosure>
<DisclosureItem title="Item 1" open>Content here</DisclosureItem>
<DisclosureItem title="Item 2">Content here</DisclosureItem>
<DisclosureItem title="Item 3">Content here</DisclosureItem>
</Disclosure>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:------------------------------------------------------------------|
| `title` | String | Title of disclosure item |
| `open` | Boolean | Default: `false`; Only one disclosure item can be opened at once |
| `section` | Boolean | Default: `false`; Bold section header for disclosure title |
---
### Icon
```javascript
//You need to import the icon component + whatever icons you want to use,
//pass the names of your icon modules to the iconName prop in the Icon component
import { Icon, IconName } from 'figma-plugin-ds-svelte';
//You can also import your own svg icon (32x32) and pass it to the icon component
import SvgName from './src/directory/image.svg';
//Example
import { Icon, IconVisible, IconSpinner } from 'figma-plugin-ds-svelte';
```
```html
<Icon iconName={IconVisible} color="black"/>
<Icon iconName={IconSpinner} color="blue" spin/>
<Icon iconText="W" color="blue"/>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:---------------------------------------------------------------------------------------------|
| `iconName` | Var | Pass an imported SVG to this prop. `iconName={IconImport}` |
| `iconText` | String | Pass a text character to use instead of an icon. Ex: width and height inputs `iconText="W"` |
| `color` | String | Pass the name of any Figma color var to this prop. `color="blue"` |
| `spin` | Boolean | Default: `false`; This will rotate the icon in an endless loop. |
**Icons**
| Icon | Var |
|----------------------------------------------------------------------------------------|-----------------------------------|
|  | `IconAdjust` |
|  | `IconAlert` |
|  | `IconAngle` |
|  | `IconArrowLeftRight` |
|  | `IconUpDown` |
|  | `IconAutoLayoutHorizontal` |
|  | `IconAutoLayoutVertical` |
|  | `IconBack` |
|  | `IconBlendEmpty` |
|  | `IconBlend` |
|  | `IconBreak` |
|  | `IconCaretDown` |
|  | `IconCaretLeft` |
|  | `IconCaretRight` |
|  | `IconCaretUp` |
|  | `IconCheck` |
|  | `IconClose` |
|  | `IconComponent` |
|  | `IconCornerRadius` |
|  | `IconCorners` |
|  | `IconDistributeHorizontalSpacing` |
|  | `IconDistributeVerticalSpacing` |
|  | `IconDraft` |
|  | `IconEffects` |
|  | `IconEllipses` |
|  | `IconEyedropper` |
|  | `IconForward` |
|  | `IconFrame` |
|  | `IconGroup` |
|  | `IconHidden` |
|  | `IconHorizontalPadding` |
|  | `IconHyperlink` |
|  | `IconImage` |
|  | `IconInstance` |
|  | `IconKey` |
|  | `IconLayoutAlignBottom` |
|  | `IconAlignHorizontalCenters` |
|  | `IconAlignLeft` |
|  | `IconAlignRight` |
|  | `IconAlignTop` |
|  | `IconAlignVerticalCenters` |
|  | `IconLayoutGridColumns` |
|  | `IconLayoutGridRows` |
|  | `IconLayoutGridUniform` |
|  | `IconLibrary` |
|  | `IconLinkBroken` |
|  | `IconLinkConnected` |
|  | `IconListDetailed` |
|  | `IconListTile` |
|  | `IconList` |
|  | `IconLockOff` |
|  | `IconLockOn` |
|  | `IconMinus` |
|  | `IconPlay` |
|  | `IconPlus` |
|  | `IconRandom` |
|  | `IconRecent` |
|  | `IconResizeToFit` |
|  | `IconResolveFilled` |
|  | `IconResolve` |
|  | `IconReverse` |
|  | `IconSearchLarge` |
|  | `IconSearch` |
|  | `IconSettings` |
|  | `IconShare` |
|  | `IconSmiley` |
|  | `IconSortAlphaAsc` |
|  | `IconSortAlphaDsc` |
|  | `IconSortTopBottom` |
|  | `IconSpacing` |
|  | `IconSpinner` |
|  | `IconStarOff` |
|  | `IconStarOn` |
|  | `IconStrokeWeight` |
|  | `IconStyles` |
|  | `IconSwap` |
|  | `IconTheme` |
|  | `IconTidyUpGrid` |
|  | `IconTidyUpListHorizontal` |
|  | `IconTidyUpListVertical` |
|  | `IconTimer` |
|  | `IconTrash` |
|  | `IconVerticalPadding` |
|  | `IconVisible` |
|  | `IconWarningLarge` |
|  | `IconWarning` |
---
### Icon button
```javascript
//use this component as you would an Icon, it accepts the same props (except color)
import { IconButton } from 'figma-plugin-ds-svelte';
```
```html
<IconButton on:click={funcName} iconName={IconVisible}/>
<IconButton on:click={funcName} iconName={IconVisible} selected/>
<IconButton on:click={funcName} iconText="@"/>
```
**Props**
| Prop | Type | Options/notes |
|------------|---------|------------------------------------------------------------------|
| `on:click` | Func | Assign a function to execute on click. Ex: `on:click={funcName}` |
| `selected` | Boolean | Default: `false` |
| `iconName` | String | _See Icon component for usage._ |
| `IconText` | String | _See Icon component for usage._ |
| `spin` | Boolean | _See Icon component for usage._ |
---
### Input
```javascript
import { Input } from 'figma-plugin-ds-svelte';
//var to define and store value
var inputValue = 'Default value';
```
```html
<Input bind:value={inputValue}/>
<Input bind:value={inputValue} disabled/>
<Input placeholder="Enter some info..."/>
<!-- You can also pass Icon props to use the icon component inside the input -->
<Input iconName={IconName} />
<Input iconName={IconSpinner} spin placeholder="Fetching data..." />
<!-- Force borders on the input -->
<Input value="Value" borders/>
```
**Props**
| Prop | Type | Options/notes |
|:--------------|:--------|:-------------------------------------------------------------------|
| `on:change` | Func | Funtion to execute on change. Ex: `on:change={funcName}` |
| `value` | String | Value that will get populated by user or specify predefined value. You can also bind this to a variable. |
| `placeholder` | String | Placeholder text. |
| `borders` | Boolean | Default: `false`; Force a border on the input field. |
| `disabled` | Boolean | Default: `false` |
| `iconName` | Var | _See Icon component for usage._ |
| `iconText` | String | _See Icon component for usage._ |
| `spin` | Boolean | _See Icon component for usage._ |
---
### Labels and sections
```javascript
import { Label, SectionHeader } from 'figma-plugin-ds-svelte';
```
```html
<Label>Label name</Label>
<Section>Section name</Section>
```
---
### Onboarding tip
```javascript
import { OnboardingTip } from 'figma-plugin-ds-svelte';
```
```html
<OnboardingTip iconName={IconStyles}>
Tip text goes here
</OnboardingTip>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:--------------------------------|
| `iconName` | Var | _See Icon component for usage._ |
| `iconText` | String | _See Icon component for usage._ |
| `spin` | Boolean | _See Icon component for usage._ |
---
### Radio button
```javascript
import { Radio } from 'figma-plugin-ds-svelte';
//use bind:group, with a var to create a radio group and store the value of selected item
//set value if this var to same value as radio item to set initial selection
var radioValue;
```
```html
<Radio bind:group={radioValue} value="a">Label</Radio>
<Radio bind:group={radioValue} value="b">Label</Radio>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:----------------------------------------------------------|
| `on:change`| Func | Funtion to execute on change. Ex: `on:change={funcName}` |
| `group` | Var | Pass name of var to store selected item from radio group. |
| `value` | String | Value of radio item. |
| `disabled` | Boolean | Default: `false` |
---
### Select menu
```javascript
import { SelectMenu } from 'figma-plugin-ds-svelte';
//You will need to pass and bind an array of menu items to this
//Note: it is up to you to sort this array however you want
let menuItemArray = [
{ 'value': 'item1', 'label': 'Menu item 1', 'group': null, 'selected': false },
{ 'value': 'item2', 'label': 'Menu item 2 ', 'group': null, 'selected': false }
];
//use bind:value, with a var bind the data of the selected item
var selectedItem;
```
```html
<SelectMenu bind:menuItems={menuItemArray} bind:value={selectedItem}/>
<SelectMenu bind:menuItems={menuItemArray} bind:value={selectedItem} showGroupLabels/>
<SelectMenu bind:menuItems={menuItemArray} bind:value={selectedItem} iconName={IconBlend}/>
<SelectMenu bind:menuItems={menuItemArray} bind:value={selectedItem} disabled/>
```
**Props**
| Prop | Type | Options/notes |
|-------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------|
| `on:change` | Func | Function to execute on change. Ex: `on:change={funcName}` |
| `menuItems` | Var | Pass in array of menu item objects. See example above for format. If you want to use option groups, update the group keys to a string. |
| `value` | Var | Bind the value of the selected item to a var. Ex: `bind:value={selectedItem}` |
| `placeholder` | String | Override default placeholder text with a string when there is no item selected. |
| `showGroupLabels` | Boolean | Default: `false`; If you are using option groups, this will show the group labels. |
| `disabled` | Boolean | Default: `false` |
| `macOSBlink` | Boolean | Default: `false`; Easter egg, old school Mac OS triple blink on select. |
| `iconName` | Var | _See Icon component for usage._ |
| `iconText` | String | _See Icon component for usage._ |
---
### Switch
```javascript
import { Switch } from 'figma-plugin-ds-svelte';
//use bind:group, with a var to create a radio group and store the value of selected item
//set value if this var to same value as radio item to set initial selection
var switchValue;
```
```html
<Switch value="value" bind:checked={switchValue}>Label</Switch>
```
**Props**
| Prop | Type | Options/notes |
|:-----------|:--------|:-----------------------------------------------------------------------------------------|
| `on:change`| Func | Funtion to execute on change. Ex: `on:change={funcName}` |
| `value` | Boolean | Default: `false`; |
| `checked` | Boolean | Default: `false`; You can bind the value when checked to a var. `bind:checked={varName}` |
| `disabled` | Boolean | Default: `false` |
---
### Textarea
```javascript
import { Textarea } from 'figma-plugin-ds-svelte';
```
```html
<Textarea placeholder="Enter some text"></Textarea>
```
**Props**
| Prop | Type | Options/notes |
|:--------------|:--------|:----------------------------------------------------------------------|
| `on:change` | Func | Function to execute on change. Ex: `on:change={funcName}` |
| `value` | String | Value of textarea. Can bind to a variable. Ex: `bind:value={someVar}` |
| `placeholder` | String | Override default placeholder text with a string. |
| `rows` | Int | Default: `2`; Number of rows (height) to display. |
| `disabled` | Boolean | Default: `false` |
---
### Type
```javascript
import { Type } from 'figma-plugin-ds-svelte';
```
```html
<Type size="large" weight="bold">Content here</Type>
```
**Props**
| Prop | Type | Options/notes |
|:----------|:--------|:---------------------------------------------------------------------------------------|
| `size` | String | Default: `"small"`; Also accepts `"xsmall"`,`"large"`, `"xlarge"` |
| `weight` | String | Default: `"normal"`; Also accepts `"medium"`,`"bold"` |
| `color` | String | Default: `"black8"`; Pass the name of any Figma color var to this prop. `color="blue"`, Default color is white when inverse is `true` and no value specified |
| `inverse` | Boolean | Default: `false`; Optimizes letter-spacing for light on dark applications. |
---
## Tokens
**Color**
| Name | Var | Type | Notes |
|:--------------|:------------------|:-----------------|:--------------------------------------------------------------|
| blue | `--blue` | Accent | Ex: primary button, hyperlinks, focus/selected states |
| purple | `--purple` | Accent | Ex: components/instances |
| hot-pink | `--hot-pink` | Accent | Ex: smart selection handles |
| green | `--green` | Accent | Ex: Toolbar selections |
| red | `--red` | Accent | Ex: Error |
| yellow | `--yellow` | Accent | Ex: Caution/warning |
| black | `--black` | Basic foreground | Ex: active states |
| black8 | `--black8` | Basic foreground | 80% black, ex: most common black used in UI text and icons |
| black8-opaque | `--black8-opaque` | Basic foreground | Opaque version of black8 |
| black3 | `--black3` | Basic foreground | 30% black, ex: lower priority messages, disabled states |
| black3-opaque | `--black3-opaque` | Basic foreground | Opaque version of black3 |
| white | `--white` | Basic foreground | Used in same way as black8, but on dark backgrounds |
| white8 | `--white8` | Basic foreground | Rarely used, only in toolbar |
| white4 | `--white4` | Basic foreground | Used in same way as black3, Ex: option group headers in menus |
| white | `--white` | Basic background | (Duplicate) White is also the most common background color |
| grey | `--grey` | Basic background | Used behind controls in active state |
| silver | `--silver` | Basic background | Ex: horizontal separators, default canvas background |
| hud | `--hud` | Basic background | Ex: background for menus |
| toolbar | `--toolbar` | Basic background | Ex: background for the toolbar |
| black1 | `--black1` | Special | Ex: input placeholder underline, textarea border |
| blue3 | `--blue3` | Special | Ex: text range selection in inputs |
| purple4 | `--purple4` | Special | Ex: disabled components/instances |
| hover-fill | `--hover-fill` | Special | Hover state for items without borders, ex: icon button |
| selection-a | `--selection-a` | Special | Selected cells, ex: selected top level layer |
| selection-b | `--selection-b` | Special | Selected cells, ex: selected child layers |
| white2 | `--white2` | Special | Ex: menu separators |
**Type**
| Property | Var | Value | Notes |
|:-----------------|:-----------------------------------|:--------------------|:-------------------------------------------------------------|
| `font-family` | `--font-stack` | 'Inter', sans-serif | Default font everywhere |
| `font-size` | `--font-size-xsmall` | 11px | Most common font size |
| `font-size` | `--font-size-small` | 12px | Used in menus |
| `font-size` | `--font-size-large` | 13px | Rarely used in editor |
| `font-size` | `--font-size-xlarge` | 14px | Rarely used in editor |
| `font-weight` | `--font-weight-normal` | 400 | |
| `font-weight` | `--font-weight-medium` | 500 | |
| `font-weight` | `--font-weight-bold` | 600 | |
| `line-height` | `--font-line-height` | 16px | For use with xsmall and small font sizes |
| `line-height` | `--font-line-height-large` | 24px | For use with large and xlarge font sizes |
| `letter-spacing` | `--font-letter-spacing-pos-xsmall` | .005em | Optimized letter spacing for xsmall text on light background |
| `letter-spacing` | `--font-letter-spacing-neg-xsmall` | .01em | Optimized letter spacing for xsmall text on dark background |
| `letter-spacing` | `--font-letter-spacing-pos-small` | 0 | Optimized letter spacing for small text on light background |
| `letter-spacing` | `--font-letter-spacing-neg-small` | .005em | Optimized letter spacing for small text on dark background |
| `letter-spacing` | `--font-letter-spacing-pos-large` | -.0025em | Optimized letter spacing for large text on light background |
| `letter-spacing` | `--font-letter-spacing-neg-large` | .0025em | Optimized letter spacing for large text on dark background |
| `letter-spacing` | `--font-letter-spacing-pos-xlarge` | -.001em | Optimized letter spacing for xlarge text on light background |
| `letter-spacing` | `--font-letter-spacing-neg-xlarge` | -.001em | Optimized letter spacing for xlarge text on dark background |
**Border Radius**
| Var | Value | Notes |
|:------------------------|:------|:--------------------------------------|
| `--border-radius-small` | 2px | Ex: menus, input borders, icon button |
| `--border-radius-med` | 5px | Ex: visual bell, toasts |
| `--border-radius-large` | 6px | Ex: buttons |
**Shadows**
| Var | Notes |
|:----------------------------|:----------------------------|
| `--shadow-hud` | Ex: menus, tooltips, toasts |
| `--shadow-floating-window:` | Ex: modal, dialog |
**Sizes**
| Var | Value |
|:------------------|:------|
| `--size-xxxsmall` | 4px |
| `--size-xxsmall` | 8px |
| `--size-xsmall` | 16px |
| `--size-small` | 24px |
| `--size-medium` | 32px |
| `--size-large` | 40px |
| `--size-xlarge` | 48px |
| `--size-xxlarge` | 64px |
| `--size-huge` | 80px |