@sckyzo/cosmos-theme 0.4.0 → 0.4.1
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/CHANGELOG.md +7 -0
- package/README.md +27 -175
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,13 @@ All notable changes to `@sckyzo/cosmos-theme` are documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.4.1](https://github.com/SckyzO/cosmos/compare/@sckyzo/cosmos-theme@0.4.0...@sckyzo/cosmos-theme@0.4.1) (2026-10-31)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Miscellaneous Chores
|
|
12
|
+
|
|
13
|
+
* **@sckyzo/cosmos-theme:** Synchronize cosmos versions
|
|
14
|
+
|
|
8
15
|
## [0.4.0](https://github.com/SckyzO/cosmos/compare/@sckyzo/cosmos-theme@0.3.0...@sckyzo/cosmos-theme@0.4.0) (2026-10-30)
|
|
9
16
|
|
|
10
17
|
|
package/README.md
CHANGED
|
@@ -2,23 +2,30 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@sckyzo/cosmos-theme)
|
|
4
4
|
|
|
5
|
-
Cosmos design tokens
|
|
5
|
+
Cosmos design tokens, CSS only: a Tailwind 4 `@theme` block, four themes, twelve accents, six
|
|
6
|
+
fonts, and text size, density and corner radius settings. It is what `@sckyzo/cosmos-react` and
|
|
7
|
+
`@sckyzo/cosmos-charts` are styled with, and it works on its own in any framework.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
| Import | Purpose |
|
|
10
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `@sckyzo/cosmos-theme/tailwind` | Tailwind 4 `@theme` block (palette, fonts, shadows, brand colors), the `dark:` and `rtl:` variants, the focus utilities |
|
|
12
|
+
| `@sckyzo/cosmos-theme/vars` | The CSS custom properties (bg, text, border, accent), the themes and the accents |
|
|
13
|
+
| `@sckyzo/cosmos-theme/fonts` | `@fontsource` font imports (Outfit + JetBrains Mono) |
|
|
14
|
+
| `@sckyzo/cosmos-theme/fonts/<name>` | One variable font for `data-font`: `inter`, `plex`, `montserrat`, `open-sans` |
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @sckyzo/cosmos-theme
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The three Cosmos packages share one version number: install the same version of each.
|
|
15
23
|
|
|
16
24
|
## Usage
|
|
17
25
|
|
|
18
26
|
### With Tailwind 4 (recommended for React apps)
|
|
19
27
|
|
|
20
|
-
Import order matters: `tailwindcss` comes first, then the Cosmos tokens, then
|
|
21
|
-
the vars.
|
|
28
|
+
Import order matters: `tailwindcss` comes first, then the Cosmos tokens, then the vars.
|
|
22
29
|
|
|
23
30
|
```css
|
|
24
31
|
/* src/index.css */
|
|
@@ -28,9 +35,7 @@ the vars.
|
|
|
28
35
|
@import '@sckyzo/cosmos-theme/fonts';
|
|
29
36
|
```
|
|
30
37
|
|
|
31
|
-
|
|
32
|
-
Tailwind scans the components — see the
|
|
33
|
-
[cosmos-react README](../react#set-up-the-styles).
|
|
38
|
+
With `@sckyzo/cosmos-react`, also add an `@source` line so Tailwind scans the components: see [Getting started](https://github.com/SckyzO/cosmos/blob/main/docs/getting-started.md#set-up-the-styles).
|
|
34
39
|
|
|
35
40
|
### Without Tailwind (e.g. Docusaurus)
|
|
36
41
|
|
|
@@ -40,175 +45,22 @@ Tailwind scans the components — see the
|
|
|
40
45
|
/* Then reference vars: var(--color-brand-500), var(--color-bg-base), etc. */
|
|
41
46
|
```
|
|
42
47
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
Two independent settings, both on the `<html>` element:
|
|
46
|
-
|
|
47
|
-
- **Theme**: one class, and only one at a time.
|
|
48
|
-
|
|
49
|
-
| Theme | Class | Look |
|
|
50
|
-
| ----------- | ------------ | -------------------------------------------- |
|
|
51
|
-
| `light` | _(none)_ | Cool gray, the default |
|
|
52
|
-
| `sand` | `.sand` | Warm beige light theme |
|
|
53
|
-
| `dark` | `.dark` | Neutral black/gray, softened (no pure black) |
|
|
54
|
-
| `deep-blue` | `.deep-blue` | Navy dark theme |
|
|
48
|
+
### Set the appearance
|
|
55
49
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
redefined to follow the nearest `dir` attribute, so a `dir="ltr"` island inside a right-to-left
|
|
60
|
-
page is not flipped. It does not follow `dir="auto"`, nor a `dir="rtl"` nested inside such an
|
|
61
|
-
island.
|
|
62
|
-
|
|
63
|
-
- **Accent**: a `data-accent` attribute that swaps the whole `--color-brand-*`
|
|
64
|
-
scale (and with it `--color-accent` and the focus ring). Leave it off for
|
|
65
|
-
`blue`. The others are `indigo`, `violet`, `purple`, `rose`, `teal`, `cyan`,
|
|
66
|
-
`graphite`, `red`, `orange`, `amber`, `green`.
|
|
50
|
+
The theme is one class on `<html>`; the accent, the font, the text size, the density and the corner
|
|
51
|
+
radius are `data-accent`, `data-font`, `data-text-size`, `data-density` and `data-radius` attributes,
|
|
52
|
+
and the reading direction is the native `dir`.
|
|
67
53
|
|
|
68
54
|
```html
|
|
69
55
|
<html class="sand" data-accent="teal"></html>
|
|
70
56
|
```
|
|
71
57
|
|
|
72
|
-
|
|
73
|
-
warning, success): a red primary button reads as a destructive action. Offer
|
|
74
|
-
them last in any picker, after the others.
|
|
75
|
-
|
|
76
|
-
Every theme × accent pair meets WCAG AA for body text, links and white text on
|
|
77
|
-
the accent. `pnpm --filter @sckyzo/cosmos-theme test` runs the contrast check
|
|
78
|
-
(`scripts/check-contrast.mjs`) against the CSS files.
|
|
79
|
-
|
|
80
|
-
## Focus indicator
|
|
81
|
-
|
|
82
|
-
Four Tailwind utilities, shipped with `@sckyzo/cosmos-theme/tailwind`, give
|
|
83
|
-
every control the same keyboard focus look: a **solid accent indicator** plus
|
|
84
|
-
the `--shadow-focus-ring` halo (12% of the accent). The halo alone is too faint
|
|
85
|
-
to count: the solid part is what reaches 3:1 against the surface (WCAG 1.4.11;
|
|
86
|
-
`brand-500` is checked on every theme × accent pair by `pnpm test`).
|
|
87
|
-
|
|
88
|
-
| Utility | Paints | For |
|
|
89
|
-
| --------------------------- | --------------------------- | --------------------------------------------------------------------- |
|
|
90
|
-
| `focus-indicator` | 2px `brand-500` ring + halo | buttons, links, toggles, tabs, menu items, cards… |
|
|
91
|
-
| `field-focus` | `brand-500` border + halo | text inputs, textarea, select and their wrappers |
|
|
92
|
-
| `field-focus-error` | `red-500` border + red halo | the same fields in error (`--shadow-focus-ring-error`) |
|
|
93
|
-
| `focus-indicator-on-accent` | 2px white ring, no halo | a control filled with `brand-500`, where the accent ring would vanish |
|
|
94
|
-
|
|
95
|
-
They hold no state: put the variant that fits in front of them.
|
|
96
|
-
|
|
97
|
-
```html
|
|
98
|
-
<button class="focus-visible:focus-indicator">Save</button>
|
|
99
|
-
<input class="focus:field-focus border border-gray-200" />
|
|
100
|
-
<div class="focus-within:field-focus border border-gray-200"><input /></div>
|
|
101
|
-
<!-- a control drawn by a sibling of a visually hidden input -->
|
|
102
|
-
<input type="checkbox" class="peer sr-only" />
|
|
103
|
-
<span class="peer-focus-visible:focus-indicator"></span>
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
There is no ring offset. Add `ring-inset` where an ancestor clips with
|
|
107
|
-
`overflow-hidden`, or a neighbour covers the outer ring. The utilities use
|
|
108
|
-
`outline-hidden`, so the indicator survives forced-colors mode, where box
|
|
109
|
-
shadows are not painted.
|
|
110
|
-
|
|
111
|
-
## Fonts & text size
|
|
112
|
-
|
|
113
|
-
Two more settings on `<html>`, both optional:
|
|
114
|
-
|
|
115
|
-
- **Font**: a `data-font` attribute that swaps `--font-sans`. Leave it off for
|
|
116
|
-
Outfit. The others are `inter`, `plex` (IBM Plex Sans), `montserrat`,
|
|
117
|
-
`open-sans`, and `system`, the platform's UI font. Each one loads from its own
|
|
118
|
-
subpath, so import only the fonts you offer; `system` loads nothing. The mono
|
|
119
|
-
font stays JetBrains Mono.
|
|
120
|
-
|
|
121
|
-
```css
|
|
122
|
-
@import '@sckyzo/cosmos-theme/fonts'; /* Outfit + JetBrains Mono */
|
|
123
|
-
@import '@sckyzo/cosmos-theme/fonts/inter';
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
- **Text size**: a `data-text-size` attribute, `sm`, `lg` or `xl`, that scales
|
|
127
|
-
every `text-*` size to 93.75%, 112.5% or 125%. Leave it off for 100%. Only the
|
|
128
|
-
text grows: spacing keeps its `rem` values, so layouts keep their density.
|
|
129
|
-
Sizes written in pixels, such as `text-[13px]`, don't scale; the `text-*`
|
|
130
|
-
scale includes `text-2xs` (11px) and `text-3xs` (10px) for small labels.
|
|
131
|
-
|
|
132
|
-
```html
|
|
133
|
-
<html class="sand" data-accent="teal" data-font="inter" data-text-size="lg"></html>
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Both attributes also work on an element below `<html>`, for one part of a page.
|
|
137
|
-
|
|
138
|
-
## Density
|
|
139
|
-
|
|
140
|
-
A `data-density` attribute on `<html>` tightens or loosens the vertical rhythm of
|
|
141
|
-
every control and row at once: `compact`, none for the default, or `comfortable`.
|
|
142
|
-
Only the heights and the vertical padding of rows move; panel padding, gaps and
|
|
143
|
-
horizontal padding stay. It applies on touch screens too: the user's choice wins.
|
|
144
|
-
|
|
145
|
-
| Token | Default | `compact` | `comfortable` | Used by |
|
|
146
|
-
| ------------------------------ | ---------- | --------- | ------------- | --------------------------- |
|
|
147
|
-
| `h-ctrl-28` … `h-ctrl-48` | 28–48px | 4px less | 4px more | buttons, fields, segments |
|
|
148
|
-
| `py-row-4` … `py-row-24` | 4–24px | 2px less | 2px more | list rows, menu items, tabs |
|
|
149
|
-
| `py-cell-head`, `py-cell-body` | 12px, 14px | 8px, 10px | 16px, 20px | table cells |
|
|
150
|
-
|
|
151
|
-
The token is named by its default size: `h-ctrl-36` is today's `h-9`. The smallest
|
|
152
|
-
control, 28px, stays at 24px in `compact`, the WCAG 2.5.8 floor, and `py-row-5`
|
|
153
|
-
stops at 4px for the same reason. They are `--spacing-ctrl-*`, `--spacing-row-*` and
|
|
154
|
-
`--spacing-cell-*` theme variables, so any utility of the spacing scale takes
|
|
155
|
-
them (`h-ctrl-36`, `min-h-ctrl-36`, `size-ctrl-32`, `py-row-8`). Use them for a
|
|
156
|
-
control or a row of your own and it follows the page.
|
|
157
|
-
|
|
158
|
-
```html
|
|
159
|
-
<html class="sand" data-density="compact"></html>
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
The attribute also works on an element below `<html>`; `data-density="default"`
|
|
163
|
-
opts a part of a compact or comfortable page out (a `DataTable` with its own
|
|
164
|
-
`density` does this).
|
|
165
|
-
|
|
166
|
-
## Radius
|
|
167
|
-
|
|
168
|
-
A `data-radius` attribute on `<html>` rescales every corner at once: `none`,
|
|
169
|
-
`sm`, none for the default, or `lg`. It rebuilds Tailwind's own `--radius-*`
|
|
170
|
-
variables, the ones `rounded-sm` to `rounded-4xl` read, so a component needs
|
|
171
|
-
nothing more than those utilities.
|
|
172
|
-
|
|
173
|
-
| Step | `--radius-*` | `rounded-lg` (8px by default) |
|
|
174
|
-
| --------- | ------------------------------- | ----------------------------- |
|
|
175
|
-
| `none` | 2px, every one | 2px |
|
|
176
|
-
| `sm` | half of Tailwind's | 4px |
|
|
177
|
-
| (default) | Tailwind's, nothing moves | 8px |
|
|
178
|
-
| `lg` | one and a half times Tailwind's | 12px |
|
|
179
|
-
|
|
180
|
-
`rounded-full` and `rounded-none` are literals and never change: avatars,
|
|
181
|
-
status dots, switches, badges and pill buttons stay round at every step. A
|
|
182
|
-
corner that must follow the page goes through the scale. A bare `rounded` is a
|
|
183
|
-
fixed `0.25rem` in Tailwind 4, so write `rounded-sm` (the same value, through
|
|
184
|
-
the variable); an arbitrary `rounded-[10px]` is fixed too, and
|
|
185
|
-
`rounded-[calc(var(--radius-lg)*1.25)]` is not.
|
|
186
|
-
|
|
187
|
-
```html
|
|
188
|
-
<html class="sand" data-radius="lg"></html>
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
The attribute also works on an element below `<html>`; `data-radius="default"`
|
|
192
|
-
opts a part of the page out of its parent's radius.
|
|
193
|
-
|
|
194
|
-
## Tokens
|
|
195
|
-
|
|
196
|
-
See [`css/tailwind-tokens.css`](css/tailwind-tokens.css) for the full source.
|
|
197
|
-
|
|
198
|
-
The brand palette, the status colors and the semantic colors are always in the CSS (`@theme static`): Tailwind
|
|
199
|
-
only emits a theme variable that a utility uses, and the charts read these as plain `var(--color-…)`.
|
|
200
|
-
|
|
201
|
-
Categories:
|
|
58
|
+
## Documentation
|
|
202
59
|
|
|
203
|
-
-
|
|
204
|
-
-
|
|
205
|
-
-
|
|
206
|
-
- **Status** : `--color-status-{ok,warn,crit,unknown}`
|
|
207
|
-
- **Typography** : `--font-sans` (Outfit), `--font-mono` (JetBrains Mono), `--text-2xs` (11px), `--text-3xs` (10px)
|
|
208
|
-
- **Shadows** : `--shadow-card`, `--shadow-card-hover`, `--shadow-focus-ring` and `--shadow-focus-ring-error` (the focus halos)
|
|
209
|
-
- **Layout vars** (theme-aware): `--color-bg-{base,panel,elevated}`, `--color-text-{base,primary,secondary,muted}`, `--color-border`, `--color-accent`
|
|
210
|
-
- **Code highlighting** (theme-aware): `--color-code-foreground` and `--color-code-token-*` (keyword, string, comment, constant, function, parameter, string-expression, punctuation, link, inserted, deleted, changed). The names match Shiki's CSS variables theme with `variablePrefix: '--color-code-'`. Each one keeps 4.5:1 on CodeBlock's background in all four themes (checked by `pnpm test`).
|
|
60
|
+
- [Appearance](https://github.com/SckyzO/cosmos/blob/main/docs/guides/appearance.md): every theme, accent, font, text size, density and radius.
|
|
61
|
+
- [Tokens and focus](https://github.com/SckyzO/cosmos/blob/main/docs/guides/tokens.md): the design tokens and the focus utilities.
|
|
62
|
+
- [Getting started](https://github.com/SckyzO/cosmos/blob/main/docs/getting-started.md).
|
|
211
63
|
|
|
212
64
|
## License
|
|
213
65
|
|
|
214
|
-
MIT
|
|
66
|
+
MIT, see [LICENSE](https://github.com/SckyzO/cosmos/blob/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sckyzo/cosmos-theme",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Tailwind 4 theme and design tokens for the Cosmos design system — palette, typography, radii and CSS variables for its light, sand, dark and deep-blue themes.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "SckyzO",
|