@shapesos/clay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shapes.co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @shapes/clay
+
+Shapes.co design system — tokens, theming, and composable React components.
+
+## Install
+
+```bash
+bun add @shapes/clay
+```
+
+## Entry Points
+
+| Import path           | What you get                               | Peer dependencies          |
+| --------------------- | ------------------------------------------ | -------------------------- |
+| `@shapes/clay/tokens` | Colors, typography, font families          | **None** (pure JS)         |
+| `@shapes/clay/chat`   | Chat compound components + types           | React, styled-components   |
+| `@shapes/clay/icon`   | Icon, IconButton components + types        | React, styled-components   |
+| `@shapes/clay`        | Everything (convenience re-export)         | React, styled-components   |
+
+## Usage
+
+### Design Tokens
+
+```typescript
+import { colors, typographyStyles, typographyTypes, typographyMixin } from "@shapes/clay/tokens";
+
+colors["brown-100"]; // "#171716"
+
+typographyStyles[typographyTypes.GEIST_BODY_S_REGULAR];
+// { fontFamily: "Geist", fontSize: 16, fontWeight: 400, lineHeight: 24, letterSpacing: -0.08 }
+
+typographyMixin(typographyTypes.GEIST_BODY_XS_MEDIUM);
+// CSS string for use in styled-components
+```
+
+### Chat Components
+
+Composable compound components assembled via a namespace:
+
+```tsx
+import { Chat } from "@shapes/clay/chat";
+import type { ChatMessage } from "@shapes/clay/chat";
+
+function MyChat() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  return (
+    <Chat.Root
+      messages={messages}
+      onSendMessage={handleSend}
+      isLoading={isLoading}
+      onStop={handleStop}
+      onCopyMessage={handleCopy}
+      onThumbUpClick={handleThumbUp}
+      onThumbDownClick={handleThumbDown}
+    >
+      <Chat.MessageList />
+      <Chat.Composer placeholder="Ask anything..." />
+    </Chat.Root>
+  );
+}
+```
+
+`Chat.Root` provides context; children consume it. This lets consumers add custom elements between the message list and composer, or wrap parts in their own layout.
+
+#### Props
+
+**Chat.Root**
+
+| Prop               | Type                                                       | Required | Description                                     |
+| ------------------ | ---------------------------------------------------------- | -------- | ----------------------------------------------- |
+| `messages`         | `ChatMessage[]`                                            | Yes      | Array of messages to display                    |
+| `onSendMessage`    | `(content: string) => void`                                | Yes      | Called when the user sends a message             |
+| `isLoading`        | `boolean`                                                  | No       | Show stop button while loading                  |
+| `onStop`           | `() => void`                                               | No       | Called when the user clicks stop                |
+| `onCopyMessage`    | `(messageId: string) => void`                              | No       | Called when a message is copied                 |
+| `onThumbUpClick`   | `(messageId: string, isHelpful: boolean \| null) => void`  | No       | Called when thumbs up is clicked                |
+| `onThumbDownClick` | `(messageId: string, isHelpful: boolean \| null) => void`  | No       | Called when thumbs down is clicked              |
+
+**Chat.Composer**
+
+| Prop          | Type     | Required | Default              | Description        |
+| ------------- | -------- | -------- | -------------------- | ------------------ |
+| `placeholder` | `string` | No       | `"Type a message..."` | Input placeholder  |
+
+**Chat.MessageList** — no props, reads messages from context.
+
+#### Data Model
+
+```typescript
+type MessageRole = "user" | "assistant";
+
+interface ChatMessage {
+  id: string;
+  role: MessageRole;
+  content: string;        // Markdown
+  isHelpful?: boolean | null;
+}
+```
+
+### Icon Components
+
+```tsx
+import { Icon, IconButton } from "@shapes/clay/icon";
+import { IconSearch, IconCopy } from "@tabler/icons-react";
+
+<Icon icon={IconSearch} size={20} color="#333" aria-label="Search" />
+
+<IconButton icon={IconCopy} size="small" onClick={handleCopy} aria-label="Copy" />
+```
+
+#### Props
+
+**Icon**
+
+| Prop         | Type                                     | Required | Default | Description             |
+| ------------ | ---------------------------------------- | -------- | ------- | ----------------------- |
+| `icon`       | `ComponentType<SVGProps<SVGSVGElement>>` | Yes      |         | Icon component to render |
+| `size`       | `number`                                 | No       | `16`    | Icon size in pixels      |
+| `color`      | `string`                                 | No       |         | Icon color               |
+| `className`  | `string`                                 | No       |         | CSS class                |
+| `aria-label` | `string`                                 | No       |         | Accessible label         |
+
+**IconButton**
+
+| Prop         | Type                                     | Required | Default   | Description                |
+| ------------ | ---------------------------------------- | -------- | --------- | -------------------------- |
+| `icon`       | `ComponentType<SVGProps<SVGSVGElement>>` | Yes      |           | Icon component to render    |
+| `size`       | `"small" \| "medium"`                    | No       | `"small"` | Button size                 |
+| `isSelected` | `boolean`                                | No       | `false`   | Selected/active state       |
+| `disabled`   | `boolean`                                | No       | `false`   | Disabled state              |
+| `onClick`    | `() => void`                             | No       |           | Click handler               |
+| `className`  | `string`                                 | No       |           | CSS class                   |
+| `aria-label` | `string`                                 | No       |           | Accessible label            |
+
+### Types
+
+```typescript
+import type { ColorToken, TypographyStyle, TypographyType } from "@shapes/clay/tokens";
+import type { ChatMessage, MessageRole, ChatContextValue } from "@shapes/clay/chat";
+import type { IconProps, IconButtonProps, IconButtonSize } from "@shapes/clay/icon";
+```
+
+## Development
+
+```bash
+git clone git@github.com:dreamteamapp/shapes-clay.git
+cd shapes-clay
+bun install
+```
+
+| Command                  | Description                                |
+| ------------------------ | ------------------------------------------ |
+| `bun run storybook`      | Component playground (http://localhost:6006)|
+| `bun run build`          | Build package (tsup)                       |
+| `bun run dev`            | Build in watch mode                        |
+| `bun run test`           | Run unit tests (Vitest)                    |
+| `bun run test:coverage`  | Unit tests with coverage report            |
+| `bun run test:e2e`       | Run E2E tests (Playwright + Storybook)     |
+| `bun run lint`           | Lint with ESLint                           |
+| `bun run format`         | Format with Prettier                       |
+| `bun run typecheck`      | TypeScript strict type checking            |
+| `bun run check`          | All quality gates (lint + typecheck + test) |
+
+See [AGENTS.md](AGENTS.md) for full project structure, architecture, and conventions.
+
+## License
+
+[MIT](LICENSE)