@classic-homes/theme-styles 0.8.0 → 0.10.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 CHANGED
@@ -25,14 +25,17 @@ The main entry defines the cascade layers, brand fonts, tokens, base, accessibil
25
25
 
26
26
  ## Exports
27
27
 
28
- | Import | Contents |
29
- | ------------------------------------------- | ---------------------------------------------------------- |
30
- | `@classic-homes/theme-styles` | All styles (fonts, tokens, base, accessibility, utilities) |
31
- | `@classic-homes/theme-styles/core` | Same as the main entry, without the brand fonts |
32
- | `@classic-homes/theme-styles/fonts` | Brand fonts |
33
- | `@classic-homes/theme-styles/base` | Base element styles |
34
- | `@classic-homes/theme-styles/accessibility` | Accessibility styles |
35
- | `@classic-homes/theme-styles/utilities` | Utility classes |
28
+ | Import | Contents |
29
+ | --------------------------------------------- | ---------------------------------------------------------- |
30
+ | `@classic-homes/theme-styles` | All styles (fonts, tokens, base, accessibility, utilities) |
31
+ | `@classic-homes/theme-styles/core` | Same as the main entry, without the brand fonts |
32
+ | `@classic-homes/theme-styles/fonts` | Brand fonts |
33
+ | `@classic-homes/theme-styles/base` | Base element styles |
34
+ | `@classic-homes/theme-styles/accessibility` | Accessibility styles |
35
+ | `@classic-homes/theme-styles/utilities` | Utility classes |
36
+ | `@classic-homes/theme-styles/tailwind-v4` | The theme for Tailwind CSS 4 (see below) |
37
+ | `@classic-homes/theme-styles/components.css` | Plain CSS `ch-*` component classes (see below) |
38
+ | `@classic-homes/theme-styles/components.json` | The `ch-*` class list as data (recipe, axis, option) |
36
39
 
37
40
  ### Touch field size
38
41
 
@@ -53,3 +56,263 @@ Use `/core` when the app already loads brand fonts:
53
56
  ```
54
57
 
55
58
  The `@layer` order must come before any other `@import` in your CSS. Keep it at the top of the file.
59
+
60
+ ## Component classes (`components.css`)
61
+
62
+ `@classic-homes/theme-styles/components.css` is plain, compiled CSS for pages with no framework and no Tailwind at runtime: HTML artifacts, emails rendered in a browser, static pages. It holds `ch-*` classes compiled at build time from the component recipes in `@classic-homes/theme-tokens/recipes`, the same class lists theme-svelte and theme-react render, so a `ch-btn` looks like a `<Button>`.
63
+
64
+ Load the tokens first, then the classes, and toggle `.dark` on `<html>` for dark mode:
65
+
66
+ ```html
67
+ <link rel="stylesheet" href="node_modules/@classic-homes/theme-tokens/dist/tokens.css" />
68
+ <link rel="stylesheet" href="node_modules/@classic-homes/theme-styles/dist/components.css" />
69
+
70
+ <button class="ch-btn">Save</button>
71
+ <button class="ch-btn ch-btn-outline ch-btn-sm">Cancel</button>
72
+ <span class="ch-badge ch-badge-success">Active</span>
73
+ <div class="ch-card">
74
+ <div class="ch-card-header"><h3 class="ch-card-title">Lot 14</h3></div>
75
+ <div class="ch-card-content">…</div>
76
+ </div>
77
+ ```
78
+
79
+ The file has no `@import`, no `@tailwind` and no `@layer`. It carries the `--tw-*` defaults the ring and shadow utilities read, and a reset scoped to `ch-*` elements (border box, solid zero borders, inherited fonts on form controls, transparent buttons); it does not include preflight or style anything else on the page. Its rules are unlayered; to let your own layered utilities override them, import it into a layer: `@import url('…/components.css') layer(components);`. See `examples/components-css/index.html` (serve the repo root).
80
+
81
+ ### Naming rules
82
+
83
+ - **Block:** one class per recipe, `ch-` + a short name: `button` → `ch-btn`, `selectTrigger` → `ch-select`, `switchRoot` → `ch-switch`, `tabsList` → `ch-tabs`, `tabsTrigger` → `ch-tab`, `tabsPanel` → `ch-tab-panel`; every other recipe is kebab-cased (`cardHeader` → `ch-card-header`, `tableRow` → `ch-table-row`).
84
+ - **Modifier:** one class per variant option, `<block>-<option>` (`ch-btn-secondary`, `ch-btn-sm`, `ch-alert-warning`). Boolean axes are `<block>-<axis>` for `true` (`ch-badge-clickable`, `ch-input-invalid`, `ch-tab-active`). Two options are renamed to read well: card `borderColor` → `ch-card-border-primary`/`ch-card-border-muted`, skeleton `animation: none` → `ch-skeleton-static`.
85
+ - **Defaults:** the block class alone renders the recipe's default variants (`ch-btn` is the default, medium button). Options named `default` and the default option of a boolean axis have no class: a boolean axis that defaults to `false` gets `ch-<block>-<axis>` for `true` (`ch-input-invalid`), one that defaults to `true` gets `ch-<block>-no-<axis>` for `false` (`ch-number-input-field-no-stepper`). A default option with another name keeps its class too (`ch-avatar-md`), which is the same as leaving it out.
86
+ - **Composition:** combine one modifier per axis: `class="ch-btn ch-btn-outline ch-btn-sm"`. A default applies only while no other option of its axis is set (it is scoped with `:where(:not(…))`, so it adds no specificity). Modifiers come after the block, axes in recipe order, then compound variants (`.ch-badge.ch-badge-secondary.ch-badge-clickable` adds the hover colour), so conflicts resolve as tailwind-merge resolves them in the components.
87
+ - **State:** recipes keep their state variants: `:hover` (only where hover is supported), `:focus-visible`, `:disabled`, `aria-disabled="true"`, `data-state="checked"`/`"open"`, `data-highlighted`, `data-disabled`. Set those attributes yourself on plain HTML (for example `role="switch" data-state="checked"` on a `ch-switch` button with a `ch-switch-thumb` child). `ch-label` dims after a disabled sibling marked with the `peer` class, as in Tailwind.
88
+ - **Not included:** the enter/exit animations of the popover recipes (`animate-in`, `fade-*`, `zoom-*`, `slide-in-from-*`) come from tailwindcss-animate, which the preset does not ship, so `ch-select-content` opens without animating.
89
+
90
+ ### Class list
91
+
92
+ Generated from the recipes; `node scripts/build-components-css.mjs --readme` rewrites it, and a test fails when it falls behind.
93
+
94
+ <!-- components-css:start -->
95
+
96
+ | Class | Applies |
97
+ | ----------------------------------- | ------------------------------------------------ |
98
+ | `ch-btn` | `button` recipe (base + defaults) |
99
+ | `ch-btn-secondary` | `variant: secondary` |
100
+ | `ch-btn-destructive` | `variant: destructive` |
101
+ | `ch-btn-outline` | `variant: outline` |
102
+ | `ch-btn-ghost` | `variant: ghost` |
103
+ | `ch-btn-link` | `variant: link` |
104
+ | `ch-btn-sm` | `size: sm` |
105
+ | `ch-btn-md` | `size: md` |
106
+ | `ch-btn-lg` | `size: lg` |
107
+ | `ch-btn-icon` | `size: icon` |
108
+ | `ch-badge` | `badge` recipe (base + defaults) |
109
+ | `ch-badge-secondary` | `variant: secondary` |
110
+ | `ch-badge-destructive` | `variant: destructive` |
111
+ | `ch-badge-outline` | `variant: outline` |
112
+ | `ch-badge-success` | `variant: success` |
113
+ | `ch-badge-warning` | `variant: warning` |
114
+ | `ch-badge-info` | `variant: info` |
115
+ | `ch-badge-sm` | `size: sm` |
116
+ | `ch-badge-dot` | `size: dot` |
117
+ | `ch-badge-clickable` | `clickable: true` |
118
+ | `ch-card` | `card` recipe (base + defaults) |
119
+ | `ch-card-border-primary` | `borderColor: primary` |
120
+ | `ch-card-border-muted` | `borderColor: muted` |
121
+ | `ch-card-featured` | `variant: featured` |
122
+ | `ch-card-highlight` | `variant: highlight` |
123
+ | `ch-card-warning` | `variant: warning` |
124
+ | `ch-card-interactive` | `interactive: true` |
125
+ | `ch-card-header` | `cardHeader` recipe (base + defaults) |
126
+ | `ch-card-header-compact` | `variant: compact` |
127
+ | `ch-card-header-bordered` | `variant: bordered` |
128
+ | `ch-card-header-shaded` | `variant: shaded` |
129
+ | `ch-card-title` | `cardTitle` recipe (base) |
130
+ | `ch-card-description` | `cardDescription` recipe (base) |
131
+ | `ch-card-content` | `cardContent` recipe (base) |
132
+ | `ch-card-footer` | `cardFooter` recipe (base) |
133
+ | `ch-alert` | `alert` recipe (base + defaults) |
134
+ | `ch-alert-destructive` | `variant: destructive` |
135
+ | `ch-alert-error` | `variant: error` |
136
+ | `ch-alert-success` | `variant: success` |
137
+ | `ch-alert-warning` | `variant: warning` |
138
+ | `ch-alert-info` | `variant: info` |
139
+ | `ch-alert-title` | `alertTitle` recipe (base) |
140
+ | `ch-alert-description` | `alertDescription` recipe (base) |
141
+ | `ch-input` | `input` recipe (base + defaults) |
142
+ | `ch-input-invalid` | `invalid: true` |
143
+ | `ch-textarea` | `textarea` recipe (base + defaults) |
144
+ | `ch-textarea-invalid` | `invalid: true` |
145
+ | `ch-label` | `label` recipe (base + defaults) |
146
+ | `ch-label-disabled` | `disabled: true` |
147
+ | `ch-select` | `selectTrigger` recipe (base + defaults) |
148
+ | `ch-select-invalid` | `invalid: true` |
149
+ | `ch-select-content` | `selectContent` recipe (base) |
150
+ | `ch-select-item` | `selectItem` recipe (base) |
151
+ | `ch-checkbox` | `checkbox` recipe (base + defaults) |
152
+ | `ch-checkbox-invalid` | `invalid: true` |
153
+ | `ch-switch` | `switchRoot` recipe (base) |
154
+ | `ch-switch-thumb` | `switchThumb` recipe (base) |
155
+ | `ch-tabs` | `tabsList` recipe (base) |
156
+ | `ch-tab` | `tabsTrigger` recipe (base + defaults) |
157
+ | `ch-tab-active` | `active: true` |
158
+ | `ch-tab-disabled` | `disabled: true` |
159
+ | `ch-tab-panel` | `tabsPanel` recipe (base) |
160
+ | `ch-avatar` | `avatar` recipe (base + defaults) |
161
+ | `ch-avatar-xs` | `size: xs` |
162
+ | `ch-avatar-sm` | `size: sm` |
163
+ | `ch-avatar-md` | `size: md` (default) |
164
+ | `ch-avatar-lg` | `size: lg` |
165
+ | `ch-avatar-xl` | `size: xl` |
166
+ | `ch-avatar-image` | `avatarImage` recipe (base) |
167
+ | `ch-avatar-fallback` | `avatarFallback` recipe (base) |
168
+ | `ch-progress` | `progress` recipe (base + defaults) |
169
+ | `ch-progress-sm` | `size: sm` |
170
+ | `ch-progress-md` | `size: md` (default) |
171
+ | `ch-progress-lg` | `size: lg` |
172
+ | `ch-progress-fill` | `progressFill` recipe (base + defaults) |
173
+ | `ch-progress-fill-success` | `variant: success` |
174
+ | `ch-progress-fill-warning` | `variant: warning` |
175
+ | `ch-progress-fill-destructive` | `variant: destructive` |
176
+ | `ch-progress-fill-indeterminate` | `indeterminate: true` |
177
+ | `ch-skeleton` | `skeleton` recipe (base + defaults) |
178
+ | `ch-skeleton-text` | `variant: text` |
179
+ | `ch-skeleton-avatar` | `variant: avatar` |
180
+ | `ch-skeleton-card` | `variant: card` |
181
+ | `ch-skeleton-button` | `variant: button` |
182
+ | `ch-skeleton-title` | `variant: title` |
183
+ | `ch-skeleton-pulse` | `animation: pulse` (default) |
184
+ | `ch-skeleton-shimmer` | `animation: shimmer` |
185
+ | `ch-skeleton-static` | `animation: none` |
186
+ | `ch-spinner` | `spinner` recipe (base + defaults) |
187
+ | `ch-spinner-sm` | `size: sm` |
188
+ | `ch-spinner-md` | `size: md` (default) |
189
+ | `ch-spinner-lg` | `size: lg` |
190
+ | `ch-spinner-xl` | `size: xl` |
191
+ | `ch-separator` | `separator` recipe (base + defaults) |
192
+ | `ch-separator-horizontal` | `orientation: horizontal` (default) |
193
+ | `ch-separator-vertical` | `orientation: vertical` |
194
+ | `ch-kbd` | `kbd` recipe (base + defaults) |
195
+ | `ch-kbd-sm` | `size: sm` (default) |
196
+ | `ch-kbd-md` | `size: md` |
197
+ | `ch-empty-state` | `emptyState` recipe (base + defaults) |
198
+ | `ch-empty-state-sm` | `size: sm` |
199
+ | `ch-empty-state-md` | `size: md` (default) |
200
+ | `ch-empty-state-icon` | `emptyStateIcon` recipe (base + defaults) |
201
+ | `ch-empty-state-icon-sm` | `size: sm` |
202
+ | `ch-empty-state-icon-md` | `size: md` (default) |
203
+ | `ch-empty-state-title` | `emptyStateTitle` recipe (base + defaults) |
204
+ | `ch-empty-state-title-sm` | `size: sm` |
205
+ | `ch-empty-state-title-md` | `size: md` (default) |
206
+ | `ch-empty-state-description` | `emptyStateDescription` recipe (base + defaults) |
207
+ | `ch-empty-state-description-sm` | `size: sm` |
208
+ | `ch-empty-state-description-md` | `size: md` (default) |
209
+ | `ch-table-container` | `tableContainer` recipe (base) |
210
+ | `ch-table` | `table` recipe (base) |
211
+ | `ch-table-header` | `tableHeader` recipe (base) |
212
+ | `ch-table-body` | `tableBody` recipe (base) |
213
+ | `ch-table-row` | `tableRow` recipe (base + defaults) |
214
+ | `ch-table-row-interactive` | `interactive: true` |
215
+ | `ch-table-row-selected` | `selected: true` |
216
+ | `ch-table-head` | `tableHead` recipe (base + defaults) |
217
+ | `ch-table-head-left` | `align: left` (default) |
218
+ | `ch-table-head-center` | `align: center` |
219
+ | `ch-table-head-right` | `align: right` |
220
+ | `ch-table-cell` | `tableCell` recipe (base + defaults) |
221
+ | `ch-table-cell-left` | `align: left` (default) |
222
+ | `ch-table-cell-center` | `align: center` |
223
+ | `ch-table-cell-right` | `align: right` |
224
+ | `ch-table-caption` | `tableCaption` recipe (base) |
225
+ | `ch-radio-group` | `radioGroup` recipe (base + defaults) |
226
+ | `ch-radio-group-vertical` | `orientation: vertical` (default) |
227
+ | `ch-radio-group-horizontal` | `orientation: horizontal` |
228
+ | `ch-radio-group-item` | `radioGroupItem` recipe (base + defaults) |
229
+ | `ch-radio-group-item-invalid` | `invalid: true` |
230
+ | `ch-radio-group-indicator` | `radioGroupIndicator` recipe (base) |
231
+ | `ch-slider-root` | `sliderRoot` recipe (base + defaults) |
232
+ | `ch-slider-root-sm` | `size: sm` |
233
+ | `ch-slider-root-md` | `size: md` (default) |
234
+ | `ch-slider-root-lg` | `size: lg` |
235
+ | `ch-slider-track` | `sliderTrack` recipe (base) |
236
+ | `ch-slider-range` | `sliderRange` recipe (base) |
237
+ | `ch-slider-thumb` | `sliderThumb` recipe (base + defaults) |
238
+ | `ch-slider-thumb-sm` | `size: sm` |
239
+ | `ch-slider-thumb-md` | `size: md` (default) |
240
+ | `ch-slider-thumb-lg` | `size: lg` |
241
+ | `ch-number-input-field` | `numberInputField` recipe (base + defaults) |
242
+ | `ch-number-input-field-no-stepper` | `stepper: false` |
243
+ | `ch-number-input-field-invalid` | `invalid: true` |
244
+ | `ch-number-input-stepper` | `numberInputStepper` recipe (base + defaults) |
245
+ | `ch-number-input-stepper-start` | `side: start` (default) |
246
+ | `ch-number-input-stepper-end` | `side: end` |
247
+ | `ch-number-input-stepper-invalid` | `invalid: true` |
248
+ | `ch-segmented-control` | `segmentedControl` recipe (base + defaults) |
249
+ | `ch-segmented-control-md` | `size: md` (default) |
250
+ | `ch-segmented-control-sm` | `size: sm` |
251
+ | `ch-segmented-control-item` | `segmentedControlItem` recipe (base + defaults) |
252
+ | `ch-segmented-control-item-md` | `size: md` (default) |
253
+ | `ch-segmented-control-item-sm` | `size: sm` |
254
+ | `ch-tooltip-content` | `tooltipContent` recipe (base) |
255
+ | `ch-tooltip-arrow` | `tooltipArrow` recipe (base) |
256
+ | `ch-popover-content` | `popoverContent` recipe (base) |
257
+ | `ch-dropdown-menu-content` | `dropdownMenuContent` recipe (base) |
258
+ | `ch-dropdown-menu-item` | `dropdownMenuItem` recipe (base + defaults) |
259
+ | `ch-dropdown-menu-item-destructive` | `destructive: true` |
260
+ | `ch-dropdown-menu-checkbox-item` | `dropdownMenuCheckboxItem` recipe (base) |
261
+ | `ch-dropdown-menu-label` | `dropdownMenuLabel` recipe (base) |
262
+ | `ch-dropdown-menu-separator` | `dropdownMenuSeparator` recipe (base) |
263
+ | `ch-collapsible-trigger` | `collapsibleTrigger` recipe (base) |
264
+ | `ch-collapsible-chevron` | `collapsibleChevron` recipe (base) |
265
+ | `ch-collapsible-content` | `collapsibleContent` recipe (base) |
266
+ | `ch-section` | `section` recipe (base) |
267
+ | `ch-section-title` | `sectionTitle` recipe (base) |
268
+ | `ch-section-description` | `sectionDescription` recipe (base) |
269
+
270
+ <!-- components-css:end -->
271
+
272
+ ## Tailwind CSS 4
273
+
274
+ `@classic-homes/theme-styles/tailwind-v4` is the Tailwind 3 preset
275
+ (`@classic-homes/theme-tailwind-preset`) for Tailwind 4: one self-contained CSS file
276
+ with no `@import`, generated at build time from the preset's own data
277
+ (`theme.js` in the preset package), so the two stay in step. It contains:
278
+
279
+ - `@custom-variant dark` for the class-based dark mode (`.dark` on an ancestor)
280
+ - an `@theme inline` block with every preset colour, font, type size (including
281
+ `text-h1`…`text-h6`), weight, radius, shadow, aspect ratio, breakpoint, easing
282
+ and animation (with its `@keyframes`), all reading the token variables
283
+ - utilities for what Tailwind 4 has no theme namespace for: `container`,
284
+ `duration-fast|base|slow|slower`, `tap-target`
285
+ - the enter/exit animations the components use (`animate-in`/`animate-out`,
286
+ `fade-*`, `zoom-*`, `slide-in-from-*`, `slide-out-to-*`)
287
+ - the heading base styles, page colours, the Tailwind 3 preflight defaults the
288
+ components assume (gray-200 borders, pointer cursor on buttons), and `skip-link`
289
+
290
+ It needs the tokens (`@classic-homes/theme-tokens/css`) loaded alongside, and
291
+ Tailwind itself imported first.
292
+
293
+ In a Tailwind 4 build:
294
+
295
+ ```css
296
+ @import 'tailwindcss';
297
+ @import '@classic-homes/theme-tokens/css';
298
+ @import '@classic-homes/theme-styles/tailwind-v4';
299
+ ```
300
+
301
+ With the browser build (`@tailwindcss/browser@4`), no build step: inline the tokens
302
+ as a plain `<style>` and the stylesheet after `@import 'tailwindcss';` in a
303
+ `<style type="text/tailwindcss">`. The browser build adds Tailwind only when that
304
+ import is there.
305
+
306
+ ```html
307
+ <style>
308
+ /* contents of @classic-homes/theme-tokens/css */
309
+ </style>
310
+ <style type="text/tailwindcss">
311
+ @import 'tailwindcss';
312
+ /* contents of @classic-homes/theme-styles/tailwind-v4 */
313
+ </style>
314
+ <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
315
+ ```
316
+
317
+ The brand fonts are not included; load Figtree and Spectral yourself (see
318
+ `./fonts`). `examples/tailwind-v4/` in the repository is a page set up this way.