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

package/README.md

@@ -18,6 +18,7 @@ A powerful automation tool that bridges the gap between design and development b
 - [Prerequisites](#-prerequisites)
 - [Installation](#-installation)
 - [Usage](#-usage)
+- [Component Development](#-component-development)
 - [For Designers](#-for-designers)
 - [For Developers](#-for-developers)
 - [Common Tasks](#-common-tasks)
@@ -29,6 +30,36 @@ A powerful automation tool that bridges the gap between design and development b
 
 ## 🚀 Quick Start
 
+### For Component Usage
+
+```bash
+# Install the package
+npm install @deriv-com/quill-ui-v2
+
+# Use components in your app
+import { Button } from '@deriv-com/quill-ui-v2';
+```
+
+### For Token Usage (Custom Styling)
+
+```bash
+# Install the package
+npm install @deriv-com/quill-ui-v2
+
+# Import tokens in your app
+import '@deriv-com/quill-ui-v2/tokens.css';
+
+# Use tokens in your CSS
+.custom-element {
+  padding: var(--quill-semantic-size-spacing-16);
+  background: var(--quill-semantic-colour-background-canvas);
+}
+```
+
+**📖 See the [Token Usage Guide](docs/token-usage-guide.md) for complete documentation.**
+
+### For Development
+
 Get up and running in 5 minutes:
 
 ```bash
@@ -42,9 +73,8 @@ cp .env.example .env
 # 3. Sync tokens from Figma
 npm run tokens
 
-# 4. Use in your code
-# Import: <link rel="stylesheet" href="./src/tokens/index.css">
-# Use: <p style="color: var(--quill-core-color-blue-500)">Styled text</p>
+# 4. Build the package
+npm run build
 ```
 
 **New to the project?** Follow the [detailed installation guide](#-installation) below.
@@ -54,9 +84,11 @@ npm run tokens
 ## ✨ Features
 
 ### Core Capabilities
+
 - ✅ **Automatic Sync** - One command updates all tokens from Figma
 - ✅ **Multi-Collection Support** - Handle multiple token collections (primitives, semantic, etc.)
 - ✅ **Multi-File Output** - Organized CSS files by collection
+- ✅ **NPM Package Export** - Tokens available as separate CSS files for custom styling
 - ✅ **TypeScript Support** - Type-safe tokens with autocomplete
 - ✅ **Token Validation** - Automatic error detection and warnings
 - ✅ **Version Tracking** - Semantic versioning for changes
@@ -68,15 +100,15 @@ npm run tokens
 
 ### Generated Outputs
 
-| File | Purpose | Auto-Generated |
-|------|---------|----------------|
-| [`index.css`](src/tokens/index.css) | Main import file for all tokens | ✅ |
-| [`primitives.css`](src/tokens/primitives.css) | Base design tokens (colors, sizes) | ✅ |
-| [`semantic.css`](src/tokens/semantic.css) | Semantic tokens (spacing, radius) | ✅ |
-| [`figma-styles.css`](src/tokens/figma-styles.css) | Figma style tokens | ✅ |
-| [`tokens.d.ts`](src/tokens/tokens.d.ts) | TypeScript definitions | ✅ |
-| [`tokens.js`](src/tokens/tokens.js) | JavaScript module | ✅ |
-| `version.json` | Version metadata | ✅ |
+| File                                              | Purpose                            | Auto-Generated |
+| ------------------------------------------------- | ---------------------------------- | -------------- |
+| [`index.css`](src/tokens/index.css)               | Main import file for all tokens    | ✅             |
+| [`primitives.css`](src/tokens/primitives.css)     | Base design tokens (colors, sizes) | ✅             |
+| [`semantic.css`](src/tokens/semantic.css)         | Semantic tokens (spacing, radius)  | ✅             |
+| [`figma-styles.css`](src/tokens/figma-styles.css) | Figma style tokens                 | ✅             |
+| [`tokens.d.ts`](src/tokens/tokens.d.ts)           | TypeScript definitions             | ✅             |
+| [`tokens.js`](src/tokens/tokens.js)               | JavaScript module                  | ✅             |
+| `version.json`                                    | Version metadata                   | ✅             |
 
 ---
 
@@ -85,6 +117,7 @@ npm run tokens
 Before you begin, ensure you have:
 
 ### Required
+
 - **Node.js** >= 18.0.0 ([Download](https://nodejs.org/))
 - **npm** >= 9.0.0 (comes with Node.js)
 - **Figma account** with access to your design file
@@ -93,7 +126,7 @@ Before you begin, ensure you have:
 ### System Requirements
 
 | Platform | Supported | Tested |
-|----------|-----------|--------|
+| -------- | --------- | ------ |
 | macOS    | ✅ Yes    | ✅     |
 | Windows  | ✅ Yes    | ✅     |
 | Linux    | ✅ Yes    | ✅     |
@@ -109,6 +142,7 @@ npm install
 ```
 
 This installs:
+
 - `dotenv` (^17.2.3) - Environment variable management
 
 ### Step 2: Configure Figma Access
@@ -141,6 +175,7 @@ nano .env
 ```
 
 Add your credentials:
+
 ```env
 # Your Figma Personal Access Token
 FIGMA_ACCESS_TOKEN=figd_your_token_here
@@ -157,6 +192,7 @@ npm run tokens
 ```
 
 Expected output:
+
 ```
 🚀 Starting Figma token extraction...
 📡 Fetching from Figma REST API...
@@ -172,7 +208,119 @@ Expected output:
 
 ## 💻 Usage
 
-### Command Line
+### Using the NPM Package
+
+#### Install the Package
+
+```bash
+npm install @deriv-com/quill-ui-v2
+```
+
+#### Import Components (CSS Bundled)
+
+```javascript
+import { Button, Textfield, SearchField } from '@deriv-com/quill-ui-v2';
+
+// Components include their styles automatically
+<Button variant="primary">Click me</Button>
+```
+
+#### Import Tokens for Custom Styling
+
+```javascript
+// In your app entry point (main.tsx, App.tsx, etc.)
+import '@deriv-com/quill-ui-v2/tokens.css';
+
+// Now use tokens in your CSS
+```
+
+```css
+.custom-element {
+  padding: var(--quill-semantic-size-spacing-16);
+  background: var(--quill-semantic-colour-background-canvas);
+  color: var(--quill-semantic-colour-text-prominent-default);
+  border-radius: var(--quill-semantic-size-radius-8);
+}
+```
+
+#### Import Tokens in JavaScript
+
+```javascript
+import { tokens } from '@deriv-com/quill-ui-v2/tokens';
+
+const styles = {
+  padding: tokens['--quill-semantic-size-spacing-16'],
+  background: tokens['--quill-semantic-colour-background-canvas']
+};
+```
+
+#### Converting Figma MCP Output to Tokens
+
+When Figma MCP generates code, it outputs hard-coded values with token names in comments:
+
+```css
+/* ❌ Figma MCP Output */
+.header {
+  gap: 16px; /* Figma token: quill-semantic-spacing-16 */
+  padding: 16px 0; /* Figma token: quill-semantic-spacing-16 */
+  background-color: #ebecef; /* Figma token: tertiary/background/default */
+  border-radius: 999px; /* Figma token: size/radius */
+}
+```
+
+Convert to use design tokens:
+
+```css
+/* ✅ With Design Tokens */
+.header {
+  gap: var(--quill-semantic-size-spacing-16);
+  padding: var(--quill-semantic-size-spacing-16) 0;
+  background-color: var(--quill-semantic-colour-button-tertiary-bg-default);
+  border-radius: var(--quill-semantic-size-radius-999);
+}
+```
+
+#### Common Token Patterns
+
+```css
+/* Custom Button */
+.custom-button {
+  padding: var(--quill-semantic-size-spacing-12) var(--quill-semantic-size-spacing-20);
+  background: var(--quill-semantic-colour-button-primary-bg-default);
+  color: var(--quill-semantic-colour-button-primary-text);
+  border-radius: var(--quill-semantic-size-radius-999);
+  font-size: var(--quill-semantic-typography-body-standard-size);
+}
+
+/* Custom Card */
+.custom-card {
+  padding: var(--quill-semantic-size-spacing-24);
+  background: var(--quill-semantic-colour-background-surface);
+  border: 1px solid var(--quill-semantic-colour-border-default-default);
+  border-radius: var(--quill-semantic-size-radius-8);
+}
+
+/* Custom Text */
+.custom-heading {
+  font-family: var(--quill-semantic-typography-font-family);
+  font-size: var(--quill-semantic-typography-title-section-size);
+  color: var(--quill-semantic-colour-text-prominent-default);
+}
+```
+
+#### Available Token Categories
+
+- **Colors**: `--quill-semantic-colour-*` (text, background, border)
+- **Spacing**: `--quill-semantic-size-spacing-*` (4, 8, 16, 24, etc.)
+- **Sizing**: `--quill-semantic-size-width-height-*` (32, 48, 56, etc.)
+- **Border Radius**: `--quill-semantic-size-radius-*` (8, 16, 999)
+- **Typography**: `--quill-semantic-typography-*` (font-size, font-family, font-weight)
+
+---
+
+### Development Commands
+
+#### Command Line
 
 ```bash
 # Fetch from Figma and generate all files
@@ -191,21 +339,19 @@ npm run tokens:watch
 npm run tokens:ci
 ```
 
-### In HTML
+#### In HTML (Development)
 
 ```html
 <!DOCTYPE html>
 <html>
-<head>
-  <!-- Import all tokens -->
-  <link rel="stylesheet" href="./src/tokens/index.css">
-</head>
-<body>
-  <!-- Use CSS variables -->
-  <div style="color: var(--quill-core-color-blue-500)">
-    Custom styled element
-  </div>
-</body>
+  <head>
+    <!-- Import all tokens -->
+    <link rel="stylesheet" href="./src/tokens/index.css" />
+  </head>
+  <body>
+    <!-- Use CSS variables -->
+    <div style="color: var(--quill-core-color-blue-500)">Custom styled element</div>
+  </body>
 </html>
 ```
 
@@ -213,7 +359,7 @@ npm run tokens:ci
 
 ```css
 /* Import tokens */
-@import './src/tokens/index.css';
+@import "./src/tokens/index.css";
 
 /* Use in your styles */
 .my-button {
@@ -226,31 +372,31 @@ npm run tokens:ci
 ### In JavaScript/TypeScript
 
 ```typescript
-import { tokens } from './src/tokens/tokens.js';
-import type { TokenName, TokenValue } from './src/tokens/tokens';
+import { tokens } from "./src/tokens/tokens.js";
+import type { TokenName, TokenValue } from "./src/tokens/tokens";
 
 // Type-safe token access with autocomplete!
-const primaryColor: string = tokens['--quill-core-color-blue-500'];
-const spacing: string = tokens['--quill-core-spacing-md'];
+const primaryColor: string = tokens["--quill-core-color-blue-500"];
+const spacing: string = tokens["--quill-core-spacing-md"];
 
 // Use in dynamic styles
-element.style.setProperty('background-color', primaryColor);
-element.style.setProperty('padding', spacing);
+element.style.setProperty("background-color", primaryColor);
+element.style.setProperty("padding", spacing);
 ```
 
 ### In React
 
 ```tsx
-import './src/tokens/index.css';
-import { tokens } from './src/tokens/tokens';
+import "./src/tokens/index.css";
+import { tokens } from "./src/tokens/tokens";
 
 function Button({ children }: { children: React.ReactNode }) {
   return (
     <button
       style={{
-        backgroundColor: tokens['--quill-core-color-blue-500'],
-        padding: tokens['--quill-core-spacing-md'],
-        borderRadius: tokens['--quill-core-radius-lg'],
+        backgroundColor: tokens["--quill-core-color-blue-500"],
+        padding: tokens["--quill-core-spacing-md"],
+        borderRadius: tokens["--quill-core-radius-lg"],
       }}
     >
       {children}
@@ -261,6 +407,96 @@ function Button({ children }: { children: React.ReactNode }) {
 
 ---
 
+## 🧩 Component Development
+
+This design system includes comprehensive guidelines for building consistent, accessible components.
+
+### Getting Started with Components
+
+All components must follow the standardized structure and patterns defined in our documentation:
+
+- **[Component Guidelines](docs/guideline.md)** - Complete standards for building components
+- **[Component Prompt Template](docs/prompt.md)** - Fill-in template for creating new components
+
+### Component Structure
+
+Each component includes 6 required files:
+
+```
+src/components/{component-name}/
+├── {ComponentName}.tsx           # React component
+├── {ComponentName}.module.css    # Styles with design tokens
+├── {ComponentName}.stories.tsx   # Storybook stories
+├── {ComponentName}.spec.json     # Cross-platform specification
+├── index.ts                      # Public exports
+└── README.md                     # Documentation
+```
+
+### Quick Component Creation
+
+1. **Sync design tokens**: Run `npm run tokens` to sync from Figma
+2. **Review the guidelines**: Read [`docs/guideline.md`](docs/guideline.md)
+3. **Fill the prompt template**: Use [`docs/prompt.md`](docs/prompt.md)
+4. **Extract with Figma MCP**: Use Figma MCP tools to get component specs
+5. **Create all 6 files**: Generate from Figma data
+6. **Export component**: Add to `src/index.ts`
+
+### Example: Creating a Button from Figma
+
+```bash
+# 1. Sync tokens from Figma Variables
+npm run tokens
+
+# 2. Get Figma component node ID (e.g., "2074:7")
+
+# 3. Use Figma MCP tools to extract:
+# - get_design_context(nodeId)
+# - get_variable_defs(nodeId)
+# - get_screenshot(nodeId)
+# - get_metadata(nodeId)
+
+# 4. Generate component files from Figma data
+
+# 5. Export in src/index.ts
+```
+
+See [`docs/prompt.md`](docs/prompt.md) for complete Figma-driven examples.
+
+### Design Token Integration
+
+All components must use design tokens from `src/tokens/`:
+
+```css
+/* ✅ CORRECT - Use design tokens */
+.button {
+  background: var(--quill-semantic-background-action-brand-normal);
+  padding: var(--quill-semantic-spacing-24);
+  border-radius: var(--quill-semantic-radius-999);
+}
+
+/* ❌ WRONG - Never hardcode values */
+.button {
+  background: #0066cc;
+  padding: 24px;
+  border-radius: 999px;
+}
+```
+
+### Component Checklist
+
+Before submitting a component, verify:
+
+- [ ] All 6 files created
+- [ ] Uses design tokens (no hardcoded values)
+- [ ] All states implemented (hover, active, focus, disabled)
+- [ ] Storybook stories complete
+- [ ] Accessibility requirements met
+- [ ] TypeScript types exported
+- [ ] Component exported in `src/index.ts`
+- [ ] README documentation complete
+
+---
+
 ## 🎨 For Designers
 
 ### Setting Up Figma Variables
@@ -270,6 +506,7 @@ function Button({ children }: { children: React.ReactNode }) {
    - Semantic: Contextual tokens (spacing, radius, etc.)
 
 2. **Name Variables** using forward slashes for grouping:
+
    ```
    colour/blue/500
    size/spacing/md
@@ -284,12 +521,14 @@ function Button({ children }: { children: React.ReactNode }) {
 ### Best Practices
 
 ✅ **DO:**
+
 - Use consistent naming conventions
 - Group related tokens together
 - Document token purposes in descriptions
 - Test tokens in Dev Mode before syncing
 
 ❌ **DON'T:**
+
 - Use spaces or special characters in names
 - Create circular references
 - Delete tokens without coordinating with developers
@@ -323,11 +562,13 @@ This allows you to see CSS variable names in Figma's Dev Mode.
 ### Workflow
 
 1. **Sync tokens** when designers notify you of changes:
+
    ```bash
    npm run tokens
    ```
 
 2. **Review changes** before committing:
+
    ```bash
    git diff src/tokens/
    ```
@@ -351,29 +592,29 @@ module.exports = {
   theme: {
     extend: {
       colors: {
-        primary: 'var(--quill-core-color-blue-500)',
-        secondary: 'var(--quill-core-color-gray-500)',
+        primary: "var(--quill-core-color-blue-500)",
+        secondary: "var(--quill-core-color-gray-500)",
       },
       spacing: {
-        'xs': 'var(--quill-core-spacing-xs)',
-        'sm': 'var(--quill-core-spacing-sm)',
-        'md': 'var(--quill-core-spacing-md)',
-      }
-    }
-  }
-}
+        xs: "var(--quill-core-spacing-xs)",
+        sm: "var(--quill-core-spacing-sm)",
+        md: "var(--quill-core-spacing-md)",
+      },
+    },
+  },
+};
 ```
 
 #### Styled Components
 
 ```typescript
-import styled from 'styled-components';
-import { tokens } from './src/tokens/tokens';
+import styled from "styled-components";
+import { tokens } from "./src/tokens/tokens";
 
 const Button = styled.button`
-  background: ${tokens['--quill-core-color-blue-500']};
-  padding: ${tokens['--quill-core-spacing-md']};
-  border-radius: ${tokens['--quill-core-radius-lg']};
+  background: ${tokens["--quill-core-color-blue-500"]};
+  padding: ${tokens["--quill-core-spacing-md"]};
+  border-radius: ${tokens["--quill-core-radius-lg"]};
 `;
 ```
 
@@ -391,10 +632,12 @@ const Button = styled.button`
 ### Version Control
 
 **What to commit:**
+
 - ✅ All files in `src/tokens/`
 - ✅ `scripts/tokens/version.json` (optional)
 
 **What to ignore:**
+
 - ❌ `scripts/tokens/tokens.json` (raw data, can be regenerated)
 - ❌ `.env` (contains secrets)
 
@@ -410,6 +653,7 @@ npm run tokens:dry-run
 ```
 
 Output:
+
 ```
 🔍 Dry Run - Preview of Changes:
 ════════════════════════════════════════════════════════════
@@ -438,6 +682,7 @@ npm run tokens:watch
 ```
 
 The script will:
+
 - Poll Figma every 30 seconds (configurable)
 - Detect when tokens change
 - Prompt you to regenerate
@@ -451,6 +696,7 @@ npm run tokens:cached
 ```
 
 Useful when:
+
 - Testing configuration changes
 - Iterating on output formats
 - Working offline
@@ -463,6 +709,7 @@ npm run tokens:ci
 ```
 
 Features:
+
 - Exits with proper error codes
 - Shows detailed error messages
 - Prevents interactive prompts
@@ -474,14 +721,17 @@ See [CONFIGURATION.md](CONFIGURATION.md#cicd-integration) for complete CI/CD set
 
 ## 📚 Documentation
 
-| Document | Purpose | Audience |
-|----------|---------|----------|
-| **[README.md](README.md)** (this file) | Quick start and overview | Everyone |
-| **[CONFIGURATION.md](CONFIGURATION.md)** | Complete configuration guide | Developers |
-| **[API-REFERENCE.md](API-REFERENCE.md)** | Technical API documentation | Advanced developers |
+| Document                                 | Purpose                          | Audience            |
+| ---------------------------------------- | -------------------------------- | ------------------- |
+| **[README.md](README.md)** (this file)   | Quick start and overview         | Everyone            |
+| **[guideline.md](docs/guideline.md)**    | Figma-driven component standards | Developers          |
+| **[prompt.md](docs/prompt.md)**          | Figma MCP prompt templates       | Developers          |
+| **[CONFIGURATION.md](CONFIGURATION.md)** | Token extractor configuration    | Developers          |
+| **[API-REFERENCE.md](API-REFERENCE.md)** | Technical API documentation      | Advanced developers |
 
 ### Quick Links
 
+- **Components:** [Figma-Driven Guidelines](docs/guideline.md) • [Figma MCP Prompts](docs/prompt.md) • [Component Structure](#-component-development)
 - **Configuration:** [Environment Variables](CONFIGURATION.md#environment-variables) • [Config Class](CONFIGURATION.md#config-class) • [Collections](CONFIGURATION.md#collection-configuration)
 - **Advanced:** [CI/CD Setup](CONFIGURATION.md#cicd-integration) • [Watch Mode](CONFIGURATION.md#watch-mode) • [Batch API](CONFIGURATION.md#performance-optimization)
 - **API:** [Architecture](API-REFERENCE.md#architecture) • [Modules](API-REFERENCE.md#modules) • [Extending](API-REFERENCE.md#extending-the-system)
@@ -495,6 +745,7 @@ See [CONFIGURATION.md](CONFIGURATION.md#cicd-integration) for complete CI/CD set
 **Problem:** Environment variables not loaded
 
 **Solution:**
+
 ```bash
 # 1. Verify .env file exists
 ls -la .env
@@ -514,6 +765,7 @@ FIGMA_FILE_KEY=your_file_key_here
 **Problem:** Collection name mismatch between Figma and configuration
 
 **Solution:**
+
 1. Check your Figma collection names
 2. Names are normalized: `"My Colors"` → `my_colors`
 3. Update `COLLECTION_DATA` in configuration
@@ -527,6 +779,7 @@ FIGMA_FILE_KEY=your_file_key_here
 **Problem:** API connection or authentication issues
 
 **Solution:**
+
 ```bash
 # 1. Verify token is valid
 curl -H "X-Figma-Token: YOUR_TOKEN" \
@@ -547,6 +800,7 @@ ping api.figma.com
 **Problem:** TypeScript can't find token definitions
 
 **Solution:**
+
 ```typescript
 // 1. Ensure tokens.d.ts is generated
 // Check: src/tokens/tokens.d.ts exists
@@ -587,6 +841,7 @@ When reporting issues, please include:
 ### Adding Features
 
 1. **Create feature branch**
+
    ```bash
    git checkout -b feature/your-feature-name
    ```
@@ -597,6 +852,7 @@ When reporting issues, please include:
    - Update documentation
 
 3. **Test thoroughly**
+
    ```bash
    npm test
    npm run tokens
@@ -654,4 +910,5 @@ MIT License - see LICENSE file for details
 **Ready to sync your design system? Let's go! 🚀**
 
 ```bash
-npm run tokens
+npm run tokens
+```