@ascribed/elements 0.2.1-next.15 → 0.2.1-next.16

package/CONTRACT.md

@@ -31,7 +31,7 @@ A change to this contract changes the site emitter (`crates/ascribe-emit`), the
 
 **Plain text of inline content.** Where an attribute holds a title or label written as inline markdown, its value is the inline content's text: phrases substituted (they already are, in the resolved page), code spans as their text, emphasis and links as their text, images as their alt text, raw inline HTML dropped, and line breaks as single spaces. So ``.Try the *new* `quill` CLI`` becomes `Try the new quill CLI`.
 
-**Labels** come from the content model: note types' `label` (docs/content/contracts/content-model.md §11), dimensions' and dimension values' `labels` (§7), and lifecycle states' `label` (§9). A value without a declared label is shown as itself.
+**Labels** come from the content model: note types' `label` (docs/content/contracts/content-model.md §10), dimensions' and dimension values' `labels` (§6), and lifecycle states' `label` (§8). A value without a declared label is shown as itself.
 
 ## 1. `<ascribe-note>`
 
@@ -201,7 +201,7 @@ The element library may style `details` and `summary`, and implements no element
 
 ## 6. Project widgets
 
-A project widget (SPEC §6) becomes a custom element whose tag is the widget's name (SPEC §9.4). Widget names are valid custom-element names: they contain a hyphen, and docs/content/contracts/content-model.md §15 rejects names starting with `ascribe-` and HTML's reserved names. The project supplies the element's implementation; the element library doesn't.
+A project widget (SPEC §6) becomes a custom element whose tag is the widget's name (SPEC §9.4). Widget names are valid custom-element names: they contain a hyphen, and docs/content/contracts/content-model.md §14 rejects names starting with `ascribe-` and HTML's reserved names. The project supplies the element's implementation; the element library doesn't.
 
 **Attributes**, in this order:
 
@@ -209,7 +209,7 @@ A project widget (SPEC §6) becomes a custom element whose tag is the widget's n
 2. `primary`: an identifier primary, if the widget takes one and it's given. A text primary is content instead (below).
 3. Each attribute in the widget's declaration, in declared order, with the value given or, if absent, its declared default. A value set's members are joined by single spaces; booleans are `true` or `false`; other values are their text. An attribute with neither a value nor a default is left out. A declaration can't use `heading`, `primary`, or HTML's global or event-handler attribute names (SPEC §7.2; content-model.md, `model-attribute-reserved`), so these never clash.
 
-**Children and placement**, by the widget's form and binding (docs/content/contracts/content-model.md §15):
+**Children and placement**, by the widget's form and binding (docs/content/contracts/content-model.md §14):
 
 | Widget | Element |
 |---|---|
@@ -225,7 +225,7 @@ A wrapping widget follows §0's layout for elements that wrap markdown; an empty
 
 ## 7. Glossary terms
 
-There's no element for glossary terms. In the site output, an occurrence the glossary links (docs/content/contracts/content-model.md §13) is an ordinary markdown link to the term's `link` target, as a route, with the term's definition as the link title, followed directly by an attribute marker (docs/content/contracts/site-render.md §2.3) that gives the `<a>` a `data-ascribe-term` attribute holding the term's id:
+There's no element for glossary terms. In the site output, an occurrence the glossary links (docs/content/contracts/content-model.md §12) is an ordinary markdown link to the term's `link` target, as a route, with the term's definition as the link title, followed directly by an attribute marker (docs/content/contracts/site-render.md §2.3) that gives the `<a>` a `data-ascribe-term` attribute holding the term's id:
 
 ```markdown
 [API key](/docs/reference/glossary/#api-key "A secret token that authenticates the Quill agent.")<ascribe-attributes data-ascribe-term="api-key"></ascribe-attributes>
@@ -241,7 +241,7 @@ Terms without a `link` stay plain text (content-model.md Q7).
 
 ## 8. `<ascribe-for-agents>`
 
-With `[consumer] agents = true` (docs/content/contracts/content-model.md §16), each page of the site output opens with a pointer for AI agents: where the index of every page, `llms.txt`, is, and where this page's Markdown version is (SPEC §9.4). It has no attributes, and wraps one paragraph of markdown with two links, both root-relative like every link in the site output:
+With `[consumer] agents = true` (docs/content/contracts/content-model.md §15), each page of the site output opens with a pointer for AI agents: where the index of every page, `llms.txt`, is, and where this page's Markdown version is (SPEC §9.4). It has no attributes, and wraps one paragraph of markdown with two links, both root-relative like every link in the site output:
 
 ```markdown
 <ascribe-for-agents>

package/README.md

@@ -34,95 +34,12 @@ choose("pm", "pnpm");
 
 ## Theming
 
-Set any of these custom properties on `:root`, or on any ancestor of the
-elements. Defaults are in `css/style.css`.
-
-The names are part of the [contract](CONTRACT.md) and don't change. The
-default values are Ascribe's design tokens, shared with review and the HTML
-report, and a release may change them; the changelog says so under **Behavior
-change**, with the previous values. A site that needs a fixed look sets the
-properties itself.
-
-| Group | Properties |
-|---|---|
-| Type | `--ascribe-font-family`, `--ascribe-font-size-small`, `--ascribe-font-weight-strong` |
-| Spacing and borders | `--ascribe-space`, `--ascribe-space-small`, `--ascribe-border-width`, `--ascribe-border-color`, `--ascribe-radius` |
-| Surfaces and text | `--ascribe-text-color`, `--ascribe-muted-color`, `--ascribe-surface-color` |
-| Notes | `--ascribe-<type>-color` and `--ascribe-<type>-background`, for `note`, `tip`, `important`, `warning`, and `caution` |
-| Steps | `--ascribe-steps-color`, `--ascribe-steps-marker-size`, `--ascribe-steps-marker-text-color` |
-| Tabs | `--ascribe-tab-color`, `--ascribe-tab-active-color`, `--ascribe-tab-focus-color`, `--ascribe-tab-hover-background` |
-| Availability | `--ascribe-state-color` and `--ascribe-state-background`, and `--ascribe-state-<state>-color` and `--ascribe-state-<state>-background` for `ga`, `preview`, `beta`, `deprecated`, and `removed` |
-
-### Light and dark
-
-The default colors are light or dark as the page is. They're dark where the
-page's `color-scheme` is `dark`, or `light dark` while the reader's system is in
-dark mode, and light otherwise, including on a page that declares no
-`color-scheme`. So a site with a dark mode gets dark elements by declaring it:
-
-```css
-:root {
-  color-scheme: light dark;
-}
-```
-
-A page whose colors don't follow its `color-scheme` sets
-`data-ascribe-scheme="light"` or `"dark"` on its root element, as the review
-marks read it. The defaults use CSS `light-dark()`; a browser without it shows
-the light colors. A property a site sets replaces both colors, so set it for
-each scheme when you set one:
-
-```css
-:root {
-  --ascribe-note-color: light-dark(#0550ae, #79c0ff);
-}
-```
-
-### Glossary terms
-
-A glossary link carries `data-ascribe-term` with the term's id, and its title
-is the definition. The library underlines it with dots; restyle it by
-selecting on the attribute, such as `a[data-ascribe-term]`.
-
-### The pointer for agents
-
-With `[consumer] agents = true`, each page opens with `<ascribe-for-agents>`,
-which tells an AI agent where `llms.txt` and the page's Markdown are. The
-library hides it from sight, not from the page's text; to show it, restyle
-`ascribe-for-agents`.
-
-### A project's own note types and lifecycle states
-
-Notes and availability targets carry their type or states as attributes, so a
-project styles its own by selecting on them. The elements take their colors
-from `--_color` and `--_background`:
-
-```css
-ascribe-note[type="security"] {
-  --_color: #b62324;
-  --_background: #fff0f0;
-}
-
-ascribe-availability-target[states="sunset"],
-ascribe-availability-target[states$=" sunset"] {
-  --_color: #6e7781;
-  --_background: #eaeef2;
-}
-```
-
-`states` lists a target's states in order and the last one styles the badge, so match it as a whole token, as above: `[states="x"], [states$=" x"]`. A bare `[states$="x"]` would also match a state named `pre-x`. Unknown types and states get the default (`note`, or the neutral state) style.
-
-### Generated text
-
-Headings and labels come from the elements' attributes through CSS generated
-content, and the availability lead-in is `ascribe-availability::before`
-(`"Available: "`). A site can restyle or translate them:
-
-```css
-ascribe-availability::before {
-  content: "Disponible : ";
-}
-```
+The [element library reference](https://ascribed-dev.com/go/elements/) lists
+the CSS custom properties that theme the elements, says what each one sets and
+how they follow the page's light or dark scheme, and shows how to style your
+own note types and lifecycle states. The properties' names are part of the
+[contract](CONTRACT.md) and don't change; their defaults, in `css/style.css`,
+may change in a release, as the changelog says.
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascribed/elements",
-  "version": "0.2.1-next.15",
+  "version": "0.2.1-next.16",
   "description": "Ascribe's web component library for the site output.",
   "type": "module",
   "license": "MPL-2.0",
@@ -36,7 +36,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b4d4611f06c75553d379e3ad09a93b809071228f",
+  "gitHead": "0077fa1e1fcd4ef67f9c6d48575c3f06f98adce8",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",