@excom/valence 0.1.0

package/support/demos/forms.html

@@ -0,0 +1,18 @@
+<form>
+  <label>
+    Email
+    <input type="email" name="email" placeholder="you@example.com" autocomplete="email" />
+  </label>
+  <label>
+    Password
+    <input type="password" name="password" aria-invalid="true" />
+    <small>At least 8 characters.</small>
+  </label>
+  <fieldset>
+    <legend>Plan</legend>
+    <label><input type="radio" name="plan" value="free" checked /> Free</label>
+    <label><input type="radio" name="plan" value="pro" /> Pro</label>
+  </fieldset>
+  <label><input type="checkbox" name="terms" /> I agree to the terms</label>
+  <button type="submit">Sign up</button>
+</form>

package/support/demos/grid.html

@@ -0,0 +1,13 @@
+<div class="grid">
+  <div>1</div>
+  <div>2</div>
+  <div>3</div>
+  <style>
+    #demo-valence-grid > :first-child > div {
+      padding: var(--v-spacing);
+      text-align: center;
+      border: 1px dashed var(--v-muted-color);
+      border-radius: var(--v-border-radius);
+    }
+  </style>
+</div>

package/support/demos/group.html

@@ -0,0 +1,14 @@
+<form>
+  <fieldset role="group">
+    <input type="email" placeholder="Email" aria-label="Email" autocomplete="email" />
+    <button type="submit">Subscribe</button>
+  </fieldset>
+  <fieldset role="search">
+    <input type="search" placeholder="Search" aria-label="Search" />
+    <button type="submit">Go</button>
+  </fieldset>
+  <fieldset role="group">
+    <input type="text" placeholder="Domain" aria-label="Domain" />
+    <label><input type="checkbox" role="switch" checked /> HTTPS</label>
+  </fieldset>
+</form>

package/support/demos/input.html

@@ -0,0 +1,11 @@
+<form>
+  <input type="text" placeholder="Text" aria-label="Text" />
+  <input type="search" placeholder="Search" aria-label="Search" />
+  <input type="date" aria-label="Date" />
+  <input type="text" value="Valid" aria-invalid="false" aria-label="Valid" />
+  <input type="text" value="Invalid" aria-invalid="true" aria-label="Invalid" />
+  <input type="text" value="Read-only" readonly aria-label="Read-only" />
+  <input type="text" value="Disabled" disabled aria-label="Disabled" />
+  <input type="file" aria-label="File" />
+  <input type="color" value="#0172ad" aria-label="Color" />
+</form>

package/support/demos/landmarks.html

@@ -0,0 +1,20 @@
+<div>
+  <section>
+    <hgroup>
+      <h4>First section</h4>
+      <p>Sections space themselves vertically</p>
+    </hgroup>
+  </section>
+  <section>
+    <hgroup>
+      <h4>Second section</h4>
+      <p><code>--v-block-spacing-vertical</code> grows with the viewport</p>
+    </hgroup>
+  </section>
+  <style>
+    #demo-valence-landmarks > :first-child section {
+      border: 1px dashed var(--v-muted-color);
+      padding: var(--v-spacing);
+    }
+  </style>
+</div>

package/support/demos/link.html

@@ -0,0 +1,7 @@
+<p>
+  <a href="#">Primary</a> ·
+  <a href="#" class="secondary">Secondary</a> ·
+  <a href="#" class="contrast">Contrast</a> ·
+  <a href="#" aria-current="page">Current</a> ·
+  <a href="#" role="button">Link as button</a>
+</p>

package/support/demos/loading.html

@@ -0,0 +1,5 @@
+<div>
+  <button aria-busy="true">Saving…</button>
+  <button class="secondary outline" aria-busy="true"></button>
+  <article aria-busy="true">Loading the card…</article>
+</div>

package/support/demos/modal.html

@@ -0,0 +1,18 @@
+<div>
+  <event-handler target-ref=":scope ~ dialog" command-name="show-modal" class="tag-button">Open modal</event-handler>
+  <dialog>
+    <article>
+      <header>
+        <event-handler target-ref=":scope ~ dialog, dialog:has(:scope)" command-name="close" class="tag-button" rel="prev" aria-label="Close"></event-handler>
+        <h5>Confirm</h5>
+      </header>
+      <p>A <code>dialog</code> centers its <code>article</code>; the header close control and the footer buttons are styled for you.</p>
+      <footer>
+        <form method="dialog">
+          <button class="secondary">Cancel</button>
+          <button>Confirm</button>
+        </form>
+      </footer>
+    </article>
+  </dialog>
+</div>

package/support/demos/nav.html

@@ -0,0 +1,39 @@
+<div>
+  <nav>
+    <ul>
+      <li><strong>Brand</strong></li>
+    </ul>
+    <ul>
+      <li><a href="#">Docs</a></li>
+      <li><a href="#" aria-current="page">Blog</a></li>
+      <li>
+        <details class="dropdown">
+          <summary>More</summary>
+          <ul dir="rtl">
+            <li><a href="#">About</a></li>
+            <li><a href="#">Contact</a></li>
+          </ul>
+        </details>
+      </li>
+    </ul>
+  </nav>
+  <nav aria-label="breadcrumb">
+    <ul>
+      <li><a href="#">Home</a></li>
+      <li><a href="#">Docs</a></li>
+      <li><a href="#" aria-current="page">Nav</a></li>
+    </ul>
+  </nav>
+  <aside>
+    <nav>
+      <ul role="tree">
+        <li><a href="#" aria-current="page">Getting started</a></li>
+        <li><a href="#">Layout</a>
+          <ul role="tree">
+            <li><a href="#">Grid</a></li>
+          </ul>
+        </li>
+      </ul>
+    </nav>
+  </aside>
+</div>

package/support/demos/opt-outs.html

@@ -0,0 +1,8 @@
+<div>
+  <button>Styled</button>
+  <button class="unstyled">Unstyled (browser default)</button>
+  <article class="unstyled-all">
+    <p>This card and everything inside it is left to the browser.</p>
+    <button>Native button</button>
+  </article>
+</div>

package/support/demos/overflow-auto.html

@@ -0,0 +1,12 @@
+<div class="overflow-auto">
+  <table>
+    <thead>
+      <tr><th>Planet</th><th>Diameter (km)</th><th>Distance from Sun (10⁶ km)</th><th>Orbital period (days)</th><th>Moons</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Mercury</td><td>4,879</td><td>57.9</td><td>88</td><td>0</td></tr>
+      <tr><td>Venus</td><td>12,104</td><td>108.2</td><td>224.7</td><td>0</td></tr>
+      <tr><td>Earth</td><td>12,756</td><td>149.6</td><td>365.2</td><td>1</td></tr>
+    </tbody>
+  </table>
+</div>

package/support/demos/popover.html

@@ -0,0 +1,6 @@
+<p>
+  <button popovertarget="demo-valence-pop-top" popovertargetaction="toggle">Top</button>
+  <div id="demo-valence-pop-top" popover>Anchored above the button.</div>
+  <button popovertarget="demo-valence-pop-bottom" class="secondary">Bottom</button>
+  <div id="demo-valence-pop-bottom" popover data-placement="bottom">Anchored below the button.</div>
+</p>

package/support/demos/progress.html

@@ -0,0 +1,4 @@
+<div>
+  <progress value="35" max="100"></progress>
+  <progress></progress>
+</div>

package/support/demos/range.html

@@ -0,0 +1,6 @@
+<form>
+  <label>
+    Brightness
+    <input type="range" min="0" max="100" value="40" />
+  </label>
+</form>

package/support/demos/schemes.html

@@ -0,0 +1,12 @@
+<div>
+  <article data-scheme="light">
+    <h4>Light</h4>
+    <p>Forced with <code>data-scheme="light"</code>.</p>
+    <button>Primary</button>
+  </article>
+  <article data-scheme="dark">
+    <h4>Dark</h4>
+    <p>Forced with <code>data-scheme="dark"</code>.</p>
+    <button>Primary</button>
+  </article>
+</div>

package/support/demos/select.html

@@ -0,0 +1,13 @@
+<form>
+  <select name="planet" aria-label="Planet" required>
+    <option selected disabled value="">Select a planet…</option>
+    <option>Mercury</option>
+    <option>Venus</option>
+    <option>Earth</option>
+  </select>
+  <select name="moons" aria-label="Moons" multiple size="3">
+    <option selected>Luna</option>
+    <option>Phobos</option>
+    <option>Deimos</option>
+  </select>
+</form>

package/support/demos/table.html

@@ -0,0 +1,18 @@
+<table class="striped">
+  <thead>
+    <tr>
+      <th scope="col" aria-sort="ascending">Planet</th>
+      <th scope="col" aria-sort="none">Diameter</th>
+      <th scope="col">Moons</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><th scope="row">Mercury</th><td>4,879 km</td><td>0</td></tr>
+    <tr><th scope="row">Venus</th><td>12,104 km</td><td>0</td></tr>
+    <tr><th scope="row">Earth</th><td>12,756 km</td><td>1</td></tr>
+    <tr><th scope="row">Mars</th><td>6,792 km</td><td>2</td></tr>
+  </tbody>
+  <tfoot>
+    <tr><th scope="row">Total</th><td></td><td>3</td></tr>
+  </tfoot>
+</table>

package/support/demos/textarea.html

@@ -0,0 +1,7 @@
+<form>
+  <label>
+    Message
+    <textarea name="message" placeholder="Write something…" rows="3"></textarea>
+    <small>Resizes vertically.</small>
+  </label>
+</form>

package/support/demos/tooltip.html

@@ -0,0 +1,7 @@
+<p>
+  <span role="tooltip" aria-description="Shown above by default">Hover me</span>
+  ·
+  <button role="tooltip" aria-description="Placed below" data-placement="bottom">Bottom</button>
+  ·
+  <a href="#" role="tooltip" aria-description="To the right" data-placement="right">Right</a>
+</p>

package/support/demos/typography.html

@@ -0,0 +1,18 @@
+<div>
+  <hgroup>
+    <h3>Heading group</h3>
+    <p>The last child of an <code>hgroup</code> is muted</p>
+  </hgroup>
+  <p>A paragraph with <strong>strong</strong>, <em>emphasis</em>, <mark>mark</mark>, <ins>ins</ins>, <del>del</del>, <abbr title="Accessible Rich Internet Applications">ARIA</abbr>, <kbd>Ctrl</kbd> and <code>code</code>.</p>
+  <ul>
+    <li>Square markers on <code>ul</code></li>
+    <li>Nested lists keep their spacing
+      <ul><li>like this one</li></ul>
+    </li>
+  </ul>
+  <blockquote>
+    Valence.css is a lightly modified fork of Pico.
+    <footer><cite>— the README</cite></footer>
+  </blockquote>
+  <small role="note">A <code>small[role="note"]</code> is a block-level muted note.</small>
+</div>

package/support/docs/ACCORDION.md

@@ -0,0 +1,26 @@
+# Accordion
+
+`details` / `summary` is the accordion: a chevron marker, animated content, and a `summary[role="button"]` variant.
+
+## Usage
+
+<include-content data-demo="accordion"></include-content>
+
+```html
+<details>
+  <summary>Title</summary>
+  <p>Content</p>
+</details>
+<details>
+  <summary role="button" class="outline secondary">Button summary</summary>
+  <p>Content</p>
+</details>
+```
+
+- The content (`::details-content`) animates height and opacity on open / close (`interpolate-size`; instant under reduced motion).
+- `summary[role="button"]` is a full-width button and takes every [button](./BUTTON.md) flavor.
+- Open state is `:--details--open`: `[open]` or `aria-expanded="true"`, so a custom disclosure element reflecting ARIA gets the rotated marker and colors.
+
+## Aliases
+
+`.tag-details` / `.tag-summary` (`details` has no ARIA role; `summary`'s implicit role is `button`, deliberately not aliased to avoid colliding with `:--button`). A [dropdown](./DROPDOWN.md) is an accordion with `.dropdown`.

package/support/docs/ALIASES.md

@@ -0,0 +1,35 @@
+# Aliases
+
+Every Valence.css tag alias is a `@custom-selector` that matches the native tag, its ARIA role and an `.tag-*` class — so a custom element or a plain `div` can wear any semantic style.
+
+## Three ways to match
+
+`:--article` expands to `article, [role="article"], .tag-article`. Pico ties its styles to tag names, which custom elements cannot reuse; Valence.css adds the role and class forms to every tag alias:
+
+<include-content data-demo="aliases"></include-content>
+
+| Alias | Matches |
+| --- | --- |
+| `:--article` | `article`, `[role="article"]`, `.tag-article` |
+| `:--button` | `button`, `[role="button"]`, `[type="button"]`, `.tag-button` |
+| `:--details` / `:--summary` | `details` / `summary`, `.tag-details` / `.tag-summary` |
+| `:--dialog` | `dialog`, `[role="dialog"]`, `.tag-dialog` |
+| `:--nav`, `:--list`, `:--li` | `nav` / `[role="navigation"]`, `ul` / `ol` / `[role="list"]`, `li` / `[role="listitem"]` |
+| `:--table`, `:--tr`, `:--th`, `:--td` | tags, `[role="table"]` / `"row"` / `"columnheader"` / `"cell"`, `[scope]` |
+| `:--heading`, `:--h1` … `:--h6` | `h1`…`h6`, `[role="heading"][aria-level]` |
+
+The full list is in the *API Reference* on the [package page](./README.md#md-api-reference) (*CSS aliases*). Prefer the role form when the element genuinely has that role (screen readers benefit too); use `.tag-*` when it does not.
+
+## State aliases
+
+States are `:--{element}--{state}` and match ARIA as well as native state: `:--details--open` is `[open], [aria-expanded="true"]`; `:--button--disabled` is `[disabled], [aria-disabled="true"]`; `:--progress--value` is `[value], [aria-valuenow]`. A custom element that reflects `aria-expanded` gets the open styling for free.
+
+## Custom elements
+
+- Put the tag alias class on the host (`<content-drawer class="tag-article">`) — styles apply without the element knowing Valence.css exists.
+- Elements with a shadow root inherit the tokens through `:host`; only the tokens cross the boundary, the rules do not.
+- `.abstract` (`display: contents`) lets a wrapper element sit between a parent and the children a rule expects (`article > header`): see [Opt-outs](./OPT_OUTS.md).
+
+## Not aliased
+
+Inimitable natives — `input`, `textarea`, `select` — have no alias; style a wrapper or use the native control. Pseudo-elements cannot be aliased (`postcss-custom-selectors` wraps in `:is()`), which is why the modal backdrop is a sibling element for custom hosts (see [Modal](./MODAL.md)).

package/support/docs/BUTTON.md

@@ -0,0 +1,28 @@
+# Button
+
+Buttons come in primary, `.secondary` and `.contrast`, each with an `.outline` variant, and the same styles apply to any `[role="button"]` or `.tag-button` element.
+
+## Flavors
+
+<include-content data-demo="button"></include-content>
+
+```html
+<button>Primary</button>
+<button class="secondary">Secondary</button>
+<button class="contrast">Contrast</button>
+<button class="outline">Outline</button>
+<button class="outline secondary">Outline secondary</button>
+```
+
+`[type="submit"]` is primary, `[type="reset"]` secondary and `[type="file"]`'s selector button secondary. Buttons are `inline-block`; a `[type="submit"]` inside a form is full-width (see [Forms](./FORMS.md)).
+
+## States
+
+- **Disabled** — `[disabled]` or `aria-disabled="true"` (`:--button--disabled`): half opacity, no pointer events; a `fieldset[disabled]` disables every button inside.
+- **Busy** — `aria-busy="true"` shows the [loading](./LOADING.md) spinner and blocks pointer events.
+- **Current** — `[aria-current]` (not `"false"`) renders the hover state.
+- **Focus** — a `--v-primary-focus` ring (`-secondary-` / `-contrast-` per flavor).
+
+## Tokens
+
+A button reads `--v-background-color`, `--v-border-color`, `--v-color` and `--v-box-shadow` from its flavor (`--v-primary-background`, `--v-primary-border`, `--v-primary-inverse`, …); override those on the element or restyle a flavor globally through the [CSS variables](./CSS_VARIABLES.md).

package/support/docs/CARD.md

@@ -0,0 +1,23 @@
+# Card
+
+An `article` is a card: padding, radius, shadow, and sectioned `header` / `footer` bands.
+
+## Usage
+
+<include-content data-demo="card"></include-content>
+
+```html
+<article>
+  <header>Header</header>
+  Body
+  <footer>Footer</footer>
+</article>
+```
+
+`header` / `footer` (direct children, or through an `.abstract` wrapper) bleed to the card edges with `--v-card-sectioning-background-color` and a `--v-card-border-color` rule. `.nested` quiets a card inside another card (`--v-multiply-color-*` surfaces).
+
+Tokens: `--v-card-background-color`, `--v-card-border-color`, `--v-card-box-shadow`, `--v-card-sectioning-background-color`; the padding is `--v-block-spacing-vertical` / `-horizontal`, so cards grow with the viewport like [sections](./LANDMARKS.md).
+
+## Aliases
+
+`[role="article"]` / `.tag-article` — the usual way to make a custom element a card (`<content-drawer class="tag-article">`).

package/support/docs/CHECKBOXES.md

@@ -0,0 +1,21 @@
+# Checkboxes, radios & switches
+
+Native `checkbox` and `radio` inputs are restyled with the primary color; `role="switch"` turns a checkbox into a toggle.
+
+## Usage
+
+<include-content data-demo="checkboxes"></include-content>
+
+```html
+<label><input type="checkbox" checked /> Checked</label>
+<label><input type="radio" name="r" /> Radio</label>
+<label><input type="checkbox" role="switch" /> Switch</label>
+```
+
+- A checkbox in the `indeterminate` state (set from JS) shows a minus.
+- A `label` that wraps a checkbox / radio shrinks to its content and gets a pointer cursor; labels after the input (`input ~ label`) stay inline.
+- `aria-invalid="true"` / `"false"` recolor the checked control.
+
+## Switch
+
+`[type="checkbox"][role="switch"]` is a `2.25em × 1.25em` track (`--v-switch-background-color`, checked `--v-switch-checked-background-color`) with an animated thumb; inside a [group](./GROUP.md) a switch label becomes an attached segment.

package/support/docs/CODE.md

@@ -0,0 +1,18 @@
+# Code
+
+`code`, `kbd`, `samp` and `pre` share the monospace tokens; `pre > code` becomes a scrollable block.
+
+## Usage
+
+<include-content data-demo="code"></include-content>
+
+```html
+<p>Press <kbd>⌘</kbd> <kbd>K</kbd> to run <code>build</code>.</p>
+<pre><code>npm install @excom/valence</code></pre>
+```
+
+- Inline `code` / `samp`: `--v-code-background-color` / `--v-code-color`, small padding, `0.75em`.
+- `kbd`: inverted (`--v-code-kbd-background-color` / `-color`).
+- `pre`: block, `overflow-x: auto`, `--v-spacing` padding on the inner `code` / `samp`.
+
+Aliases: `[role="code"]` / `.tag-code`, `.tag-pre`, `.tag-kbd`, `.tag-samp`.

package/support/docs/CONTAINER.md

@@ -0,0 +1,24 @@
+# Container
+
+`.container` centers content in a responsive column; `.container-fluid` spans the full width with padding only.
+
+## Usage
+
+<include-content data-demo="container"></include-content>
+
+```html
+<main class="container">…</main>
+```
+
+## Breakpoints
+
+| Viewport | `.container` max-width |
+| --- | --- |
+| < 576px | 100% (with `--v-spacing` padding) |
+| ≥ 576px | 510px |
+| ≥ 768px | 700px |
+| ≥ 1024px | 950px |
+| ≥ 1280px | 1200px |
+| ≥ 1536px | 1450px |
+
+Landmark children of `body` (`header`, `main`, `footer`) get the same column without any class — see [Landmarks & section](./LANDMARKS.md).

package/support/docs/CSS_VARIABLES.md

@@ -0,0 +1,44 @@
+# CSS variables
+
+Every color, size and spacing is a `--v-*` custom property; override them on `:root` or on any subtree.
+
+## Overriding tokens
+
+<include-content data-demo="css-variables"></include-content>
+
+```css
+:root {
+  --v-primary: #7c3aed;
+  --v-primary-background: #7c3aed;
+  --v-border-radius: 2rem;
+}
+```
+
+Scheme-dependent tokens (colors) are declared per scheme, so override them under both `[data-scheme="light"]` / `:root:not([data-scheme="dark"])` and `[data-scheme="dark"]` (plus the `prefers-color-scheme: dark` auto case) when the value should differ — see [Color schemes](./SCHEMES.md).
+
+## Token families
+
+| Family | Examples |
+| --- | --- |
+| Typography | `--v-font-family`, `--v-font-size`, `--v-line-height`, `--v-font-weight`, `--v-h1-color` … `--v-h6-color` |
+| Spacing | `--v-spacing`, `--v-typography-spacing-vertical`, `--v-block-spacing-vertical` / `-horizontal`, `--v-grid-column-gap` / `-row-gap` |
+| Borders & outline | `--v-border-radius`, `--v-border-width`, `--v-outline-width`, `--v-box-shadow` |
+| Colors | `--v-background-color`, `--v-color`, `--v-muted-color`, `--v-muted-border-color`, `--v-primary*`, `--v-secondary*`, `--v-contrast*` (each with `-background`, `-border`, `-hover`, `-focus`, `-inverse`, `-underline`) |
+| Forms | `--v-form-element-*` (background, border, color, placeholder, active, focus, valid / invalid, disabled opacity), `--v-switch-*`, `--v-range-*`, `--v-icon-*` |
+| Components | `--v-card-*`, `--v-accordion-*`, `--v-dropdown-*`, `--v-modal-overlay-*`, `--v-popover-*`, `--v-progress-*`, `--v-tooltip-*`, `--v-nav-*`, `--v-table-*`, `--v-code-*` |
+| Motion | `--v-transition`, `--v-transition-duration-fast` / `-standard` / `-slow`, `--v-transition-ease-out` / `-in` / `-in-out` |
+
+The complete list with defaults is the *CSS properties* table of the [API Reference](./README.md#md-api-reference).
+
+## Element-level tokens
+
+Elements redefine tokens locally rather than setting properties: a button sets `--v-background-color` and `--v-color`, headings set `--v-font-size`, `--v-line-height` and `--v-typography-spacing-top`. Override those on the element to restyle one kind of element without touching the rule:
+
+```css
+h1 { --v-font-size: 2.5rem; }
+button.cta { --v-background-color: var(--v-contrast-background); }
+```
+
+## Writing tokens from Quark
+
+`--name:` declarations write custom properties on matched elements, so State can drive theming (`:scope { --v-primary: $brand; }`) — see the quark docs *CSS variables*.

package/support/docs/DROPDOWN.md

@@ -0,0 +1,22 @@
+# Dropdown
+
+A `details.dropdown` opens a menu below its `summary`: select-styled by default, button-styled with `role="button"`, and inline inside a [nav](./NAV.md).
+
+## Usage
+
+<include-content data-demo="dropdown"></include-content>
+
+```html
+<details class="dropdown">
+  <summary>Choose…</summary>
+  <ul>
+    <li><a href="#">Option</a></li>
+    <li><label><input type="checkbox" /> Toggle</label></li>
+  </ul>
+</details>
+```
+
+- The default `summary` looks like a `select` (chevron, `--v-form-element-*` tokens, `aria-invalid` colors); `summary[role="button"]` looks like a [button](./BUTTON.md).
+- The menu is the `ul` right after the summary: absolutely positioned, `--v-dropdown-*` tokens, links and labels fill each row; `dir="rtl"` on the list right-aligns it.
+- While open, an invisible full-page `::before` on the summary closes the menu on an outside click — no JS.
+- Inside a `nav`, the dropdown sits inline with the links; inside a `label`, it aligns like a control.

package/support/docs/EMBEDDED.md

@@ -0,0 +1,18 @@
+# Embedded content
+
+Images, media and figures are responsive by default; `figcaption` is muted.
+
+## Usage
+
+<include-content data-demo="embedded"></include-content>
+
+```html
+<figure>
+  <img src="…" alt="…" />
+  <figcaption>Caption</figcaption>
+</figure>
+```
+
+- `img` (and `[role="img"]` / `.tag-img`): `max-width: 100%`, `height: auto`, no border.
+- `audio`, `canvas`, `iframe`, `img`, `svg`, `video`: middle-aligned; `iframe` has no border; `svg` without `fill` inherits `currentColor`.
+- `figure` has no margin; `figcaption` (`[role="caption"]` inside a figure) is padded and `--v-muted-color`.

package/support/docs/FORMS.md

@@ -0,0 +1,44 @@
+# Forms
+
+Form controls are full-width, labels stack above them, and validity, helper text and disabled states come from attributes alone.
+
+## Overview
+
+<include-content data-demo="forms"></include-content>
+
+```html
+<form>
+  <label>
+    Email
+    <input type="email" name="email" />
+    <small>We never share it.</small>
+  </label>
+  <fieldset>
+    <legend>Plan</legend>
+    <label><input type="radio" name="plan" checked /> Free</label>
+  </fieldset>
+  <button type="submit">Sign up</button>
+</form>
+```
+
+## Layout
+
+- `input` (except checkbox / radio), `select`, `textarea` and `button[type="submit"]` are `width: 100%` with `--v-spacing` below.
+- A `label` is a block with the control inside it or before it; `fieldset` / `legend` group controls without borders.
+- Put controls in a [`.grid`](./GRID.md) for columns, or in a [group](./GROUP.md) for an input + button pair.
+
+## Helper text
+
+A `small` right after an `input`, `select`, `textarea`, `fieldset` or `.grid` becomes a muted note; it turns green / red after a control with `aria-invalid="false"` / `"true"`.
+
+## Validation
+
+`aria-invalid="true"` / `"false"` colors the border and focus ring and draws an icon inside text-like inputs (`--v-icon-invalid` / `--v-icon-valid`). No class is needed and the state stays in the document, where CSS, Quark and assistive technology all read it.
+
+## Disabled
+
+`[disabled]` controls (and every control inside a `fieldset[disabled]`) drop to `--v-form-element-disabled-opacity` and ignore the pointer; a `label[aria-disabled="true"]` mutes its text too.
+
+## Controls
+
+[Input](./INPUT.md) · [Textarea](./TEXTAREA.md) · [Select](./SELECT.md) · [Checkboxes, radios & switches](./CHECKBOXES.md) · [Range](./RANGE.md)

package/support/docs/GRID.md

@@ -0,0 +1,19 @@
+# Grid
+
+`.grid` lays its children out in equal auto-fit columns from 768px up, and stacks them below.
+
+## Usage
+
+<include-content data-demo="grid"></include-content>
+
+```html
+<div class="grid">
+  <div>1</div>
+  <div>2</div>
+  <div>3</div>
+</div>
+```
+
+Gaps are `--v-grid-column-gap` / `--v-grid-row-gap` (both `--v-spacing`). Children get `min-width: 0` so overflowing content scrolls instead of stretching the column.
+
+Inside a form, `.grid` also carries the helper-text rule: a `small` right after a `.grid` of inputs is a muted note (see [Forms](./FORMS.md)).