handoff-app 0.15.2 → 0.17.0

package/.eslintrc.json

@@ -1,4 +1,4 @@
 {
-  "extends": "next/core-web-vitals",
+  "extends": ["next", "prettier"],
   "ignorePatterns": ["./src/app/out/**/*", "**/*.js"]
 }

package/.prettierignore

@@ -1,2 +0,0 @@
-*.sass
-*.css

package/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+    "trailingComma": "es5",
+    "semi": true,
+    "tabWidth": 2,
+    "singleQuote": true,
+    "jsxSingleQuote": true,
+    "plugins": ["prettier-plugin-tailwindcss"]
+  }

package/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "explicit"
+  },
+  "[xml]": {
+    "editor.defaultFormatter": "redhat.vscode-xml"
+  }
+}

package/Changelog.md

@@ -6,21 +6,372 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.17.0] - 2025-08-06
+
+## Major Highlights
+
+### Vite Migration
+
+The project has transitioned from Webpack to Vite as the new build tool. This significantly improves performance, simplifies configuration, and lays the groundwork for future extensibility. Legacy integration steps and commands related to Webpack have been removed.
+
+### Modularization via `handoff-core`
+
+Core token pipeline logic has been extracted into a new shared package: `handoff-core`.
+This change makes the internal architecture of `handoff-app` cleaner and enables easier maintenance across related tools like the Figma plugin.
+
+### SSR and Hydration Support
+
+Initial support for Server-Side Rendering (SSR) and hydration is now available.
+
+- SSR is enabled for static previews and production-ready rendering
+- Hydration allows React components to become interactive after being statically rendered
+- These features are considered stable but may still evolve in upcoming releases
+
+### JavaScript-Based Configuration
+
+All configuration files now support JavaScript in addition to JSON.
+You can now define your config using `handoff.config.js` or `handoff.config.cjs`, and other related files (such as component config files) also support JS formats.
+JSON is still supported, but JavaScript usage is encouraged for better flexibility.
+
+## Hook-Based Extensibility
+
+A new hook system allows developers to customize parts of the build and schema pipeline.
+**Available hooks:**
+
+- `validateComponent`
+- `ssrBuildConfig`
+- `clientBuildConfig`
+- `getSchemaFromExports`
+- `schemaToProperties`
+- `jsBuildConfig`
+- `cssBuildConfig`
+- `htmlBuildConfig`
+
+## Additional Features
+
+- Component schema export support to help generate documentation tables and property lists
+- Preview filtering to improve navigation in large component libraries
+- New transform generates `.tsx` pages from `.mdx` for better compatibility with typed docs
+- Replaced use of unofficial Next.js APIs with `cross-spawn` for build and dev processes
+- More informative error handling and validation messages
+- Default doc format now set to `.mdx`
+
+## Cleanup and Refactors
+
+- Removed deprecated integrations and plugin code
+- Dropped part of unused dependencies including `axios`
+- Standardized configuration logic and naming
+- Improved fallback behavior for missing component CSS or schema
+- Cleaned up type definitions and utility functions
+
+## Compatibility Notes
+
+- Now tested with React 19 and Next.js 15
+- Older React and Next versions may no longer be compatible
+
+## [0.16.0] - 2025-06-03
+
+This release is a major reorganization of Handoff. We've preserved the core
+Figma Token ETL behavior, but this release significantly rethinks and improves
+the documentation application.
+
+**This is a significant breaking change. We recommend starting from a fresh
+project.** Its possible to upgrade an existing Handoff project, but its
+easier to start fresh. Previous versions of handoff depended on specific
+structure. We're working to remove any structure or conventions, so you can
+use handoff in any project as you see fit.
+
+Contact us if you need help upgrading a legacy project handoff@convertiv.com.
+
+### Justification
+
+The Handoff documentation app was initial designed to complement the token e
+xtraction and document simple tokens. Over time, we added the ability to
+document Figma components in the application. We supported integrations that
+would allow users to describe Figma components in code.
+
+As we built out more complex design system documentation, we quickly hit the limits
+of what we could build and describe with that simple system. We needed a way
+to flexibly describe components - both defined in Figma, and standalone custom
+components. There are other open source products like Storybook that have some
+of this functionality but we were looking for a more flexible, and robust
+architecture for describing and distributing components across ecosystems.
+
+This release does a number major things -
+
+- Introduces a new component architecture, allowing users to describe components
+  using handlebars, css, and JSON
+  - These components are built, compiled, and validated on each handoff build. The
+    build system is designed to be highly configurable.
+  - Each component has a set of typed properties allowing users to pass pass in
+    data to the component, and visualize variations
+  - Components can be annotated with metadata to allow users to provide robust
+    usage guidelines.
+  - Each component is semver versioned
+  -
+- Publishes a robust API at /api/components.json that allows remote systems to
+  query the
+  - Each component is published at /api/component/{name}.json. This allows systems
+    to fetch just the relevant component.
+- Completely redesigns and rearchitects the application.
+  - Redesigned using shadCn tailwind components
+  - Reorganized the information architecture to default to best practice in
+    organizing foundations, systems and guidelines.
+  - This architecture and design can be customized
+
+See the demo site at demo.handoff.com and the demo code at h
+https://github.com/Convertiv/handoff-demo to have a sample of how this should be
+structured
+
+## Component Structure
+
+In this version components should be stored at `{integrationPath}/components`.
+Each integration should be in a folder with a unique name. This name will be
+used as the id for the component.
+
+Within each component folder, there should be at least one folder, named
+with a semver name. The structure of this should look like
+
+- {integrationPath}
+  - components
+    - component1
+      - 1.0.0
+        - component1.json - Describes the component in a JSON format documented below
+        - component1.hbs - A handlebar template to describe the markup of the component
+        - component1.scss - An optional style sheet to include with the project
+        - component1.js - An optional js file to include with the project
+
+### Minimum Component JSON
+
+This is a sample json component to show how you can structure the component
+documenation. Most of this is metadata used to construct robust documentation
+for users.
+
+The two important semantic sections are `previews` and `properties`. Properties
+defines a list of properties the component accepts. They are defined using the
+OpenAPI json specification.
+
+Once you define a list of properties, you can then define a list of previews.
+Each preview defines values for the properties. Handoff will then render a set
+of html previews of your component. This way you can render variations
+simply.
+
+```JSON
+{
+  "title": "Accordion",
+  "image": "https://placehold.co/1360x900",
+  "description": "Collapsible sections for toggling sections of content on and off.",
+  "figma": "https://www.figma.com/design/0gKWw8gYChpItKWzh8o23N/SS%26C-Design-System?node-id=301-598&t=qoaWE7Tx8sH4njGu-4",
+  "type": "block",
+  "group": "Accordion",
+  "categories": ["Components"],
+  "tags": ["accordion"],
+  "should_do": ["Show a list of items in an accordion format.", "Allow users to expand and collapse each item individually."],
+  "should_not_do": ["Use this component for a large number of items."],
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2021-01-01",
+      "changes": ["Initial version."]
+    }
+  ],
+  "previews": {
+    "generic": {
+      "title": "Generic",
+      "values": {
+        "id": "accordion",
+        "items": [
+          {
+            "id": "accordion-item-1",
+            "title": "Accordion Item 1",
+            "paragraph": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.",
+            "image": {
+              "url": "https://placehold.co/1360x900",
+              "alt": "Image alt text"
+            }
+          },
+          }
+        ]
+      }
+    }
+  },
+  "properties": {
+    "id": {
+      "name": "ID",
+      "description": "Unique identifier for the accordion.",
+      "type": "text",
+      "default": "accordion",
+      "rules": {
+        "required": true,
+        "content": {
+          "min": 5,
+          "max": 25
+        },
+        "pattern": "^[a-z0-9-]+$"
+      }
+    },
+    "items": {
+      "name": "Items",
+      "description": "Accordion items",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "name": "ID",
+            "description": "Unique identifier for the accordion item.",
+            "type": "text",
+            "default": "accordion-item-1",
+            "rules": {
+              "required": true,
+              "content": {
+                "min": 5,
+                "max": 25
+              },
+              "pattern": "^[a-z0-9-]+$"
+            }
+          },
+          "title": {
+            "name": "Title",
+            "description": "Title of the accordion item.",
+            "type": "text",
+            "default": "Accordion Item 1",
+            "rules": {
+              "required": true,
+              "content": {
+                "min": 5,
+                "max": 25
+              }
+            }
+          },
+          "paragraph": {
+            "name": "Paragraph",
+            "description": "Paragraph of the accordion item.",
+            "type": "text",
+            "default": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.",
+            "rules": {
+              "required": true,
+              "content": {
+                "min": 5,
+                "max": 100
+              }
+            }
+          },
+          "image": {
+            "name": "Image",
+            "description": "Image of the accordion item.",
+            "type": "image",
+            "default": {
+              "url": "https://placehold.co/1360x900",
+              "alt": "Image alt text"
+            },
+            "rules": {
+              "required": true,
+              "dimensions": {
+                "min": {
+                  "width": 1360,
+                  "height": 900
+                },
+                "max": {
+                  "width": 1360,
+                  "height": 900
+                }
+              }
+            }
+          }
+        }
+      },
+      "rules": {
+        "required": true,
+        "min": 1,
+        "max": 10
+      }
+    }
+  }
+}
+```
+
+### Handlebars Templates
+
+We anticipate allowing other templating systems in the future, but in this
+version, we support handlebars with limited logic. Using Handlebars allows
+us to create a simple system that will be compatible with most downstream
+platforms.
+
+There are two special feature of this handlebars file -
+
+- `#field` This allows you wrap a field in a tag. This allows handoff to inject
+  metadata around a field to make the field inline editable, and to allow us to
+  open a sidebar with metadata about the property. You don't have to use this
+  but its helpful.
+- `style` and `script` - These tags allow us to inject automatically the built
+  script and style artifacts.
+
+```html
+<head>
+  {{{style}}} {{{script}}}
+</head>
+<body class="preview-body">
+  <section class="py-lg-12 py-8">
+    <div class="container">
+      <div class="row justify-content-center">
+        <div class="col-12 col-lg-10">
+          <div class="accordion accordion-spaced" id="{{properties.id}}">
+            {{#each properties.items}}
+            <div class="accordion-item">
+              <h3 class="accordion-header" id="{{../properties.id}}-heading-{{this.id}}">
+                <button
+                  class="accordion-button"
+                  type="button"
+                  data-bs-toggle="collapse"
+                  data-bs-target="#{{../properties.id}}-collapse-{{this.id}}"
+                  aria-expanded="true"
+                  aria-controls="{{../properties.id}}-collapse-{{this.id}}"
+                >
+                  {{#field "items.title" }}{{this.title}}{{/field}}
+                </button>
+              </h3>
+              <div
+                id="{{../properties.id}}-collapse-{{this.id}}"
+                class="accordion-collapse collapse"
+                aria-labelledby="{{this.id}}"
+                data-bs-parent="#{{../properties.id}}-heading-{{this.id}}"
+              >
+                <div class="accordion-body w-lg-90 mx-lg-auto fs-lg">
+                  <p>{{#field "items.paragraph" }}{{this.paragraph}}{{/field}}</p>
+                </div>
+              </div>
+            </div>
+            {{/each}}
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+</body>
+```
+
+### Bugfixes
+
 ## [0.15.2] - 2024-12-11
+
 This release fixes a small bug when pulling foundation tokens with nested names.
 
 ### Bugfixes
-- Figma's name schema delivers names as {group}/{name}. If your foundation 
-(color, shadow, etc) names include a slash `Blue/100` Handoff would only grab
-the first part of that name, and construct the token excluding the remaining
-data. This patch resolves that so instead of getting `primitive-blue` you will
-now get `primitive-blue-100` as your token.
+
+- Figma's name schema delivers names as {group}/{name}. If your foundation
+  (color, shadow, etc) names include a slash `Blue/100` Handoff would only grab
+  the first part of that name, and construct the token excluding the remaining
+  data. This patch resolves that so instead of getting `primitive-blue` you will
+  now get `primitive-blue-100` as your token.
 
 ## [0.15.1] - 2024-11-27
-This is a minor release to fix several small typing issues that cause problems 
+
+This is a minor release to fix several small typing issues that cause problems
 in the linter when running as a local NPM package.
 
 ### Bugfixes
+
 - Fixes a typing issue in the transformers when including the handoff core package
 - Fixes a typing issue when including the ReferenceObject type
 
@@ -37,8 +388,8 @@ to structure and reuse styles across multiple large components.
   component styles in the tokens export. This allows you to use foundation styles
   as variables in component styles in CSS, SASS, and Style Dictionaries.
   - To enable, set `useVariables` to `true` in the `handoff.config.json` file.
-  - You can also enable variable support via the `.env` var 
-  `HANDOFF_USE_VARIABLES`. You can use a boolean or string ("true"/"false")
+  - You can also enable variable support via the `.env` var
+    `HANDOFF_USE_VARIABLES`. You can use a boolean or string ("true"/"false")
   - When enabled, Handoff will create variable references in the component styles
     for the foundation styles wherever possible instead of using the string value.
   - For example a color foundation style `Blue` in the `Primary` color group
@@ -169,7 +520,6 @@ This release fixes a couple of small path issues that affect running 0.13.0 from
 ### Changes
 
 - **Integration System Overhaul**
-
   - **Local Integrations Only:** From this release onward, only local (ejected) integrations are supported. Handoff will automatically use the locally found integration.
     - Create a new local integration using `handoff-app make:integration` (or `eject:integration` which is still supported as an alias).
     - Since there is no need to specify integration information, integration options in `handoff.config.json` such as name and version are no longer recognized, making the integration section of `handoff.config.json` obsolete.

package/components.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "style": "new-york",
+    "rsc": false,
+    "tsx": true,
+    "tailwind": {
+      "config": "tailwind.config.ts",
+      "css": "src/app/css/index.css",
+      "baseColor": "zinc",
+      "cssVariables": true,
+      "prefix": ""
+    },
+    "aliases": {
+      "components": "src/app/components",
+      "utils": "src/app/lib/utils",
+      "ui": "src/app/components/ui",
+      "lib": "src/app/lib",
+      "hooks": "src/app/hooks"
+    },
+    "iconLibrary": "lucide"
+  }

package/config/docs/{assets → foundations}/icon.md

@@ -1,6 +1,6 @@
 ---
-title: Iconography
+title: Icon Library
 description: Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.
-metaTitle: 'Fonts | Handoff Design System'
+metaTitle: 'Icon Library | Handoff Design System'
 metaDescription: 'Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.'
----
+---

package/config/docs/{assets → foundations}/icons.md

@@ -1,6 +1,6 @@
 ---
-title: Iconography
+title: Icon Library
 description: Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.
-metaTitle: 'Fonts | Handoff Design System'
+metaTitle: 'Icon Library | Handoff Design System'
 metaDescription: 'Set of icons used to provide users with a way to process information faster and instinctively recognize actions signified by the icon.'
----
+---

package/config/docs/foundations.md

@@ -1,23 +1,74 @@
 ---
 title: Design Foundations
 description: Sets of recommendations on how to apply design principles to provide a positive user experience.
-weight: 5
+weight: 0
 image: hero-design
 menuTitle: 'Foundations'
 metaTitle: 'Design Foundations | Handoff Design System'
 metaDescription: 'Sets of recommendations on how to apply design principles to provide a positive user experience.'
 enabled: true
-menu: 
-  - path: foundations/colors
-    title: Colors
-    image: hero-colors
-  - path: foundations/effects
-    title: Effects
-    image: hero-effects
-  - path: foundations/logo
-    title: Logos
-    image: react
-  - path: foundations/typography
-    title: Typography
-    image: hero-design
+menu:
+  - title: Getting Started
+    menu:
+      - path: foundations
+        title: Foundations
+  - title: Foundations
+    menu:
+      - path: foundations/logo
+        title: Logo
+        image: react
+        menu:
+          - path: foundations/logo
+            title: Overview
+          - path: foundations/logo/resources
+            title: Resources
+      - path: foundations/colors
+        title: Colors
+        image: hero-colors
+        menu:
+          - path: foundations/colors
+            title: Our Colors
+          - path: foundations/colors/guidelines
+            title: Guidelines
+      - path: foundations/typography
+        title: Typography
+        image: hero-design
+        menu:
+          - path: foundations/typography
+            title: Overview
+          - path: foundations/typography/guidelines
+            title: Guidelines
+          - path: foundations/typography/resources
+            title: Resources
+      - path: foundations/grid
+        title: Grid
+        image: hero-effects
+      - path: foundations/effects
+        title: Effects
+        image: hero-effects
+        menu:
+          - path: foundations/effects
+            title: Our Effects
+          - path: foundations/effects/guidelines
+            title: Guidelines
+          - path: foundations/effects/resources
+            title: Resources
+      - path: foundations/icons
+        title: Icons
+        image: hero-effects
+        menu:
+          - path: foundations/icons
+            title: Library
+          - path: foundations/icons/guidelines
+            title: Guidelines
+  - title: Assets
+    menu:
+      - path: foundations/images
+        title: Images
+        image: hero-effects
+        menu:
+          - path: foundations/icons
+            title: Library
+          - path: foundations/icons/guidelines
+            title: Guidelines
 ---

package/config/docs/guidelines.md

@@ -0,0 +1,11 @@
+---
+title: Guidelines
+description: How to build out a robust project built on the designs, tokens, and components documented here.
+weight: 10
+image: hero-components
+menuTitle: 'Guidelines'
+metaTitle: 'Guidelines | Handoff Design System'
+metaDescription: 'How to build out a robust project built on the designs, tokens, and components documented here.'
+enabled: true
+menu:
+---

package/config/docs/{components → system}/alert.md

@@ -5,6 +5,7 @@ image: component-alert
 metaTitle: 'Alerts | Handoff Design System'
 metaDescription: 'Alerts are used to communicate a state that affects a system, feature or page. They are used to provide feedback about an action that has taken place.'
 ---
+
 ### Accessibility
 
 Make it clear what this alert does for the user.
@@ -12,18 +13,18 @@ Make it clear what this alert does for the user.
 <div className="c-do-dont">
   <div className="c-do-dont__do">
 
-<Icon name="check" className="" /> DO
+<Check /> DO
 
 - What to do with alerts
 
   </div>
   <div className="c-do-dont__dont">
 
-<Icon name="x" className="" /> DON&apos;T
+<X /> DON&apos;T
 
 - What not to do with alerts
 
   </div>
 </div>
 
----
+---

package/config/docs/{components → system}/button.md

@@ -13,7 +13,7 @@ Make it clear what this button does for the user.
 <div className="c-do-dont">
   <div className="c-do-dont__do">
 
-<Icon name="check" className="" /> DO
+<Check /> DO
 
 - Make it clear what this button does for the user.
 - Use at most two buttons in one group.
@@ -22,7 +22,7 @@ Make it clear what this button does for the user.
   </div>
   <div className="c-do-dont__dont">
 
-<Icon name="x" className="" /> DON&apos;T
+<X /> DON&apos;T
 
 - Use more than two words for call to action.
 - First letter of each sentence defaults to a capital letter.

package/config/docs/{components → system}/checkbox.md

@@ -13,18 +13,18 @@ Make it clear what this checkboxes does for the user.
 <div className="c-do-dont">
   <div className="c-do-dont__do">
 
-<Icon name="check" className="" /> DO
+<Check /> DO
 
 - What to do with checkboxes
 
   </div>
   <div className="c-do-dont__dont">
 
-<Icon name="x" className="" /> DON&apos;T
+<X /> DON&apos;T
 
 - What not to do with checkboxes
 
   </div>
 </div>
 
----
+---

package/config/docs/{components → system}/input.md

@@ -14,18 +14,18 @@ Make it clear what this input does for the user.
 <div className="c-do-dont">
   <div className="c-do-dont__do">
 
-<Icon name="check" className="" /> DO
+<Check /> DO
 
 - What to do with inputs
 
   </div>
   <div className="c-do-dont__dont">
 
-<Icon name="x" className="" /> DON&apos;T
+<X /> DON&apos;T
 
 - What not to do with inputs
 
   </div>
 </div>
 
----
+---