@classic-homes/theme-styles 0.8.0 → 0.11.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,28 @@ 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, fold) |
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/fold` | Foldable layout rules (see below) |
37
+ | `@classic-homes/theme-styles/tailwind-v4` | The theme for Tailwind CSS 4 (see below) |
38
+ | `@classic-homes/theme-styles/components.css` | Plain CSS `ch-*` component classes (see below) |
39
+ | `@classic-homes/theme-styles/components.json` | The `ch-*` class list as data (recipe, axis, option) |
40
+
41
+ ### Foldable phones (iPhone Duo)
42
+
43
+ While a foldable is partly open, the Classic Theme iOS shell sets `<html data-fold="vertical|horizontal">` and `--fold-left/-top/-width/-height` (`@classic-homes/native`, Foldable). `fold.css` (in both entry points) then keeps content out of the fold; with no active fold, and everywhere else, it does nothing:
44
+
45
+ - the `Header` mobile menu stays in one pane;
46
+ - a full-width layout's main region (`main#main-content` without a sidebar before it, as in `PublicLayout`) is centred on a vertical fold, and its two-column grids (`grid-cols-2`, `md:grid-cols-2`, …) widen their gap to the fold, so the gap lands on it. Add `.fold-center` to centre another full-width element, `.fold-gap` to widen another grid's gap;
47
+ - `.fold-split` lays its first two children out one per pane, for an element that starts at the viewport's left (or top) edge, such as a full-screen view.
48
+
49
+ Its rules are unlayered so they win over the page's own utilities while folded.
36
50
 
37
51
  ### Touch field size
38
52
 
@@ -53,3 +67,263 @@ Use `/core` when the app already loads brand fonts:
53
67
  ```
54
68
 
55
69
  The `@layer` order must come before any other `@import` in your CSS. Keep it at the top of the file.
70
+
71
+ ## Component classes (`components.css`)
72
+
73
+ `@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>`.
74
+
75
+ Load the tokens first, then the classes, and toggle `.dark` on `<html>` for dark mode:
76
+
77
+ ```html
78
+ <link rel="stylesheet" href="node_modules/@classic-homes/theme-tokens/dist/tokens.css" />
79
+ <link rel="stylesheet" href="node_modules/@classic-homes/theme-styles/dist/components.css" />
80
+
81
+ <button class="ch-btn">Save</button>
82
+ <button class="ch-btn ch-btn-outline ch-btn-sm">Cancel</button>
83
+ <span class="ch-badge ch-badge-success">Active</span>
84
+ <div class="ch-card">
85
+ <div class="ch-card-header"><h3 class="ch-card-title">Lot 14</h3></div>
86
+ <div class="ch-card-content">…</div>
87
+ </div>
88
+ ```
89
+
90
+ 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).
91
+
92
+ ### Naming rules
93
+
94
+ - **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`).
95
+ - **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`.
96
+ - **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.
97
+ - **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.
98
+ - **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.
99
+ - **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.
100
+
101
+ ### Class list
102
+
103
+ Generated from the recipes; `node scripts/build-components-css.mjs --readme` rewrites it, and a test fails when it falls behind.
104
+
105
+ <!-- components-css:start -->
106
+
107
+ | Class | Applies |
108
+ | ----------------------------------- | ------------------------------------------------ |
109
+ | `ch-btn` | `button` recipe (base + defaults) |
110
+ | `ch-btn-secondary` | `variant: secondary` |
111
+ | `ch-btn-destructive` | `variant: destructive` |
112
+ | `ch-btn-outline` | `variant: outline` |
113
+ | `ch-btn-ghost` | `variant: ghost` |
114
+ | `ch-btn-link` | `variant: link` |
115
+ | `ch-btn-sm` | `size: sm` |
116
+ | `ch-btn-md` | `size: md` |
117
+ | `ch-btn-lg` | `size: lg` |
118
+ | `ch-btn-icon` | `size: icon` |
119
+ | `ch-badge` | `badge` recipe (base + defaults) |
120
+ | `ch-badge-secondary` | `variant: secondary` |
121
+ | `ch-badge-destructive` | `variant: destructive` |
122
+ | `ch-badge-outline` | `variant: outline` |
123
+ | `ch-badge-success` | `variant: success` |
124
+ | `ch-badge-warning` | `variant: warning` |
125
+ | `ch-badge-info` | `variant: info` |
126
+ | `ch-badge-sm` | `size: sm` |
127
+ | `ch-badge-dot` | `size: dot` |
128
+ | `ch-badge-clickable` | `clickable: true` |
129
+ | `ch-card` | `card` recipe (base + defaults) |
130
+ | `ch-card-border-primary` | `borderColor: primary` |
131
+ | `ch-card-border-muted` | `borderColor: muted` |
132
+ | `ch-card-featured` | `variant: featured` |
133
+ | `ch-card-highlight` | `variant: highlight` |
134
+ | `ch-card-warning` | `variant: warning` |
135
+ | `ch-card-interactive` | `interactive: true` |
136
+ | `ch-card-header` | `cardHeader` recipe (base + defaults) |
137
+ | `ch-card-header-compact` | `variant: compact` |
138
+ | `ch-card-header-bordered` | `variant: bordered` |
139
+ | `ch-card-header-shaded` | `variant: shaded` |
140
+ | `ch-card-title` | `cardTitle` recipe (base) |
141
+ | `ch-card-description` | `cardDescription` recipe (base) |
142
+ | `ch-card-content` | `cardContent` recipe (base) |
143
+ | `ch-card-footer` | `cardFooter` recipe (base) |
144
+ | `ch-alert` | `alert` recipe (base + defaults) |
145
+ | `ch-alert-destructive` | `variant: destructive` |
146
+ | `ch-alert-error` | `variant: error` |
147
+ | `ch-alert-success` | `variant: success` |
148
+ | `ch-alert-warning` | `variant: warning` |
149
+ | `ch-alert-info` | `variant: info` |
150
+ | `ch-alert-title` | `alertTitle` recipe (base) |
151
+ | `ch-alert-description` | `alertDescription` recipe (base) |
152
+ | `ch-input` | `input` recipe (base + defaults) |
153
+ | `ch-input-invalid` | `invalid: true` |
154
+ | `ch-textarea` | `textarea` recipe (base + defaults) |
155
+ | `ch-textarea-invalid` | `invalid: true` |
156
+ | `ch-label` | `label` recipe (base + defaults) |
157
+ | `ch-label-disabled` | `disabled: true` |
158
+ | `ch-select` | `selectTrigger` recipe (base + defaults) |
159
+ | `ch-select-invalid` | `invalid: true` |
160
+ | `ch-select-content` | `selectContent` recipe (base) |
161
+ | `ch-select-item` | `selectItem` recipe (base) |
162
+ | `ch-checkbox` | `checkbox` recipe (base + defaults) |
163
+ | `ch-checkbox-invalid` | `invalid: true` |
164
+ | `ch-switch` | `switchRoot` recipe (base) |
165
+ | `ch-switch-thumb` | `switchThumb` recipe (base) |
166
+ | `ch-tabs` | `tabsList` recipe (base) |
167
+ | `ch-tab` | `tabsTrigger` recipe (base + defaults) |
168
+ | `ch-tab-active` | `active: true` |
169
+ | `ch-tab-disabled` | `disabled: true` |
170
+ | `ch-tab-panel` | `tabsPanel` recipe (base) |
171
+ | `ch-avatar` | `avatar` recipe (base + defaults) |
172
+ | `ch-avatar-xs` | `size: xs` |
173
+ | `ch-avatar-sm` | `size: sm` |
174
+ | `ch-avatar-md` | `size: md` (default) |
175
+ | `ch-avatar-lg` | `size: lg` |
176
+ | `ch-avatar-xl` | `size: xl` |
177
+ | `ch-avatar-image` | `avatarImage` recipe (base) |
178
+ | `ch-avatar-fallback` | `avatarFallback` recipe (base) |
179
+ | `ch-progress` | `progress` recipe (base + defaults) |
180
+ | `ch-progress-sm` | `size: sm` |
181
+ | `ch-progress-md` | `size: md` (default) |
182
+ | `ch-progress-lg` | `size: lg` |
183
+ | `ch-progress-fill` | `progressFill` recipe (base + defaults) |
184
+ | `ch-progress-fill-success` | `variant: success` |
185
+ | `ch-progress-fill-warning` | `variant: warning` |
186
+ | `ch-progress-fill-destructive` | `variant: destructive` |
187
+ | `ch-progress-fill-indeterminate` | `indeterminate: true` |
188
+ | `ch-skeleton` | `skeleton` recipe (base + defaults) |
189
+ | `ch-skeleton-text` | `variant: text` |
190
+ | `ch-skeleton-avatar` | `variant: avatar` |
191
+ | `ch-skeleton-card` | `variant: card` |
192
+ | `ch-skeleton-button` | `variant: button` |
193
+ | `ch-skeleton-title` | `variant: title` |
194
+ | `ch-skeleton-pulse` | `animation: pulse` (default) |
195
+ | `ch-skeleton-shimmer` | `animation: shimmer` |
196
+ | `ch-skeleton-static` | `animation: none` |
197
+ | `ch-spinner` | `spinner` recipe (base + defaults) |
198
+ | `ch-spinner-sm` | `size: sm` |
199
+ | `ch-spinner-md` | `size: md` (default) |
200
+ | `ch-spinner-lg` | `size: lg` |
201
+ | `ch-spinner-xl` | `size: xl` |
202
+ | `ch-separator` | `separator` recipe (base + defaults) |
203
+ | `ch-separator-horizontal` | `orientation: horizontal` (default) |
204
+ | `ch-separator-vertical` | `orientation: vertical` |
205
+ | `ch-kbd` | `kbd` recipe (base + defaults) |
206
+ | `ch-kbd-sm` | `size: sm` (default) |
207
+ | `ch-kbd-md` | `size: md` |
208
+ | `ch-empty-state` | `emptyState` recipe (base + defaults) |
209
+ | `ch-empty-state-sm` | `size: sm` |
210
+ | `ch-empty-state-md` | `size: md` (default) |
211
+ | `ch-empty-state-icon` | `emptyStateIcon` recipe (base + defaults) |
212
+ | `ch-empty-state-icon-sm` | `size: sm` |
213
+ | `ch-empty-state-icon-md` | `size: md` (default) |
214
+ | `ch-empty-state-title` | `emptyStateTitle` recipe (base + defaults) |
215
+ | `ch-empty-state-title-sm` | `size: sm` |
216
+ | `ch-empty-state-title-md` | `size: md` (default) |
217
+ | `ch-empty-state-description` | `emptyStateDescription` recipe (base + defaults) |
218
+ | `ch-empty-state-description-sm` | `size: sm` |
219
+ | `ch-empty-state-description-md` | `size: md` (default) |
220
+ | `ch-table-container` | `tableContainer` recipe (base) |
221
+ | `ch-table` | `table` recipe (base) |
222
+ | `ch-table-header` | `tableHeader` recipe (base) |
223
+ | `ch-table-body` | `tableBody` recipe (base) |
224
+ | `ch-table-row` | `tableRow` recipe (base + defaults) |
225
+ | `ch-table-row-interactive` | `interactive: true` |
226
+ | `ch-table-row-selected` | `selected: true` |
227
+ | `ch-table-head` | `tableHead` recipe (base + defaults) |
228
+ | `ch-table-head-left` | `align: left` (default) |
229
+ | `ch-table-head-center` | `align: center` |
230
+ | `ch-table-head-right` | `align: right` |
231
+ | `ch-table-cell` | `tableCell` recipe (base + defaults) |
232
+ | `ch-table-cell-left` | `align: left` (default) |
233
+ | `ch-table-cell-center` | `align: center` |
234
+ | `ch-table-cell-right` | `align: right` |
235
+ | `ch-table-caption` | `tableCaption` recipe (base) |
236
+ | `ch-radio-group` | `radioGroup` recipe (base + defaults) |
237
+ | `ch-radio-group-vertical` | `orientation: vertical` (default) |
238
+ | `ch-radio-group-horizontal` | `orientation: horizontal` |
239
+ | `ch-radio-group-item` | `radioGroupItem` recipe (base + defaults) |
240
+ | `ch-radio-group-item-invalid` | `invalid: true` |
241
+ | `ch-radio-group-indicator` | `radioGroupIndicator` recipe (base) |
242
+ | `ch-slider-root` | `sliderRoot` recipe (base + defaults) |
243
+ | `ch-slider-root-sm` | `size: sm` |
244
+ | `ch-slider-root-md` | `size: md` (default) |
245
+ | `ch-slider-root-lg` | `size: lg` |
246
+ | `ch-slider-track` | `sliderTrack` recipe (base) |
247
+ | `ch-slider-range` | `sliderRange` recipe (base) |
248
+ | `ch-slider-thumb` | `sliderThumb` recipe (base + defaults) |
249
+ | `ch-slider-thumb-sm` | `size: sm` |
250
+ | `ch-slider-thumb-md` | `size: md` (default) |
251
+ | `ch-slider-thumb-lg` | `size: lg` |
252
+ | `ch-number-input-field` | `numberInputField` recipe (base + defaults) |
253
+ | `ch-number-input-field-no-stepper` | `stepper: false` |
254
+ | `ch-number-input-field-invalid` | `invalid: true` |
255
+ | `ch-number-input-stepper` | `numberInputStepper` recipe (base + defaults) |
256
+ | `ch-number-input-stepper-start` | `side: start` (default) |
257
+ | `ch-number-input-stepper-end` | `side: end` |
258
+ | `ch-number-input-stepper-invalid` | `invalid: true` |
259
+ | `ch-segmented-control` | `segmentedControl` recipe (base + defaults) |
260
+ | `ch-segmented-control-md` | `size: md` (default) |
261
+ | `ch-segmented-control-sm` | `size: sm` |
262
+ | `ch-segmented-control-item` | `segmentedControlItem` recipe (base + defaults) |
263
+ | `ch-segmented-control-item-md` | `size: md` (default) |
264
+ | `ch-segmented-control-item-sm` | `size: sm` |
265
+ | `ch-tooltip-content` | `tooltipContent` recipe (base) |
266
+ | `ch-tooltip-arrow` | `tooltipArrow` recipe (base) |
267
+ | `ch-popover-content` | `popoverContent` recipe (base) |
268
+ | `ch-dropdown-menu-content` | `dropdownMenuContent` recipe (base) |
269
+ | `ch-dropdown-menu-item` | `dropdownMenuItem` recipe (base + defaults) |
270
+ | `ch-dropdown-menu-item-destructive` | `destructive: true` |
271
+ | `ch-dropdown-menu-checkbox-item` | `dropdownMenuCheckboxItem` recipe (base) |
272
+ | `ch-dropdown-menu-label` | `dropdownMenuLabel` recipe (base) |
273
+ | `ch-dropdown-menu-separator` | `dropdownMenuSeparator` recipe (base) |
274
+ | `ch-collapsible-trigger` | `collapsibleTrigger` recipe (base) |
275
+ | `ch-collapsible-chevron` | `collapsibleChevron` recipe (base) |
276
+ | `ch-collapsible-content` | `collapsibleContent` recipe (base) |
277
+ | `ch-section` | `section` recipe (base) |
278
+ | `ch-section-title` | `sectionTitle` recipe (base) |
279
+ | `ch-section-description` | `sectionDescription` recipe (base) |
280
+
281
+ <!-- components-css:end -->
282
+
283
+ ## Tailwind CSS 4
284
+
285
+ `@classic-homes/theme-styles/tailwind-v4` is the Tailwind 3 preset
286
+ (`@classic-homes/theme-tailwind-preset`) for Tailwind 4: one self-contained CSS file
287
+ with no `@import`, generated at build time from the preset's own data
288
+ (`theme.js` in the preset package), so the two stay in step. It contains:
289
+
290
+ - `@custom-variant dark` for the class-based dark mode (`.dark` on an ancestor)
291
+ - an `@theme inline` block with every preset colour, font, type size (including
292
+ `text-h1`…`text-h6`), weight, radius, shadow, aspect ratio, breakpoint, easing
293
+ and animation (with its `@keyframes`), all reading the token variables
294
+ - utilities for what Tailwind 4 has no theme namespace for: `container`,
295
+ `duration-fast|base|slow|slower`, `tap-target`
296
+ - the enter/exit animations the components use (`animate-in`/`animate-out`,
297
+ `fade-*`, `zoom-*`, `slide-in-from-*`, `slide-out-to-*`)
298
+ - the heading base styles, page colours, the Tailwind 3 preflight defaults the
299
+ components assume (gray-200 borders, pointer cursor on buttons), and `skip-link`
300
+
301
+ It needs the tokens (`@classic-homes/theme-tokens/css`) loaded alongside, and
302
+ Tailwind itself imported first.
303
+
304
+ In a Tailwind 4 build:
305
+
306
+ ```css
307
+ @import 'tailwindcss';
308
+ @import '@classic-homes/theme-tokens/css';
309
+ @import '@classic-homes/theme-styles/tailwind-v4';
310
+ ```
311
+
312
+ With the browser build (`@tailwindcss/browser@4`), no build step: inline the tokens
313
+ as a plain `<style>` and the stylesheet after `@import 'tailwindcss';` in a
314
+ `<style type="text/tailwindcss">`. The browser build adds Tailwind only when that
315
+ import is there.
316
+
317
+ ```html
318
+ <style>
319
+ /* contents of @classic-homes/theme-tokens/css */
320
+ </style>
321
+ <style type="text/tailwindcss">
322
+ @import 'tailwindcss';
323
+ /* contents of @classic-homes/theme-styles/tailwind-v4 */
324
+ </style>
325
+ <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
326
+ ```
327
+
328
+ The brand fonts are not included; load Figtree and Spectral yourself (see
329
+ `./fonts`). `examples/tailwind-v4/` in the repository is a page set up this way.