@deriv-com/quill-ui-v2 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +167 -52
  2. package/dist/index.d.ts +344 -15
  3. package/dist/quill-ui-v2.cjs +2 -2
  4. package/dist/quill-ui-v2.cjs.map +1 -1
  5. package/dist/quill-ui-v2.mjs +403 -78
  6. package/dist/quill-ui-v2.mjs.map +1 -1
  7. package/package.json +15 -4
package/README.md CHANGED
@@ -18,6 +18,7 @@ A powerful automation tool that bridges the gap between design and development b
18
18
  - [Prerequisites](#-prerequisites)
19
19
  - [Installation](#-installation)
20
20
  - [Usage](#-usage)
21
+ - [Component Development](#-component-development)
21
22
  - [For Designers](#-for-designers)
22
23
  - [For Developers](#-for-developers)
23
24
  - [Common Tasks](#-common-tasks)
@@ -54,6 +55,7 @@ npm run tokens
54
55
  ## ✨ Features
55
56
 
56
57
  ### Core Capabilities
58
+
57
59
  - ✅ **Automatic Sync** - One command updates all tokens from Figma
58
60
  - ✅ **Multi-Collection Support** - Handle multiple token collections (primitives, semantic, etc.)
59
61
  - ✅ **Multi-File Output** - Organized CSS files by collection
@@ -68,15 +70,15 @@ npm run tokens
68
70
 
69
71
  ### Generated Outputs
70
72
 
71
- | File | Purpose | Auto-Generated |
72
- |------|---------|----------------|
73
- | [`index.css`](src/tokens/index.css) | Main import file for all tokens | ✅ |
74
- | [`primitives.css`](src/tokens/primitives.css) | Base design tokens (colors, sizes) | ✅ |
75
- | [`semantic.css`](src/tokens/semantic.css) | Semantic tokens (spacing, radius) | ✅ |
76
- | [`figma-styles.css`](src/tokens/figma-styles.css) | Figma style tokens | ✅ |
77
- | [`tokens.d.ts`](src/tokens/tokens.d.ts) | TypeScript definitions | ✅ |
78
- | [`tokens.js`](src/tokens/tokens.js) | JavaScript module | ✅ |
79
- | `version.json` | Version metadata | ✅ |
73
+ | File | Purpose | Auto-Generated |
74
+ | ------------------------------------------------- | ---------------------------------- | -------------- |
75
+ | [`index.css`](src/tokens/index.css) | Main import file for all tokens | ✅ |
76
+ | [`primitives.css`](src/tokens/primitives.css) | Base design tokens (colors, sizes) | ✅ |
77
+ | [`semantic.css`](src/tokens/semantic.css) | Semantic tokens (spacing, radius) | ✅ |
78
+ | [`figma-styles.css`](src/tokens/figma-styles.css) | Figma style tokens | ✅ |
79
+ | [`tokens.d.ts`](src/tokens/tokens.d.ts) | TypeScript definitions | ✅ |
80
+ | [`tokens.js`](src/tokens/tokens.js) | JavaScript module | ✅ |
81
+ | `version.json` | Version metadata | ✅ |
80
82
 
81
83
  ---
82
84
 
@@ -85,6 +87,7 @@ npm run tokens
85
87
  Before you begin, ensure you have:
86
88
 
87
89
  ### Required
90
+
88
91
  - **Node.js** >= 18.0.0 ([Download](https://nodejs.org/))
89
92
  - **npm** >= 9.0.0 (comes with Node.js)
90
93
  - **Figma account** with access to your design file
@@ -93,7 +96,7 @@ Before you begin, ensure you have:
93
96
  ### System Requirements
94
97
 
95
98
  | Platform | Supported | Tested |
96
- |----------|-----------|--------|
99
+ | -------- | --------- | ------ |
97
100
  | macOS | ✅ Yes | ✅ |
98
101
  | Windows | ✅ Yes | ✅ |
99
102
  | Linux | ✅ Yes | ✅ |
@@ -109,6 +112,7 @@ npm install
109
112
  ```
110
113
 
111
114
  This installs:
115
+
112
116
  - `dotenv` (^17.2.3) - Environment variable management
113
117
 
114
118
  ### Step 2: Configure Figma Access
@@ -141,6 +145,7 @@ nano .env
141
145
  ```
142
146
 
143
147
  Add your credentials:
148
+
144
149
  ```env
145
150
  # Your Figma Personal Access Token
146
151
  FIGMA_ACCESS_TOKEN=figd_your_token_here
@@ -157,6 +162,7 @@ npm run tokens
157
162
  ```
158
163
 
159
164
  Expected output:
165
+
160
166
  ```
161
167
  🚀 Starting Figma token extraction...
162
168
  📡 Fetching from Figma REST API...
@@ -196,16 +202,14 @@ npm run tokens:ci
196
202
  ```html
197
203
  <!DOCTYPE html>
198
204
  <html>
199
- <head>
200
- <!-- Import all tokens -->
201
- <link rel="stylesheet" href="./src/tokens/index.css">
202
- </head>
203
- <body>
204
- <!-- Use CSS variables -->
205
- <div style="color: var(--quill-core-color-blue-500)">
206
- Custom styled element
207
- </div>
208
- </body>
205
+ <head>
206
+ <!-- Import all tokens -->
207
+ <link rel="stylesheet" href="./src/tokens/index.css" />
208
+ </head>
209
+ <body>
210
+ <!-- Use CSS variables -->
211
+ <div style="color: var(--quill-core-color-blue-500)">Custom styled element</div>
212
+ </body>
209
213
  </html>
210
214
  ```
211
215
 
@@ -213,7 +217,7 @@ npm run tokens:ci
213
217
 
214
218
  ```css
215
219
  /* Import tokens */
216
- @import './src/tokens/index.css';
220
+ @import "./src/tokens/index.css";
217
221
 
218
222
  /* Use in your styles */
219
223
  .my-button {
@@ -226,31 +230,31 @@ npm run tokens:ci
226
230
  ### In JavaScript/TypeScript
227
231
 
228
232
  ```typescript
229
- import { tokens } from './src/tokens/tokens.js';
230
- import type { TokenName, TokenValue } from './src/tokens/tokens';
233
+ import { tokens } from "./src/tokens/tokens.js";
234
+ import type { TokenName, TokenValue } from "./src/tokens/tokens";
231
235
 
232
236
  // Type-safe token access with autocomplete!
233
- const primaryColor: string = tokens['--quill-core-color-blue-500'];
234
- const spacing: string = tokens['--quill-core-spacing-md'];
237
+ const primaryColor: string = tokens["--quill-core-color-blue-500"];
238
+ const spacing: string = tokens["--quill-core-spacing-md"];
235
239
 
236
240
  // Use in dynamic styles
237
- element.style.setProperty('background-color', primaryColor);
238
- element.style.setProperty('padding', spacing);
241
+ element.style.setProperty("background-color", primaryColor);
242
+ element.style.setProperty("padding", spacing);
239
243
  ```
240
244
 
241
245
  ### In React
242
246
 
243
247
  ```tsx
244
- import './src/tokens/index.css';
245
- import { tokens } from './src/tokens/tokens';
248
+ import "./src/tokens/index.css";
249
+ import { tokens } from "./src/tokens/tokens";
246
250
 
247
251
  function Button({ children }: { children: React.ReactNode }) {
248
252
  return (
249
253
  <button
250
254
  style={{
251
- backgroundColor: tokens['--quill-core-color-blue-500'],
252
- padding: tokens['--quill-core-spacing-md'],
253
- borderRadius: tokens['--quill-core-radius-lg'],
255
+ backgroundColor: tokens["--quill-core-color-blue-500"],
256
+ padding: tokens["--quill-core-spacing-md"],
257
+ borderRadius: tokens["--quill-core-radius-lg"],
254
258
  }}
255
259
  >
256
260
  {children}
@@ -261,6 +265,96 @@ function Button({ children }: { children: React.ReactNode }) {
261
265
 
262
266
  ---
263
267
 
268
+ ## 🧩 Component Development
269
+
270
+ This design system includes comprehensive guidelines for building consistent, accessible components.
271
+
272
+ ### Getting Started with Components
273
+
274
+ All components must follow the standardized structure and patterns defined in our documentation:
275
+
276
+ - **[Component Guidelines](docs/guideline.md)** - Complete standards for building components
277
+ - **[Component Prompt Template](docs/prompt.md)** - Fill-in template for creating new components
278
+
279
+ ### Component Structure
280
+
281
+ Each component includes 6 required files:
282
+
283
+ ```
284
+ src/components/{component-name}/
285
+ ├── {ComponentName}.tsx # React component
286
+ ├── {ComponentName}.module.css # Styles with design tokens
287
+ ├── {ComponentName}.stories.tsx # Storybook stories
288
+ ├── {ComponentName}.spec.json # Cross-platform specification
289
+ ├── index.ts # Public exports
290
+ └── README.md # Documentation
291
+ ```
292
+
293
+ ### Quick Component Creation
294
+
295
+ 1. **Sync design tokens**: Run `npm run tokens` to sync from Figma
296
+ 2. **Review the guidelines**: Read [`docs/guideline.md`](docs/guideline.md)
297
+ 3. **Fill the prompt template**: Use [`docs/prompt.md`](docs/prompt.md)
298
+ 4. **Extract with Figma MCP**: Use Figma MCP tools to get component specs
299
+ 5. **Create all 6 files**: Generate from Figma data
300
+ 6. **Export component**: Add to `src/index.ts`
301
+
302
+ ### Example: Creating a Button from Figma
303
+
304
+ ```bash
305
+ # 1. Sync tokens from Figma Variables
306
+ npm run tokens
307
+
308
+ # 2. Get Figma component node ID (e.g., "2074:7")
309
+
310
+ # 3. Use Figma MCP tools to extract:
311
+ # - get_design_context(nodeId)
312
+ # - get_variable_defs(nodeId)
313
+ # - get_screenshot(nodeId)
314
+ # - get_metadata(nodeId)
315
+
316
+ # 4. Generate component files from Figma data
317
+
318
+ # 5. Export in src/index.ts
319
+ ```
320
+
321
+ See [`docs/prompt.md`](docs/prompt.md) for complete Figma-driven examples.
322
+
323
+ ### Design Token Integration
324
+
325
+ All components must use design tokens from `src/tokens/`:
326
+
327
+ ```css
328
+ /* ✅ CORRECT - Use design tokens */
329
+ .button {
330
+ background: var(--quill-semantic-background-action-brand-normal);
331
+ padding: var(--quill-semantic-spacing-24);
332
+ border-radius: var(--quill-semantic-radius-999);
333
+ }
334
+
335
+ /* ❌ WRONG - Never hardcode values */
336
+ .button {
337
+ background: #0066cc;
338
+ padding: 24px;
339
+ border-radius: 999px;
340
+ }
341
+ ```
342
+
343
+ ### Component Checklist
344
+
345
+ Before submitting a component, verify:
346
+
347
+ - [ ] All 6 files created
348
+ - [ ] Uses design tokens (no hardcoded values)
349
+ - [ ] All states implemented (hover, active, focus, disabled)
350
+ - [ ] Storybook stories complete
351
+ - [ ] Accessibility requirements met
352
+ - [ ] TypeScript types exported
353
+ - [ ] Component exported in `src/index.ts`
354
+ - [ ] README documentation complete
355
+
356
+ ---
357
+
264
358
  ## 🎨 For Designers
265
359
 
266
360
  ### Setting Up Figma Variables
@@ -270,6 +364,7 @@ function Button({ children }: { children: React.ReactNode }) {
270
364
  - Semantic: Contextual tokens (spacing, radius, etc.)
271
365
 
272
366
  2. **Name Variables** using forward slashes for grouping:
367
+
273
368
  ```
274
369
  colour/blue/500
275
370
  size/spacing/md
@@ -284,12 +379,14 @@ function Button({ children }: { children: React.ReactNode }) {
284
379
  ### Best Practices
285
380
 
286
381
  ✅ **DO:**
382
+
287
383
  - Use consistent naming conventions
288
384
  - Group related tokens together
289
385
  - Document token purposes in descriptions
290
386
  - Test tokens in Dev Mode before syncing
291
387
 
292
388
  ❌ **DON'T:**
389
+
293
390
  - Use spaces or special characters in names
294
391
  - Create circular references
295
392
  - Delete tokens without coordinating with developers
@@ -323,11 +420,13 @@ This allows you to see CSS variable names in Figma's Dev Mode.
323
420
  ### Workflow
324
421
 
325
422
  1. **Sync tokens** when designers notify you of changes:
423
+
326
424
  ```bash
327
425
  npm run tokens
328
426
  ```
329
427
 
330
428
  2. **Review changes** before committing:
429
+
331
430
  ```bash
332
431
  git diff src/tokens/
333
432
  ```
@@ -351,29 +450,29 @@ module.exports = {
351
450
  theme: {
352
451
  extend: {
353
452
  colors: {
354
- primary: 'var(--quill-core-color-blue-500)',
355
- secondary: 'var(--quill-core-color-gray-500)',
453
+ primary: "var(--quill-core-color-blue-500)",
454
+ secondary: "var(--quill-core-color-gray-500)",
356
455
  },
357
456
  spacing: {
358
- 'xs': 'var(--quill-core-spacing-xs)',
359
- 'sm': 'var(--quill-core-spacing-sm)',
360
- 'md': 'var(--quill-core-spacing-md)',
361
- }
362
- }
363
- }
364
- }
457
+ xs: "var(--quill-core-spacing-xs)",
458
+ sm: "var(--quill-core-spacing-sm)",
459
+ md: "var(--quill-core-spacing-md)",
460
+ },
461
+ },
462
+ },
463
+ };
365
464
  ```
366
465
 
367
466
  #### Styled Components
368
467
 
369
468
  ```typescript
370
- import styled from 'styled-components';
371
- import { tokens } from './src/tokens/tokens';
469
+ import styled from "styled-components";
470
+ import { tokens } from "./src/tokens/tokens";
372
471
 
373
472
  const Button = styled.button`
374
- background: ${tokens['--quill-core-color-blue-500']};
375
- padding: ${tokens['--quill-core-spacing-md']};
376
- border-radius: ${tokens['--quill-core-radius-lg']};
473
+ background: ${tokens["--quill-core-color-blue-500"]};
474
+ padding: ${tokens["--quill-core-spacing-md"]};
475
+ border-radius: ${tokens["--quill-core-radius-lg"]};
377
476
  `;
378
477
  ```
379
478
 
@@ -391,10 +490,12 @@ const Button = styled.button`
391
490
  ### Version Control
392
491
 
393
492
  **What to commit:**
493
+
394
494
  - ✅ All files in `src/tokens/`
395
495
  - ✅ `scripts/tokens/version.json` (optional)
396
496
 
397
497
  **What to ignore:**
498
+
398
499
  - ❌ `scripts/tokens/tokens.json` (raw data, can be regenerated)
399
500
  - ❌ `.env` (contains secrets)
400
501
 
@@ -410,6 +511,7 @@ npm run tokens:dry-run
410
511
  ```
411
512
 
412
513
  Output:
514
+
413
515
  ```
414
516
  🔍 Dry Run - Preview of Changes:
415
517
  ════════════════════════════════════════════════════════════
@@ -438,6 +540,7 @@ npm run tokens:watch
438
540
  ```
439
541
 
440
542
  The script will:
543
+
441
544
  - Poll Figma every 30 seconds (configurable)
442
545
  - Detect when tokens change
443
546
  - Prompt you to regenerate
@@ -451,6 +554,7 @@ npm run tokens:cached
451
554
  ```
452
555
 
453
556
  Useful when:
557
+
454
558
  - Testing configuration changes
455
559
  - Iterating on output formats
456
560
  - Working offline
@@ -463,6 +567,7 @@ npm run tokens:ci
463
567
  ```
464
568
 
465
569
  Features:
570
+
466
571
  - Exits with proper error codes
467
572
  - Shows detailed error messages
468
573
  - Prevents interactive prompts
@@ -474,14 +579,17 @@ See [CONFIGURATION.md](CONFIGURATION.md#cicd-integration) for complete CI/CD set
474
579
 
475
580
  ## 📚 Documentation
476
581
 
477
- | Document | Purpose | Audience |
478
- |----------|---------|----------|
479
- | **[README.md](README.md)** (this file) | Quick start and overview | Everyone |
480
- | **[CONFIGURATION.md](CONFIGURATION.md)** | Complete configuration guide | Developers |
481
- | **[API-REFERENCE.md](API-REFERENCE.md)** | Technical API documentation | Advanced developers |
582
+ | Document | Purpose | Audience |
583
+ | ---------------------------------------- | -------------------------------- | ------------------- |
584
+ | **[README.md](README.md)** (this file) | Quick start and overview | Everyone |
585
+ | **[guideline.md](docs/guideline.md)** | Figma-driven component standards | Developers |
586
+ | **[prompt.md](docs/prompt.md)** | Figma MCP prompt templates | Developers |
587
+ | **[CONFIGURATION.md](CONFIGURATION.md)** | Token extractor configuration | Developers |
588
+ | **[API-REFERENCE.md](API-REFERENCE.md)** | Technical API documentation | Advanced developers |
482
589
 
483
590
  ### Quick Links
484
591
 
592
+ - **Components:** [Figma-Driven Guidelines](docs/guideline.md) • [Figma MCP Prompts](docs/prompt.md) • [Component Structure](#-component-development)
485
593
  - **Configuration:** [Environment Variables](CONFIGURATION.md#environment-variables) • [Config Class](CONFIGURATION.md#config-class) • [Collections](CONFIGURATION.md#collection-configuration)
486
594
  - **Advanced:** [CI/CD Setup](CONFIGURATION.md#cicd-integration) • [Watch Mode](CONFIGURATION.md#watch-mode) • [Batch API](CONFIGURATION.md#performance-optimization)
487
595
  - **API:** [Architecture](API-REFERENCE.md#architecture) • [Modules](API-REFERENCE.md#modules) • [Extending](API-REFERENCE.md#extending-the-system)
@@ -495,6 +603,7 @@ See [CONFIGURATION.md](CONFIGURATION.md#cicd-integration) for complete CI/CD set
495
603
  **Problem:** Environment variables not loaded
496
604
 
497
605
  **Solution:**
606
+
498
607
  ```bash
499
608
  # 1. Verify .env file exists
500
609
  ls -la .env
@@ -514,6 +623,7 @@ FIGMA_FILE_KEY=your_file_key_here
514
623
  **Problem:** Collection name mismatch between Figma and configuration
515
624
 
516
625
  **Solution:**
626
+
517
627
  1. Check your Figma collection names
518
628
  2. Names are normalized: `"My Colors"` → `my_colors`
519
629
  3. Update `COLLECTION_DATA` in configuration
@@ -527,6 +637,7 @@ FIGMA_FILE_KEY=your_file_key_here
527
637
  **Problem:** API connection or authentication issues
528
638
 
529
639
  **Solution:**
640
+
530
641
  ```bash
531
642
  # 1. Verify token is valid
532
643
  curl -H "X-Figma-Token: YOUR_TOKEN" \
@@ -547,6 +658,7 @@ ping api.figma.com
547
658
  **Problem:** TypeScript can't find token definitions
548
659
 
549
660
  **Solution:**
661
+
550
662
  ```typescript
551
663
  // 1. Ensure tokens.d.ts is generated
552
664
  // Check: src/tokens/tokens.d.ts exists
@@ -587,6 +699,7 @@ When reporting issues, please include:
587
699
  ### Adding Features
588
700
 
589
701
  1. **Create feature branch**
702
+
590
703
  ```bash
591
704
  git checkout -b feature/your-feature-name
592
705
  ```
@@ -597,6 +710,7 @@ When reporting issues, please include:
597
710
  - Update documentation
598
711
 
599
712
  3. **Test thoroughly**
713
+
600
714
  ```bash
601
715
  npm test
602
716
  npm run tokens
@@ -654,4 +768,5 @@ MIT License - see LICENSE file for details
654
768
  **Ready to sync your design system? Let's go! 🚀**
655
769
 
656
770
  ```bash
657
- npm run tokens
771
+ npm run tokens
772
+ ```