@atom63/styles 0.1.0-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 +233 -0
- package/generated/atom63.figma-tokens.json +21650 -0
- package/generated/atom63.tokens.json +21909 -0
- package/package.json +116 -0
- package/src/animations/animations.css +55 -0
- package/src/animations/index.css +1 -0
- package/src/compat/a63-from-shadcn.css +141 -0
- package/src/compat/index.css +2 -0
- package/src/compat/mdx.css +13 -0
- package/src/compat/shadcn.css +52 -0
- package/src/contracts/action.css +31 -0
- package/src/contracts/badge.css +68 -0
- package/src/contracts/choice.css +32 -0
- package/src/contracts/control.css +102 -0
- package/src/contracts/environment.css +158 -0
- package/src/contracts/field.css +26 -0
- package/src/contracts/index.css +26 -0
- package/src/contracts/marker.css +23 -0
- package/src/contracts/menu.css +100 -0
- package/src/contracts/overlay.css +44 -0
- package/src/contracts/segment.css +100 -0
- package/src/contracts/selection.css +21 -0
- package/src/contracts/skeleton.css +14 -0
- package/src/contracts/surface.css +56 -0
- package/src/contracts/toggle.css +26 -0
- package/src/contracts/track.css +26 -0
- package/src/contracts/trigger.css +28 -0
- package/src/contracts/widget.css +196 -0
- package/src/index.css +17 -0
- package/src/manifest/types.ts +61 -0
- package/src/os/index.css +2 -0
- package/src/os/macos.css +54 -0
- package/src/os/windows.css +299 -0
- package/src/tailwind/animations.css +8 -0
- package/src/tailwind/index.css +4 -0
- package/src/tailwind/theme.css +516 -0
- package/src/tailwind/utilities.css +41 -0
- package/src/tailwind/variants.css +64 -0
- package/src/test/apply-styles.ts +30 -0
- package/src/themes/aqua.css +240 -0
- package/src/themes/index.css +4 -0
- package/src/themes/modern.css +55 -0
- package/src/themes/retro.css +112 -0
- package/src/themes/terminal.css +179 -0
- package/src/tokens/brand.css +148 -0
- package/src/tokens/contrast.browser.test.ts +140 -0
- package/src/tokens/font.css +24 -0
- package/src/tokens/foundation/aliases.css +28 -0
- package/src/tokens/foundation/effects.css +31 -0
- package/src/tokens/foundation/fonts.css +11 -0
- package/src/tokens/foundation/motion.css +19 -0
- package/src/tokens/foundation/palette.css +255 -0
- package/src/tokens/foundation/primitives.css +420 -0
- package/src/tokens/foundation/radius.css +36 -0
- package/src/tokens/foundation/typography.css +191 -0
- package/src/tokens/foundation.css +15 -0
- package/src/tokens/index.css +9 -0
- package/src/tokens/motion.css +27 -0
- package/src/tokens/personalization-axes.browser.test.ts +240 -0
- package/src/tokens/radius.css +35 -0
- package/src/tokens/semantics.css +157 -0
- package/src/tokens/space.css +21 -0
- package/src/tokens/surface.css +184 -0
- package/src/tokens/theme-overrides.browser.test.ts +140 -0
- package/src/tokens/type-scale.css +20 -0
- package/src/tokens/widget-chrome-signature.browser.test.ts +225 -0
- package/src/tokens/widget-paint.browser.test.ts +98 -0
- package/src/utils/code-highlighting.css +35 -0
- package/src/utils/debug.css +453 -0
- package/src/utils/index.css +9 -0
- package/src/utils/scroll-bar.css +78 -0
- package/src/utils/scroll-mask.css +119 -0
- package/src/utils/view-transition.css +16 -0
- package/src/z-layers.ts +40 -0
package/README.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# @atom63/styles
|
|
2
|
+
|
|
3
|
+
## What this package is
|
|
4
|
+
|
|
5
|
+
The executable style foundation for the React-first design system. Plain CSS
|
|
6
|
+
custom properties — **no Tailwind dependency in the core**. Tailwind and shadcn
|
|
7
|
+
are opt-in adapters, never required.
|
|
8
|
+
|
|
9
|
+
This is the canonical executable style layer used by `@atom63/ui-react` and the
|
|
10
|
+
Atom63 apps. See `docs/design-system/react-first-executable-design-system.md`
|
|
11
|
+
for the architecture that established it.
|
|
12
|
+
|
|
13
|
+
Built by You Zhang through Hermes Agent
|
|
14
|
+
|
|
15
|
+
## Quickstart
|
|
16
|
+
|
|
17
|
+
### Install
|
|
18
|
+
|
|
19
|
+
The package name is `@atom63/styles`. Public npm availability is not promised
|
|
20
|
+
yet: the currently verified paths are a workspace dependency or a locally
|
|
21
|
+
packed tarball. Public publishing requires YZ approval and confirmation of the
|
|
22
|
+
npm organization policy.
|
|
23
|
+
|
|
24
|
+
After an approved public release, install by package name:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
pnpm add @atom63/styles
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Until then, use the workspace dependency:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"@atom63/styles": "workspace:*"
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
For a non-workspace consumer, pack the package and install the generated
|
|
41
|
+
`atom63-styles-*.tgz` file by path.
|
|
42
|
+
|
|
43
|
+
### Minimum setup
|
|
44
|
+
|
|
45
|
+
Load the default entry once. No JavaScript provider or runtime initialization is
|
|
46
|
+
required.
|
|
47
|
+
|
|
48
|
+
### CSS imports
|
|
49
|
+
|
|
50
|
+
Import the foundation once from your application CSS or JavaScript entry:
|
|
51
|
+
|
|
52
|
+
```css
|
|
53
|
+
@import "@atom63/styles";
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
This default entry includes tokens, contracts, themes, OS styles, animations,
|
|
57
|
+
and utilities. It does not include the Tailwind or shadcn adapters.
|
|
58
|
+
|
|
59
|
+
### First contract usage
|
|
60
|
+
|
|
61
|
+
Use semantic variables for intent and shared scale variables for dimensions in
|
|
62
|
+
application CSS:
|
|
63
|
+
|
|
64
|
+
```css
|
|
65
|
+
.product-panel {
|
|
66
|
+
color: var(--a63-text-primary);
|
|
67
|
+
background: var(--a63-surface-panel);
|
|
68
|
+
border: 1px solid var(--a63-border-subtle);
|
|
69
|
+
border-radius: var(--radius-lg);
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Theming
|
|
74
|
+
|
|
75
|
+
The default import includes the `modern`, `aqua`, `retro`, and `terminal`
|
|
76
|
+
themes. Set theme and mode on a shared ancestor, normally `<html>`:
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<html class="dark" data-a63-mode="dark" data-a63-theme="aqua">
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Use `light` or `dark` for mode and one theme value at a time. Tailwind v4 users
|
|
83
|
+
can additionally import `@atom63/styles/tailwind`; Atom63 apps that need shadcn
|
|
84
|
+
variable names can import `@atom63/styles/compat/shadcn`.
|
|
85
|
+
|
|
86
|
+
### Stable vs preview
|
|
87
|
+
|
|
88
|
+
The production consumption path is verified by `pnpm check:ds-pack-smoke`
|
|
89
|
+
against packed tarballs. Public publishing still requires YZ approval and npm
|
|
90
|
+
organization policy. Some token, adapter, and package surfaces may remain
|
|
91
|
+
preview while API hardening continues; do not infer stability from an export
|
|
92
|
+
alone.
|
|
93
|
+
|
|
94
|
+
### Docs
|
|
95
|
+
|
|
96
|
+
- [Design system handbook](../../docs/design-system/README.md)
|
|
97
|
+
- [Authoring surfaces](../../docs/design-system/authoring-surfaces.md)
|
|
98
|
+
- [Production readiness audit](../../docs/design-system/production-readiness-audit.md)
|
|
99
|
+
|
|
100
|
+
**Authoring (where to edit):** start at [`docs/design-system/README.md`](../../docs/design-system/README.md), then [`authoring-surfaces.md`](../../docs/design-system/authoring-surfaces.md) —
|
|
101
|
+
foundation owns **shared** dictionaries; themes may own skin-private material
|
|
102
|
+
under `[data-a63-theme]`; semantics/contracts/adapters alias or remap.
|
|
103
|
+
Tailwind/shadcn names are the day-to-day design surface. Shared-scale drift
|
|
104
|
+
(deferred): [`foundation-value-drift.md`](../../docs/design-system/foundation-value-drift.md).
|
|
105
|
+
|
|
106
|
+
```css
|
|
107
|
+
@import "@atom63/styles";
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Layer model
|
|
111
|
+
|
|
112
|
+
Default entry `@atom63/styles` (`src/index.css`) imports **tokens → contracts →
|
|
113
|
+
themes → os → animations → utils only** — never `tailwind/`, never `compat/`.
|
|
114
|
+
|
|
115
|
+
| Layer | Path | Purpose | May reference |
|
|
116
|
+
| --- | --- | --- | --- |
|
|
117
|
+
| **Foundation** | `tokens/foundation/*` | **Shared dictionaries** — palette, spacing, sizes, z, radius, fonts, typography, generic shadow/blur scales, motion | nothing (literals) or other foundation |
|
|
118
|
+
| **Semantic** (canonical) | `tokens/semantics.css` + `tokens/brand.css` | `--a63-*` intent roles (surface/text/border/status; primary + focus in brand). Alias/compose foundation; light/dark resolution lives here | foundation |
|
|
119
|
+
| **Scale bridges** | `tokens/{space,radius,type-scale,font,motion}.css` | `--a63-*` semantic scale aliases over the foundation | foundation |
|
|
120
|
+
| **Contract** | `contracts/*` | Shared component-family contracts (`control`, `field`, `overlay`, `badge`, …) + environment dimensions (`environment.css`) | semantic + scale bridges |
|
|
121
|
+
| **Theme** | `themes/*` | Skin character under `[data-a63-theme]` — assigns contracts; **may** own theme-private material (gel/bevel/CRT). No new shared scales; never structure | semantic + foundation |
|
|
122
|
+
| **OS** | `os/*` | Chrome **structure** + chrome-specific paint tokens that compose from semantics (`--a63-os-*`) under `[data-a63-os]` — peer of theme | foundation + semantic |
|
|
123
|
+
| **Animations** | `animations/*` | Generic executable CSS (keyframes) | foundation |
|
|
124
|
+
| **Utils** | `utils/*` | Reusable utilities (scrollbars, masks, code highlighting, view transitions, debug) | semantic + foundation |
|
|
125
|
+
| **Adapters** (opt-in) | `tailwind/*`, `compat/*` | Re-expose the canonical layer to Tailwind v4 and shadcn/MDX consumers | canonical values (re-reference only) |
|
|
126
|
+
|
|
127
|
+
Component **recipes** (variants/states/local overrides) live with the renderer
|
|
128
|
+
(`@atom63/ui-react/.../recipes/*.css`), not here. They consume `--a63-*`
|
|
129
|
+
semantic + contract tokens.
|
|
130
|
+
|
|
131
|
+
## Precedence chain (north-star)
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
Primitive → Semantic (--a63-*) → Design Language → Mode → Theme → OS → Variant → State → Local Override
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- **Primitive / Semantic** — `tokens/foundation/*`, `tokens/semantics.css`
|
|
138
|
+
- **Design Language / Input / Density** — `contracts/environment.css`
|
|
139
|
+
(`[data-a63-design-language]`, `[data-a63-input]`, `[data-a63-density]`)
|
|
140
|
+
- **Mode** — `.light` / `.dark` (`[data-a63-mode]`) on the semantic layer
|
|
141
|
+
- **Theme** — `themes/*.css` under `[data-a63-theme]` (visual skin / paint)
|
|
142
|
+
- **OS** — `os/*.css` under `[data-a63-os]` (chrome structure + chrome paint
|
|
143
|
+
tokens that resolve through semantics; peer of theme)
|
|
144
|
+
- **Variant / State / Local** — renderer recipes
|
|
145
|
+
|
|
146
|
+
Each dimension is a **personalization axis** with its own values, default, and
|
|
147
|
+
token ownership — see [Personalization axes](../../docs/design-system/personalization-axes.md)
|
|
148
|
+
(single source of truth: `@atom63/ui-foundation` → `personalizationAxes`).
|
|
149
|
+
|
|
150
|
+
## The mirror rule (invariant)
|
|
151
|
+
|
|
152
|
+
**Every token category keeps its real values in a plain `:root` layer. Adapters
|
|
153
|
+
(`tailwind/`, `compat/`) only _re-reference_ those values — they never
|
|
154
|
+
recompute.** Violating this silently breaks the default, adapter-free path,
|
|
155
|
+
because the adapter layers are not imported by `src/index.css`.
|
|
156
|
+
|
|
157
|
+
> **Cautionary example.** The derived `--radius-*` scale (and later `--blur-*`)
|
|
158
|
+
> once lived only inside `tailwind/theme.css` (`@theme inline`). Every other
|
|
159
|
+
> category mirrored a plain `:root` var; those were the exceptions. Result: on
|
|
160
|
+
> the default path the tokens were undefined. Fixed by moving the scales into
|
|
161
|
+
> `tokens/foundation/{radius,effects}.css` and making Tailwind re-reference them.
|
|
162
|
+
|
|
163
|
+
A `find … -not -path "*/tailwind/*" -not -path "*/compat/*"` resolver that checks
|
|
164
|
+
every `var(--x)` on the default path resolves to a definition catches this class
|
|
165
|
+
of bug; run it after touching the token layers.
|
|
166
|
+
|
|
167
|
+
## Canonical `--a63-*` semantic tokens
|
|
168
|
+
|
|
169
|
+
Surfaces, text, borders, danger/status, and scrim are defined in
|
|
170
|
+
`tokens/semantics.css` (`:root, .light` + `.dark` overrides). Primary action and
|
|
171
|
+
focus ring are brand-derived in `tokens/brand.css` (scoped to
|
|
172
|
+
`:root, [data-a63-brand]` so they re-resolve per ramp). Together these are the
|
|
173
|
+
single source of semantic truth.
|
|
174
|
+
|
|
175
|
+
| Group | Tokens | Home |
|
|
176
|
+
| --- | --- | --- |
|
|
177
|
+
| Surface | `--a63-surface-page`, `--a63-surface-panel`, `--a63-surface-overlay`, `--a63-surface-muted`, `--a63-surface-control`, `--a63-surface-control-hover` | `semantics.css` |
|
|
178
|
+
| Text | `--a63-text-primary`, `--a63-text-secondary` | `semantics.css` |
|
|
179
|
+
| Border | `--a63-border-subtle`, `--a63-border-control` | `semantics.css` |
|
|
180
|
+
| Action | `--a63-action-primary` (+ `-hover`, `-foreground`), `--a63-action-danger` (+ `-hover`, `-foreground`), `--a63-action-neutral` (+ `-foreground`) | primary/focus in `brand.css`; danger/neutral in `semantics.css` |
|
|
181
|
+
| Status | `--a63-status-info`, `--a63-status-success`, `--a63-status-warning` (+ `-foreground`) | `semantics.css` |
|
|
182
|
+
| Focus | `--a63-focus-ring` | `brand.css` |
|
|
183
|
+
| Scrim | `--a63-scrim` | `semantics.css` |
|
|
184
|
+
|
|
185
|
+
Contract tokens (`--a63-control-*`, `--a63-field-*`, `--a63-overlay-*`,
|
|
186
|
+
`--a63-badge-*`, `--a63-space-*`, `--a63-radius-*`, `--a63-motion-*`,
|
|
187
|
+
`--a63-platform-*`, `--a63-density-scale`) build on these; see `contracts/*` and
|
|
188
|
+
the `tokens/*` bridges.
|
|
189
|
+
|
|
190
|
+
## shadcn compatibility (opt-in bridges)
|
|
191
|
+
|
|
192
|
+
Two **opposite** adapters — pick one direction per app, never both:
|
|
193
|
+
|
|
194
|
+
| Import | Direction | Use when |
|
|
195
|
+
| --- | --- | --- |
|
|
196
|
+
| `@atom63/styles/compat/shadcn` | `--a63-*` → shadcn names (`--background`, …) | Atom63 apps that load `@atom63/styles` (canonical) |
|
|
197
|
+
| `@atom63/styles/compat/a63-from-shadcn` | shadcn → `--a63-*` (+ flat control defaults) | External shadcn hosts that render `@atom63/ui-react` without the Atom63 foundation |
|
|
198
|
+
|
|
199
|
+
`@atom63/styles/compat` (barrel) loads **mdx + forward shadcn only** — not the reverse bridge.
|
|
200
|
+
|
|
201
|
+
### Forward map (`compat/shadcn`)
|
|
202
|
+
|
|
203
|
+
Aliases the shadcn vocabulary back onto `--a63-*`. Import only if you consume
|
|
204
|
+
shadcn-named variables; not part of the default bundle.
|
|
205
|
+
|
|
206
|
+
| shadcn | canonical |
|
|
207
|
+
| --- | --- |
|
|
208
|
+
| `--background` | `--a63-surface-page` |
|
|
209
|
+
| `--foreground` | `--a63-text-primary` |
|
|
210
|
+
| `--card` / `--card-foreground` | `--a63-surface-panel` / `--a63-text-primary` |
|
|
211
|
+
| `--popover` / `--popover-foreground` | `--a63-surface-overlay` / `--a63-text-primary` |
|
|
212
|
+
| `--muted` / `--muted-foreground` | `--a63-surface-muted` / `--a63-text-secondary` |
|
|
213
|
+
| `--secondary` / `--secondary-foreground` | `--a63-surface-muted` / `--a63-text-secondary` |
|
|
214
|
+
| `--accent` / `--accent-foreground` | `--a63-surface-control-hover` / `--a63-text-primary` |
|
|
215
|
+
| `--border` / `--input` | `--a63-border-subtle` / `--a63-border-control` |
|
|
216
|
+
| `--ring` | `--a63-focus-ring` |
|
|
217
|
+
| `--primary` / `--primary-foreground` | `--a63-action-primary` / `--a63-action-primary-foreground` |
|
|
218
|
+
| `--destructive` | `--a63-action-danger` |
|
|
219
|
+
| `--info` / `--success` / `--warning` | `--a63-status-*` |
|
|
220
|
+
| `--sidebar-*` | derived from the `--a63-*` above |
|
|
221
|
+
|
|
222
|
+
The Tailwind adapter (`@atom63/styles/tailwind`) maps its `--color-*` theme keys
|
|
223
|
+
onto the same canonical `--a63-*` layer.
|
|
224
|
+
|
|
225
|
+
## Entry points
|
|
226
|
+
|
|
227
|
+
- `@atom63/styles` — default, Tailwind- and shadcn-free foundation.
|
|
228
|
+
- `@atom63/styles/tailwind` — Tailwind v4 `@theme` adapter (opt-in).
|
|
229
|
+
- `@atom63/styles/compat/shadcn` — shadcn variable names from `--a63-*` (Atom63 apps).
|
|
230
|
+
- `@atom63/styles/compat/a63-from-shadcn` — `--a63-*` from shadcn (external hosts only; do not combine with `compat/shadcn`).
|
|
231
|
+
- `@atom63/styles/compat/mdx` — `@atom63/mdx` motion names (opt-in).
|
|
232
|
+
- Granular `./tokens/*`, `./contracts/*`, `./themes/*`, `./utils/*` exports for
|
|
233
|
+
targeted imports.
|