Sailwind

A React component library for vibe coding that speaks Appian SAIL

Overview

Sailwind provides React components that mirror Appian SAIL parameter names and conventions. Components use exact SAIL syntax (size="STANDARD", color="ACCENT") so prototype code translates almost directly to production SAIL.

Built on Radix UI primitives, Tailwind CSS, and TypeScript.

For Prototypers

Use the sailwind-starter template to start building prototypes. It comes pre-configured with Sailwind and is ready for LLM-assisted development (Kiro, Cursor, Claude Code, etc.).

Browse the Component Reference to see what's available.

Installation

pnpm add @pglevy/sailwind

Peer Dependencies

Sailwind requires React 18 or 19 as a peer dependency:

pnpm add react react-dom

Supported versions:

• react — ^18.0.0 || ^19.0.0
• react-dom — ^18.0.0 || ^19.0.0

These are listed as peerDependencies in the package, so your project needs to provide them.

Setup

Import the CSS in your main entry file (e.g., main.tsx or App.tsx):

import '@pglevy/sailwind/index.css'

If you're using Tailwind CSS in your project and want Tailwind to detect utility classes used by Sailwind components, add a @source directive to your CSS:

@import "@pglevy/sailwind/index.css";
@source "../node_modules/@pglevy/sailwind/dist";

This ensures Tailwind scans Sailwind's compiled output for class names. The @import brings in the theme tokens, base styles, and pre-built utility classes, while @source lets your project's Tailwind build include any additional classes it discovers.

Using Images

The ApplicationHeader component includes all its icon assets as embedded data URIs — no image copying or configuration needed. Icons render automatically based on the objectType prop, and you can override them via iconSrc and appianLogoSrc if needed.

For Contributors

Setup

git clone https://github.com/pglevy/sailwind.git
cd sailwind
pnpm install

Development

Storybook is the primary development environment:

pnpm run storybook     # Start Storybook at http://localhost:6006

Every component has a .stories.tsx file for documentation and interactive testing. When adding or modifying components, update the corresponding stories.

Build

pnpm run generate:css      # Generate CSS custom properties from tokens/tokens.json
pnpm run build:tokens      # Generate and validate dist/tokens.json
pnpm run build:lib         # Build the npm package (dist/) + generate tokens
pnpm run build-storybook   # Build the Storybook site (storybook-static/)
pnpm run lint              # Run ESLint

Design Tokens

Sailwind's design tokens live in tokens/tokens.json as the single source of truth, using W3C DTCG 2025.10 format. The token file covers colors, typography (text sizes, font families, weights), spacing (margins, padding, radius), and gradients.

From that source file, two things are generated:

• CSS custom properties in src/index.css — via pnpm run generate:css
• Distributable tokens in dist/tokens.json and public/tokens.json — via pnpm run build:tokens (adds semantic color aliases on top of the source)

The distributable file is available in two places:

• dist/tokens.json — included in the npm package (@pglevy/sailwind/tokens.json)
• public/tokens.json — committed to the repo for versioned CDN access

You can access the latest version here:

https://cdn.jsdelivr.net/gh/pglevy/sailwind@latest/public/tokens.json

Or a specific version here:

https://cdn.jsdelivr.net/gh/pglevy/sailwind@0.10.2/public/tokens.json

Token Editor

A standalone visual editor for design tokens runs alongside Storybook:

pnpm run token-server      # Start the token editor at http://localhost:3001

Edit colors, typography, and spacing values in the browser. Saving writes back to tokens/tokens.json and regenerates the CSS, which Storybook picks up via HMR.

See scripts/README.md for details on the generation and validation pipeline.

Project Structure

tokens/
└── tokens.json             # Source of truth for all design tokens (DTCG format)
src/
├── components/             # SAIL components (Button, Card, Dropdown, etc.)
│   └── */                  # Each component has its own directory with stories
├── stories/
│   ├── pages/              # Full page examples (realistic Appian interfaces)
│   └── patterns/           # Common UI patterns (forms, grids, data displays)
├── types/                  # Shared TypeScript types (SAILSize, SAILAlign, etc.)
└── index.css               # Tailwind v4 theme (generated from tokens)
scripts/
├── generate-css.ts         # tokens/tokens.json → CSS custom properties
├── generate-tokens.ts      # tokens/tokens.json → dist + public (with semantic aliases)
├── validate-tokens.ts      # DTCG format validation
├── token-server.ts         # Dev server for the visual token editor
└── token-editor.html       # Standalone token editor UI

Publishing to npm

pnpm run build:lib
pnpm publish --access public

See PUBLISHING.md for detailed release instructions.

Component Comparison

React (Sailwind):

<TagField
  size="STANDARD"
  tags={[
    { text: "URGENT", backgroundColor: "#FED7DE", textColor: "#9F0019" }
  ]}
/>

SAIL (Production):

a!tagField(
  size: "STANDARD",
  tags: {
    a!tagItem(text: "URGENT", backgroundColor: "#FED7DE", textColor: "#9F0019")
  }
)

Documentation

• Component Reference — Live Storybook with all components
• TAILWIND-SAIL-MAPPING.md — Tailwind to SAIL style mappings
• CONTRIBUTING.md — How to contribute to the project
• AGENTS.md — Guidance for AI agents working with the library
• SAIL Docs — Official Appian SAIL reference

License

MIT