@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.
Files changed (74) hide show
  1. package/README.md +233 -0
  2. package/generated/atom63.figma-tokens.json +21650 -0
  3. package/generated/atom63.tokens.json +21909 -0
  4. package/package.json +116 -0
  5. package/src/animations/animations.css +55 -0
  6. package/src/animations/index.css +1 -0
  7. package/src/compat/a63-from-shadcn.css +141 -0
  8. package/src/compat/index.css +2 -0
  9. package/src/compat/mdx.css +13 -0
  10. package/src/compat/shadcn.css +52 -0
  11. package/src/contracts/action.css +31 -0
  12. package/src/contracts/badge.css +68 -0
  13. package/src/contracts/choice.css +32 -0
  14. package/src/contracts/control.css +102 -0
  15. package/src/contracts/environment.css +158 -0
  16. package/src/contracts/field.css +26 -0
  17. package/src/contracts/index.css +26 -0
  18. package/src/contracts/marker.css +23 -0
  19. package/src/contracts/menu.css +100 -0
  20. package/src/contracts/overlay.css +44 -0
  21. package/src/contracts/segment.css +100 -0
  22. package/src/contracts/selection.css +21 -0
  23. package/src/contracts/skeleton.css +14 -0
  24. package/src/contracts/surface.css +56 -0
  25. package/src/contracts/toggle.css +26 -0
  26. package/src/contracts/track.css +26 -0
  27. package/src/contracts/trigger.css +28 -0
  28. package/src/contracts/widget.css +196 -0
  29. package/src/index.css +17 -0
  30. package/src/manifest/types.ts +61 -0
  31. package/src/os/index.css +2 -0
  32. package/src/os/macos.css +54 -0
  33. package/src/os/windows.css +299 -0
  34. package/src/tailwind/animations.css +8 -0
  35. package/src/tailwind/index.css +4 -0
  36. package/src/tailwind/theme.css +516 -0
  37. package/src/tailwind/utilities.css +41 -0
  38. package/src/tailwind/variants.css +64 -0
  39. package/src/test/apply-styles.ts +30 -0
  40. package/src/themes/aqua.css +240 -0
  41. package/src/themes/index.css +4 -0
  42. package/src/themes/modern.css +55 -0
  43. package/src/themes/retro.css +112 -0
  44. package/src/themes/terminal.css +179 -0
  45. package/src/tokens/brand.css +148 -0
  46. package/src/tokens/contrast.browser.test.ts +140 -0
  47. package/src/tokens/font.css +24 -0
  48. package/src/tokens/foundation/aliases.css +28 -0
  49. package/src/tokens/foundation/effects.css +31 -0
  50. package/src/tokens/foundation/fonts.css +11 -0
  51. package/src/tokens/foundation/motion.css +19 -0
  52. package/src/tokens/foundation/palette.css +255 -0
  53. package/src/tokens/foundation/primitives.css +420 -0
  54. package/src/tokens/foundation/radius.css +36 -0
  55. package/src/tokens/foundation/typography.css +191 -0
  56. package/src/tokens/foundation.css +15 -0
  57. package/src/tokens/index.css +9 -0
  58. package/src/tokens/motion.css +27 -0
  59. package/src/tokens/personalization-axes.browser.test.ts +240 -0
  60. package/src/tokens/radius.css +35 -0
  61. package/src/tokens/semantics.css +157 -0
  62. package/src/tokens/space.css +21 -0
  63. package/src/tokens/surface.css +184 -0
  64. package/src/tokens/theme-overrides.browser.test.ts +140 -0
  65. package/src/tokens/type-scale.css +20 -0
  66. package/src/tokens/widget-chrome-signature.browser.test.ts +225 -0
  67. package/src/tokens/widget-paint.browser.test.ts +98 -0
  68. package/src/utils/code-highlighting.css +35 -0
  69. package/src/utils/debug.css +453 -0
  70. package/src/utils/index.css +9 -0
  71. package/src/utils/scroll-bar.css +78 -0
  72. package/src/utils/scroll-mask.css +119 -0
  73. package/src/utils/view-transition.css +16 -0
  74. 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.