@handled-ai/design-system 0.2.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 (2) hide show
  1. package/README.md +80 -65
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,58 +1,68 @@
1
1
  # @handled Design System
2
2
 
3
- A shared design system built on [shadcn/ui](https://ui.shadcn.com), hosted as a custom shadcn registry. Components are customized shadcn primitives distributed via the `shadcn` CLI.
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
- ## What You Can View
5
+ ## Documentation
6
6
 
7
- When the app is running locally, there are two main experiences:
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 |
8
14
 
9
- - **Component gallery:** `/`
10
- Browse individual components and UX blocks rendered directly on the page.
11
- - **Prototype view:** `/preview`
12
- See the Acme Co-style end-to-end product prototype (sidebar, inbox/work queue, detail view, insights dashboard, meetings, and coaching banner patterns).
15
+ ## Architecture
13
16
 
14
- 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.
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
15
23
 
16
- ## Architecture
24
+ ## Cursor Rules
25
+
26
+ This repo includes Cursor rules that provide AI-assisted development context.
27
+
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 |
32
+
33
+ Consuming apps can adopt their own design system rule using the [template](docs/CONSUMING_APP_RULE_TEMPLATE.mdc).
34
+
35
+ ## Components
36
+
37
+ The design system includes 62+ components across these categories:
38
+
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
17
48
 
18
- - **Registry format:** Static JSON files served at `/r/{name}.json`
19
- - **Component source:** `registry/new-york/ui/` — customized shadcn primitives + custom UX blocks
20
- - **Theming:** CSS variables — consuming projects define their own palette
21
- - **Build tool:** `shadcn build` generates distributable JSON from source
22
-
23
- ## Available Components
24
-
25
- | Component | Description |
26
- |-----------|-------------|
27
- | `button` | Button with multiple variants and sizes |
28
- | `card` | Card container with header, content, footer |
29
- | `dialog` | Modal dialog (Radix UI) |
30
- | `input` | Styled text input |
31
- | `label` | Form label |
32
- | `select` | Select dropdown (Radix UI) |
33
- | `table` | Responsive table |
34
- | `tabs` | Tab navigation (Radix UI) |
35
- | `badge` | Status indicator badges |
36
- | `avatar` | Avatar with image/fallback |
37
- | `dropdown-menu` | Dropdown menu with keyboard nav |
38
- | `tooltip` | Hover tooltip |
39
- | `sheet` | Slide-out panel |
40
- | `separator` | Visual divider |
41
- | `skeleton` | Loading placeholder |
42
- | `scroll-area` | Custom scrollable area |
43
- | `textarea` | Multi-line text input |
44
- | `activity-log` | Activity stream row pattern |
45
- | `chart` | Chart container and helpers |
46
- | `detail-view` | Production-style detail panel primitives |
47
- | `inbox-row` | Row-based inbox/work queue item |
48
- | `metric-card` | KPI cards with variants (including donut-style) |
49
- | `sidebar` | App navigation sidebar primitives |
49
+ See the [Component Reference](docs/COMPONENTS.md) for full API documentation including props, variants, and usage examples.
50
50
 
51
51
  ## Usage in a Consuming Project
52
52
 
53
- ### 1. Add the registry namespace
53
+ ### Install via npm (primary)
54
54
 
55
- In your project's `components.json`:
55
+ ```bash
56
+ pnpm add @handled-ai/design-system
57
+ ```
58
+
59
+ ```tsx
60
+ import { Button, Card, Input } from "@handled-ai/design-system"
61
+ ```
62
+
63
+ ### Install via shadcn registry (alternative)
64
+
65
+ Add the registry namespace to your project's `components.json`:
56
66
 
57
67
  ```json
58
68
  {
@@ -62,49 +72,54 @@ In your project's `components.json`:
62
72
  }
63
73
  ```
64
74
 
65
- ### 2. Install components
75
+ Then install individual components:
66
76
 
67
77
  ```bash
68
78
  npx shadcn@latest add @handled/button @handled/card @handled/input
69
79
  ```
70
80
 
71
- ### 3. Set your theme
81
+ ### Set your theme
72
82
 
73
- 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.
74
84
 
75
85
  ## Development
76
86
 
77
87
  ```bash
78
88
  pnpm install
79
- 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
80
91
  pnpm run registry:build # Build registry JSON files
92
+ pnpm run typecheck # Type-check the codebase
93
+ pnpm run lint # Run linter
81
94
  ```
82
95
 
83
96
  ### Local URLs
84
97
 
85
- - `http://localhost:3000/` (or the port shown in terminal): component gallery
86
- - `http://localhost:3000/preview` (or same active port): full prototype
87
- - `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
88
101
 
89
- ## Publishing Flow
102
+ If port 3000 is taken, Next.js will auto-pick the next available port.
90
103
 
91
- 1. Make component changes in `registry/new-york/ui/` (and app previews as needed).
92
- 2. Update `registry.json` entries.
93
- 3. Run `pnpm run registry:build`.
94
- 4. Validate both `/` and `/preview`.
95
- 5. Commit and push to `main` (Vercel deploys automatically).
104
+ ## Publishing
96
105
 
97
- ### Adding a new component
106
+ See the [Publishing Guide](docs/PUBLISHING.md) for the full workflow. Quick summary:
98
107
 
99
- 1. Add the component to `registry/new-york/ui/`
100
- 2. Register it in `registry.json`
101
- 3. Run `pnpm run registry:build`
102
- 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.
103
114
 
104
115
  ## Theme Presets
105
116
 
106
- 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 |
107
124
 
108
- - **neutral** (default) — Black/white, grayscale accents
109
- - **forest** — Dark green primary, earthy tones
110
- - **ocean** — Deep blue primary, cool tones
125
+ See the [Styling Reference](docs/STYLING.md) for detailed token tables and instructions on creating custom themes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@handled-ai/design-system",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Handled UI component library (shadcn-style, New York)",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",