Keystone UI Design System

Production React components generated from Figma "Design Systems" file via One-Shot Prompting.

Quick Start

# Install dependencies
npm install

# Start dev server (preview components)
npm run dev
# Open http://localhost:5173

Project Structure

keystone-ui/
├── src/
│   ├── tokens/
│   │   └── colors.css                  # Design tokens (CSS custom properties)
│   ├── components/                     # 36 components
│   │   ├── AIResponseActions/
│   │   ├── Alert/
│   │   ├── Avatar/
│   │   ├── Badge/
│   │   ├── Banner/
│   │   ├── BlockButton/
│   │   ├── BottomSheet/
│   │   ├── Breadcrumb/
│   │   ├── Button/
│   │   ├── Card/
│   │   ├── ChatBubble/
│   │   ├── Checkbox/
│   │   ├── Chip/
│   │   ├── ConversationList/
│   │   ├── DatePicker/
│   │   ├── Dialog/
│   │   ├── Dropdown/
│   │   ├── FileUpload/
│   │   ├── FloatingActionButton/
│   │   ├── Icons/
│   │   ├── List/
│   │   ├── Loading/
│   │   ├── MediaPlayer/
│   │   ├── MessageInput/
│   │   ├── Progress/
│   │   ├── Radio/
│   │   ├── SearchBar/
│   │   ├── SegmentedControl/
│   │   ├── Slider/
│   │   ├── Stepper/
│   │   ├── TabBar/
│   │   ├── TextField/
│   │   ├── Toggle/
│   │   ├── TokenUsage/
│   │   ├── Tooltip/
│   │   └── Typography/
│   ├── preview.tsx                     # Visual preview page
│   └── index.ts                        # Public API
├── mcp-server/                         # MCP Server for AI integration
│   ├── src/
│   │   ├── server.ts                   # MCP server registrations
│   │   ├── index.ts                    # Entry point
│   │   └── data/
│   │       ├── tokens.ts               # JS mirror of design tokens
│   │       ├── components.ts           # Component metadata
│   │       └── generated/              # Auto-generated at build time
│   │           ├── sources.ts          # Embedded component source code
│   │           ├── versions.ts         # Component version data
│   │           └── colors-css.ts       # Embedded CSS tokens
│   ├── scripts/
│   │   └── bundle-data.ts              # Prebuild script for standalone MCP
│   ├── build/index.js
│   ├── package.json
│   └── tsconfig.json
├── .mcp.json                           # Claude Code MCP config
├── index.html
├── vite.config.ts
├── tsconfig.json
└── package.json

Components

Button

Versatile button with 120 variants (5 styles x 4 sizes x 3 states x 2 icon modes).

import { Button } from "keystone-ui";

<Button variant="primary" size="medium" leftIcon={<Icon />}>Click me</Button>
<Button variant="accent" size="large">Submit</Button>
<Button variant="destructive" size="small" iconOnly leftIcon={<TrashIcon />} />
<Button variant="ghost" disabled>Cancel</Button>

| Prop | Type | Default | Options | |------|------|---------|---------| | variant | ButtonVariant | "primary" | primary secondary ghost accent destructive | | size | ButtonSize | "medium" | small (28px) medium (36px) large (48px) xlarge (56px) | | iconOnly | boolean | false | | | leftIcon | ReactNode | — | | | rightIcon | ReactNode | — | | | disabled | boolean | false | |

BlockButton

Toggle button with gradient border for active state.

import { BlockButton } from "keystone-ui";

<BlockButton icon={<SparklesIcon />} label="AI" />
<BlockButton icon={<SparklesIcon />} label="AI" active />

| Prop | Type | Default | |------|------|---------| | active | boolean | false | | icon | ReactNode | — | | label | string | "Button" |

Avatar

User avatar supporting images, initials, icons, and online status indicators.

import { Avatar } from "keystone-ui";

<Avatar type="image" src="/photo.jpg" alt="User" size="medium" />
<Avatar type="initials" initials="JD" size="large" status="online" />
<Avatar type="icon" icon={<UserIcon />} size="small" />

| Prop | Type | Default | Options | |------|------|---------|---------| | size | string | "medium" | xxs xs small medium large xl xxl | | type | string | "placeholder" | image initials icon placeholder | | src | string | — | | | initials | string | — | | | status | string | — | online offline busy |

Badge

Three badge types: LabelBadge, NotificationBadge, and MarketingBadge.

import { LabelBadge, NotificationBadge, MarketingBadge } from "keystone-ui";

<LabelBadge variant="success" size="medium">Active</LabelBadge>
<NotificationBadge type="count" count={5} />
<MarketingBadge type="urgency">New</MarketingBadge>

Alert

Contextual feedback messages with variant-based styling.

import { Alert } from "keystone-ui";

<Alert variant="info" title="Info" subtitle="Something happened" />
<Alert variant="error" title="Error" onClose={() => {}} />

| Prop | Type | Default | Options | |------|------|---------|---------| | variant | string | — | info success warning error | | type | string | "default" | default inline | | title | string | — | | | subtitle | string | — | | | onClose | () => void | — | |

Banner

Promotional and informational banners with multiple layout types.

import { Banner } from "keystone-ui";

<Banner type="branded" title="Welcome" subtitle="Get started" />
<Banner type="feature" title="New Feature" overline="Announcement" hero={<img />} />
<Banner type="strip" title="Sale" onPress={() => {}} />

| Prop | Type | Options | |------|------|---------| | type | string | branded countdown gradient feature glass strip | | title | string | | | subtitle | string | | | onClose | () => void | |

Breadcrumb

Navigation breadcrumb trail.

import { Breadcrumb } from "keystone-ui";

<Breadcrumb items={[{ label: "Home", href: "/" }, { label: "Settings" }]} />

BottomSheet

Modal sheet that slides up from the bottom.

import { BottomSheet } from "keystone-ui";

<BottomSheet open={true} onClose={() => {}} title="Options" showGrabber>
  {content}
</BottomSheet>

| Prop | Type | Default | |------|------|---------| | open | boolean | false | | onClose | () => void | — | | title | string | — | | showGrabber | boolean | — | | showClose | boolean | — | | footer | ReactNode | — | | footerLayout | string | "stacked" or "side-by-side" |

Card

Flexible content container with vertical/horizontal layouts.

import { Card, CardImage, CardHeader, CardContent, CardActions } from "keystone-ui";

<Card layout="vertical" elevated>
  <CardImage src="/image.jpg" alt="Cover" />
  <CardHeader title="Card Title" subtitle="Subtitle" />
  <CardContent title="Content" meta="Meta info" />
  <CardActions><Button>Action</Button></CardActions>
</Card>

| Prop | Type | Default | Options | |------|------|---------|---------| | layout | string | "vertical" | vertical horizontal | | padding | string | "padded" | padded flush | | elevated | boolean | false | | | interactive | boolean | false | |

ChatBubble

Chat message bubbles for messaging interfaces.

import { ChatBubble } from "keystone-ui";

<ChatBubble role="outgoing" text="Hello!" time="10:30" status="delivered" />
<ChatBubble role="incoming" sender="Alice" text="Hi there!" avatar={<Avatar />} />
<ChatBubble role="ai" text="Here's your answer..." thinking />

| Prop | Type | Options | |------|------|---------| | role | string | outgoing incoming ai system | | status | string | sending sent delivered read failed | | text | string | | | image | string | | | codeBlock | string | | | reactions | ChatBubbleReaction[] | |

Checkbox

Checkbox input with rectangle or rounded shape.

import { Checkbox } from "keystone-ui";

<Checkbox label="Accept terms" />
<Checkbox shape="rounded" checked disabled />

Chip

Compact interactive element for filters and selections.

import { Chip } from "keystone-ui";

<Chip label="Tag" variant="outline" />
<Chip label="Selected" variant="fill" selected icon={<Icon />} />
<Chip label="Removable" removable onRemove={() => {}} />

| Prop | Type | Options | |------|------|---------| | variant | string | outline fill semantic | | selected | boolean | | | removable | boolean | | | count | number | |

ConversationList

Chat conversation list items with swipe actions.

import { ConversationListItem, SwipeAction } from "keystone-ui";

<SwipeAction leftActions={[...]} rightActions={[...]}>
  <ConversationListItem
    name="Alice"
    message="See you tomorrow"
    time="10:30"
    unreadCount={3}
  />
</SwipeAction>

DatePicker

Date and time picker with inline and overlay styles.

import { DatePicker } from "keystone-ui";

<DatePicker value={date} onDateChange={setDate} />
<DatePicker pickerStyle="overlay" showTime />

Dialog

Modal dialog for alerts, confirmations, and inputs.

import { Dialog } from "keystone-ui";

<Dialog open={true} onClose={() => {}} type="confirm" title="Delete?" subtitle="This cannot be undone.">
  <Button variant="destructive">Delete</Button>
</Dialog>

| Prop | Type | Options | |------|------|---------| | type | string | alert confirm success input | | actionsLayout | string | stacked side-by-side |

Dropdown

Context menus and dropdowns with items, sections, and submenus.

import { Dropdown, DropdownItem, DropdownSeparator, DropdownSectionTitle } from "keystone-ui";

<Dropdown>
  <DropdownSectionTitle title="Actions" />
  <DropdownItem label="Edit" icon={<EditIcon />} />
  <DropdownSeparator />
  <DropdownItem label="Delete" state="destructive" />
</Dropdown>

FileUpload

Drag-and-drop file upload zone with progress tracking.

import { UploadZone, FileUploadItem } from "keystone-ui";

<UploadZone label="Drop files here" onFileDrop={handleDrop} />
<FileUploadItem fileName="doc.pdf" fileSize="2.4 MB" status="progress" progress={60} />

FloatingActionButton

Floating action button (FAB) for primary actions.

import { FloatingActionButton } from "keystone-ui";

<FloatingActionButton fabType="primary" icon={<PlusIcon />} />
<FloatingActionButton fabType="accent" size="large" icon={<PlusIcon />} label="Create" />

Icons

Full icon set with configurable size and color.

import { PlusIcon, SearchIcon, CloseIcon } from "keystone-ui";

<PlusIcon size="medium" />
<SearchIcon size="large" color="#0050ff" />

| Prop | Type | Default | Options | |------|------|---------|---------| | size | string | "medium" | xs small medium large xl | | color | string | — | |

List

Structured list with headers, items, and separators.

import { List, ListHeader, ListItem, ListSeparator } from "keystone-ui";

<List>
  <ListHeader type="prominent" title="Settings" />
  <ListItem title="Profile" subtitle="Edit your profile" showChevron />
  <ListSeparator />
  <ListItem title="Notifications" trailing={<Toggle />} />
</List>

Loading

Loading spinner indicator.

import { Loading } from "keystone-ui";

<Loading size="medium" />

MediaPlayer

Audio/media player with playback controls.

import { MediaPlayer } from "keystone-ui";

<MediaPlayer title="Track Name" subtitle="Artist" artworkSrc="/cover.jpg" currentTime="1:30" />

MessageInput / PromptInput

Chat message input and AI prompt input fields.

import { MessageInput, PromptInput } from "keystone-ui";

<MessageInput placeholder="Type a message..." onSubmit={handleSend} />
<PromptInput placeholder="Ask anything..." submitLabel="Send" onSubmit={handleSubmit} />

Progress

Progress bar and spinner components.

import { ProgressBar, Spinner } from "keystone-ui";

<ProgressBar value={75} />
<Spinner size="regular" />

Radio

Radio button input.

import { Radio } from "keystone-ui";

<Radio label="Option A" checked />
<Radio label="Option B" />

SearchBar

Search input with cancel support.

import { SearchBar } from "keystone-ui";

<SearchBar placeholder="Search..." onSearch={handleSearch} onCancel={() => {}} />

SegmentedControl / Tabs

Segmented toggle and tabbed navigation.

import { SegmentedControl, Tabs } from "keystone-ui";

<SegmentedControl items={[{ value: "a", label: "A" }, { value: "b", label: "B" }]} value="a" />
<Tabs items={[{ value: "tab1", label: "Tab 1" }]} value="tab1" />

Slider

Range slider input with optional labels and ticks.

import { Slider } from "keystone-ui";

<Slider min={0} max={100} value={50} onValueChange={setValue} showLabels />

Stepper

Numeric stepper for incrementing/decrementing values.

import { Stepper } from "keystone-ui";

<Stepper min={0} max={10} value={5} onValueChange={setValue} showValue />

TabBar

Bottom tab bar navigation.

import { TabBar } from "keystone-ui";

<TabBar items={[{ value: "home", label: "Home", icon: <HomeIcon /> }]} value="home" />

TextField

Text input with label, helper text, and error states.

import { TextField } from "keystone-ui";

<TextField label="Email" placeholder="[email protected]" type="email" />
<TextField label="Password" type="password" error helperText="Required" />

| Prop | Type | Options | |------|------|---------| | type | string | text password email number tel url | | error | boolean | | | showClear | boolean | | | disabled | boolean | |

Toggle

On/off toggle switch.

import { Toggle } from "keystone-ui";

<Toggle checked={true} onCheckedChange={setChecked} />
<Toggle disabled />

TokenUsage

Token/usage display with progress indicator.

import { TokenUsage } from "keystone-ui";

<TokenUsage title="API Tokens" value={750} maxValue="1,000" percentage={75} />

Tooltip

Informational tooltip with configurable arrow position.

import { Tooltip } from "keystone-ui";

<Tooltip text="Helpful tip" arrowPosition="center" />

Typography

Text component with design system type scale.

import { Typography } from "keystone-ui";

<Typography variant="h1-bold">Heading</Typography>
<Typography variant="body-default" color="subtitle">Body text</Typography>
<Typography variant="caption-meta" color="disabled">Meta</Typography>

| Prop | Type | Options | |------|------|---------| | variant | string | display-hero display-large h1-bold h1-semibold t1-bold t1-semibold t2-bold t2-semibold subheading-strong subheading-default body-strong body-emphasis body-default body-italic dense-strong dense-emphasis dense-default dense-italic link-body link-dense caption-strong caption-label caption-meta overline | | color | string | title subtitle body disabled link on-primary inherit | | align | string | left center right | | as | ElementType | | | truncate | boolean | |

AIResponseActions

Action toolbar for AI-generated responses (copy, regenerate, like, dislike).

import { AIResponseActions } from "keystone-ui";

<AIResponseActions
  actions={[{ type: "copy" }, { type: "regenerate" }, { type: "like" }, { type: "dislike" }]}
  onAction={(type) => console.log(type)}
/>

Design Tokens

All tokens are defined as CSS custom properties in src/tokens/colors.css:

--btn-primary-bg: #09090b;
--btn-accent-bg: #0050ff;
--btn-destructive-bg: #ff2525;
/* ... see full file for all tokens */

MCP Server (AI Integration)

The MCP server exposes the design system to AI tools (Claude Code, Cursor, etc.).

Setup

# Install MCP server dependencies
cd mcp-server
npm install

# Build
npm run build

Connect to Claude Code

The .mcp.json at the project root auto-configures Claude Code:

{
  "mcpServers": {
    "keystone-ui-design-system": {
      "command": "node",
      "args": ["mcp-server/build/index.js"],
      "cwd": "/absolute/path/to/keystone-ui"
    }
  }
}

Restart Claude Code in this project directory — it will auto-detect and connect.

Available MCP Tools

| Tool | Description | |------|-------------| | get_component | Get props, tokens, usage examples, and source for a component | | get_tokens | Get design tokens by category (colors/spacing/typography/all) | | generate_button | Generate JSX code for a Button with specific props | | search_components | Search components by keyword or prop name | | get_migration_guide | Get migration guides for a component between versions |

Available MCP Resources

| URI | Description | |-----|-------------| | keystoneui://tokens | All design tokens (JSON) | | keystoneui://components | Component list with props and usage | | keystoneui://components/{name}/source | Component source code (TSX + CSS) | | keystoneui://tokens/colors.css | Raw CSS custom properties | | keystoneui://components/versions | Component version history | | keystoneui://components/{name}/changelog | Changelog for a specific component |

Available MCP Prompts

| Prompt | Description | |--------|-------------| | use-component | Guide for using a specific component | | create-ui | Generate UI using Keystone UI components | | create-component | Convert a Figma component to production React code |

Example AI Usage

"Create a login form using Keystone UI"
→ AI calls get_component, get_tokens, generate_button automatically

"What button variants are available?"
→ AI calls search_components with query "variant"

Connect to Other AI Tools (Cursor, Windsurf, etc.)

Add to your AI tool's MCP config:

{
  "keystone-ui-design-system": {
    "command": "node",
    "args": ["/absolute/path/to/keystone-ui/mcp-server/build/index.js"]
  }
}

Figma Source

• File: Design Systems
• Button: Node ID 5:661 (120 variants)
• BlockButton: Node ID 5:1204 (2 variants)
• Colors Page: Full color palette (B&W, Accents, Background, Button, Text, etc.)