@excom/valence 0.1.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 (123) hide show
  1. package/.rush/temp/chunked-rush-logs/valence.apply-exports.chunks.jsonl +1 -0
  2. package/.rush/temp/chunked-rush-logs/valence.build_package-metas.chunks.jsonl +1 -0
  3. package/.rush/temp/operation/apply-exports/all.log +1 -0
  4. package/.rush/temp/operation/apply-exports/log-chunks.jsonl +1 -0
  5. package/.rush/temp/operation/apply-exports/state.json +3 -0
  6. package/.rush/temp/operation/build_package-metas/all.log +1 -0
  7. package/.rush/temp/operation/build_package-metas/log-chunks.jsonl +1 -0
  8. package/.rush/temp/operation/build_package-metas/state.json +3 -0
  9. package/.rush/temp/shrinkwrap-deps.json +3 -0
  10. package/basic-vars.css +395 -0
  11. package/basic.css +3 -0
  12. package/package.json +35 -0
  13. package/rush-logs/valence.apply-exports.cache.log +1 -0
  14. package/rush-logs/valence.apply-exports.log +1 -0
  15. package/rush-logs/valence.build_package-metas.cache.log +1 -0
  16. package/rush-logs/valence.build_package-metas.log +1 -0
  17. package/src/aliases.css +125 -0
  18. package/src/apply.css +54 -0
  19. package/src/components/accordion.css +134 -0
  20. package/src/components/card.css +54 -0
  21. package/src/components/dropdown.css +235 -0
  22. package/src/components/group.css +119 -0
  23. package/src/components/loading.css +41 -0
  24. package/src/components/modal.css +172 -0
  25. package/src/components/nav.css +198 -0
  26. package/src/components/popover.css +83 -0
  27. package/src/components/progress.css +88 -0
  28. package/src/components/tooltip.css +209 -0
  29. package/src/content/button.css +184 -0
  30. package/src/content/code.css +68 -0
  31. package/src/content/embedded.css +49 -0
  32. package/src/content/figure.css +17 -0
  33. package/src/content/link.css +79 -0
  34. package/src/content/misc.css +29 -0
  35. package/src/content/table.css +144 -0
  36. package/src/content/typography.css +218 -0
  37. package/src/forms/basics.css +415 -0
  38. package/src/forms/checkbox-radio-switch.css +163 -0
  39. package/src/forms/input-color.css +27 -0
  40. package/src/forms/input-date.css +66 -0
  41. package/src/forms/input-file.css +37 -0
  42. package/src/forms/input-range.css +109 -0
  43. package/src/forms/input-search.css +52 -0
  44. package/src/layout/abstract.css +9 -0
  45. package/src/layout/container.css +43 -0
  46. package/src/layout/document.css +45 -0
  47. package/src/layout/grid.css +24 -0
  48. package/src/layout/landmarks.css +54 -0
  49. package/src/layout/overflow-auto.css +33 -0
  50. package/src/layout/section.css +10 -0
  51. package/src/mixins.basic.css +308 -0
  52. package/src/mixins.default.css +49 -0
  53. package/src/util.default.css +55 -0
  54. package/src/utilities/accessibility.css +69 -0
  55. package/src/utilities/opt-outs.css +32 -0
  56. package/support/demos/accordion.html +18 -0
  57. package/support/demos/aliases.html +6 -0
  58. package/support/demos/button.html +14 -0
  59. package/support/demos/card.html +8 -0
  60. package/support/demos/checkboxes.html +22 -0
  61. package/support/demos/code.html +6 -0
  62. package/support/demos/container.html +15 -0
  63. package/support/demos/css-variables.html +14 -0
  64. package/support/demos/dropdown.html +17 -0
  65. package/support/demos/embedded.html +7 -0
  66. package/support/demos/forms.html +18 -0
  67. package/support/demos/grid.html +13 -0
  68. package/support/demos/group.html +14 -0
  69. package/support/demos/input.html +11 -0
  70. package/support/demos/landmarks.html +20 -0
  71. package/support/demos/link.html +7 -0
  72. package/support/demos/loading.html +5 -0
  73. package/support/demos/modal.html +18 -0
  74. package/support/demos/nav.html +39 -0
  75. package/support/demos/opt-outs.html +8 -0
  76. package/support/demos/overflow-auto.html +12 -0
  77. package/support/demos/popover.html +6 -0
  78. package/support/demos/progress.html +4 -0
  79. package/support/demos/range.html +6 -0
  80. package/support/demos/schemes.html +12 -0
  81. package/support/demos/select.html +13 -0
  82. package/support/demos/table.html +18 -0
  83. package/support/demos/textarea.html +7 -0
  84. package/support/demos/tooltip.html +7 -0
  85. package/support/demos/typography.html +18 -0
  86. package/support/docs/ACCORDION.md +26 -0
  87. package/support/docs/ALIASES.md +35 -0
  88. package/support/docs/BUTTON.md +28 -0
  89. package/support/docs/CARD.md +23 -0
  90. package/support/docs/CHECKBOXES.md +21 -0
  91. package/support/docs/CODE.md +18 -0
  92. package/support/docs/CONTAINER.md +24 -0
  93. package/support/docs/CSS_VARIABLES.md +44 -0
  94. package/support/docs/DROPDOWN.md +22 -0
  95. package/support/docs/EMBEDDED.md +18 -0
  96. package/support/docs/FORMS.md +44 -0
  97. package/support/docs/GRID.md +19 -0
  98. package/support/docs/GROUP.md +24 -0
  99. package/support/docs/INPUT.md +26 -0
  100. package/support/docs/LANDMARKS.md +25 -0
  101. package/support/docs/LINK.md +23 -0
  102. package/support/docs/LOADING.md +15 -0
  103. package/support/docs/MODAL.md +36 -0
  104. package/support/docs/NAV.md +25 -0
  105. package/support/docs/OPT_OUTS.md +31 -0
  106. package/support/docs/OVERFLOW_AUTO.md +15 -0
  107. package/support/docs/POPOVER.md +19 -0
  108. package/support/docs/PROGRESS.md +14 -0
  109. package/support/docs/RANGE.md +16 -0
  110. package/support/docs/README.md +70 -0
  111. package/support/docs/SCHEMES.md +20 -0
  112. package/support/docs/SELECT.md +18 -0
  113. package/support/docs/TABLE.md +29 -0
  114. package/support/docs/TEXTAREA.md +16 -0
  115. package/support/docs/THEMES.md +39 -0
  116. package/support/docs/TOOLTIP.md +18 -0
  117. package/support/docs/TYPOGRAPHY.md +29 -0
  118. package/support/docs-sections.json +45 -0
  119. package/support/flat-vars.css +197 -0
  120. package/support/flat.css +4 -0
  121. package/support/package-meta.json +1820 -0
  122. package/support/paper-vars.css +203 -0
  123. package/support/paper.css +4 -0
package/support/docs/GROUP.md ADDED
@@ -0,0 +1,24 @@
1
+ # Group
2
+
3
+ `[role="group"]` joins an input and a button (or several controls) into one pill; `[role="search"]` is the rounded variant.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="group"></include-content>
8
+
9
+ ```html
10
+ <fieldset role="group">
11
+ <input type="email" placeholder="Email" />
12
+ <button type="submit">Subscribe</button>
13
+ </fieldset>
14
+ <fieldset role="search">
15
+ <input type="search" placeholder="Search" />
16
+ <button type="submit">Go</button>
17
+ </fieldset>
18
+ ```
19
+
20
+ - Children lose their inner radii and margins; buttons shrink to their content and get wider padding.
21
+ - Focus moves to the group: `--v-group-box-shadow-focus-with-input` when an input is focused, `--v-group-box-shadow-focus-with-button` (per button flavor) when a button is.
22
+ - A `label` holding a `role="switch"` checkbox becomes an attached segment.
23
+
24
+ Aliases: `.tag-group`, `.tag-search`.
package/support/docs/INPUT.md ADDED
@@ -0,0 +1,26 @@
1
+ # Input
2
+
3
+ Text-like inputs share one look; `search`, date / time, `color` and `file` add their own affordances.
4
+
5
+ ## Types
6
+
7
+ <include-content data-demo="input"></include-content>
8
+
9
+ | Type | Extra |
10
+ | --- | --- |
11
+ | `text`, `email`, `password`, `number`, `tel`, `url` | The base look: `--v-form-element-*` tokens, focus ring |
12
+ | `search` | Pill radius (`5rem`) and a leading search icon |
13
+ | `date`, `datetime-local`, `month`, `time`, `week` | Trailing calendar / clock icon over the native picker |
14
+ | `color` | Swatch fills the control |
15
+ | `file` | Borderless, with a secondary-flavored selector button |
16
+ | `range` | See [Range](./RANGE.md) |
17
+
18
+ ## States
19
+
20
+ - `placeholder` uses `--v-form-element-placeholder-color`.
21
+ - `aria-invalid="true"` / `"false"` — border, focus ring and a trailing icon (see [Forms](./FORMS.md)).
22
+ - `readonly` keeps the resting look on focus; `disabled` fades the control.
23
+
24
+ ## Sizing
25
+
26
+ Height is derived from the tokens (`1rem × --v-line-height + 2 × --v-form-element-spacing-vertical + 2 × --v-border-width`), so a button and an input line up in a [group](./GROUP.md).
package/support/docs/LANDMARKS.md ADDED
@@ -0,0 +1,25 @@
1
+ # Landmarks & section
2
+
3
+ `body > header`, `main` and `footer` are centered columns out of the box; `section`s space themselves vertically.
4
+
5
+ ## Landmarks
6
+
7
+ ```html
8
+ <body>
9
+ <header>…</header>
10
+ <main>…</main>
11
+ <footer>…</footer>
12
+ </body>
13
+ ```
14
+
15
+ Each direct landmark child of `body` gets the [container](./CONTAINER.md) column and `--v-block-spacing-vertical` / `-horizontal` padding. The role and class aliases (`[role="main"]`, `.tag-main`, …) count as landmarks too, and an `.abstract` wrapper between `body` and the landmark is looked through (an `<include-content class="abstract">` around a header keeps it a landmark).
16
+
17
+ ## Section
18
+
19
+ <include-content data-demo="landmarks"></include-content>
20
+
21
+ `section` (and `[role="section"]` / `.tag-section`) is a block with `--v-block-spacing-vertical` below it. The spacing grows with the viewport: `1×` `--v-spacing` below 576px up to `2.25×` at 1536px, on landmarks, sections and cards alike.
22
+
23
+ ## Document
24
+
25
+ The root sets the font stack, size, weight, line height, `overflow-wrap: break-word`, `box-sizing: border-box` everywhere and a responsive root font size (`100%` → `131.25%` at 1536px), so every `rem` scales with the viewport.
package/support/docs/LINK.md ADDED
@@ -0,0 +1,23 @@
1
+ # Link
2
+
3
+ Links are primary-colored and underlined; `.secondary` and `.contrast` change the flavor, `aria-current` marks the active one.
4
+
5
+ ## Flavors
6
+
7
+ <include-content data-demo="link"></include-content>
8
+
9
+ ```html
10
+ <a href="#">Primary</a>
11
+ <a href="#" class="secondary">Secondary</a>
12
+ <a href="#" class="contrast">Contrast</a>
13
+ ```
14
+
15
+ Hover, focus, active and `[aria-current]` (any value but `"false"`) switch to the `-hover` tokens; `:focus-visible` adds a `--v-primary-focus` ring. The underline color is `--v-primary-underline` (and `-secondary-` / `-contrast-`).
16
+
17
+ ## Link as button
18
+
19
+ `<a role="button">` (or `.tag-button`) takes the full [button](./BUTTON.md) styling, including the flavors and `.outline`.
20
+
21
+ ## Aliases
22
+
23
+ `:--link` is `a`, `[role="link"]`, `.tag-link` — a `<spa-a role="link">` custom element is styled as a link without any CSS of its own.
package/support/docs/LOADING.md ADDED
@@ -0,0 +1,15 @@
1
+ # Loading
2
+
3
+ `aria-busy="true"` on almost any element shows a spinner before its content; on buttons and links it also blocks the pointer.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="loading"></include-content>
8
+
9
+ ```html
10
+ <button aria-busy="true">Saving…</button>
11
+ <button aria-busy="true"></button> <!-- spinner only -->
12
+ <article aria-busy="true">Loading…</article>
13
+ ```
14
+
15
+ The spinner is `--v-icon-loading` (`1em`); empty busy elements center it. Form controls (`input`, `select`, `textarea`) and `form` / `html` are excluded. Because the state is an attribute, a Quark rule sets it from any fact: `button { aria-busy: attr("is-loading") != null; }` or `provider-fetch[is-loading] button { aria-busy: "true"; }` (with its inverse).
package/support/docs/MODAL.md ADDED
@@ -0,0 +1,36 @@
1
+ # Modal
2
+
3
+ A native `dialog` centers an `article` over a dimmed backdrop; the header's close control and the footer buttons are styled, and `[role="dialog"]` hosts get the same look with a sibling backdrop.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="modal"></include-content>
8
+
9
+ ```html
10
+ <dialog>
11
+ <article>
12
+ <header>
13
+ <button rel="prev" aria-label="Close"></button>
14
+ <h5>Confirm</h5>
15
+ </header>
16
+ <p>…</p>
17
+ <footer>
18
+ <form method="dialog">
19
+ <button class="secondary">Cancel</button>
20
+ <button>Confirm</button>
21
+ </form>
22
+ </footer>
23
+ </article>
24
+ </dialog>
25
+ ```
26
+
27
+ - Open it with `dialog.showModal()`, `<dialog-anchor>`, or an `<event-handler command-name="show-modal">` (the demo); a `form[method="dialog"]` closes it without JS.
28
+ - **Close control**: `.close`, or a `button` / `a` with `rel="prev"` (`:--dialog-close`), renders the `--v-icon-close` glyph; in the `header` it floats right.
29
+ - The `article` caps its width per breakpoint (510px / 700px), scrolls internally, and its `footer` right-aligns buttons.
30
+ - `dialog::backdrop` blurs and dims (`--v-modal-overlay-backdrop-filter`, `--v-modal-overlay-background-color`); scrolling stays inside the dialog.
31
+
32
+ ## Custom hosts
33
+
34
+ `[role="dialog"]` / `.tag-dialog` (`:--dialog`) get the same layout; open state is `[open]` or `aria-expanded="true"`. Pseudo-elements cannot be aliased, so a custom host dims with a **sibling** element: `[role="presentation"]` or `.tag-backdrop` as the dialog's first child (`:--dialog-backdrop-aliases`) — `<content-drawer>` uses this. `.absolute` on the dialog positions it (and its backdrop) inside a `position: relative` parent instead of the viewport.
35
+
36
+ Element authors reuse the exact same dimmer through the `modal-backdrop` mixin — see [Themes & layers](./THEMES.md).
package/support/docs/NAV.md ADDED
@@ -0,0 +1,25 @@
1
+ # Nav
2
+
3
+ A `nav` lays its lists out horizontally — one left, one right — and becomes a breadcrumb with `aria-label="breadcrumb"`, a vertical menu inside an `aside`, or an outline tree with `role="tree"`.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="nav"></include-content>
8
+
9
+ ```html
10
+ <nav>
11
+ <ul><li><strong>Brand</strong></li></ul>
12
+ <ul>
13
+ <li><a href="#">Docs</a></li>
14
+ <li><a href="#" aria-current="page">Blog</a></li>
15
+ <li><details class="dropdown"><summary>More</summary><ul dir="rtl">…</ul></details></li>
16
+ </ul>
17
+ </nav>
18
+ ```
19
+
20
+ - Links are padded pills (`--v-nav-link-spacing-*`) without underline until hover; buttons, inputs and selects inside a nav shrink to fit; a [dropdown](./DROPDOWN.md) sits inline.
21
+ - **Breadcrumb**: `nav[aria-label="breadcrumb"]` joins items with `--v-nav-breadcrumb-divider` (`>`) and mutes the `aria-current` link.
22
+ - **Vertical**: inside an `aside`, `nav`, its lists and items stack; links fill the row.
23
+ - **Tree**: `ul[role="tree"]` (or `.tag-tree`) draws a left rule, indents nested trees and highlights the `aria-current` link with a primary border — the docs sidebar is one.
24
+
25
+ Aliases: `[role="navigation"]` / `.tag-nav`, `[role="list"]` / `.tag-list`, `[role="listitem"]` / `.tag-li`.
package/support/docs/OPT_OUTS.md ADDED
@@ -0,0 +1,31 @@
1
+ # Opt-outs
2
+
3
+ Valence.css is opinionated; these classes hand an element — or a subtree — back to the browser.
4
+
5
+ ## Unstyled
6
+
7
+ `.unstyled` reverts every Valence.css rule on one element; `.unstyled-all` does it for the element and all its descendants (`all: revert !important`).
8
+
9
+ <include-content data-demo="opt-outs"></include-content>
10
+
11
+ Use them where a third-party widget or a custom element brings its own styling and Valence.css would fight it.
12
+
13
+ ## Unanimated
14
+
15
+ `.unanimated` / `.unanimated-all` kill transitions and animations (the same rules `prefers-reduced-motion: reduce` applies everywhere, except on `[aria-busy="true"]` spinners).
16
+
17
+ ## Abstract wrappers
18
+
19
+ `.abstract` sets `display: contents`, so a wrapper — typically a custom element — is invisible to layout *and* to the Valence.css direct-child rules: `article > .abstract > header` is still styled as a card header. Rules that expect direct children (`article > header`, `details > summary`, `dialog > article`, `label > input`) look through one or two `.abstract` levels.
20
+
21
+ ```html
22
+ <article>
23
+ <event-handler class="abstract">
24
+ <header>Still a card header</header>
25
+ </event-handler>
26
+ </article>
27
+ ```
28
+
29
+ ## Layers
30
+
31
+ Element and alias styles sit in an anonymous `@layer`, so a consumer stylesheet or a custom element's own CSS overrides them at any specificity. The class utilities (`.grid`, `.container`, `.abstract`, the opt-outs) stay unlayered so they still win — see [Themes & layers](./THEMES.md).
package/support/docs/OVERFLOW_AUTO.md ADDED
@@ -0,0 +1,15 @@
1
+ # Overflow auto
2
+
3
+ Wrap wide content in `.overflow-auto` to scroll it inside its box; `.show-scrollbar` keeps a styled scrollbar visible.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="overflow-auto"></include-content>
8
+
9
+ ```html
10
+ <div class="overflow-auto">
11
+ <table>…</table>
12
+ </div>
13
+ ```
14
+
15
+ `.show-scrollbar` forces `overflow-y: scroll` with a slim themed thumb (`--v-muted-color`) — useful for panels whose content changes height.
package/support/docs/POPOVER.md ADDED
@@ -0,0 +1,19 @@
1
+ # Popover
2
+
3
+ A native `[popover]` opened by a `popovertarget` button is styled as a bubble and anchored to its invoker; `data-placement` picks the side.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="popover"></include-content>
8
+
9
+ ```html
10
+ <button popovertarget="tip">Info</button>
11
+ <div id="tip" popover data-placement="bottom">Bubble content</div>
12
+ ```
13
+
14
+ - Anchored with CSS anchor positioning (`position-anchor` on the invoker's parent); `data-placement` is `top` (default), `bottom`, `left` or `right`.
15
+ - Fades in and out (`@starting-style`, `transition-behavior: allow-discrete`); the UA backdrop is hidden.
16
+ - `--v-popover-max-width` (20rem), `--v-popover-background-color`, `--v-popover-border-color`, `--v-popover-color`, `--v-popover-box-shadow`.
17
+ - Open state is `:--popover--open`: `:popover-open` or `aria-expanded="true"` (`.tag-popover` for custom hosts).
18
+
19
+ For text-only hints use a [tooltip](./TOOLTIP.md).
package/support/docs/PROGRESS.md ADDED
@@ -0,0 +1,14 @@
1
+ # Progress
2
+
3
+ `progress` is a slim primary bar; without a `value` it animates as indeterminate.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="progress"></include-content>
8
+
9
+ ```html
10
+ <progress value="35" max="100"></progress>
11
+ <progress></progress>
12
+ ```
13
+
14
+ Tokens: `--v-progress-background-color`, `--v-progress-color`. The indeterminate animation respects `prefers-reduced-motion`. `[role="progressbar"]` / `.tag-progress` hosts get the track and, with `aria-valuenow`, the bar color on their `::before` (custom hosts size the bar themselves).
package/support/docs/RANGE.md ADDED
@@ -0,0 +1,16 @@
1
+ # Range
2
+
3
+ `input[type="range"]` is a themed slider: a slim track and a round thumb that grows while dragging.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="range"></include-content>
8
+
9
+ ```html
10
+ <label>
11
+ Brightness
12
+ <input type="range" min="0" max="100" value="40" />
13
+ </label>
14
+ ```
15
+
16
+ Tokens: `--v-range-border-color` (track), `--v-range-active-border-color`, `--v-range-thumb-color`, `--v-range-thumb-active-color`, `--v-range-thumb-border-color`.
package/support/docs/README.md ADDED
@@ -0,0 +1,70 @@
1
+ # Valence.css
2
+
3
+ Classless CSS that still loves your custom elements — Pico's elegance, remixed for the modern web.
4
+
5
+ Valence.css is a lightly modified fork of the excellent [Pico CSS](https://picocss.com). Pico styles are tightly bound to native tag names (`article`, `button`, …), which custom elements cannot reuse. Valence.css keeps Pico's look and adds:
6
+
7
+ - **Tag aliases** — `@custom-selector` synonyms so `[role="…"]` / `.tag-*` (and custom element tags) share the same semantic styles
8
+ - **Opt-outs** — `.unstyled` / `.unstyled-all` (and `.unanimated*`) for document flexibility where framework styles would fight you
9
+ - **Drop-in themes** — `basic` (Pico-faithful) ships today; further themes share the same tokens so they can be swapped without touching markup. Light/dark is a *scheme* (`[data-scheme]`)
10
+ - **Molecules** — cards, dropdowns, modals (`dialog::backdrop` / `[role="presentation"]` / `.tag-backdrop`), nav, progress, and native `[popover]` styles on top of Pico's element styles
11
+ - **Tokens** — `--pico-*` renamed to `--v-*` for a clear Valence.css namespace
12
+
13
+ ## Features
14
+
15
+ - **Semantic tag aliases** Style `article`, `dialog`, `button`, … — the same rules apply to the `[role="…"]` / `.tag-*` forms
16
+ - **Custom-element friendly** `class="tag-article"` on any host inherits Valence.css styles without rewriting selectors
17
+ - **Drop-in themes** `basic` (Pico-flavor) ships; further themes share the same tokens. Scheme via `[data-scheme="light|dark"]`
18
+ - **Opt-outs** `.unstyled` / `.unstyled-all` (and motion: `.unanimated*`)
19
+ - **Molecules** Cards, dropdowns, modals (`dialog::backdrop` / `[role="presentation"]` / `.tag-backdrop`), nav, progress, popovers, tooltips
20
+
21
+ ## Installation
22
+
23
+ <include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
24
+
25
+ ## Usage
26
+
27
+ Import a theme entry (CSS). Prefer aliases when styling custom elements.
28
+
29
+ ```css
30
+ @import "@excom/valence/basic.css";
31
+ ```
32
+
33
+ ```html
34
+ <article>Native card</article>
35
+ <event-handler class="tag-article">Aliased card</event-handler>
36
+ <button class="outline secondary">Outline</button>
37
+ ```
38
+
39
+ ### Documentation
40
+
41
+ Getting started
42
+
43
+ - [Color schemes](./SCHEMES.md) — automatic light / dark, `data-scheme`
44
+ - [Aliases](./ALIASES.md) — tag, role and `.tag-*` forms of every alias; custom elements
45
+ - [Opt-outs](./OPT_OUTS.md) — `.unstyled`, `.unanimated`, `.abstract`
46
+
47
+ Customization
48
+
49
+ - [CSS variables](./CSS_VARIABLES.md) — the `--v-*` tokens
50
+ - [Themes & layers](./THEMES.md) — entries, `@layer` strategy, mixins for element authors
51
+
52
+ Layout
53
+
54
+ - [Container](./CONTAINER.md) · [Landmarks & section](./LANDMARKS.md) · [Grid](./GRID.md) · [Overflow auto](./OVERFLOW_AUTO.md)
55
+
56
+ Content
57
+
58
+ - [Typography](./TYPOGRAPHY.md) · [Link](./LINK.md) · [Button](./BUTTON.md) · [Table](./TABLE.md) · [Code](./CODE.md) · [Embedded content](./EMBEDDED.md)
59
+
60
+ Forms
61
+
62
+ - [Forms](./FORMS.md) · [Input](./INPUT.md) · [Textarea](./TEXTAREA.md) · [Select](./SELECT.md) · [Checkboxes, radios & switches](./CHECKBOXES.md) · [Range](./RANGE.md)
63
+
64
+ Components
65
+
66
+ - [Accordion](./ACCORDION.md) · [Card](./CARD.md) · [Dropdown](./DROPDOWN.md) · [Group](./GROUP.md) · [Loading](./LOADING.md) · [Modal](./MODAL.md) · [Nav](./NAV.md) · [Popover](./POPOVER.md) · [Progress](./PROGRESS.md) · [Tooltip](./TOOLTIP.md)
67
+
68
+ ### API Reference
69
+
70
+ <include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
package/support/docs/SCHEMES.md ADDED
@@ -0,0 +1,20 @@
1
+ # Color schemes
2
+
3
+ Light and dark are a *scheme*: automatic from the OS, or forced on any subtree with `data-scheme`.
4
+
5
+ ## Automatic
6
+
7
+ With no attribute, the document follows `prefers-color-scheme`. Every token that differs between the two schemes (`--v-background-color`, `--v-color`, `--v-primary`, the form and card colors, …) is defined once per scheme, so the whole page — and every custom element using the tokens — flips together.
8
+
9
+ ## Forcing a scheme
10
+
11
+ `data-scheme="light"` or `data-scheme="dark"` on `<html>` forces the document; on any other element it forces that subtree. The attribute also sets `color-scheme`, so native controls and scrollbars follow.
12
+
13
+ <include-content data-demo="schemes"></include-content>
14
+
15
+ ```html
16
+ <html data-scheme="dark">…</html>
17
+ <article data-scheme="light">Always light</article>
18
+ ```
19
+
20
+ Switching at runtime is one attribute write — a Quark rule (`html { data-scheme: $theme; }`) or `<provider-storage>` can own it. Custom elements with a shadow root get the same tokens through `:host`.
package/support/docs/SELECT.md ADDED
@@ -0,0 +1,18 @@
1
+ # Select
2
+
3
+ A `select` gets the input look plus a chevron; `multiple` / `size` lists drop the chevron and highlight selected options.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="select"></include-content>
8
+
9
+ ```html
10
+ <select name="planet" required>
11
+ <option selected disabled value="">Select a planet…</option>
12
+ <option>Earth</option>
13
+ </select>
14
+ ```
15
+
16
+ A `required` select whose selected option has an empty value renders in the placeholder color (`select:invalid`). Selected options in a `[multiple]` list use `--v-form-element-selected-background-color`.
17
+
18
+ `select` has no alias; for a custom picker style a [dropdown](./DROPDOWN.md).
package/support/docs/TABLE.md ADDED
@@ -0,0 +1,29 @@
1
+ # Table
2
+
3
+ Tables are full-width with bordered rows; `.striped` alternates rows, `thead.sticky` pins the header, and `aria-sort` draws sort markers.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="table"></include-content>
8
+
9
+ ```html
10
+ <table class="striped">
11
+ <thead><tr><th scope="col" aria-sort="ascending">Planet</th>…</tr></thead>
12
+ <tbody>…</tbody>
13
+ <tfoot>…</tfoot>
14
+ </table>
15
+ ```
16
+
17
+ ## Modifiers
18
+
19
+ | Modifier | Effect |
20
+ | --- | --- |
21
+ | `.striped` | Odd body rows get `--v-table-row-stripped-background-color` |
22
+ | `thead.sticky` | Header cells stick to `--v-table-sticky-top` (default `0px`) while the table scrolls |
23
+ | `th[aria-sort]` | A `▲▼` marker; `"ascending"` / `"descending"` show one arrow, and the cell gets a pointer cursor |
24
+
25
+ Corner cells are rounded (`--v-border-radius`); the last row loses its bottom border so a table sits flush in a card.
26
+
27
+ ## Role-based tables
28
+
29
+ `[role="table"]`, `[role="row"]`, `[role="columnheader"]` / `[role="rowheader"]`, `[role="cell"]` and `[role="rowgroup"]` (or the `.tag-table` … `.tag-td` classes) render as table parts, so a custom element such as `<data-table>` can build a grid from `div`s and still look like a table. `thead` / `tbody` are told apart by their cells (`th[scope="col"]` vs `th[scope="row"]` / `td`); `tfoot` has no role equivalent.
package/support/docs/TEXTAREA.md ADDED
@@ -0,0 +1,16 @@
1
+ # Textarea
2
+
3
+ A `textarea` is a block that resizes vertically only and follows the same tokens and validity styling as inputs.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="textarea"></include-content>
8
+
9
+ ```html
10
+ <label>
11
+ Message
12
+ <textarea name="message" rows="3"></textarea>
13
+ </label>
14
+ ```
15
+
16
+ `aria-invalid` draws its icon in the top-right corner; helper text and disabled states behave as on [Forms](./FORMS.md).
package/support/docs/THEMES.md ADDED
@@ -0,0 +1,39 @@
1
+ # Themes & layers
2
+
3
+ A theme is a token file plus the shared mixins; `basic` (Pico-faithful) ships today, and every theme shares the same tokens so markup never changes.
4
+
5
+ ## Entry points
6
+
7
+ ```css
8
+ @import "@excom/valence/basic.css"; /* the theme: mixins + tokens + every module */
9
+ @import "@excom/valence/src/mixins.basic.css"; /* mixins only, for element authors */
10
+ ```
11
+
12
+ `basic.css` is `mixins.basic.css` + `basic-vars.css` (the tokens, both schemes) + `apply.css` (every module applied once). `basic-vars.css` alone gives the tokens without any element styling.
13
+
14
+ The `nucleus-kit` bundle re-exports `basic.css`, so Nucleus Kit users already have it.
15
+
16
+ ## Layers
17
+
18
+ `apply.css` puts every element / alias module inside one anonymous `@layer`. Anything unlayered — your stylesheet, a custom element's CSS — beats it regardless of specificity, so overriding Valence.css never needs `!important`. The class utilities (`.container`, `.grid`, `.overflow-auto`, `.abstract`, [opt-outs](./OPT_OUTS.md)) are deliberately *unlayered* so they win over element styles a custom element ships later.
19
+
20
+ ## Mixins for element authors
21
+
22
+ Custom elements that want to look native import `src/mixins.basic.css` (tokens are read from the document; no theme is duplicated) and apply the mixins in their own CSS:
23
+
24
+ | Mixin | Use |
25
+ | --- | --- |
26
+ | `modal-backdrop` | The dimmer behind a dialog / drawer (`dialog::backdrop`, `[role="presentation"]`, `.tag-backdrop`) |
27
+ | `modal-close-control` | The close icon control (`.close`, `[rel="prev"]`) |
28
+ | `util-nested-card`, `util-elevated` | Card surfaces |
29
+ | `util-focus-ring`, `util-press-feedback` | Interaction states |
30
+ | `util-small-note` | Muted block note (what `small[role="note"]` uses) |
31
+ | `abstract-wrapper` | Donut-scope a direct-child rule through `.abstract` wrappers |
32
+ | `details-animated-content` | The accordion's animated `::details-content` |
33
+ | `unanimated` | Kill motion (the opt-out) |
34
+
35
+ Module mixins (`module-button`, `module-card`, …) apply a whole module; a theme calls them all from `apply.css`.
36
+
37
+ ## Further themes
38
+
39
+ `flat` and `paper` token files exist in the repository (`support/`) but are not published entries yet; they will swap in without markup changes because they only redefine tokens.
package/support/docs/TOOLTIP.md ADDED
@@ -0,0 +1,18 @@
1
+ # Tooltip
2
+
3
+ `role="tooltip"` with an `aria-description` shows the text in a bubble on hover and focus, above the element by default.
4
+
5
+ ## Usage
6
+
7
+ <include-content data-demo="tooltip"></include-content>
8
+
9
+ ```html
10
+ <span role="tooltip" aria-description="Shown above">Hover me</span>
11
+ <button role="tooltip" aria-description="Placed below" data-placement="bottom">Bottom</button>
12
+ ```
13
+
14
+ - `data-placement`: `top` (default), `bottom`, `left`, `right`.
15
+ - Plain elements get a dotted underline and help cursor; links, buttons and inputs keep their own look.
16
+ - Pure CSS (`::before` / `::after` read `aria-description`), with a slide animation on fine pointers; `--v-tooltip-background-color`, `--v-tooltip-color`.
17
+
18
+ The docs site uses it on its icon buttons (`role="tooltip" aria-description="Copy source"`). For rich content use a [popover](./POPOVER.md).
package/support/docs/TYPOGRAPHY.md ADDED
@@ -0,0 +1,29 @@
1
+ # Typography
2
+
3
+ Headings, paragraphs, lists, quotes and inline text primitives — every one available as a tag, a role or an `.tag-*` class.
4
+
5
+ ## Headings
6
+
7
+ `h1`–`h6` (or `[role="heading"][aria-level="n"]`) set their own `--v-font-size`, `--v-line-height` and color (`--v-h1-color` … `--v-h6-color`). A heading that follows a block (`p`, `ul`, `article`, `table`, …) gets `--v-typography-spacing-top` above it, so sections breathe without extra markup.
8
+
9
+ An `hgroup` keeps its children tight and mutes the last one — a title plus a subtitle:
10
+
11
+ <include-content data-demo="typography"></include-content>
12
+
13
+ ## Blocks
14
+
15
+ `p`, `ul` / `ol`, `dl`, `blockquote`, `address`, `pre`, `table` share `--v-typography-spacing-vertical` below them. `ul` lists use square markers; nested lists drop their outer margin. A `blockquote` gets a left rule (`--v-blockquote-border-color`) and a muted `footer` for the citation.
16
+
17
+ ## Inline
18
+
19
+ | Element | Style |
20
+ | --- | --- |
21
+ | `strong`, `b` | Bolder |
22
+ | `mark` | `--v-mark-background-color` highlight |
23
+ | `ins`, `del` | `--v-ins-color` / `--v-del-color` |
24
+ | `abbr[title]` | Dotted underline, help cursor |
25
+ | `sub`, `sup` | No line-height change |
26
+ | `small` | `0.875em`; `small[role="note"]` is a block-level muted note |
27
+ | `kbd`, `code`, `samp` | See [Code](./CODE.md) |
28
+
29
+ `hr` is a 1px `--v-muted-border-color` rule with vertical spacing. Text selection uses `--v-text-selection-color`.
package/support/docs-sections.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "sections": [
3
+ {
4
+ "id": "getting-started",
5
+ "title": "Getting Started",
6
+ "docs": ["schemes", "aliases", "opt_outs"]
7
+ },
8
+ {
9
+ "id": "customization",
10
+ "title": "Customization",
11
+ "docs": ["css_variables", "themes"]
12
+ },
13
+ {
14
+ "id": "layout",
15
+ "title": "Layout",
16
+ "docs": ["container", "landmarks", "grid", "overflow_auto"]
17
+ },
18
+ {
19
+ "id": "content",
20
+ "title": "Content",
21
+ "docs": ["typography", "link", "button", "table", "code", "embedded"]
22
+ },
23
+ {
24
+ "id": "forms",
25
+ "title": "Forms",
26
+ "docs": ["forms", "input", "textarea", "select", "checkboxes", "range"]
27
+ },
28
+ {
29
+ "id": "components",
30
+ "title": "Components",
31
+ "docs": [
32
+ "accordion",
33
+ "card",
34
+ "dropdown",
35
+ "group",
36
+ "loading",
37
+ "modal",
38
+ "nav",
39
+ "popover",
40
+ "progress",
41
+ "tooltip"
42
+ ]
43
+ }
44
+ ]
45
+ }