@f-ewald/components 1.40.2 → 1.41.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 (106) hide show
  1. package/README.md +11 -3
  2. package/custom-elements.json +788 -97
  3. package/dist/app-shell.js +1 -1
  4. package/dist/app-shell.js.map +1 -1
  5. package/dist/blink-cursor.d.ts +27 -0
  6. package/dist/blink-cursor.d.ts.map +1 -0
  7. package/dist/blink-cursor.js +78 -0
  8. package/dist/blink-cursor.js.map +1 -0
  9. package/dist/button-group.d.ts.map +1 -1
  10. package/dist/button-group.js +3 -0
  11. package/dist/button-group.js.map +1 -1
  12. package/dist/calendar-day.d.ts.map +1 -1
  13. package/dist/calendar-day.js +5 -0
  14. package/dist/calendar-day.js.map +1 -1
  15. package/dist/calendar-week.d.ts.map +1 -1
  16. package/dist/calendar-week.js +5 -0
  17. package/dist/calendar-week.js.map +1 -1
  18. package/dist/code-diff.d.ts +41 -0
  19. package/dist/code-diff.d.ts.map +1 -0
  20. package/dist/code-diff.js +161 -0
  21. package/dist/code-diff.js.map +1 -0
  22. package/dist/comment-label.d.ts +26 -0
  23. package/dist/comment-label.d.ts.map +1 -0
  24. package/dist/comment-label.js +81 -0
  25. package/dist/comment-label.js.map +1 -0
  26. package/dist/confirm-dialog.d.ts +12 -6
  27. package/dist/confirm-dialog.d.ts.map +1 -1
  28. package/dist/confirm-dialog.js +50 -88
  29. package/dist/confirm-dialog.js.map +1 -1
  30. package/dist/frame-box.d.ts.map +1 -1
  31. package/dist/frame-box.js +4 -0
  32. package/dist/frame-box.js.map +1 -1
  33. package/dist/index.d.ts +8 -1
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +8 -1
  36. package/dist/index.js.map +1 -1
  37. package/dist/mcp-server.js +1 -1
  38. package/dist/mcp-server.js.map +1 -1
  39. package/dist/modal-dialog.d.ts +16 -13
  40. package/dist/modal-dialog.d.ts.map +1 -1
  41. package/dist/modal-dialog.js +69 -104
  42. package/dist/modal-dialog.js.map +1 -1
  43. package/dist/photo-gallery.js +1 -1
  44. package/dist/photo-gallery.js.map +1 -1
  45. package/dist/price-history-chart.js +1 -1
  46. package/dist/price-history-chart.js.map +1 -1
  47. package/dist/progress-bar.d.ts.map +1 -1
  48. package/dist/progress-bar.js +23 -17
  49. package/dist/progress-bar.js.map +1 -1
  50. package/dist/radio-pills.d.ts.map +1 -1
  51. package/dist/radio-pills.js +3 -0
  52. package/dist/radio-pills.js.map +1 -1
  53. package/dist/slide-panel.d.ts +3 -3
  54. package/dist/slide-panel.d.ts.map +1 -1
  55. package/dist/slide-panel.js +38 -22
  56. package/dist/slide-panel.js.map +1 -1
  57. package/dist/stat-strip.d.ts +30 -0
  58. package/dist/stat-strip.d.ts.map +1 -0
  59. package/dist/stat-strip.js +111 -0
  60. package/dist/stat-strip.js.map +1 -0
  61. package/dist/step-ladder.d.ts +46 -0
  62. package/dist/step-ladder.d.ts.map +1 -0
  63. package/dist/step-ladder.js +175 -0
  64. package/dist/step-ladder.js.map +1 -0
  65. package/dist/terminal-block.d.ts +45 -0
  66. package/dist/terminal-block.d.ts.map +1 -0
  67. package/dist/terminal-block.js +113 -0
  68. package/dist/terminal-block.js.map +1 -0
  69. package/dist/tile-grid.d.ts.map +1 -1
  70. package/dist/tile-grid.js +3 -0
  71. package/dist/tile-grid.js.map +1 -1
  72. package/dist/toast-notification.d.ts +7 -0
  73. package/dist/toast-notification.d.ts.map +1 -1
  74. package/dist/toast-notification.js +34 -0
  75. package/dist/toast-notification.js.map +1 -1
  76. package/dist/tokens.css +60 -1
  77. package/dist/tokens.d.ts +58 -0
  78. package/dist/tokens.d.ts.map +1 -1
  79. package/dist/tokens.js +135 -0
  80. package/dist/tokens.js.map +1 -1
  81. package/dist/ui-button.js +2 -2
  82. package/dist/ui-button.js.map +1 -1
  83. package/dist/window-chrome.d.ts +34 -0
  84. package/dist/window-chrome.d.ts.map +1 -0
  85. package/dist/window-chrome.js +141 -0
  86. package/dist/window-chrome.js.map +1 -0
  87. package/docs/app-shell.md +1 -1
  88. package/docs/blink-cursor.md +45 -0
  89. package/docs/code-diff.md +64 -0
  90. package/docs/comment-label.md +49 -0
  91. package/docs/confirm-dialog.md +4 -3
  92. package/docs/design-language.md +80 -28
  93. package/docs/layouts/marketing-landing.md +102 -0
  94. package/docs/modal-dialog.md +9 -9
  95. package/docs/photo-gallery.md +1 -1
  96. package/docs/price-history-chart.md +1 -0
  97. package/docs/radio-pills.md +1 -0
  98. package/docs/slide-panel.md +2 -2
  99. package/docs/stat-strip.md +57 -0
  100. package/docs/step-ladder.md +63 -0
  101. package/docs/terminal-block.md +69 -0
  102. package/docs/tile-grid.md +1 -0
  103. package/docs/ui-button.md +2 -0
  104. package/docs/window-chrome.md +64 -0
  105. package/llms.txt +227 -20
  106. package/package.json +1 -1
@@ -0,0 +1,64 @@
1
+ # `<code-diff>`
2
+
3
+ A compact, read-only code diff viewer: a bordered panel with a header bar
4
+ for `filename` and `stat`, followed by a numbered `<pre>` listing of
5
+ `lines`. Each CodeDiffLine renders as `"add"`, `"del"`, or
6
+ `"context"` with fixed `"+ "` / `"- "` / `" "` prefixes so the diff
7
+ remains understandable even when color is unavailable.
8
+
9
+ Added and removed rows reuse `--ui-success` / `--ui-danger` for their text
10
+ and low-alpha background washes, while the shell itself reuses
11
+ `--ui-font-mono`, `--ui-border`, and `--ui-surface`. The caller owns the
12
+ data shape entirely: `filename` and `stat` are passed through verbatim, and
13
+ `lines` is a flat ordered array of `{ type, text }` objects.
14
+
15
+ ## Install
16
+
17
+ ```js
18
+ import "@f-ewald/components/code-diff.js";
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ ```html
24
+ <code-diff filename="cache.py" stat="&minus;48 +1"></code-diff>
25
+ <script type="module">
26
+ document.querySelector("code-diff").lines = [
27
+ { type: "del", text: "class CacheManager:" },
28
+ { type: "add", text: "@lru_cache(maxsize=1000)" },
29
+ ];
30
+ </script>
31
+ ```
32
+
33
+ ## Attributes / properties
34
+
35
+ | Property | Attribute | Type | Default | Description |
36
+ | --- | --- | --- | --- | --- |
37
+ | `filename` | `filename` | `string` | `""` | The filename shown in the header bar's left side. |
38
+ | `stat` | `stat` | `string` | `""` | The caller-supplied stat summary shown in the header bar's right side. |
39
+ | `lines` | `lines` | `CodeDiffLine[]` | `[]` | Ordered diff lines, each rendered with its type-driven prefix and styling. |
40
+
41
+ ## Events
42
+
43
+ _None._
44
+
45
+ ## Slots
46
+
47
+ _None._
48
+
49
+ ## CSS custom properties
50
+
51
+ | Custom property |
52
+ | --- |
53
+ | `--ui-border` |
54
+ | `--ui-border-width` |
55
+ | `--ui-danger` |
56
+ | `--ui-font-mono` |
57
+ | `--ui-font-size-sm` |
58
+ | `--ui-line-height-normal` |
59
+ | `--ui-numeric` |
60
+ | `--ui-radius` |
61
+ | `--ui-success` |
62
+ | `--ui-surface` |
63
+ | `--ui-text` |
64
+ | `--ui-text-muted` |
@@ -0,0 +1,49 @@
1
+ # `<comment-label>`
2
+
3
+ A code-comment-style eyebrow line for section chrome in terminal- or
4
+ editor-themed pages. It renders a colored comment marker (`##` by default)
5
+ before muted slotted text, so `<comment-label>the_whole_idea</comment-label>`
6
+ reads like a short section kicker. Set `prefix="//"` and `italic` for a
7
+ closing or footer quote line that keeps the marker upright while the message
8
+ itself turns italic.
9
+
10
+ ## Install
11
+
12
+ ```js
13
+ import "@f-ewald/components/comment-label.js";
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```html
19
+ <comment-label>the_whole_idea</comment-label>
20
+ <comment-label prefix="//" italic>the best code is the code never written.</comment-label>
21
+ ```
22
+
23
+ ## Attributes / properties
24
+
25
+ | Property | Attribute | Type | Default | Description |
26
+ | --- | --- | --- | --- | --- |
27
+ | `prefix` | `prefix` | `string` | `"##"` | Comment marker rendered before the slotted label text. |
28
+ | `italic` | `italic` | `boolean` | `false` | Renders the slotted label text in italics while leaving the prefix upright. |
29
+
30
+ ## Events
31
+
32
+ _None._
33
+
34
+ ## Slots
35
+
36
+ _None._
37
+
38
+ ## CSS custom properties
39
+
40
+ | Custom property |
41
+ | --- |
42
+ | `--ui-font-mono` |
43
+ | `--ui-font-size-sm` |
44
+ | `--ui-font-weight-semibold` |
45
+ | `--ui-label-transform` |
46
+ | `--ui-line-height-tight` |
47
+ | `--ui-primary` |
48
+ | `--ui-text-muted` |
49
+ | `--ui-tracking-wide` |
@@ -1,8 +1,9 @@
1
1
  # `<confirm-dialog>`
2
2
 
3
- Reusable confirmation dialog: overlay + centered card with a slotted body,
4
- an optional error line, and Cancel/Confirm actions. Instant `display:none`
5
- → `display:flex` toggle (no transitions). Fires `confirm`/`cancel`
3
+ Reusable confirmation dialog: a native modal `<dialog>` (top layer, inert
4
+ page behind it, built-in focus containment) with a slotted body, an
5
+ optional error line, and Cancel/Confirm actions. Instant open/close (no
6
+ transitions). Fires `confirm`/`cancel`
6
7
  (bubbling, composed) instead of owning any deletion logic itself —
7
8
  callers stay in charge of the request. Set `size="sm"` for compact
8
9
  actions one step below the default, matching `ui-button`'s `sm` size.
@@ -24,29 +24,41 @@ defines the details used when creating or reviewing components.
24
24
  - Themes are single-valued and mutually exclusive, selected by `data-theme` on
25
25
  `<html>`: `dark` and `light` force one of the two flat palettes, `gradient`
26
26
  glosses buttons and toasts, `metro` squares corners and flattens shadows over
27
- a blue accent, and `blueprint` restyles the palette as a monospace technical
27
+ a blue accent, `blueprint` restyles the palette as a monospace technical
28
28
  spec sheet — ink on paper, one pure-blue accent, square corners, and
29
- structure carried by 1.5px hairline rules instead of shadows. `dark` aside,
30
- each is layered on the light palette and
31
- must be excluded from `tokens.css`'s `prefers-color-scheme: dark` media query
32
- — that selector outranks a bare `[data-theme]`, so a missing exclusion yields
33
- a half-dark hybrid rather than an outright failure. Adding a theme therefore
34
- means adding it to `lightThemes` in `generate-tokens-css.mjs`, which derives
35
- both the block and the exclusion from that one list.
29
+ structure carried by 1.5px hairline rules instead of shadows — and
30
+ `developer-dark`/`developer-light` restyle it as a monospace editor/terminal
31
+ theme — a near-black warm palette (or its light counterpart) with one green
32
+ accent, small (not squared) corners, and chrome micro-labels left in
33
+ sentence case rather than shouted.
34
+ `dark`/`developer-dark` aside, each is layered on the light palette and must
35
+ be excluded from `tokens.css`'s `prefers-color-scheme: dark` media query —
36
+ that selector outranks a bare `[data-theme]`, so a missing exclusion yields
37
+ a half-dark hybrid rather than an outright failure. Adding a theme layered on
38
+ the light palette therefore means adding it to `lightThemes` in
39
+ `generate-tokens-css.mjs`, which derives both the block and the exclusion
40
+ from that one list. Adding a second *true dark* theme (like
41
+ `developer-dark`) instead means adding it to `darkThemes`, which layers the
42
+ theme's overrides over `darkTokenValues` and needs no such exclusion, since
43
+ its own `[data-theme]` block already outranks the bare `:root` the media
44
+ query types into regardless of the reader's OS preference.
36
45
  - Colors are the normal subject of a theme. Three other axes are themeable, each
37
46
  introduced by exactly one theme and each defaulting to the behavior that
38
47
  predates it:
39
- - **Shape** — `metro` and `blueprint` set every `--ui-radius*` to `0`.
48
+ - **Shape** — `metro` and `blueprint` set every `--ui-radius*` to `0`;
49
+ `developer-dark`/`developer-light` set `--ui-radius`/`--ui-radius-sm` to a
50
+ small but non-zero step (`0.25rem`/`0.125rem`) rather than squaring them.
40
51
  - **Border weight** — `--ui-border-width` (`1px`), which `blueprint` takes to
41
52
  `1.5px`. Every genuine surface or control border reads it; see "Borders"
42
53
  below for what is deliberately excluded.
43
54
  - **Label case** — `--ui-label-transform` (`none`), which `blueprint` takes to
44
- `uppercase`, and `--ui-numeric` (`normal`), which it takes to
45
- `tabular-nums`.
55
+ `uppercase`, and `--ui-numeric` (`normal`), which `blueprint` and
56
+ `developer-dark`/`developer-light` take to `tabular-nums`.
46
57
  - **Type family** — `--ui-font` only. `blueprint` retargets it to a monospace
47
- stack led by "Space Mono", which falls through to the system mono stack when
48
- no webfont is loaded, so the theme still renders correctly with zero
49
- external CSS.
58
+ stack led by "Space Mono", and `developer-dark`/`developer-light` retarget
59
+ it to one led by "JetBrains Mono" — both fall through to the system mono
60
+ stack when no webfont is loaded, so the theme still renders correctly with
61
+ zero external CSS.
50
62
  Type *metrics* — size, weight, line height, tracking — are never themed in any
51
63
  theme: they encode hierarchy rather than style.
52
64
  - Semantic states use `primary`, `info`, `success`, `warning`, and `danger`.
@@ -66,12 +78,30 @@ defines the details used when creating or reviewing components.
66
78
  the active tab's `--ui-primary` line drawn on top of it) rather than
67
79
  introducing a new token — the same precedent as `ui-button`'s `secondary`
68
80
  variant, which is realized via `--ui-border`/`--ui-text-muted`, not a hue.
69
- - **A bordered control paints an opaque base.** `--ui-button-secondary-*`
70
- defaults to `none`, so any control that uses it directly would let the page
71
- behind it show through — invisible on a plain `--ui-surface` page, obviously
72
- broken on a tinted, textured, or image-backed one, and inconsistent with
73
- text fields, which are already opaque. Every such control therefore layers
74
- the token over an opaque base rather than declaring it alone:
81
+ - **A bordered surface paints an opaque base.** A component that draws a border
82
+ but leaves its background unset is invisible on a plain `--ui-surface` page
83
+ and obviously broken on a tinted, textured, or image-backed one — and it is
84
+ inconsistent with text fields, which are already opaque. Anything that reads
85
+ as a panel, card, control, or canvas therefore declares a background, even
86
+ when that background is just the page's own paper:
87
+
88
+ ```css
89
+ background: var(--ui-surface, #ffffff);
90
+ ```
91
+
92
+ This reaches surfaces that never painted at all — `radio-pills`' unchecked
93
+ pill, `tile-grid`'s resting tile, `frame-box`'s frame (whose legend already
94
+ painted `--ui-surface` to notch the border, so a see-through body left the
95
+ notch reading as a stray white patch), `button-group`'s strip behind its
96
+ segments, and `calendar-day`/`calendar-week`'s hour grid, where only the
97
+ weekend and today columns had a fill. A translucent state tint such as
98
+ `calendar-day`'s `.today` then composites over that paper rather than over
99
+ the page, which is what it was always meant to do.
100
+
101
+ The `--ui-button-secondary-*` family is the same rule with an extra step: it
102
+ defaults to `none`, so a control using it directly would still be
103
+ see-through. Those layer the token over the base rather than declaring it
104
+ alone:
75
105
 
76
106
  ```css
77
107
  background:
@@ -81,12 +111,20 @@ defines the details used when creating or reviewing components.
81
111
 
82
112
  A themed gradient still paints over that base, so a theme overriding the
83
113
  token behaves exactly as before; only the "token contributes nothing" case
84
- changes. This applies to `ui-button`'s `secondary` variant,
114
+ changes. The layered form applies to `ui-button`'s `secondary` variant,
85
115
  `confirm-dialog`'s Cancel, `button-group`'s unchecked segments,
86
116
  `pagination-nav`'s buttons, `radio-cards`' unchecked cards, and the floating
87
- `scroll-to-top`/`scroll-to-bottom`/`fullscreen-button` controls. It does not
88
- apply to states that already resolve to an opaque value
89
- (`--ui-button-secondary-surface-muted`, `--ui-surface-muted`).
117
+ `scroll-to-top`/`scroll-to-bottom`/`fullscreen-button` controls. Neither form
118
+ applies to states that already resolve to an opaque value
119
+ (`--ui-button-secondary-surface-muted`, `--ui-surface-muted`), nor to
120
+ elements that draw a *line* or a *mark* rather than a surface —
121
+ `content-divider`'s rule, `calendar-month`'s entry underline,
122
+ `app-sidebar`'s footer, which sits on the sidebar's own paper, and
123
+ `step-ladder`'s rung border, which separates rows the same way
124
+ `content-divider`'s rule does. Those four
125
+ are the allowlist in `design-tests/opaque-surfaces.spec.ts`, which walks
126
+ every shadow root under the blueprint theme and fails on any bordered,
127
+ see-through surface that is not one of them.
90
128
  - `--ui-ai-1`…`--ui-ai-4` are the one multi-hue family: the stops of
91
129
  `ui-button[ai]`'s animated ring, where the rainbow itself is the meaning
92
130
  ("this action is AI-powered") rather than a semantic state. They are only
@@ -387,10 +425,15 @@ backbone, and `app-sidebar`, `action-bar`, `page-header`, `pagination-nav`, and
387
425
 
388
426
  ### Templates
389
427
 
390
- The recipes under `docs/layouts/` compose these into four pages — list-only,
391
- list + detail, detail-only, and form — and the MCP `list_layouts` /
392
- `get_layout` tools serve them. Add a page by adding a `docs/layouts/<name>.md`
393
- recipe and, ideally, a matching full-page demo under `demo/layouts/`.
428
+ The recipes under `docs/layouts/` compose these into five pages — list-only,
429
+ list + detail, detail-only, form, and marketing-landing — and the MCP
430
+ `list_layouts` / `get_layout` tools serve them. Add a page by adding a
431
+ `docs/layouts/<name>.md` recipe and, ideally, a matching full-page demo under
432
+ `demo/layouts/`. Not every recipe is an `app-shell` dashboard page:
433
+ `marketing-landing` is shell-less — a `window-chrome`-topped page built
434
+ directly from section components (`code-diff`, `step-ladder`, `stat-strip`,
435
+ `terminal-block`, etc.), for a marketing/landing-page context rather than an
436
+ authenticated app view.
394
437
 
395
438
  ## Playground and documentation
396
439
 
@@ -402,6 +445,15 @@ recipe and, ideally, a matching full-page demo under `demo/layouts/`.
402
445
  linked parent section.
403
446
  - Public API changes update JSDoc, generated docs, `llms.txt`, README when
404
447
  relevant, and the changelog.
448
+ - Every example container in `index.html` carries the `demo-example` class.
449
+ The playground chrome is Tailwind slate, which is transparent by default, so
450
+ without it a theme that repaints the page (blueprint draws a dot grid and a
451
+ grain wash) shows straight through the example — the same rule the components
452
+ follow, applied to the demo's own boxes. `demo/demo.css` maps that class, the
453
+ demo's bordered native controls, and the slate values that have a token
454
+ counterpart onto `--ui-surface`/`--ui-surface-muted`/`--ui-border`/
455
+ `--ui-text`/`--ui-text-muted`; slate steps with no counterpart stay literal
456
+ rather than being approximated.
405
457
 
406
458
  ## Measurement contracts
407
459
 
@@ -0,0 +1,102 @@
1
+ # Marketing landing page
2
+
3
+ A monospace, editor/terminal-chrome marketing/landing page — no `app-shell`,
4
+ no sidebar: a sticky `window-chrome` bar, a hero, and a stack of section
5
+ components, set in the `developer-dark` theme by default with a working
6
+ toggle to `developer-light`.
7
+
8
+ **When to use:** a public-facing marketing/landing page for a developer
9
+ tool or product, in the terminal-styled `developer-dark`/`developer-light`
10
+ themes — not an authenticated dashboard view (use one of the other recipes
11
+ for that; this is the one shell-less exception in this set).
12
+
13
+ ## Page structure
14
+
15
+ - `window-chrome` — sticky top bar; its `actions` slot holds a real
16
+ `icon-button` (sun/moon) that toggles `data-theme` between
17
+ `developer-dark`/`developer-light` — and actually reapplies the token
18
+ values, unlike a real consumer that only needs to flip the attribute once
19
+ `dist/tokens.css` is loaded (see the Notes below).
20
+ - Hero — a heading with a trailing `blink-cursor`, tagline, `ui-button` CTAs
21
+ (bracket styling is literal slot text, e.g. `[ view on github ]` — not a
22
+ component feature), and a `ui-admonition` callout.
23
+ - `comment-label` above each section heading (the `## section_name` eyebrow).
24
+ - `code-diff` — the "why" section's before/after snippet.
25
+ - `step-ladder` — the prioritized fallback list.
26
+ - `stat-strip` — the benchmark numbers row.
27
+ - `terminal-block` — install instructions, plus a `tile-grid` for other
28
+ agents' install commands.
29
+ - `data-table` — the commands reference table.
30
+ - `frame-box` cards in a plain grid (each with a `status-pill` "default"
31
+ badge on one) — the intensity/mode cards.
32
+ - Footer — `comment-label` (`prefix="//"` `italic`) quote line, plus a
33
+ second `blink-cursor` after a prompt string.
34
+
35
+ ## Markup
36
+
37
+ ```html
38
+ <html data-theme="developer-dark">
39
+ <body>
40
+ <window-chrome label="~/product — README.md">
41
+ <icon-button id="theme-toggle" slot="actions" label="Toggle light/dark"></icon-button>
42
+ </window-chrome>
43
+
44
+ <main class="wrap">
45
+ <header class="hero">
46
+ <h1>product<blink-cursor></blink-cursor></h1>
47
+ <p class="tag">One line. It works.</p>
48
+ <div class="cta">
49
+ <ui-button variant="primary">[ view on github ]</ui-button>
50
+ <ui-button variant="secondary">[ install ]</ui-button>
51
+ </div>
52
+ <ui-admonition variant="warning">
53
+ Something's coming. Be the first to know.
54
+ <ui-button slot="actions" size="sm" variant="secondary">Notify me</ui-button>
55
+ </ui-admonition>
56
+ </header>
57
+
58
+ <section>
59
+ <comment-label>the_whole_idea</comment-label>
60
+ <h2>Your agent reaches for fifty lines. The job needs one.</h2>
61
+ <code-diff id="landing-diff" filename="cache.py" stat="−48 +1"></code-diff>
62
+ </section>
63
+
64
+ <section>
65
+ <comment-label>the_ladder</comment-label>
66
+ <h2>Stop at the first rung that holds.</h2>
67
+ <step-ladder id="landing-ladder"></step-ladder>
68
+ </section>
69
+
70
+ <footer>
71
+ <comment-label prefix="//" italic>the best code is the code never written.</comment-label>
72
+ <p class="prompt">~/product ❯ <blink-cursor></blink-cursor></p>
73
+ </footer>
74
+ </main>
75
+ </body>
76
+ </html>
77
+ ```
78
+
79
+ ## Notes
80
+
81
+ - This recipe has no `app-shell` slots to fill — it's a plain document, styled
82
+ by the page's own `<style>` block (`max-width`/section rhythm/hero type),
83
+ the same way a component's own playground section owns its layout chrome.
84
+ - `data-diff`/`step-ladder`/`stat-strip`/`terminal-block`/`data-table`/
85
+ `tile-grid` are all headless: seed their `items`/`lines`/`columns`/`rows`
86
+ properties from a script, the same pattern `data-table` already uses in
87
+ every other recipe.
88
+ - The theme toggle icon (`iconSun`/`iconMoon` from `icons.js`) is swapped by
89
+ hand on click — `icon-button`'s `icon` property takes a pre-rendered
90
+ template, it does not know about themes.
91
+ - A real consumer that has loaded `dist/tokens.css` only needs to flip
92
+ `data-theme` between `"developer-dark"`/`"developer-light"` on `<html>` —
93
+ the demo additionally re-applies the token values as inline custom
94
+ properties because, like every demo/playground page, it imports component
95
+ *sources* and never loads the built `dist/tokens.css` (see `CLAUDE.md`).
96
+ - Bracket CTAs (`[ view on github ]`) are literal text passed to `ui-button`'s
97
+ default slot, not a component variant — `ui-button` itself is unchanged by
98
+ this theme.
99
+
100
+ **Live demo:** `demo/layouts/marketing-landing.html`
101
+
102
+ **Components:** window-chrome, blink-cursor, comment-label, ui-button, ui-admonition, code-diff, step-ladder, stat-strip, terminal-block, tile-grid, data-table, frame-box, status-pill, icon-button
@@ -1,14 +1,14 @@
1
1
  # `<modal-dialog>`
2
2
 
3
- Generic centered modal-dialog shell: overlay + card with header chrome, a
4
- close button, and an arbitrary slotted body — the modal sibling to
5
- `slide-panel` (fixed-edge) and `popover-panel` (anchored). Unlike
6
- `confirm-dialog`, it has no baked-in actions; the consumer supplies the
7
- body content (a form, a read-only viewer, a table) and any footer buttons
8
- itself. Instant `display:none` → `display:flex` toggle, no transition.
9
- Traps focus, closes on Escape, and restores focus to the trigger on
10
- close, stacking correctly against other open `confirm-dialog`/
11
- `slide-panel`/`popover-panel`/`modal-dialog` layers.
3
+ Generic centered modal-dialog shell: a native modal `<dialog>` card with
4
+ header chrome, a close button, and an arbitrary slotted body — the modal
5
+ sibling to `slide-panel` (fixed-edge) and `popover-panel` (anchored).
6
+ Unlike `confirm-dialog`, it has no baked-in actions; the consumer supplies
7
+ the body content (a form, a read-only viewer, a table) and any footer
8
+ buttons itself. Instant open/close, no transition. Because it uses
9
+ `showModal()`, it renders in the browser's top layer, makes the rest of the
10
+ page inert, contains focus, and restores focus to the trigger on close;
11
+ Escape is routed to the topmost layer only (see `utils/layer-stack`).
12
12
 
13
13
  ## Install
14
14
 
@@ -74,8 +74,8 @@ import "@f-ewald/components/photo-gallery.js";
74
74
  | `--ui-font-size-sm` |
75
75
  | `--ui-line-height-normal` |
76
76
  | `--ui-line-height-tight` |
77
- | `--ui-on-accent` |
78
77
  | `--ui-overlay` |
78
+ | `--ui-overlay-text` |
79
79
  | `--ui-primary` |
80
80
  | `--ui-radius` |
81
81
  | `--ui-radius-pill` |
@@ -49,3 +49,4 @@ _None._
49
49
  | `--ui-primary` |
50
50
  | `--ui-text-muted` |
51
51
  | `--ui-tooltip` |
52
+ | `--ui-tooltip-text` |
@@ -66,5 +66,6 @@ _None._
66
66
  | `--ui-line-height-tight` |
67
67
  | `--ui-primary` |
68
68
  | `--ui-radius-pill` |
69
+ | `--ui-surface` |
69
70
  | `--ui-surface-muted` |
70
71
  | `--ui-text` |
@@ -1,7 +1,7 @@
1
1
  # `<slide-panel>`
2
2
 
3
- Generic sliding panel shell. Handles positioning, open/close animation,
4
- header chrome, and a close button. Body content is provided via the
3
+ Generic sliding panel shell: a non-modal native `<dialog>` (`show()`). Handles
4
+ positioning, open/close animation, header chrome, and a close button. Body content is provided via the
5
5
  default slot; the consumer controls its own padding and overflow.
6
6
 
7
7
  Desktop: fixed right-side panel that slides from the right.
@@ -0,0 +1,57 @@
1
+ # `<stat-strip>`
2
+
3
+ A headless, presentational strip of headline stats — one large figure plus
4
+ one muted caption per `items` entry, wrapping across lines on narrow
5
+ viewports. Unlike `stat-meter`, this component does not compute percentages
6
+ or render a fill bar: callers pass preformatted figure strings as-is and
7
+ `stat-strip` only lays them out for marketing, benchmark, or dashboard
8
+ summary rows.
9
+
10
+ ## Install
11
+
12
+ ```js
13
+ import "@f-ewald/components/stat-strip.js";
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```html
19
+ <stat-strip></stat-strip>
20
+ <script type="module">
21
+ document.querySelector("stat-strip").items = [
22
+ { value: "54%", label: "less code" },
23
+ { value: "22%", label: "fewer tokens" },
24
+ { value: "100%", label: "safety kept" },
25
+ ];
26
+ </script>
27
+ ```
28
+
29
+ ## Attributes / properties
30
+
31
+ | Property | Attribute | Type | Default | Description |
32
+ | --- | --- | --- | --- | --- |
33
+ | `items` | `items` | `StatStripItem[]` | `[]` | Stats rendered in display order; each item is shown as a large figure with a caption beneath it. |
34
+
35
+ ## Events
36
+
37
+ _None._
38
+
39
+ ## Slots
40
+
41
+ _None._
42
+
43
+ ## CSS custom properties
44
+
45
+ | Custom property |
46
+ | --- |
47
+ | `--ui-font` |
48
+ | `--ui-font-size-lg` |
49
+ | `--ui-font-size-sm` |
50
+ | `--ui-font-weight-bold` |
51
+ | `--ui-font-weight-medium` |
52
+ | `--ui-label-transform` |
53
+ | `--ui-line-height-tight` |
54
+ | `--ui-numeric` |
55
+ | `--ui-primary` |
56
+ | `--ui-text-muted` |
57
+ | `--ui-tracking-wide` |
@@ -0,0 +1,63 @@
1
+ # `<step-ladder>`
2
+
3
+ A flat ordered ladder of fallback steps — an escalating "try this first,
4
+ then move to the next rung only if it does not solve it" list. Each rung
5
+ shows a zero-padded ordinal, a bold title, and a muted description, with a
6
+ hairline rule between rows.
7
+
8
+ Feed it the `items` array for the plain data path, where each
9
+ StepLadderItem supplies a `title` and `description`, or slot bare
10
+ `<li>` steps when a rung needs links, emphasis, or other richer markup.
11
+ Slotted content takes precedence over `items`; with neither, nothing is
12
+ rendered. As with `spec-list`, richer wrapper elements are accepted too, but
13
+ those own their own inner markup.
14
+
15
+ ## Install
16
+
17
+ ```js
18
+ import "@f-ewald/components/step-ladder.js";
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ ```html
24
+ <step-ladder></step-ladder>
25
+ <script type="module">
26
+ document.querySelector("step-ladder").items = [
27
+ { title: "Does this need to exist?", description: "Speculative need = skip it." },
28
+ { title: "Already in this codebase?", description: "Reuse the helper that already lives here." },
29
+ { title: "Does the standard library do it?", description: "Use it." },
30
+ ];
31
+ </script>
32
+ ```
33
+
34
+ ## Attributes / properties
35
+
36
+ | Property | Attribute | Type | Default | Description |
37
+ | --- | --- | --- | --- | --- |
38
+ | `items` | `items` | `StepLadderItem[]` | `[]` | The rungs for the data-driven path. Ignored when the default slot has content. |
39
+
40
+ ## Events
41
+
42
+ _None._
43
+
44
+ ## Slots
45
+
46
+ _None._
47
+
48
+ ## CSS custom properties
49
+
50
+ | Custom property |
51
+ | --- |
52
+ | `--ui-border` |
53
+ | `--ui-border-width` |
54
+ | `--ui-font` |
55
+ | `--ui-font-size` |
56
+ | `--ui-font-size-sm` |
57
+ | `--ui-font-weight-bold` |
58
+ | `--ui-font-weight-regular` |
59
+ | `--ui-line-height-normal` |
60
+ | `--ui-numeric` |
61
+ | `--ui-primary` |
62
+ | `--ui-text` |
63
+ | `--ui-text-muted` |
@@ -0,0 +1,69 @@
1
+ # `<terminal-block>`
2
+
3
+ A headless, data-driven terminal transcript shell for short install or usage
4
+ instructions. Callers provide a flat ordered `lines` array of
5
+ `TerminalLine` objects, and the component renders each line exactly in that
6
+ order with a type-driven visual treatment: `"prompt"` lines get a fixed
7
+ leading `❯` marker in `--ui-primary`, `"comment"` lines render as dim italic
8
+ guidance, and `"output"` lines render as plain terminal text.
9
+
10
+ The panel deliberately stays dark regardless of the surrounding page theme:
11
+ it reuses `--ui-tooltip` for the surface and `--ui-tooltip-text` for the
12
+ main foreground (not `--ui-on-accent` — that token means "text on a solid
13
+ *semantic* fill" and a theme is free to darken it for a light accent color,
14
+ whereas `--ui-tooltip`'s own fill stays dark unconditionally), because this
15
+ is meant to read as "the terminal" rather than as a normal page card that
16
+ follows the ambient surface palette.
17
+
18
+ An empty `lines` array still renders the bordered, padded shell so consumers
19
+ can see that an instruction block is present but currently has no transcript
20
+ content, rather than having the component silently disappear.
21
+
22
+ ## Install
23
+
24
+ ```js
25
+ import "@f-ewald/components/terminal-block.js";
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ ```html
31
+ <terminal-block></terminal-block>
32
+ <script type="module">
33
+ document.querySelector("terminal-block").lines = [
34
+ { type: "comment", text: "# Claude Code" },
35
+ { type: "prompt", text: "/plugin marketplace add example/example" },
36
+ { type: "prompt", text: "/plugin install example@example" },
37
+ ];
38
+ </script>
39
+ ```
40
+
41
+ ## Attributes / properties
42
+
43
+ | Property | Attribute | Type | Default | Description |
44
+ | --- | --- | --- | --- | --- |
45
+ | `lines` | `lines` | `TerminalLine[]` | `[]` | Ordered terminal transcript lines. Each entry is a `{ type, text }` object, and an empty array still renders the visible terminal shell. |
46
+
47
+ ## Events
48
+
49
+ _None._
50
+
51
+ ## Slots
52
+
53
+ _None._
54
+
55
+ ## CSS custom properties
56
+
57
+ | Custom property |
58
+ | --- |
59
+ | `--ui-border` |
60
+ | `--ui-border-width` |
61
+ | `--ui-font-mono` |
62
+ | `--ui-font-size` |
63
+ | `--ui-font-weight-semibold` |
64
+ | `--ui-line-height-normal` |
65
+ | `--ui-on-accent` |
66
+ | `--ui-primary` |
67
+ | `--ui-radius` |
68
+ | `--ui-tooltip` |
69
+ | `--ui-tooltip-text` |
package/docs/tile-grid.md CHANGED
@@ -63,6 +63,7 @@ _None._
63
63
  | `--ui-font` |
64
64
  | `--ui-font-size-sm` |
65
65
  | `--ui-radius` |
66
+ | `--ui-surface` |
66
67
  | `--ui-surface-muted` |
67
68
  | `--ui-text` |
68
69
  | `--ui-text-muted` |
package/docs/ui-button.md CHANGED
@@ -113,6 +113,7 @@ _None._
113
113
  | `--ui-button-danger-background-active` |
114
114
  | `--ui-button-danger-background-hover` |
115
115
  | `--ui-button-danger-border` |
116
+ | `--ui-button-danger-text` |
116
117
  | `--ui-button-highlight` |
117
118
  | `--ui-button-secondary-` |
118
119
  | `--ui-button-secondary-background` |
@@ -120,6 +121,7 @@ _None._
120
121
  | `--ui-button-secondary-background-hover` |
121
122
  | `--ui-button-secondary-border` |
122
123
  | `--ui-button-secondary-border-hover` |
124
+ | `--ui-button-text` |
123
125
  | `--ui-button-text-shadow` |
124
126
  | `--ui-danger` |
125
127
  | `--ui-danger-hover` |