# SyncupSuite

> Build culturally-intelligent SaaS products faster.

SyncupSuite is a design-system-first platform providing culturally-grounded design tokens, multi-tenant architecture patterns, and a Claude Code marketplace plugin. It powers two SaaS products (BrandSyncUp, LegalSyncUp) and offers its design token pipeline and platform skills as open-source packages.

## Products

### BrandSyncUp
- **Domain**: brandsyncup.com
- **Purpose**: Enterprise brand collaboration — brand identity wizard, OSINT discovery, brand footprint analysis, Figma token integration, multi-tenant brand governance
- **Stack**: React 19, TypeScript 5.7, Tailwind CSS 4, Vite 7, Cloudflare Workers, Neon PostgreSQL, Drizzle ORM, Better Auth, tRPC 11
- **Status**: Pre-launch

### LegalSyncUp
- **Domain**: legalsyncup.com
- **Purpose**: Swiss legal compliance — GDPR consent management, DSAR handling, document versioning, content distribution platform
- **Stack**: React 19, TypeScript 5.7, Tailwind CSS 4, Vite 7, Cloudflare Workers, Neon PostgreSQL, Drizzle ORM, Better Auth
- **Status**: Pre-launch

---

## npm Packages

All packages are published under the `@syncupsuite` scope on npm. MIT licensed. Source: https://github.com/syncupsuite/themes

### @syncupsuite/themes (v0.4.0)

Pre-built, culturally-grounded design themes. Each theme includes `tokens.json` (DTCG), `tokens.css` (custom properties), `tailwind.css` (Tailwind v4 @theme), and `meta.json` (cultural context and seed colors). All themes are WCAG AA contrast validated.

**Install:**
```bash
npm install @syncupsuite/themes
```

**Available themes (12):**
- `swiss-international` — Swiss International Typographic Style. Basel/Zurich schools, grid-based clarity, neo-grotesque typography.
- `nihon-traditional` — Nihon no Dentou Iro (Japanese Traditional Colors). Wabi-sabi, seasonal colors, humanist-serif typography.
- `nordic-modern` — Scandinavian modernism. Functional warmth, natural materials, democratic design.
- `tang-imperial` — Tang Dynasty imperial aesthetics. Silk Road colors, ceremonial richness.
- `shuimo-modern` — Chinese ink wash (Shuimo) painting translated to digital. Ink gradients, contemplative space.
- `nihon-minimal` — Japanese minimalism. Ma (negative space), Muji-influenced restraint.
- `renaissance` — Italian Renaissance. Venetian pigments, Florentine gold, humanist proportion.
- `art-deco` — Machine-age luxury. Jazz Age geometry, champagne gold, Chrysler Building glamour.
- `wiener-werkstaette` — Vienna Workshops (1903-1932). Klimt-era decorative arts, Jugendstil geometry.
- `milanese-design` — Milanese design tradition. Castiglioni, Sottsass, Olivetti rationalism.
- `de-stijl` — Dutch Neo-Plasticism. Mondrian primaries, Rietveld spatial geometry, absolute abstraction.
- `swiss-modernist` — Swiss Modernist variant. Extended Swiss tradition with contemporary sensibility.

**Subpath exports:**
```
@syncupsuite/themes                      → JS/TS entry (theme registry, types)
@syncupsuite/themes/<name>/tokens.json   → DTCG design tokens
@syncupsuite/themes/<name>/tokens.css    → CSS custom properties (light + dark mode)
@syncupsuite/themes/<name>/tailwind.css  → Tailwind v4 @theme integration
@syncupsuite/themes/<name>/meta.json     → Cultural context, seed colors, philosophy
```

Replace `<name>` with any theme slug from the list above (e.g., `swiss-international`, `nihon-traditional`).

**Usage — CSS custom properties:**
```css
@import "@syncupsuite/themes/swiss-international/tokens.css";

.card {
  background: var(--background-surface);
  color: var(--text-primary);
  border: 1px solid var(--border-default);
}
```

**Usage — Tailwind v4:**
```css
/* In your main CSS file */
@import "@syncupsuite/themes/nihon-traditional/tailwind.css";
```
```html
<div class="bg-background-canvas text-text-primary border border-border-default">
  Content styled with Nihon Traditional tokens
</div>
```

**Usage — Dark mode:**
Add `data-theme="dark"` to any parent element. The `tokens.css` file includes both light and dark mode definitions.

**Semantic Color API (available in all themes):**
```
Backgrounds:  var(--background-canvas | surface | muted)
Text:         var(--text-primary | secondary | muted | inverse)
Interactive:  var(--interactive-primary | primary-hover | primary-active)
Borders:      var(--border-default | strong)
Status:       var(--status-error | success | warning | info)
Focus:        var(--focus-ring)
```

**meta.json structure:**
```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "foundation": {
    "story": "string (cultural history)",
    "philosophy": "string (design philosophy)",
    "era": "string",
    "harmonyMode": "monochromatic | complementary | triadic | golden-ratio",
    "radiusTendency": "none | subtle | rounded",
    "typographyCategory": "neo-grotesque | humanist-serif | geometric-sans | ..."
  },
  "seedColors": [
    {
      "hex": "#RRGGBB",
      "name": "string (cultural name)",
      "tradition": "string (historical context)",
      "source": "string (bibliographic reference)"
    }
  ],
  "validation": {
    "schema": true,
    "contrast": true,
    "completeness": true
  }
}
```

### @syncupsuite/tokens (v0.2.0)

DTCG design token type definitions, utilities, and validation. Zero runtime dependencies.

**Install:**
```bash
npm install @syncupsuite/tokens
```

**Purpose:** TypeScript types for the W3C Design Token Community Group (DTCG) specification. Used internally by `@syncupsuite/foundations` and `@syncupsuite/themes`.

**Exports:** Single entry point with DTCG token types, validation utilities, and type guards.

**Module format:** Dual CJS + ESM via tsup. TypeScript strict mode, ES2022 target.

### @syncupsuite/foundations (v0.2.0)

Cultural design foundations — color expansion engine, semantic mapping, typography rules.

**Install:**
```bash
npm install @syncupsuite/foundations
```

**Purpose:** Takes seed colors from a cultural tradition and expands them into full color scales (50-900), semantic mappings (background, text, interactive, status), and typography configurations. Contains the cultural token data files that define each tradition.

**Dependencies:** `@syncupsuite/tokens`

**Exports:** Color expansion functions, semantic mappers, cultural data loaders, typography configuration builders.

**Module format:** Dual CJS + ESM via tsup. TypeScript strict mode, ES2022 target.

### @syncupsuite/transformers (v0.2.1)

Token transformers — converts DTCG tokens into CSS custom properties and Tailwind v4 @theme output.

**Install:**
```bash
npm install @syncupsuite/transformers
```

**Purpose:** Takes expanded token data and generates output files: `tokens.css` (CSS custom properties with light/dark mode), `tailwind.css` (Tailwind v4 `@theme` block with `@import "tailwindcss"`), and `tokens.json` (DTCG-compliant JSON).

**Dependencies:** `@syncupsuite/tokens`

**Exports:** CSS generator, Tailwind generator, DTCG JSON serializer.

**Module format:** Dual CJS + ESM via tsup. TypeScript strict mode, ES2022 target.

### Package dependency graph

```
@syncupsuite/tokens           ← DTCG types, zero runtime deps
       |
       v
@syncupsuite/foundations      ← Color engine, cultural data
@syncupsuite/transformers     ← CSS + Tailwind output generators
       |
       v
@syncupsuite/themes           ← Pre-built theme bundles (consumer package)
```

Most consumers only need `@syncupsuite/themes`. Use the lower-level packages to build custom themes from your own cultural foundations.

---

## Claude Code Marketplace Plugin

**Repository**: https://github.com/syncupsuite/webplatform4sync

**Install:**
```bash
claude mcp add https://raw.githubusercontent.com/syncupsuite/webplatform4sync/main/.claude-plugin/manifest.json
```

### Skills (4)

1. **multi-tenant-platform** — 3-tier multi-tenant architecture (Platform T0, Partner T1, Customer T2). Hierarchical governance, data isolation, tenant-scoped configuration.
2. **graduated-auth** — Authentication graduation model: Anonymous -> Preview/Inquiry -> OAuth (Google/GitHub) -> Full Account (Better Auth + Firebase). Non-binary auth progression.
3. **neon-multi-tenant** — Neon PostgreSQL patterns: schema design, Row Level Security (RLS), branch isolation for dev/preview, Drizzle ORM integration, Hyperdrive connection pooling.
4. **theme-inspired-tokens** — Culturally-grounded design token system. DTCG JSON generation, React artifact with live preview, cultural identity picker, WCAG AA validation, Tailwind v4 integration.

### Command Frames (2)

The same 4 skills are exposed through two mental models — choose whichever fits your workflow.

**Construction Frame** — Physical build sequence with hard stage gates:
- `site` — Initialize environment, scaffold project
- `pour` — Platform core, database, multi-tenant foundation
- `frame` — Auth, API routes, edge infrastructure
- `wire` — CI/CD, secrets, integrations
- `finish` — Design tokens, accessibility, observability, deploy

**Shu-Ha-Ri Frame** — Mastery per concern, non-linear progression:
- `shu` (Follow) — Adopt patterns without modification
- `ha` (Break) — Deviate with intention, customize to your domain
- `ri` (Transcend) — Operate the whole system

A project can be in different stages per concern (e.g., Shu on auth, Ha on design, Ri on deployment).

---

## Architecture

### Multi-tenant model (3-tier)

```
Tier 0 (Platform)  — Control plane, global defaults, design tokens, platform admin
Tier 1 (Partner)   — Branded instance, manages sub-tenants, owns custom domains
Tier 2 (Customer)  — End consumer, inherits branding, scoped data access
```

Simple projects start with dormant T1/T2 (hardcoded tenant_id). The machinery activates later without retrofitting.

### Authentication graduation

```
Anonymous → Preview/Inquiry → OAuth (Google/GitHub) → Full Account
```

Firebase handles identity (Google Identity Platform). Better Auth handles sessions and RBAC in Neon (neon_auth schema).

### Technology stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 19, TypeScript 5.7 strict |
| Styling | Tailwind CSS 4 (CSS-first @theme, no config file) |
| Build | Vite 7, tsup (library packages) |
| Edge | Cloudflare Workers, wrangler 4.x |
| Database | Neon PostgreSQL, Drizzle ORM 0.38+, Hyperdrive pooling |
| Auth | Better Auth (sessions/RBAC) + Firebase (identity) |
| Secrets | Doppler (dev/stg/prd environments) |
| CI/CD | GitHub Actions |
| Monorepo | pnpm 9.15+ workspaces, Turborepo |

---

## Key URLs

- **Website**: https://syncupsuite.com
- **Developer docs**: https://docs.syncupsuite.com
- **GitHub org**: https://github.com/syncupsuite
- **Marketplace plugin**: https://github.com/syncupsuite/webplatform4sync
- **Themes repo**: https://github.com/syncupsuite/themes
- **npm org**: https://www.npmjs.com/org/syncupsuite
- **BrandSyncUp**: https://brandsyncup.com
- **LegalSyncUp**: https://legalsyncup.com
- **llms.txt**: https://syncupsuite.com/llms.txt