@handled-ai/design-system 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +73 -117
  2. package/dist/index.d.ts +978 -7
  3. package/dist/index.js +7202 -802
  4. package/dist/index.js.map +1 -1
  5. package/package.json +20 -20
package/README.md CHANGED
@@ -1,108 +1,68 @@
1
- # @handled-ai/design-system
1
+ # @handled Design System
2
2
 
3
- A shared design system built on [shadcn/ui](https://ui.shadcn.com). Use it as an **npm package** in React/Next.js apps or via the **shadcn registry** (copy-paste).
3
+ A shared design system built on [shadcn/ui](https://ui.shadcn.com). Components are customized shadcn primitives distributed as an npm package (`@handled-ai/design-system`) and hosted as a custom shadcn registry for showcase/discovery.
4
4
 
5
- ## Install as npm package (recommended)
5
+ ## Documentation
6
6
 
7
- ```bash
8
- npm install @handled-ai/design-system
9
- # or
10
- pnpm add @handled-ai/design-system
11
- # or
12
- yarn add @handled-ai/design-system
13
- ```
14
-
15
- **Peer dependencies:** Install React and the UI primitives if not already present:
16
-
17
- ```bash
18
- pnpm add react react-dom @radix-ui/react-slot @radix-ui/react-label radix-ui class-variance-authority clsx tailwind-merge lucide-react
19
- # Optional, only if you use Chart / ActivityLog / MetricCard etc.:
20
- pnpm add date-fns recharts zod
21
- ```
7
+ | Document | Description |
8
+ |---|---|
9
+ | [Component Reference](docs/COMPONENTS.md) | Full API reference for all 62+ components, organized by category (primitives, overlays, cards, charts, data tables, activity, detail views, actions, utilities) |
10
+ | [Styling Reference](docs/STYLING.md) | Typography scale, color tokens, grayscale system, theming architecture, dark mode, border radius, and Tailwind integration |
11
+ | [Publishing Guide](docs/PUBLISHING.md) | Version bumping (semver), publishing steps, post-publish verification, safe update workflow for consuming apps, peer dependencies, and rollback procedures |
12
+ | [Consuming App Rule Template](docs/CONSUMING_APP_RULE_TEMPLATE.mdc) | Cursor rule template to drop into consuming projects for design system contract enforcement |
13
+ | **Per-component docs** | `docs/components/{name}.md` — individual prop tables, usage examples, and dependency notes for each component |
22
14
 
23
- **Use in your app:**
15
+ ## Architecture
24
16
 
25
- ```tsx
26
- import { Button, Card, cn } from "@handled-ai/design-system"
27
-
28
- export function MyPage() {
29
- return (
30
- <Card>
31
- <Button>Click me</Button>
32
- </Card>
33
- )
34
- }
35
- ```
17
+ - **Primary distribution:** npm package `@handled-ai/design-system`, built with `npm run build:lib` (tsup)
18
+ - **Secondary distribution:** shadcn registry at `/r/{name}.json`, deployed on Vercel for showcase/discovery
19
+ - **Component source:** `registry/new-york/ui/` — customized shadcn primitives and custom UX blocks
20
+ - **Package entry point:** root `index.ts`
21
+ - **Theming:** Semantic CSS variable tokens — consuming projects define their own palette (see [Styling Reference](docs/STYLING.md))
22
+ - **Build tool:** `shadcn build` generates distributable registry JSON from source
36
23
 
37
- **Tailwind:** Components use Tailwind classes. In your Tailwind config (or `postcss.config` for Tailwind v4), include the package in `content` so classes are not purged:
24
+ ## Cursor Rules
38
25
 
39
- ```js
40
- // tailwind.config.js (v3) or postcss / @config (v4)
41
- content: [
42
- "./src/**/*.{js,ts,jsx,tsx}",
43
- "./node_modules/@handled-ai/design-system/dist/**/*.js",
44
- ]
45
- ```
26
+ This repo includes Cursor rules that provide AI-assisted development context.
46
27
 
47
- **Theme:** Define the same CSS variables in your app (e.g. in `globals.css`) so tokens like `--primary`, `--background`, `--radius` exist. You can copy the `:root` and `.dark` blocks from this repo’s `app/globals.css`, or use your own palette.
28
+ | Rule | File | Scope |
29
+ |---|---|---|
30
+ | Architecture | `.cursor/rules/architecture.mdc` | Always active — project structure, conventions, distribution channels, documentation locations |
31
+ | Component Editing | `.cursor/rules/component-editing.mdc` | Auto-applied when editing `registry/new-york/ui/*.tsx` — checklist for exports, docs, versioning, and dependencies |
48
32
 
49
- ---
33
+ Consuming apps can adopt their own design system rule using the [template](docs/CONSUMING_APP_RULE_TEMPLATE.mdc).
50
34
 
51
- ## Registry (copy-paste) usage
35
+ ## Components
52
36
 
53
- The project is also published as a custom shadcn registry. Components are copy-pasted into your repo via the `shadcn` CLI.
37
+ The design system includes 62+ components across these categories:
54
38
 
55
- ## What You Can View
39
+ - **Primitives & Foundation** — Button, Input, Label, Textarea, Select, Badge, Avatar, Separator, Skeleton, Progress, ScrollArea, Table
40
+ - **Overlays & Navigation** — Dialog, DropdownMenu, Tooltip, Sheet, Tabs, Sidebar, ViewModeToggle, QuickActionSidebarNav
41
+ - **Cards & Metrics** — Card, MetricCard, ReportCard, DashboardCards, TopLineMetrics, PerformanceMetricsTable, ScoreRing, ScoreFeedback, ScoreBreakdown, ScoreAnalysisModal
42
+ - **Charts** — Chart, ChartTooltip, DonutChart, TrendAreaChart, BarChartComponent, StyledBarList, SankeyChart, VolumeAnalysisChart, PipelineOverview
43
+ - **Data Table** — DataTable, DataTableFilter, DataTableDisplay, DataTableQuickViews, DataTableToolbar
44
+ - **Item List** — ItemList, ItemListFilter, ItemListDisplay, ItemListToolbar
45
+ - **Activity & Timeline** — ActivityLog, ActivityDetail, TimelineActivity
46
+ - **Detail & Entity Views** — DetailView, EntityPanel, InboxRow, InboxToolbar, ContactList, PreviewList
47
+ - **Actions & Feedback** — SignalFeedbackInline, RecommendedActionsSection, SuggestedActions, QuickActionChatArea, QuickActionModal
56
48
 
57
- When the app is running locally, there are two main experiences:
49
+ See the [Component Reference](docs/COMPONENTS.md) for full API documentation including props, variants, and usage examples.
58
50
 
59
- - **Component gallery:** `/`
60
- Browse individual components and UX blocks rendered directly on the page.
61
- - **Prototype view:** `/preview`
62
- See the Mercury-style end-to-end product prototype (sidebar, inbox/work queue, detail view, insights dashboard, meetings, and coaching banner patterns).
51
+ ## Usage in a Consuming Project
63
52
 
64
- If port `3000` is taken, Next.js will auto-pick another port (for example `3001`, `3002`, `3003`). Use whatever port appears in your terminal output.
53
+ ### Install via npm (primary)
65
54
 
66
- ## Architecture
67
-
68
- - **Registry format:** Static JSON files served at `/r/{name}.json`
69
- - **Component source:** `registry/new-york/ui/` — customized shadcn primitives + custom UX blocks
70
- - **Theming:** CSS variables — consuming projects define their own palette
71
- - **Build tool:** `shadcn build` generates distributable JSON from source
72
-
73
- ## Available Components
74
-
75
- | Component | Description |
76
- |-----------|-------------|
77
- | `button` | Button with multiple variants and sizes |
78
- | `card` | Card container with header, content, footer |
79
- | `dialog` | Modal dialog (Radix UI) |
80
- | `input` | Styled text input |
81
- | `label` | Form label |
82
- | `select` | Select dropdown (Radix UI) |
83
- | `table` | Responsive table |
84
- | `tabs` | Tab navigation (Radix UI) |
85
- | `badge` | Status indicator badges |
86
- | `avatar` | Avatar with image/fallback |
87
- | `dropdown-menu` | Dropdown menu with keyboard nav |
88
- | `tooltip` | Hover tooltip |
89
- | `sheet` | Slide-out panel |
90
- | `separator` | Visual divider |
91
- | `skeleton` | Loading placeholder |
92
- | `scroll-area` | Custom scrollable area |
93
- | `textarea` | Multi-line text input |
94
- | `activity-log` | Activity stream row pattern |
95
- | `chart` | Chart container and helpers |
96
- | `detail-view` | Production-style detail panel primitives |
97
- | `inbox-row` | Row-based inbox/work queue item |
98
- | `metric-card` | KPI cards with variants (including donut-style) |
99
- | `sidebar` | App navigation sidebar primitives |
55
+ ```bash
56
+ pnpm add @handled-ai/design-system
57
+ ```
100
58
 
101
- ## Usage in a Consuming Project
59
+ ```tsx
60
+ import { Button, Card, Input } from "@handled-ai/design-system"
61
+ ```
102
62
 
103
- ### 1. Add the registry namespace
63
+ ### Install via shadcn registry (alternative)
104
64
 
105
- In your project's `components.json`:
65
+ Add the registry namespace to your project's `components.json`:
106
66
 
107
67
  ```json
108
68
  {
@@ -112,58 +72,54 @@ In your project's `components.json`:
112
72
  }
113
73
  ```
114
74
 
115
- ### 2. Install components
75
+ Then install individual components:
116
76
 
117
77
  ```bash
118
78
  npx shadcn@latest add @handled/button @handled/card @handled/input
119
79
  ```
120
80
 
121
- ### 3. Set your theme
81
+ ### Set your theme
122
82
 
123
- Override CSS variables in your `globals.css` — see the Theming Contract section in `docs/processes/design-system.md` (Barb repo).
83
+ Override CSS variables in your `globals.css` to apply your own palette. See the [Styling Reference](docs/STYLING.md) for the full list of tokens and theming instructions.
124
84
 
125
85
  ## Development
126
86
 
127
87
  ```bash
128
88
  pnpm install
129
- pnpm run dev # Start local app (component gallery at /, prototype at /preview)
89
+ pnpm run dev # Start local app (component gallery + prototype)
90
+ pnpm run build:lib # Build npm package
130
91
  pnpm run registry:build # Build registry JSON files
92
+ pnpm run typecheck # Type-check the codebase
93
+ pnpm run lint # Run linter
131
94
  ```
132
95
 
133
96
  ### Local URLs
134
97
 
135
- - `http://localhost:3000/` (or the port shown in terminal): component gallery
136
- - `http://localhost:3000/preview` (or same active port): full prototype
137
- - `http://localhost:3000/r/registry.json` (or same active port): built registry index
98
+ - `http://localhost:3000/` — Component gallery
99
+ - `http://localhost:3000/preview` — Full product prototype (sidebar, inbox, detail view, dashboard)
100
+ - `http://localhost:3000/r/registry.json` — Built registry index
138
101
 
139
- ## Publishing
140
-
141
- ### Publishing to npm (public package)
142
-
143
- 1. Bump version in `package.json` (e.g. `0.1.1`).
144
- 2. Build the library: `pnpm run build:lib` (outputs to `dist/`).
145
- 3. Log in to npm: `npm login`.
146
- 4. Publish: `npm publish`. (Scoped package is public thanks to `"publishConfig": { "access": "public" }`.)
102
+ If port 3000 is taken, Next.js will auto-pick the next available port.
147
103
 
148
- ### Registry / Vercel
149
-
150
- 1. Make component changes in `registry/new-york/ui/` (and app previews as needed).
151
- 2. Update `registry.json` entries.
152
- 3. Run `pnpm run registry:build`.
153
- 4. Validate both `/` and `/preview`.
154
- 5. Commit and push to `main` (Vercel deploys automatically).
104
+ ## Publishing
155
105
 
156
- ### Adding a new component
106
+ See the [Publishing Guide](docs/PUBLISHING.md) for the full workflow. Quick summary:
157
107
 
158
- 1. Add the component to `registry/new-york/ui/`
159
- 2. Register it in `registry.json`
160
- 3. Run `pnpm run registry:build`
161
- 4. Commit and push — Vercel auto-deploys
108
+ 1. Make component changes in `registry/new-york/ui/`.
109
+ 2. Export new components from `index.ts`.
110
+ 3. Update `docs/components/{name}.md` and `docs/COMPONENTS.md`.
111
+ 4. Bump the version in `package.json` (semver: patch / minor / major).
112
+ 5. Run `npm publish` (build runs automatically via `prepublishOnly`).
113
+ 6. Optionally run `pnpm run registry:build` and push to deploy the showcase site.
162
114
 
163
115
  ## Theme Presets
164
116
 
165
- The `app/themes/` directory contains example theme presets to validate the theming contract:
117
+ Three example presets in `app/themes/` validate the theming contract:
118
+
119
+ | Preset | Description |
120
+ |---|---|
121
+ | **Neutral** (default) | Black/white, grayscale accents |
122
+ | **Forest** | Dark green primary, earthy tones |
123
+ | **Ocean** | Deep blue primary, cool tones |
166
124
 
167
- - **neutral** (default) — Black/white, grayscale accents
168
- - **forest** — Dark green primary, earthy tones
169
- - **ocean** — Deep blue primary, cool tones
125
+ See the [Styling Reference](docs/STYLING.md) for detailed token tables and instructions on creating custom themes.