@atom63/ui-foundation 0.1.1-beta.0

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.
package/README.md ADDED
@@ -0,0 +1,83 @@
1
+ # @atom63/ui-foundation
2
+
3
+ ## What this package is
4
+
5
+ Platform-neutral TypeScript contracts for renderer authors and Atom63 design-system
6
+ maintainers. This package describes component variants, sizes, states, slots,
7
+ token slots, and personalization axes. It is not a UI runtime and renders
8
+ nothing by itself; React application authors should normally start with
9
+ `@atom63/ui-react`.
10
+
11
+ Built by You Zhang through Hermes Agent
12
+
13
+ ## Install
14
+
15
+ The package name is `@atom63/ui-foundation`. Public npm availability is not
16
+ promised yet: the currently verified paths are a workspace dependency or a
17
+ locally packed tarball. Public publishing requires YZ approval and confirmation
18
+ of the npm organization policy.
19
+
20
+ After an approved public release, install by package name:
21
+
22
+ ```sh
23
+ pnpm add @atom63/ui-foundation
24
+ ```
25
+
26
+ Until then, use the workspace dependency:
27
+
28
+ ```json
29
+ {
30
+ "dependencies": {
31
+ "@atom63/ui-foundation": "workspace:*"
32
+ }
33
+ }
34
+ ```
35
+
36
+ For a non-workspace consumer, pack the package and install the generated
37
+ `atom63-ui-foundation-*.tgz` file by path.
38
+
39
+ ## Minimum setup
40
+
41
+ Import contracts from the package root. No provider, initialization, or DOM
42
+ setup is required.
43
+
44
+ ## First contract usage
45
+
46
+ ```ts
47
+ import { buttonContract, type ButtonContract } from '@atom63/ui-foundation'
48
+
49
+ const contract: ButtonContract = buttonContract
50
+
51
+ export const rendererDefaults = {
52
+ size: contract.defaultSize,
53
+ variant: contract.defaultVariant,
54
+ }
55
+ ```
56
+
57
+ Use the exported readonly contract data to keep another renderer or design tool
58
+ aligned with Atom63. Do not mutate it or treat it as rendered component code.
59
+
60
+ ## CSS imports
61
+
62
+ None. This package has no runtime side effects and ships TypeScript/JavaScript
63
+ contract data only. Use `@atom63/styles` for executable CSS.
64
+
65
+ ## Theming
66
+
67
+ Themes are implemented by `@atom63/styles`. This package defines the shared
68
+ personalization-axis vocabulary, including theme and mode metadata, for code
69
+ that builds or validates renderers.
70
+
71
+ ## Stable vs preview
72
+
73
+ The production consumption path is verified by `pnpm check:ds-pack-smoke`
74
+ against packed tarballs. Public publishing still requires YZ approval and npm
75
+ organization policy. Some contracts may remain preview while cross-renderer API
76
+ hardening continues; an exported contract is not automatically a stable public
77
+ commitment.
78
+
79
+ ## Docs
80
+
81
+ - [Design system handbook](../../docs/design-system/README.md)
82
+ - [Cross-renderer contracts](../../docs/design-system/cross-renderer-contracts.md)
83
+ - [Production readiness audit](../../docs/design-system/production-readiness-audit.md)