@plopaton42/design-system

Token-driven, AI-first dual-framework (Vue 3 + React) component library.

Single source of truth flows from Figma → DTCG JSON tokens → CSS custom properties (--ds-*) → Tailwind v4 utility classes. Components are available for both Vue 3 and React.

Install

npm install @plopaton42/design-system

Import

// React
import { Button } from '@plopaton42/design-system/react'
import '@plopaton42/design-system/style.css'

<!-- Vue -->
<script setup>
import { Button } from '@plopaton42/design-system'
import '@plopaton42/design-system/style.css'
</script>

/* CSS tokens only (if you want to use --ds-* variables without components) */
@import '@plopaton42/design-system/tokens/variables.css';
@import '@plopaton42/design-system/tokens/semantic.css';

Available components

| Component | Vue | React | Description | |-------------|:---:|:-----:|-------------| | Button | ✅ | ✅ | Primary, secondary, ghost variants — 3 sizes — loading/disabled states | | Checkbox | ✅ | ✅ | Controlled/uncontrolled — indeterminate state — label slot | | SplitButton | ✅ | ✅ | Button + dropdown trigger — same variants as Button |

MCP server (for AI agents)

This design system exposes an MCP server so AI agents can retrieve components and tokens directly.

HTTP endpoint (public): https://next-production-316b.up.railway.app/mcp

Tools

| Tool | Description | |------|-------------| | list_components | Lists all available components with framework info | | get_component | Returns full source code + copy instructions for a component | | get_token_styles | Returns the built CSS (--ds-* variables) to paste into your project | | list_tokens | Returns raw DTCG token JSON from tokens/source/ | | get_conventions | Returns the full design system conventions (CLAUDE.md) |

Typical AI workflow using the MCP

1. list_components          → see what's available
2. get_component("Button")  → get source code + copy instructions
3. get_token_styles         → get the CSS variables to add to your project

Configure in your project (.mcp.json)

{
  "mcpServers": {
    "design-system": {
      "type": "http",
      "url": "https://next-production-316b.up.railway.app/mcp"
    }
  }
}

Design tokens

All CSS custom properties are prefixed --ds-*. Two layers:

| File | Contents | |------|----------| | tokens/variables.css | Primitive scales: colors, spacing, radius, typography, shadows | | tokens/semantic.css | Semantic tokens: button surfaces, text colors, borders, focus rings |

Token source files live in tokens/source/ (DTCG JSON format). Run npm run build:tokens to regenerate.

Architecture

tokens/source/**/*.json   (DTCG format — source of truth)
        │
        ▼  npm run build:tokens
tokens/build/
  ├── variables.css   → :root { --ds-* }
  ├── semantic.css    → :root { --ds-* }
  └── theme.ts        → typed TS object
        │
        ▼  imported in src/style.css
@theme inline { ... }  → Tailwind v4 utility classes

Each component follows this structure:

components/Button/
  ├── Button.vue           ← Vue 3 SFC
  ├── Button.tsx           ← React functional component
  ├── Button.types.ts      ← Shared TypeScript interfaces
  ├── Button.stories.ts    ← Vue Storybook stories (port 6009)
  ├── Button.react.stories.tsx  ← React Storybook stories (port 6010)
  ├── Button.figma.ts      ← Figma Code Connect mapping
  └── README.md            ← Props, tokens, a11y, changelog

Contributing / local dev

npm install
npm run build:tokens   # required before anything else
npm run dev            # Vite dev server
npm run storybook:vue  # Vue Storybook — port 6009
npm run storybook:react  # React Storybook — port 6010
npm run mcp:http       # MCP HTTP server — port 3001

See CLAUDE.md for the full conventions guide: token naming, component architecture, Figma fidelity rules, git workflow, and self-review checklist.