@threelight/ui 0.2.0-alpha.1 → 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 +52 -140
- package/css/base.css +660 -457
- package/dist/index.d.ts +240 -29
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +103 -87
- package/dist/index.js.map +1 -1
- package/examples/index.html +150 -111
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,199 +1,111 @@
|
|
|
1
1
|
# @threelight/ui
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
`@threelight/ui` ships CSS, tokens, examples, and typed metadata. It does not
|
|
6
|
-
depend on React, Vue, Svelte, routing, data fetching, or application business
|
|
7
|
-
logic.
|
|
3
|
+
Short-class CSS, role tokens, and metadata for service UI systems.
|
|
8
4
|
|
|
9
5
|
```bash
|
|
10
6
|
pnpm add @threelight/ui@alpha
|
|
11
7
|
```
|
|
12
8
|
|
|
13
|
-
|
|
14
|
-
import "@threelight/ui/base.css"
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Import the CSS once from an application entrypoint or global stylesheet before
|
|
18
|
-
project-specific overrides:
|
|
9
|
+
Import the CSS once:
|
|
19
10
|
|
|
20
11
|
```ts
|
|
21
|
-
import
|
|
22
|
-
import "./app.css"
|
|
12
|
+
import '@threelight/ui/base.css'
|
|
23
13
|
```
|
|
24
14
|
|
|
25
|
-
|
|
15
|
+
Opt a subtree into ThreeLight:
|
|
26
16
|
|
|
27
17
|
```html
|
|
28
18
|
<body data-tl-root data-tl-theme="default" data-tl-mode="light">
|
|
29
|
-
<
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
<h1 class="tl-component-display">Project archive</h1>
|
|
33
|
-
<p class="tl-component-body">Readable governed UI foundations.</p>
|
|
34
|
-
</div>
|
|
35
|
-
<div class="tl-pattern-page-header__actions">
|
|
36
|
-
<button class="tl-component-button" data-tl-tone="primary" type="button">
|
|
37
|
-
New report
|
|
38
|
-
</button>
|
|
39
|
-
</div>
|
|
40
|
-
</header>
|
|
41
|
-
</main>
|
|
19
|
+
<button class="tl-button" data-tl-variant="solid" data-tl-tone="primary">
|
|
20
|
+
Deploy
|
|
21
|
+
</button>
|
|
42
22
|
</body>
|
|
43
23
|
```
|
|
44
24
|
|
|
45
|
-
##
|
|
25
|
+
## Contract
|
|
46
26
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
public contract.
|
|
50
|
-
|
|
51
|
-
Future adapters such as `@threelight/ui-react`, `@threelight/ui-vue`, or
|
|
52
|
-
`@threelight/ui-svelte` can wrap these approved class/data/token combinations
|
|
53
|
-
with thin component APIs. This package remains the framework-neutral HTML/CSS
|
|
54
|
-
core.
|
|
55
|
-
|
|
56
|
-
Class names follow a layer-prefixed alpha contract:
|
|
27
|
+
This alpha reset intentionally removes the old layer-prefixed contract. Public
|
|
28
|
+
classes are short and component-shaped:
|
|
57
29
|
|
|
58
30
|
```text
|
|
59
|
-
tl-
|
|
60
|
-
tl-
|
|
31
|
+
tl-button
|
|
32
|
+
tl-table
|
|
33
|
+
tl-app-shell
|
|
34
|
+
tl-button__icon
|
|
35
|
+
tl-table__cell
|
|
61
36
|
```
|
|
62
37
|
|
|
63
|
-
|
|
64
|
-
- `pattern`: repeated structures that combine components/layout, such as
|
|
65
|
-
`tl-pattern-page-header`.
|
|
66
|
-
- `layout`: structure without product meaning, such as `tl-layout-stack`.
|
|
67
|
-
- `utility`: small single-purpose adjustments, such as
|
|
68
|
-
`tl-utility-truncate`.
|
|
69
|
-
|
|
70
|
-
Do not put product or documentation-app names such as Lab, Studio, or MapBridge
|
|
71
|
-
in public class names.
|
|
72
|
-
|
|
73
|
-
## Adapter-Ready Foundations
|
|
38
|
+
Variants, tone, size, density, and state are data attributes:
|
|
74
39
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
Button is a component foundation, not a pattern.
|
|
86
|
-
|
|
87
|
-
## Data Attributes
|
|
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
|
+
```
|
|
88
50
|
|
|
89
|
-
|
|
90
|
-
|
|
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.
|
|
91
54
|
|
|
92
|
-
|
|
55
|
+
## P0 Surface
|
|
93
56
|
|
|
94
|
-
|
|
95
|
-
<article class="tl-component-alert" data-tl-tone="warning" role="status">
|
|
96
|
-
<p class="tl-component-body">This warning uses semantic tone tokens.</p>
|
|
97
|
-
</article>
|
|
98
|
-
```
|
|
57
|
+
Core:
|
|
99
58
|
|
|
100
|
-
|
|
101
|
-
`
|
|
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`
|
|
102
63
|
|
|
103
|
-
|
|
104
|
-
when content is loading, empty, or error; `@threelight/ui` provides safe
|
|
105
|
-
structure and readable defaults when those states are displayed.
|
|
64
|
+
Candidate:
|
|
106
65
|
|
|
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
71
|
## Tokens
|
|
110
72
|
|
|
111
|
-
|
|
112
|
-
utility classes. Do not add `tl-color-*` classes.
|
|
113
|
-
|
|
114
|
-
Global color tokens use an explicit namespace:
|
|
73
|
+
Public tokens are role-based:
|
|
115
74
|
|
|
116
75
|
```text
|
|
117
76
|
--tl-color-canvas
|
|
118
77
|
--tl-color-surface
|
|
119
|
-
--tl-color-layer
|
|
120
78
|
--tl-color-content-primary
|
|
121
|
-
--tl-color-content-secondary
|
|
122
|
-
--tl-color-content-subtle
|
|
123
79
|
--tl-color-border-subtle
|
|
124
|
-
--tl-color-border-strong
|
|
125
|
-
--tl-color-focus
|
|
126
80
|
--tl-color-primary-fill
|
|
127
|
-
--tl-
|
|
128
|
-
--tl-
|
|
129
|
-
--tl-
|
|
81
|
+
--tl-radius-control
|
|
82
|
+
--tl-radius-card
|
|
83
|
+
--tl-shadow-card
|
|
84
|
+
--tl-density-compact
|
|
85
|
+
--tl-motion-duration-base
|
|
130
86
|
```
|
|
131
87
|
|
|
132
|
-
|
|
133
|
-
`--tl-color-info-fill`, `--tl-color-success-content`, and
|
|
134
|
-
`--tl-color-danger-border`.
|
|
135
|
-
|
|
136
|
-
Component-local tokens such as `--tl-button-background`,
|
|
137
|
-
`--tl-button-content`, `--tl-button-disabled-content`, and
|
|
138
|
-
`--tl-component-border` may remain local to a component contract, but color
|
|
139
|
-
values should resolve to global `--tl-color-*` tokens.
|
|
140
|
-
|
|
141
|
-
Spacing, radius, font, font-size, and shadow tokens remain separately
|
|
142
|
-
namespaced: `--tl-space-*`, `--tl-radius-*`, `--tl-font-*`,
|
|
143
|
-
`--tl-font-size-*`, and `--tl-shadow-*`. Font-size tokens provide predictable
|
|
144
|
-
component scale without viewport-width font sizing.
|
|
88
|
+
Override tokens at `[data-tl-root]` after importing `base.css`.
|
|
145
89
|
|
|
146
90
|
## Metadata
|
|
147
91
|
|
|
148
|
-
Use the package metadata exports to avoid hard-coding public contract names in
|
|
149
|
-
adapters or migration tools:
|
|
150
|
-
|
|
151
92
|
```ts
|
|
152
93
|
import {
|
|
94
|
+
componentContracts,
|
|
153
95
|
componentClasses,
|
|
154
|
-
layoutClasses,
|
|
155
|
-
patternClasses,
|
|
156
|
-
patternPartClasses,
|
|
157
96
|
primitiveClasses,
|
|
158
|
-
stateNames,
|
|
159
|
-
themeAttributes,
|
|
160
97
|
tokenNames,
|
|
161
98
|
toneNames,
|
|
162
|
-
|
|
163
|
-
} from
|
|
99
|
+
variantNames,
|
|
100
|
+
} from '@threelight/ui'
|
|
164
101
|
```
|
|
165
102
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
Earlier alpha builds used short class names such as `tl-button`, `tl-card`, and
|
|
169
|
-
`tl-section`, plus unnamespaced color tokens such as `--tl-primary-fill` and
|
|
170
|
-
`--tl-primary-on-fill`.
|
|
171
|
-
|
|
172
|
-
Those short alpha class names are not the stable contract. They are not exported
|
|
173
|
-
from metadata, they are not used by primary examples, and future adapters should
|
|
174
|
-
not wrap them.
|
|
175
|
-
|
|
176
|
-
The primary class contract is the layer-prefixed naming:
|
|
177
|
-
`tl-component-*`, `tl-pattern-*`, `tl-layout-*`, and `tl-utility-*`.
|
|
178
|
-
|
|
179
|
-
The primary color token contract is `--tl-color-*`. Old unnamespaced color
|
|
180
|
-
tokens may exist temporarily inside CSS as alpha compatibility aliases to reduce
|
|
181
|
-
breakage, but they are not the preferred public contract and are not exported as
|
|
182
|
-
metadata. Consumers should migrate to the new class and token contract before
|
|
183
|
-
stable.
|
|
103
|
+
Use metadata for docs, adapters, migration tools, and guards instead of
|
|
104
|
+
hard-coding class names.
|
|
184
105
|
|
|
185
106
|
## Publishing
|
|
186
107
|
|
|
187
|
-
Publish alpha releases from the repository root with the scripted command:
|
|
188
|
-
|
|
189
108
|
```bash
|
|
190
109
|
pnpm release:ui:alpha
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Check the published dist-tags with:
|
|
194
|
-
|
|
195
|
-
```bash
|
|
196
110
|
pnpm release:ui:tags
|
|
197
111
|
```
|
|
198
|
-
|
|
199
|
-
The tag check contacts the npm registry, so it requires network access.
|