Shoelace Make Kit

A React wrapper package for the Shoelace web component design system, built specifically for use with Figma Make (a prompt-to-prototype tool that only supports React).

Problem

Figma Make is React-only. Teams using Lit-based design systems (like Shoelace) can't integrate their components directly, causing prototypes to drift from their actual design system.

Solution

This package wraps all 58 Shoelace Lit web components as native React components using @lit/react. The output is an npm package that Figma Make can consume directly — no runtime translation needed.

The approach is generalizable to any Lit-based design system — see workflow.md for the step-by-step process.

What's Included

@stoovles/shoelace-make-kit/
├── src/
│   ├── components/      # 58 React wrapper files (one per Shoelace component)
│   ├── index.ts          # Barrel export for all components
│   └── setup.ts          # Theme + icon CDN setup (side-effect import)
├── guidelines/           # Markdown guidelines for Figma Make's AI
│   ├── Guidelines.md     # Package overview and reading order (Make kit entry point)
│   ├── setup.md          # Theme and dark mode setup
│   ├── styling.md        # Shadow DOM and styling constraints
│   ├── tokens.md         # Design token reference
│   └── components/       # Per-component usage guides (props, events, slots, examples)
├── test-app/             # Vite + React test app with comprehensive component demos
├── vite.config.ts        # Vite library-mode build config
├── tsconfig.json
└── package.json

Quick Start

Install

npm install
npm run build

Use in a React app

// Entry point — load themes and icon CDN path
import '@stoovles/shoelace-make-kit/setup';

// Import components
import { SlButton, SlInput, SlDialog } from '@stoovles/shoelace-make-kit';

function App() {
  return <SlButton variant="primary">Click me</SlButton>;
}

Run the test app

cd test-app
npm install
npm run dev

The test app showcases every wrapped component with all variants, sizes, states, and slot usage — modeled after the Shoelace documentation.

How It Works

Each Shoelace component is wrapped using @lit/react's createComponent():

import React from 'react';
import { createComponent } from '@lit/react';
import SlButtonElement from '@shoelace-style/shoelace/dist/components/button/button.js';

export const SlButton = createComponent({
  tagName: 'sl-button',
  elementClass: SlButtonElement,
  react: React,
  events: {
    onSlBlur: 'sl-blur',
    onSlFocus: 'sl-focus',
    onSlInvalid: 'sl-invalid',
  },
});

This gives you:

• Full React prop passing (attributes, properties, booleans)
• Properly mapped custom events as React onXxx callbacks
• TypeScript types inherited from the Lit element class
• Slot support via the standard slot attribute on children

Build Architecture

The package is built with Vite library mode, outputting ES modules. Key design decisions:

• Two entry points: index.ts (components) and setup.ts (theme/icon setup) — kept separate so setup is a one-time side-effect import
• All dependencies externalized: react, @shoelace-style/shoelace, @lit/react, and lit are externalized to produce bare import specifiers. This is critical for Figma Make's esm.sh CDN to resolve them at runtime.
• Theme loading: Both light and dark Shoelace themes are imported in setup.ts. Shoelace inlines utility CSS (_utility.css) into both theme files, so no separate import is needed.

Figma Make Integration

To use this as a Figma Make kit:

1. Publish the package to npm (public or private registry)
2. The guidelines/ folder serves as the Make kit's markdown guidelines
3. Figma Make's AI reads the guidelines to learn how to use the components
4. The AI imports from @stoovles/shoelace-make-kit and uses components with correct props, events, and slots

Dark Mode

Dark mode is pre-loaded. Activate it by adding the sl-theme-dark class:

<div className="sl-theme-dark">
  <App />
</div>

Light and dark can coexist on the same page by scoping the class to specific containers.

Component List

All 58 Shoelace components are wrapped:

General: Button, ButtonGroup, Icon, IconButton Form Controls: Input, Textarea, Select, Option, Checkbox, Switch, Radio, RadioButton, RadioGroup, Range, Rating, ColorPicker Feedback: Alert, Badge, Tag, ProgressBar, ProgressRing, Spinner, Skeleton Data Display: Card, Avatar, Details, Divider, QrCode, CopyButton Overlays: Dialog, Drawer, Dropdown, Tooltip, Popup Navigation: Breadcrumb, BreadcrumbItem, TabGroup, Tab, TabPanel, Menu, MenuItem, MenuLabel, Tree, TreeItem Media & Layout: Carousel, CarouselItem, ImageComparer, SplitPanel, AnimatedImage, Animation Formatting: FormatBytes, FormatDate, FormatNumber, RelativeTime Utility: Include, MutationObserver, ResizeObserver, VisuallyHidden

Tech Stack

• Shoelace 2.20.1 — Lit-based web component library
• @lit/react 1.x — Official Lit-to-React wrapper
• Vite 5 — Build tool (library mode)
• TypeScript 5 — Type declarations via tsc --emitDeclarationOnly

License

MIT