@threelight/ui 0.2.0-alpha.0 → 0.3.0-alpha.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 +62 -121
- package/css/base.css +735 -407
- package/dist/index.d.ts +242 -17
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +119 -54
- package/dist/index.js.map +1 -1
- package/examples/index.html +151 -53
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,170 +1,111 @@
|
|
|
1
1
|
# @threelight/ui
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
This package is an early alpha for the ThreeLight UI grammar. It publishes CSS
|
|
6
|
-
primitives, safe default theme tokens, examples, and typed registry metadata.
|
|
3
|
+
Short-class CSS, role tokens, and metadata for service UI systems.
|
|
7
4
|
|
|
8
5
|
```bash
|
|
9
6
|
pnpm add @threelight/ui@alpha
|
|
10
7
|
```
|
|
11
8
|
|
|
12
|
-
|
|
13
|
-
import "@threelight/ui/base.css"
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
Import this once from the application entrypoint or global stylesheet entry
|
|
17
|
-
before project-specific override CSS:
|
|
9
|
+
Import the CSS once:
|
|
18
10
|
|
|
19
11
|
```ts
|
|
20
|
-
import
|
|
21
|
-
import "./app.css"
|
|
12
|
+
import '@threelight/ui/base.css'
|
|
22
13
|
```
|
|
23
14
|
|
|
24
|
-
|
|
25
|
-
loaded later can intentionally override project-specific details.
|
|
26
|
-
|
|
27
|
-
## Applying The Styles
|
|
28
|
-
|
|
29
|
-
Importing the CSS loads ThreeLight styles globally, but primitives only apply
|
|
30
|
-
inside an explicit `data-tl-root` scope. This keeps existing project CSS from
|
|
31
|
-
being changed by import alone.
|
|
32
|
-
|
|
33
|
-
Apply ThreeLight to the whole app by putting the root attributes on `body`:
|
|
15
|
+
Opt a subtree into ThreeLight:
|
|
34
16
|
|
|
35
17
|
```html
|
|
36
18
|
<body data-tl-root data-tl-theme="default" data-tl-mode="light">
|
|
37
|
-
<
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
</main>
|
|
19
|
+
<button class="tl-button" data-tl-variant="solid" data-tl-tone="primary">
|
|
20
|
+
Deploy
|
|
21
|
+
</button>
|
|
41
22
|
</body>
|
|
42
23
|
```
|
|
43
24
|
|
|
44
|
-
|
|
25
|
+
## Contract
|
|
45
26
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
<main>
|
|
49
|
-
<section data-tl-root data-tl-theme="default" data-tl-mode="dark">
|
|
50
|
-
<article class="tl-card tl-stack" data-tl-tone="info">
|
|
51
|
-
<h2 class="tl-heading">Scoped preview</h2>
|
|
52
|
-
<p class="tl-body">Only this subtree uses ThreeLight primitives.</p>
|
|
53
|
-
</article>
|
|
54
|
-
</section>
|
|
55
|
-
</main>
|
|
56
|
-
</body>
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
`tl-*` classes outside `data-tl-root` are intentionally not styled.
|
|
60
|
-
|
|
61
|
-
## Overriding Styles
|
|
27
|
+
This alpha reset intentionally removes the old layer-prefixed contract. Public
|
|
28
|
+
classes are short and component-shaped:
|
|
62
29
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
--tl-primary-fill: #55ffff;
|
|
70
|
-
--tl-primary-on-fill: #061010;
|
|
71
|
-
--tl-primary-border: #27757c;
|
|
72
|
-
}
|
|
30
|
+
```text
|
|
31
|
+
tl-button
|
|
32
|
+
tl-table
|
|
33
|
+
tl-app-shell
|
|
34
|
+
tl-button__icon
|
|
35
|
+
tl-table__cell
|
|
73
36
|
```
|
|
74
37
|
|
|
75
|
-
|
|
76
|
-
primitive structure. For example, later app CSS such as `.my-page .tl-button {
|
|
77
|
-
padding: 0; border: 0; }` will change how that button renders.
|
|
78
|
-
|
|
79
|
-
## Primitive Contract
|
|
38
|
+
Variants, tone, size, density, and state are data attributes:
|
|
80
39
|
|
|
81
|
-
|
|
82
|
-
|
|
40
|
+
```html
|
|
41
|
+
<button
|
|
42
|
+
class="tl-button"
|
|
43
|
+
data-tl-variant="soft"
|
|
44
|
+
data-tl-tone="danger"
|
|
45
|
+
data-tl-size="sm"
|
|
46
|
+
>
|
|
47
|
+
Delete
|
|
48
|
+
</button>
|
|
49
|
+
```
|
|
83
50
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
- Action/status: `tl-button`, `tl-badge`, `tl-alert`
|
|
88
|
-
- Form: `tl-field`, `tl-input`, `tl-help`
|
|
51
|
+
Metadata exported from the package records each item as `core` or `candidate`.
|
|
52
|
+
Candidate components are public during alpha but may change as service templates
|
|
53
|
+
are reviewed.
|
|
89
54
|
|
|
90
|
-
|
|
91
|
-
`danger`. Omit `data-tl-tone` for neutral behavior.
|
|
55
|
+
## P0 Surface
|
|
92
56
|
|
|
93
|
-
|
|
94
|
-
text at the 14px readable floor, and expose spacing overrides through CSS custom
|
|
95
|
-
properties such as `--tl-gap`, `--tl-grid-min`, and `--tl-surface-padding`.
|
|
57
|
+
Core:
|
|
96
58
|
|
|
97
|
-
|
|
59
|
+
- `tl-button`, `tl-icon-button`, `tl-badge`, `tl-alert`
|
|
60
|
+
- `tl-card`, `tl-panel`, `tl-field`, `tl-input`, `tl-select`, `tl-switch`
|
|
61
|
+
- `tl-tabs`, `tl-table`, `tl-code-block`
|
|
62
|
+
- `tl-stack`, `tl-cluster`, `tl-grid`, `tl-heading`, `tl-text`, `tl-caption`
|
|
98
63
|
|
|
99
|
-
|
|
64
|
+
Candidate:
|
|
100
65
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
</article>
|
|
106
|
-
</body>
|
|
107
|
-
```
|
|
66
|
+
- `tl-app-shell`, `tl-side-nav`, `tl-top-bar`, `tl-toolbar`
|
|
67
|
+
- `tl-filter-bar`, `tl-metric-card`, `tl-metric-group`, `tl-data-panel`
|
|
68
|
+
- `tl-settings-section`, `tl-stepper`, `tl-choice-card`, `tl-empty-state`
|
|
69
|
+
- `tl-toast`, `tl-toast-region`, `tl-docs-shell`
|
|
108
70
|
|
|
109
|
-
|
|
110
|
-
- `data-tl-theme` selects palette family, initially `default`.
|
|
111
|
-
- `data-tl-mode` selects lightness mode, initially `light` or `dark`.
|
|
112
|
-
- `data-tl-tone` expresses component meaning and stays stable across themes.
|
|
71
|
+
## Tokens
|
|
113
72
|
|
|
114
|
-
|
|
73
|
+
Public tokens are role-based:
|
|
115
74
|
|
|
116
75
|
```text
|
|
117
|
-
--tl-canvas
|
|
118
|
-
--tl-surface
|
|
119
|
-
--tl-
|
|
120
|
-
--tl-
|
|
121
|
-
--tl-
|
|
122
|
-
--tl-
|
|
123
|
-
--tl-
|
|
124
|
-
--tl-
|
|
125
|
-
--tl-
|
|
76
|
+
--tl-color-canvas
|
|
77
|
+
--tl-color-surface
|
|
78
|
+
--tl-color-content-primary
|
|
79
|
+
--tl-color-border-subtle
|
|
80
|
+
--tl-color-primary-fill
|
|
81
|
+
--tl-radius-control
|
|
82
|
+
--tl-radius-card
|
|
83
|
+
--tl-shadow-card
|
|
84
|
+
--tl-density-compact
|
|
85
|
+
--tl-motion-duration-base
|
|
126
86
|
```
|
|
127
87
|
|
|
128
|
-
|
|
129
|
-
rewrite a component from `warning` to another tone unless the component meaning
|
|
130
|
-
changes.
|
|
88
|
+
Override tokens at `[data-tl-root]` after importing `base.css`.
|
|
131
89
|
|
|
132
|
-
##
|
|
133
|
-
|
|
134
|
-
The package exports readonly registry metadata for adapters and migration tools:
|
|
90
|
+
## Metadata
|
|
135
91
|
|
|
136
92
|
```ts
|
|
137
93
|
import {
|
|
94
|
+
componentContracts,
|
|
95
|
+
componentClasses,
|
|
138
96
|
primitiveClasses,
|
|
139
|
-
|
|
140
|
-
themeAttributes,
|
|
141
|
-
themeFamilies,
|
|
142
|
-
themeModes,
|
|
97
|
+
tokenNames,
|
|
143
98
|
toneNames,
|
|
144
|
-
|
|
99
|
+
variantNames,
|
|
100
|
+
} from '@threelight/ui'
|
|
145
101
|
```
|
|
146
102
|
|
|
147
|
-
Use
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
## Status
|
|
151
|
-
|
|
152
|
-
`@threelight/ui` is experimental. Public APIs may change before the first stable
|
|
153
|
-
release.
|
|
103
|
+
Use metadata for docs, adapters, migration tools, and guards instead of
|
|
104
|
+
hard-coding class names.
|
|
154
105
|
|
|
155
106
|
## Publishing
|
|
156
107
|
|
|
157
|
-
Publish alpha releases from the repository root with the scripted command. The
|
|
158
|
-
script runs package publish with an explicit `alpha` dist-tag.
|
|
159
|
-
|
|
160
108
|
```bash
|
|
161
109
|
pnpm release:ui:alpha
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
Check the published dist-tags with:
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
110
|
pnpm release:ui:tags
|
|
168
111
|
```
|
|
169
|
-
|
|
170
|
-
The tag check contacts the npm registry, so it requires network access.
|