CleanPlate

A headless React UI framework — reusable, accessible components you can style to match your brand. No opinionated theme; you bring the look and feel.

• Installation
• Quick start
• Available components
• Documentation
• TypeScript
• LLM / AI-friendly docs & agents
• AGENTS.md in your app repo
• GitHub MCP server

---

Requirements

• React 18 or higher
• React DOM 18 or higher

---

Installation

npm install cleanplate

Or with Yarn:

yarn add cleanplate

Published packages: npm — cleanplate

---

Quick start

1. Add styles

Import the reset and base styles once at your app root (e.g. main.jsx, App.jsx, or index.js):

import "cleanplate/dist/index.css";

2. Import and use components

All components are named exports from cleanplate:

import { Button, Typography, Container } from "cleanplate";

function App() {
  return (
    <Container padding="4">
      <Typography variant="h1">Hello</Typography>
      <Button variant="solid" onClick={() => alert("Saved!")}>
        Save
      </Button>
    </Container>
  );
}

Example: Button

import { Button } from "cleanplate";

<Button variant="solid">Primary action</Button>
<Button variant="outline">Secondary</Button>
<Button variant="ghost">Tertiary</Button>

Variants: solid, outline, ghost, icon. Sizes: small, medium.

Example: Typography

import { Typography } from "cleanplate";

<Typography variant="h1">Heading 1</Typography>
<Typography variant="h4">Heading 4</Typography>
<Typography variant="p">Body paragraph.</Typography>

Variants: h1–h6, p, span, small.

Example: Form controls

import { FormControls } from "cleanplate";

<FormControls.Input
  label="Email"
  value={email}
  onChange={(e) => setEmail(e.target.value)}
/>

<FormControls.Select
  label="Country"
  options={[
    { label: "United States", value: "us" },
    { label: "Canada", value: "ca" },
  ]}
  value={country}
  onChange={(e) => setCountry(e.target.value)}
/>

Other form primitives: TextArea, Checkbox, Radio, Date, File, Toggle, etc.

Example: Icon

Uses Google Material Symbols. Include the font in your app; then:

import { Icon } from "cleanplate";

<Icon name="settings" size="small" color="black" />
<Icon name="check_circle" size="medium" />

---

Available components

Component	Use case
Accordion	Collapsible panels, FAQ sections
Alert	Inline feedback (success, error, warning, info)
Animated	Scroll-triggered animations
AppShell	Full-page layout with Header, Footer, sidebar
Avatar	User initials, image, or icon
Badge	Status labels, tags
BottomSheet	Slide-up panel
Drawer	Edge slide-in panel; bottom sheet on mobile
BreadCrumb	Navigation trail
Button	Actions and buttons
ConfirmDialog	Confirmation modals
Container	Layout, spacing, flex
Dropdown	Menus, floating panels
Footer	App footer
FormControls	Input, Select, TextArea, Checkbox, etc.
Header	App header with nav
Icon	Material Symbols icons
MediaObject	Media + title + description
MenuList	Navigation lists; tabs / tab bar (no separate Tabs component)
Modal	Dialogs, overlays
PageHeader	Page title + CTA + more menu
Pagination	Page navigation
Pills	Tags/chips
ProgressBar	Progress indicator
Spinner	Loading indicator
Stepper	Multi-step flows
Table	Tabular data
Toast	Transient messages
Typography	Headings and text

Import any of them from cleanplate:

import {
  Button,
  Typography,
  Container,
  Header,
  PageHeader,
  BreadCrumb,
  Table,
  FormControls,
  // ... etc.
} from "cleanplate";

---

Documentation

• Storybook — Interactive playground and docs for every component:
  https://cleanplate.sivadass.in
• GitHub — Source and issue tracker:
  github.com/sivadass/cleanplate

---

TypeScript

CleanPlate is written in TypeScript and ships type definitions. Types are included in the package (dist/index.d.ts). No extra @types package needed.

import { Button } from "cleanplate";
import type { ButtonProps } from "cleanplate";

---

LLM / AI-friendly docs & agents

Documentation for coding agents and LLMs ships with the npm package alongside the compiled library.

After npm install cleanplate

• Index: node_modules/cleanplate/llms.txt — component list, conventions, and links to each doc file.
• Per-component docs: node_modules/cleanplate/docs/<ComponentName>.md — props, types, examples, behavior.

Agent workflow: read node_modules/cleanplate/llms.txt first, then open the specific files under node_modules/cleanplate/docs/ (not imports alone).

Version-pinned URLs (no download step)

CDN mirrors of the published tarball work well for prompts and CI; pin the semver you depend on:

• Latest: unpkg — llms.txt · jsDelivr — llms.txt
• Pinned example: https://unpkg.com/cleanplate@0.2.0/llms.txt and https://unpkg.com/cleanplate@0.2.0/docs/Button.md (substitute your installed version)

Human-facing Storybook: cleanplate.sivadass.in.

AGENTS.md in your app repo

Many coding agents automatically read AGENTS.md at the root of the repository they are working in. To give agents CleanPlate-specific context in your frontend project:

1. Copy the template into your app root:
   • From this repo: AGENTS.md (raw: AGENTS.md raw)
   • Or from an install: node_modules/cleanplate/AGENTS.md → paste/rename as AGENTS.md at your project root
2. Commit AGENTS.md so teammates and agents see the same rules.

The published tarball also includes AGENTS.md next to llms.txt for easy copying after npm install.

---

GitHub MCP server

This repository is compatible with the GitHub MCP server (Model Context Protocol). The GitHub MCP server lets AI assistants (e.g. in Cursor or VS Code) access GitHub—repos, issues, pull requests, and workflows—so you can work with this codebase using natural language.

• Compatibility: CleanPlate is a standard GitHub repo with no special constraints. The GitHub MCP server can read and interact with it once connected.
• Setup: Add the GitHub MCP server in your editor:
  • Cursor: Settings → Tools & MCP → add the GitHub MCP server (or add it to ~/.cursor/mcp.json). Use Cursor’s MCP docs for the exact config.
  • VS Code (1.101+): Use the MCP servers UI or add the server to .vscode/mcp.json. See GitHub: Using the GitHub MCP Server.
• Auth: You’ll need to authenticate with GitHub (OAuth or a Personal Access Token with the scopes the MCP server needs).

No project-level MCP config is required; configure the GitHub MCP server in your editor or global config and point it at this repo.

---

License

MIT © Sivadass N