cleanplate 0.2.0 → 0.2.1

package/README.md

@@ -1,104 +1,237 @@
-# cleanplate
+# CleanPlate
 
-CleanPlate - Headless React UI Framework
+**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
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Available components](#available-components)
+- [Documentation](#documentation)
+- [TypeScript](#typescript)
+- [LLM / AI-friendly docs & agents](#llm--ai-friendly-docs--agents)
+- [GitHub MCP server](#github-mcp-server)
 
-```
-npm install cleanplate
-```
+---
 
-Check all versions at [NPM](https://www.npmjs.com/package/cleanplate).
+## Requirements
 
-### Usage
+- **React** 18 or higher
+- **React DOM** 18 or higher
 
-All components can be consumed by `import` using their respective names from `cleanplate` package.
+---
 
-#### Initial Setup
+## Installation
 
-Import the CSS Reset and minimal cleanplate styles at top most level or root level.
-
-```
-import "cleanplate/dist/index.css";
+```bash
+npm install cleanplate
 ```
 
-#### Button
+Or with Yarn:
 
+```bash
+yarn add cleanplate
 ```
-import { Button } from "cleanplate";
 
-<Button variant="primary" onClick={() => {}}>Save</Button>
-<Button variant="secondary" onClick={() => {}}>Save</Button>
-<Button variant="nude" onClick={() => {}}>Save</Button>
-<Button variant="special" onClick={() => {}}>Save</Button>
-```
+Published packages: [npm — cleanplate](https://www.npmjs.com/package/cleanplate)
 
-#### Typography
+---
 
-```
-import { Typography } from "cleanplate";
+## Quick start
 
-<Typography variant="h1">Hello World!</Typography>
-<Typography variant="h2">Hello World!</Typography>
-<Typography variant="h3">Hello World!</Typography>
-<Typography variant="h4">Hello World!</Typography>
-<Typography variant="h5">Hello World!</Typography>
-<Typography variant="h6">Hello World!</Typography>
-<Typography variant="p">Hello World!</Typography>
-<Typography variant="small">Hello World!</Typography>
+### 1. Add styles
 
+Import the reset and base styles **once** at your app root (e.g. `main.jsx`, `App.jsx`, or `index.js`):
+
+```jsx
+import "cleanplate/dist/index.css";
 ```
 
-#### Badge
+### 2. Import and use components
 
-```
-import { Badge } from "cleanplate";
+All components are **named exports** from `cleanplate`:
 
-<Badge label="New" />
+```jsx
+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>
+  );
+}
 ```
 
-#### AppShell
+### Example: Button
 
-```
-import { AppShell } from "cleanplate";
+```jsx
+import { Button } from "cleanplate";
 
-<AppShell />
+<Button variant="solid">Primary action</Button>
+<Button variant="outline">Secondary</Button>
+<Button variant="ghost">Tertiary</Button>
 ```
 
-#### Form Controls
+Variants: `solid`, `outline`, `ghost`, `icon`. Sizes: `small`, `medium`.
+
+### Example: Typography
 
+```jsx
+import { Typography } from "cleanplate";
+
+<Typography variant="h1">Heading 1</Typography>
+<Typography variant="h4">Heading 4</Typography>
+<Typography variant="p">Body paragraph.</Typography>
 ```
-import { FormControl } from "cleanplate";
 
-<FormControl.Input
-    name="email"
-    onChange={(e) => handleChange(e)}
-    value={values.email}
+Variants: `h1`–`h6`, `p`, `span`, `small`.
+
+### Example: Form controls
+
+```jsx
+import { FormControls } from "cleanplate";
+
+<FormControls.Input
+  label="Email"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
 />
 
-<FormControl.TextArea
-    name="bio"
-    onChange={(e) => handleChange(e)}
-    value={values.bio}
+<FormControls.Select
+  label="Country"
+  options={[
+    { label: "United States", value: "us" },
+    { label: "Canada", value: "ca" },
+  ]}
+  value={country}
+  onChange={(e) => setCountry(e.target.value)}
 />
 ```
 
-#### Icon
+Other form primitives: `TextArea`, `Checkbox`, `Radio`, `Date`, `File`, `Toggle`, etc.
 
-```
+### Example: Icon
+
+Uses [Google Material Symbols](https://fonts.google.com/icons). Include the font in your app; then:
+
+```jsx
 import { Icon } from "cleanplate";
 
-<Icon name="settings" size="small" color="balck">
+<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`:
+
+```jsx
+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](https://cleanplate.sivadass.in)
+- **GitHub** — Source and issue tracker:  
+  [github.com/sivadass/cleanplate](https://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.
+
+```tsx
+import { Button } from "cleanplate";
+import type { ButtonProps } from "cleanplate";
 ```
 
-View all the available icon names from [Google Material Icons](https://fonts.google.com/icons).
+---
 
-#### Modal
+## LLM / AI-friendly docs & agents
 
-```
-import { Modal } from "cleanplate";
-```
+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`](https://unpkg.com/cleanplate@latest/llms.txt) · [jsDelivr — `llms.txt`](https://cdn.jsdelivr.net/npm/cleanplate@latest/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](https://cleanplate.sivadass.in).
+
+---
+
+## GitHub MCP server
+
+This repository is **compatible with the [GitHub MCP server](https://github.com/github/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](https://cursor.com/docs/context/mcp) 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](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/use-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.
+
+---
 
-### Documentation & Demo
+## License
 
-Storybook playground is available for all components at [https://cleanplate.sivadass.in](https://cleanplate.sivadass.in).
+MIT © Sivadass N