GitHub tokens sync

.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) KALEIDOS INC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,83 @@
-# penpot-github-sync-plugin
-A Penpot plugin that syncs design tokens stored in Penpot with files stored in GitHub repositories.
+# Penpot Tokens Sync Plugin
+
+A professional, high-quality Penpot plugin designed to bridge the gap between Penpot design tokens and developer-friendly token formats (Tokens Studio/DTCG). Sync your tokens directly with GitHub repositories for a seamless Design-to-Code workflow.
+
+## 🚀 Purpose
+
+This plugin serves as a "Source of Truth" connector. It allows designers using Penpot to:
+1.  **Sync** the tokens with a GitHub repository using Push and Pull operations.
+2.  **Review** semantic differences before committing or applying changes to ensure design consistency.
+
+## ✨ Features
+
+-   **DTCG Support**: Full compatibility with the Design Tokens Community Group (DTCG) specification.
+-   **GitHub Integration**: Built-in support for GitHub sync using Personal Access Tokens (PAT).
+-   **Visual Diffing**: Review exactly what changed (Added, Modified, Removed) before applying updates.
+-   **Theme Management**: Support for multi-theme exports and token sets.
+-   **Zero Dependencies (Runtime)**: Lightweight, modular JavaScript architecture with no heavy external libraries in the plugin bundle.
+
+## 🛠 Setup Instructions
+
+### Prerequisites
+-   A Penpot account and a Penpot project.
+-   A GitHub account and a repository to store your tokens.
+-   [GitHub Personal Access Token (PAT)](https://github.com/settings/tokens) with `repo` scope.
+
+### Installation
+1.  Clone this repository:
+    ```bash
+    git clone https://github.com/tokens-studio/penpot-github-sync-plugin.git
+    cd penpot-github-sync-plugin
+    ```
+2.  Install dependencies:
+    ```bash
+    npm install
+    ```
+3.  Start the development server:
+    ```bash
+    npm run dev
+    ```
+4.  In Penpot, go to **Plugins** -> **Developer** -> **Create Plugin**.
+5.  Set the **URL** to `http://localhost:4400/manifest.json`.
+6.  Open the plugin in your Penpot file.
+
+## 🔄 GitHub Sync Functionality
+
+### 1. Adding a Provider
+Click the **+ Add Provider** button and fill in the details:
+-   **Name**: A label for this configuration.
+-   **Token**: Your GitHub PAT.
+-   **Repository**: The path to your repo (e.g., `owner/repo`).
+-   **Branch**: The branch to sync with (e.g., `main`).
+-   **Path**: The file path in the repo (e.g., `tokens/design-tokens.json`).
+
+### 2. Pushing Tokens (Design -> Code)
+-   Click **↑ Push** next to a provider.
+-   The plugin extracts your Penpot tokens and compares them with the remote file.
+-   Review the differences in the modal.
+-   Enter a commit message and confirm.
+
+### 3. Pulling Tokens (Code -> Design)
+-   Click **↓ Pull** next to a provider.
+-   The plugin fetches the remote tokens.
+-   Review the changes that will be applied to your Penpot file.
+-   Confirm to update your local sets, tokens, and themes.
+
+## 🧪 Development
+
+### Build for Production
+To generate a production-ready bundle:
+```bash
+npm run build
+```
+The output will be in the `dist/` directory.
+
+### Project Structure
+-   `src/plugin/`: Penpot API logic (runs in the Penpot environment).
+-   `src/ui/`: Plugin UI logic (runs in the iframe).
+-   `src/common/`: Shared utilities (e.g., semantic diff logic).
+-   `index.html`: Main UI template.
+-   `style.css`: Design system and component styles.
+
+## 📄 License
+MIT License. See [LICENSE](LICENSE) for details.

index.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Penpot Tokens Sync</title>
+  </head>
+  <body>
+    <!-- Main Dashboard View -->
+    <div id="main-view" class="view">
+      <header class="view-header">
+        <h1>Penpot Tokens Sync</h1>
+        <p class="subtitle">Sync your design tokens with Tokens Studio/DTCG format.</p>
+      </header>
+
+      <section class="sync-section">
+        <div class="section-header">
+          <h2>GitHub Sync</h2>
+          <button id="add-sync-btn" class="secondary-btn small">+ Add Provider</button>
+        </div>
+        <div id="providers-list" class="providers-list">
+          <!-- Providers will be rendered here -->
+        </div>
+      </section>
+    </div>
+
+    <!-- Sync Form View -->
+    <div id="sync-form-view" class="view" style="display: none">
+      <header class="view-header">
+        <h2 id="form-title">📦 Add Sync Provider</h2>
+      </header>
+
+      <form id="github-sync-form" class="sync-form">
+        <div class="form-group">
+          <label for="sync-name">Configuration Name</label>
+          <input type="text" id="sync-name" name="name" placeholder="e.g., My Project Tokens" required />
+        </div>
+        <div class="form-group">
+          <label for="sync-token">GitHub Personal Access Token (PAT)</label>
+          <input type="password" id="sync-token" name="token" placeholder="ghp_..." required />
+          <p class="help-text">Requires 'repo' scope.</p>
+        </div>
+        <div class="form-row">
+          <div class="form-group">
+            <label for="sync-repository">Repository (owner/repo)</label>
+            <input type="text" id="sync-repository" name="repository" placeholder="acme/design-system" required />
+          </div>
+          <div class="form-group">
+            <label for="sync-branch">Branch</label>
+            <input type="text" id="sync-branch" name="branch" placeholder="main" required />
+          </div>
+        </div>
+        <div class="form-group">
+          <label for="sync-path">Storage Path (in repo)</label>
+          <input type="text" id="sync-path" name="storagePath" placeholder="tokens.json" required />
+        </div>
+
+        <div class="form-actions">
+          <button type="button" id="cancel-sync" class="secondary-btn">Cancel</button>
+          <button type="submit" class="primary-btn">Save Configuration</button>
+        </div>
+      </form>
+    </div>
+
+    <!-- Modals -->
+    <div id="diff-modal" class="modal-overlay" style="display: none">
+      <div class="modal-content large">
+        <div class="modal-header">
+          <h2 id="diff-title">Review Changes</h2>
+          <button id="close-diff-btn" class="close-btn">&times;</button>
+        </div>
+        <div class="modal-body">
+          <p id="diff-message" class="diff-intro"></p>
+          <div id="diff-results" class="diff-scroll-area"></div>
+        </div>
+        <div class="modal-footer">
+          <button id="cancel-diff-btn" class="secondary-btn">Cancel</button>
+          <button id="confirm-diff-btn" class="primary-btn">Confirm & Sync</button>
+        </div>
+      </div>
+    </div>
+
+    <div id="commit-modal" class="modal-overlay" style="display: none">
+      <div class="modal-content">
+        <div class="modal-header">
+          <h2>Commit Message</h2>
+          <button id="close-commit-btn" class="close-btn">&times;</button>
+        </div>
+        <div class="modal-body">
+          <div class="form-group">
+            <label for="commit-message-input">What changed?</label>
+            <textarea id="commit-message-input" rows="3" placeholder="Updated colors from Penpot..."></textarea>
+          </div>
+        </div>
+        <div class="modal-footer">
+          <button id="cancel-commit-btn" class="secondary-btn">Cancel</button>
+          <button id="confirm-commit-btn" class="primary-btn">Push to GitHub</button>
+        </div>
+      </div>
+    </div>
+
+    <footer id="status" class="status"></footer>
+
+    <script type="module" src="/src/ui/index.js"></script>
+  </body>
+</html>