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 | | 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 | | 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/[email protected]/llms.txt and https://unpkg.com/[email protected]/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