https://github.com/pglevy/sailwind
A React component library for vibe coding that speaks Appian SAIL
https://github.com/pglevy/sailwind
Last synced: about 2 months ago
JSON representation
A React component library for vibe coding that speaks Appian SAIL
- Host: GitHub
- URL: https://github.com/pglevy/sailwind
- Owner: pglevy
- Created: 2025-10-08T00:53:33.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-23T01:11:49.000Z (about 2 months ago)
- Last Synced: 2026-04-23T03:33:55.023Z (about 2 months ago)
- Language: TypeScript
- Homepage: https://pglevy.github.io/sailwind/
- Size: 778 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Sailwind
[](https://www.npmjs.com/package/@pglevy/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](https://github.com/pglevy/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](https://pglevy.github.io/sailwind/)** to see what's available.
### Installation
```bash
pnpm add @pglevy/sailwind
```
### Peer Dependencies
Sailwind requires React 18 or 19 as a peer dependency:
```bash
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`):
```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:
```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
```bash
git clone https://github.com/pglevy/sailwind.git
cd sailwind
pnpm install
```
### Development
Storybook is the primary development environment:
```bash
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
```bash
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](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) 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:
```bash
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
```bash
pnpm run build:lib
pnpm publish --access public
```
See [PUBLISHING.md](PUBLISHING.md) for detailed release instructions.
## Component Comparison
**React (Sailwind):**
```tsx
```
**SAIL (Production):**
```sail
a!tagField(
size: "STANDARD",
tags: {
a!tagItem(text: "URGENT", backgroundColor: "#FED7DE", textColor: "#9F0019")
}
)
```
## Documentation
- **[Component Reference](https://pglevy.github.io/sailwind/)** — Live Storybook with all components
- **[TAILWIND-SAIL-MAPPING.md](TAILWIND-SAIL-MAPPING.md)** — Tailwind to SAIL style mappings
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — How to contribute to the project
- **[AGENTS.md](AGENTS.md)** — Guidance for AI agents working with the library
- **[SAIL Docs](https://docs.appian.com/suite/help/25.3/)** — Official Appian SAIL reference
## License
MIT