@contractspec/lib.design-system 3.8.9 → 3.8.11

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 (4) hide show
  1. package/README.md +105 -46
  2. package/dist/browser/index.js +1 -1196
  3. package/dist/index.js +1 -1196
  4. package/package.json +16 -16
package/README.md CHANGED
@@ -1,68 +1,127 @@
1
1
  # @contractspec/lib.design-system
2
2
 
3
- Website: https://contractspec.io
3
+ `@contractspec/lib.design-system` provides higher-level design-system components, tokens, platform adapters, renderers, and composed layouts used across web, native, marketing, legal, agent, and application surfaces.
4
4
 
5
- **Design tokens and theming primitives.**
5
+ Website: https://contractspec.io
6
6
 
7
- ## What It Provides
7
+ ## Installation
8
8
 
9
- - **Layer**: lib.
10
- - **Consumers**: accessibility, presentation-runtime-react, video-gen, bundles, apps.
11
- - Related ContractSpec packages include `@contractspec/lib.ai-agent`, `@contractspec/lib.contracts-runtime-client-react`, `@contractspec/lib.contracts-spec`, `@contractspec/lib.example-shared-ui`, `@contractspec/lib.presentation-runtime-react`, `@contractspec/lib.ui-kit`, ...
9
+ `bun add @contractspec/lib.design-system`
12
10
 
13
- ## Installation
11
+ or
14
12
 
15
13
  `npm install @contractspec/lib.design-system`
16
14
 
17
- or
15
+ ## What belongs here
18
16
 
19
- `bun add @contractspec/lib.design-system`
17
+ This package owns the higher-level design-system layer:
18
+
19
+ - Theme tokens and token bridging.
20
+ - Platform helpers and responsive hooks.
21
+ - Renderers and form-contract integration.
22
+ - Higher-level atoms, molecules, organisms, templates, and visualization components.
23
+ - Registry metadata and shadcn-style component registry support.
24
+
25
+ Use this package when you want the composed design-system layer. Do not use it when a lower-level primitive from `ui-kit` or `ui-kit-web` is enough.
26
+
27
+ ## Core workflows
28
+
29
+ ### Import a higher-level design-system component
30
+
31
+ ```ts
32
+ import { AppLayout, Button, HeroSection } from "@contractspec/lib.design-system";
33
+ ```
34
+
35
+ ### Work with tokens and platform helpers
36
+
37
+ ```ts
38
+ import {
39
+ defaultTokens,
40
+ mapTokensForPlatform,
41
+ withPlatformUI,
42
+ } from "@contractspec/lib.design-system";
43
+
44
+ const nativeTokens = mapTokensForPlatform("native");
45
+ const ui = withPlatformUI({
46
+ tokens: defaultTokens,
47
+ platform: "web",
48
+ });
49
+ ```
50
+
51
+ ## API map
52
+
53
+ ### Theme and platform
54
+
55
+ - `defaultTokens` and token interfaces from `./theme/tokens`
56
+ - `mapTokensForPlatform` from `./theme/tokenBridge`
57
+ - theme variants
58
+ - `withPlatformUI`
59
+ - `useColorScheme`
60
+ - `useReducedMotion`
61
+ - `useResponsive`
62
+
63
+ ### Renderers and hooks
64
+
65
+ - renderer exports from `./renderers`
66
+ - form-contract renderer support
67
+ - hooks such as `useListUrlState`
68
+ - navigation-related shared types
69
+
70
+ ### Component composition layers
71
+
72
+ - atoms
73
+ - forms
74
+ - legal
75
+ - marketing
76
+ - molecules
77
+ - organisms
78
+ - templates
79
+ - visualization
80
+ - agent and approval components
81
+
82
+ The root barrel is the primary API and already groups these exports in one place.
83
+
84
+ ## Public surface
85
+
86
+ The root barrel at `src/index.ts` is the main public API for this package.
20
87
 
21
- ## Usage
88
+ The export map is broad, but it is centralized:
22
89
 
23
- Import the root entrypoint from `@contractspec/lib.design-system`, or choose a documented subpath when you only need one part of the package surface.
90
+ - theme and platform helpers
91
+ - renderer exports
92
+ - high-level components grouped by composition layer
93
+ - hooks and shared types
24
94
 
25
- ## Architecture
95
+ The package also ships registry metadata and build support:
26
96
 
27
- - `src/components/` contains reusable UI components and view composition.
28
- - `src/hooks/` contains custom hooks for host applications.
29
- - `src/index.ts` is the root public barrel and package entrypoint.
30
- - `src/lib/` contains package-local helper utilities and adapters.
31
- - `src/platform` is part of the package's public or composition surface.
32
- - `src/renderers` is part of the package's public or composition surface.
33
- - `src/theme` is part of the package's public or composition surface.
97
+ - `components.json`
98
+ - `registry/registry.json`
99
+ - `bun run registry:build`
34
100
 
35
- ## Public Entry Points
101
+ ## Operational semantics and gotchas
36
102
 
37
- - Export `.` resolves through `./src/index.ts`.
103
+ - Token names and token shapes are compatibility surface.
104
+ - `mapTokensForPlatform()` deliberately returns different token shapes for web and native.
105
+ - `withPlatformUI()` is a lightweight adapter, not a full runtime framework.
106
+ - The root barrel is broad and therefore high-blast-radius.
107
+ - This package depends on both `ui-kit` and `ui-kit-web`.
108
+ - The package includes legal, marketing, agent, app-shell, and visualization compositions, not just low-level primitives.
38
109
 
39
- ## Local Commands
110
+ ## When not to use this package
40
111
 
41
- - `bun run dev` — contractspec-bun-build dev
42
- - `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
43
- - `bun run test` — bun test --pass-with-no-tests
44
- - `bun run lint` — bun run lint:fix
45
- - `bun run lint:check` — biome check .
46
- - `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
47
- - `bun run typecheck` — tsc --noEmit -p tsconfig.build.json
48
- - `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
49
- - `bun run publish:pkg:canary` — bun publish:pkg --tag canary
50
- - `bun run build:bundle` — contractspec-bun-build transpile
51
- - `bun run build:types` — contractspec-bun-build types
52
- - `bun run registry:build` — bun run scripts/build-registry.ts
53
- - `bun run prebuild` — contractspec-bun-build prebuild
112
+ - Do not use it for tiny low-level utilities.
113
+ - Do not use it for router-agnostic links.
114
+ - Do not use it when a single lower-level primitive from `ui-kit` or `ui-kit-web` is enough.
54
115
 
55
- ## Recent Updates
116
+ ## Related packages
56
117
 
57
- - Replace eslint+prettier by biomejs to optimize speed.
58
- - Add data visualization capabilities.
59
- - Add table capabilities.
60
- - Resolve lint, build, and type errors across nine packages.
61
- - Add AI provider ranking system with ranking-driven model selection.
62
- - Stabilize marketing header interactions.
118
+ - `@contractspec/lib.ui-kit`
119
+ - `@contractspec/lib.ui-kit-web`
120
+ - `@contractspec/lib.ui-kit-core`
121
+ - `@contractspec/lib.ui-link`
63
122
 
64
- ## Notes
123
+ ## Local commands
65
124
 
66
- - **High blast radius** — all UI surfaces depend on design tokens; treat token names and values as public API.
67
- - Component hierarchy must be preserved; do not flatten or restructure without coordinating downstream consumers.
68
- - Token removals or renames are breaking changes.
125
+ - `bun run lint:check`
126
+ - `bun run typecheck`
127
+ - `bun run test`