@overcrow/mcp 0.0.0-stage → 0.1.0

package/dist/content/docs/en/style-properties.md

@@ -0,0 +1,270 @@
+# Style properties and tokens
+
+Every property that `style.ocss` accepts in a PlayerVox OverCrow widget,
+with its values and its initial value, then the design tokens and the
+icons. [The style](style.md) explains selectors, layout, tokens and
+animations; this page is the list.
+
+<!-- source: templates/chart/style.ocss -->
+```css
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+```
+
+Anything that is not on this page is refused when the widget is checked:
+a property, a keyword or a unit outside the lists below is an error, with
+the closest name as a suggestion.
+
+## How to read a property
+
+- **Value** uses the notations of [values](#values): `<px>`, `<percent>`,
+  `<color>`… A `|` separates alternatives, `?` marks an optional part.
+- **Initial** is the value of an element that no rule styles.
+- **Inherited** properties take the value of the parent when no rule sets
+  them: set them on a container.
+- **Animatable** properties can appear in a `transition` and in
+  `@keyframes`.
+
+## Properties
+
+<!-- generated:style-properties -->
+### Layout
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `display` | `flex` \| `grid` \| `none` | `flex` | no | no |
+| `position` | `relative` \| `absolute` | `relative` | no | no |
+| `top` | `<px>` \| `<percent>` \| `auto`, negative allowed | `auto` | no | no |
+| `right` | `<px>` \| `<percent>` \| `auto`, negative allowed | `auto` | no | no |
+| `bottom` | `<px>` \| `<percent>` \| `auto`, negative allowed | `auto` | no | no |
+| `left` | `<px>` \| `<percent>` \| `auto`, negative allowed | `auto` | no | no |
+| `flex-direction` | `row` \| `column` \| `row-reverse` \| `column-reverse` | `row` | no | no |
+| `flex-wrap` | `nowrap` \| `wrap` | `nowrap` | no | no |
+| `flex-grow` | number 0 to 1000 | `0` | no | no |
+| `flex-shrink` | number 0 to 1000 | `1` | no | no |
+| `flex-basis` | `<px>` \| `<percent>` \| `auto` | `auto` | no | no |
+| `justify-content` | `start` \| `end` \| `center` \| `stretch` \| `space-between` \| `space-around` \| `space-evenly` | `start` | no | no |
+| `align-items` | `start` \| `end` \| `center` \| `baseline` \| `stretch` | `stretch` | no | no |
+| `align-self` | `auto` \| `start` \| `end` \| `center` \| `baseline` \| `stretch` | `auto` | no | no |
+| `align-content` | `start` \| `end` \| `center` \| `stretch` \| `space-between` \| `space-around` \| `space-evenly` | `stretch` | no | no |
+| `justify-items` | `start` \| `end` \| `center` \| `stretch` | `stretch` | no | no |
+| `justify-self` | `auto` \| `start` \| `end` \| `center` \| `stretch` | `auto` | no | no |
+| `gap` | 1–2 × (`<px>` \| `<percent>`) | `0` | no | no |
+| `row-gap` | `<px>` \| `<percent>` | `0` | no | no |
+| `column-gap` | `<px>` \| `<percent>` | `0` | no | no |
+| `grid-template-columns` | `none` \| list ≤ 24 of `<track>`, or `repeat(<integer>, <track>)` | `none` | no | no |
+| `grid-template-rows` | `none` \| list ≤ 24 of `<track>`, or `repeat(<integer>, <track>)` | `none` | no | no |
+| `grid-auto-flow` | `row` \| `column` | `row` | no | no |
+| `grid-auto-columns` | `<track>`: `<px>` \| `<percent>` \| `<fr>` \| `auto` \| `min-content` \| `max-content` \| `minmax(<track>, <track>)` | `auto` | no | no |
+| `grid-auto-rows` | `<track>`: `<px>` \| `<percent>` \| `<fr>` \| `auto` \| `min-content` \| `max-content` \| `minmax(<track>, <track>)` | `auto` | no | no |
+| `grid-column` | `auto` \| `<integer>` \| `span <integer>` \| `<start> / <end>`, lines 1 to 24 | `auto` | no | no |
+| `grid-row` | `auto` \| `<integer>` \| `span <integer>` \| `<start> / <end>`, lines 1 to 24 | `auto` | no | no |
+
+### Box
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `width` | `<px>` \| `<percent>` \| `auto` | `auto` | no | no |
+| `height` | `<px>` \| `<percent>` \| `auto` | `auto` | no | no |
+| `min-width` | `<px>` \| `<percent>` \| `auto` | `auto` | no | no |
+| `min-height` | `<px>` \| `<percent>` \| `auto` | `auto` | no | no |
+| `max-width` | `<px>` \| `<percent>` \| `none` | `none` | no | no |
+| `max-height` | `<px>` \| `<percent>` \| `none` | `none` | no | no |
+| `aspect-ratio` | number 0.01 to 100 | `auto` | no | no |
+| `margin` | 1–4 × (`<px>` \| `<percent>` \| `auto`), negative allowed | `0` | no | no |
+| `margin-top` | `<px>` \| `<percent>` \| `auto`, negative allowed | `0` | no | no |
+| `margin-right` | `<px>` \| `<percent>` \| `auto`, negative allowed | `0` | no | no |
+| `margin-bottom` | `<px>` \| `<percent>` \| `auto`, negative allowed | `0` | no | no |
+| `margin-left` | `<px>` \| `<percent>` \| `auto`, negative allowed | `0` | no | no |
+| `padding` | 1–4 × (`<px>` \| `<percent>`) | `0` | no | no |
+| `padding-top` | `<px>` \| `<percent>` | `0` | no | no |
+| `padding-right` | `<px>` \| `<percent>` | `0` | no | no |
+| `padding-bottom` | `<px>` \| `<percent>` | `0` | no | no |
+| `padding-left` | `<px>` \| `<percent>` | `0` | no | no |
+| `overflow` | `visible` \| `hidden` | `visible` | no | no |
+
+### Appearance
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `background-color` | `<color>` | `transparent` | no | yes |
+| `background` | `<color>` \| `linear-gradient(<angle>?, <color> <percent>?, …)`, stops ≤ 8 | `transparent` | no | no |
+| `border` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | no | no |
+| `border-top` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | no | no |
+| `border-right` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | no | no |
+| `border-bottom` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | no | no |
+| `border-left` | `<px>` (`solid` \| `none`)? `<color>`? | `0 none` | no | no |
+| `border-width` | 1–4 × (`<px>`) | `0` | no | no |
+| `border-style` | `solid` \| `none` | `none` | no | no |
+| `border-color` | `<color>` | `currentColor` | no | yes |
+| `border-radius` | 1–4 × (`<px>` \| `<percent>`) | `0` | no | no |
+| `box-shadow` | `none` \| `var(--shadow-…)` alone \| list ≤ 2 of `inset`? `<px> <px> <px>? <px>? <color>` | `none` | no | no |
+| `opacity` | number 0 to 1 | `1` | no | yes |
+| `visibility` | `visible` \| `hidden` | `visible` | yes | no |
+| `object-fit` | `contain` \| `cover` \| `fill` \| `none` | `contain` | no | no |
+
+### Text
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `color` | `<color>` | `var(--color-text)` | yes | yes |
+| `font-family` | `ui` \| `mono` \| `display`, or a font token | `ui` | yes | no |
+| `font-size` | `<px>` within 6 px to 96 px, or a size token | `var(--font-size-body)` | yes | no |
+| `font-weight` | `400` \| `500` \| `600` \| `700` \| `normal` \| `bold` | `400` | yes | no |
+| `font-style` | `normal` \| `italic` | `normal` | yes | no |
+| `font-variant-numeric` | `normal` \| `tabular-nums` | `normal` | yes | no |
+| `line-height` | number 0.5 to 4 (× font size) \| `<px>` | `1.3` | yes | no |
+| `letter-spacing` | `<px>`, negative allowed | `0` | yes | no |
+| `text-align` | `start` \| `center` \| `end` | `start` | yes | no |
+| `text-decoration` | `none` \| `underline` \| `line-through` | `none` | no | no |
+| `text-transform` | `none` \| `uppercase` \| `lowercase` \| `capitalize` | `none` | yes | no |
+| `white-space` | `normal` \| `nowrap` \| `pre-wrap` | `normal` | yes | no |
+| `vertical-align` | `baseline` \| `middle` | `baseline` | no | no |
+| `text-overflow` | `clip` \| `ellipsis` \| `marquee` | `clip` | no | no |
+| `line-clamp` | integer 0 to 64 | `0` | no | no |
+| `overflow-wrap` | `normal` \| `anywhere` | `normal` | yes | no |
+
+### Motion
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `transform` | `none` \| up to 4 of `translate(<length>, <length>)` with `<px>` or `<percent>`, `translateX()`, `translateY()`, `scale(<number>{1,2})` 0 to 8, `rotate(<angle>)` | `none` | no | yes |
+| `transform-origin` | 1–2 × (`left` \| `center` \| `right` \| `top` \| `bottom` \| `<percent>` \| `<px>`) | `center` | no | no |
+| `transition` | `none` \| list ≤ 8 of `<animatable-property> <time> <easing>? <time>?` | `none` | no | no |
+| `animation` | `none` \| list ≤ 8 of `<keyframes-name> <time> <easing>? <time>? (<integer> \| infinite)? <direction>? <fill-mode>?`, integer 1 to 10000 | `none` | no | no |
+
+### Interaction
+
+| Property | Value | Initial | Inherited | Animatable |
+| --- | --- | --- | --- | --- |
+| `cursor` | `default` \| `pointer` \| `text` \| `not-allowed` \| `grab` \| `grabbing` | `default` | yes | no |
+| `pointer-events` | `auto` \| `none` | `auto` | no | no |
+<!-- /generated:style-properties -->
+
+## Values
+
+<!-- generated:style-values -->
+| Syntax | Meaning |
+| --- | --- |
+| `<px>` | `12px`; `0` may omit the unit. Decimal numbers, no exponent. |
+| `<percent>` | `50%` of the containing block, as in CSS; at most 1000 either way. |
+| `<fr>` | `1fr`, grid tracks only; from 0 to 1000. |
+| `<time>` | `120ms` or `0.12s`, from 0 to 300000 ms. |
+| `<angle>` | `4deg` or `0.5turn`, at most 3600 degrees either way. |
+| `<color>` | `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb(r g b)`, `rgb(r g b / a)`, `transparent`, `currentColor`, or a colour token. No named colours. |
+| `var(--token)` | Design-system token of the expected type, as a whole value or a component of a composite value. No fallback argument; widgets cannot declare custom properties. |
+| `<easing>` | `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`, `steps(<integer 1..=MAX_EASING_STEPS>)`. |
+| `<direction>` | `normal`, `reverse`, `alternate`. |
+| `<fill-mode>` | `none`, `forwards`, `backwards`, `both`. |
+<!-- /generated:style-values -->
+
+## Design tokens
+
+A token is written `var(--name)` where a value of its type is expected.
+Colour and shadow tokens have a value per theme; the others are the same in
+both.
+
+<!-- source: templates/list/style.ocss -->
+```css
+.summary {
+  font-size: var(--font-size-caption);
+  color: var(--color-text-secondary);
+}
+```
+
+<!-- generated:tokens -->
+### Colours
+
+| Token | Dark | Light | Meaning |
+| --- | --- | --- | --- |
+| `--color-accent` | `#a3e635` | `#4d7c0f` | Brand accent: primary actions, checked state. |
+| `--color-accent-hover` | `#b5f153` | `#3f6212` | Accent under the pointer. |
+| `--color-accent-soft` | `#a3e6351c` | `#4d7c0f1f` | Accent wash behind selected content. |
+| `--color-on-accent` | `#09090b` | `#ffffff` | Text and icons drawn on the accent and its hover state. |
+| `--color-surface-panel` | `#111114ee` | `#fafafaee` | Widget panel background, drawn by the host behind the content. |
+| `--color-surface-raised` | `#1e1e22e0` | `#f4f4f5eb` | Raised surface inside the panel. |
+| `--color-surface-hover` | `#28282deb` | `#e4e4e7f0` | Surface under the pointer. |
+| `--color-surface-field` | `#0f0f12` | `#ffffff` | Text input background. |
+| `--color-surface-popover` | `#18181c` | `#ffffff` | Popover and drop-down background. |
+| `--color-border` | `#ffffff18` | `#0000001a` | Default border. |
+| `--color-border-strong` | `#ffffff2a` | `#0000002e` | Emphasized border and separator. |
+| `--color-text` | `#f7f7f8` | `#18181b` | Primary text. |
+| `--color-text-secondary` | `#d4d4d8` | `#3f3f46` | Secondary text. |
+| `--color-text-muted` | `#a1a1aa` | `#52525b` | Captions and metadata. |
+| `--color-text-subtle` | `#71717a` | `#71717a` | Placeholders and disabled text. |
+| `--color-danger` | `#fb7185` | `#e11d48` | Errors and destructive actions. |
+| `--color-danger-soft` | `#fb71851a` | `#e11d481a` | Danger wash behind destructive confirmations and errors. |
+| `--color-warning` | `#fbbf24` | `#b45309` | Warnings. |
+| `--color-success` | `#86efac` | `#15803d` | Success and healthy states. |
+
+### Lengths
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--space-1` | `2px` | Spacing step 1. |
+| `--space-2` | `4px` | Spacing step 2. |
+| `--space-3` | `6px` | Spacing step 3 (default item spacing). |
+| `--space-4` | `8px` | Spacing step 4. |
+| `--space-5` | `12px` | Spacing step 5. |
+| `--space-6` | `16px` | Spacing step 6. |
+| `--radius-sm` | `6px` | Small controls and images. |
+| `--radius-md` | `9px` | Buttons. |
+| `--radius-lg` | `10px` | Cards. |
+| `--radius-pill` | `999px` | Pills and round buttons. |
+| `--control-height` | `28px` | Standard control height. |
+| `--icon-button-size` | `22px` | Compact icon button. |
+
+### Font sizes
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--font-size-caption` | `10px` | Eyebrow and captions. |
+| `--font-size-small` | `11px` | Metadata. |
+| `--font-size-button` | `13px` | Button labels. |
+| `--font-size-body` | `14px` | Body text. |
+| `--font-size-title` | `18px` | Section titles. |
+| `--font-size-value` | `22px` | Headline values (clock, FPS). |
+
+### Font families
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--font-ui` | `ui` | Noto Sans UI, the interface face. |
+| `--font-mono` | `mono` | Noto Sans Mono, for values. |
+| `--font-display` | `display` | Space Grotesk, for grades and scores. |
+
+### Durations
+
+| Token | Value | Meaning |
+| --- | --- | --- |
+| `--duration-fast` | `120ms` | State transitions. |
+| `--duration-medium` | `240ms` | Panels and popovers. |
+
+### Shadows
+
+| Token | Dark | Light | Meaning |
+| --- | --- | --- | --- |
+| `--shadow-panel` | `0px 4px 16px 0px #00000066` | `0px 4px 16px 0px #0000001f` | Shadow of the widget panel and of floating host surfaces. |
+<!-- /generated:tokens -->
+
+## Icons
+
+The `icon` element and the rows of the options menu take the name of a
+Lucide icon, in its usual spelling: `circle-check`, `rotate-ccw`,
+`chevron-down`.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+          <icon name="x"/>
+```
+
+<!-- generated:icons -->
+Lucide 1.34.0, 1777 icons.
+<!-- /generated:icons -->
+
+Any other name is refused, and the SDK's `IconName` type lists them all, so
+a wrong name in the logic is a TypeScript error. Within API v1 the set may
+grow but never loses or renames an icon. OverCrow draws the icons itself: a
+widget ships no icon font.

package/dist/content/docs/en/style.md

@@ -0,0 +1,266 @@
+# The style
+
+`style.ocss` styles the view of a PlayerVox OverCrow widget with a small,
+bounded subset of CSS: rules, class and element selectors, flex and grid
+layout, colours, borders, typography, transitions and animations. If you
+know CSS you know the syntax; what differs is that the subset is closed. A
+property, a selector or a value outside it is an error that
+`overcrow-widget check` reports, not something that silently does nothing.
+
+<!-- source: templates/counter/style.ocss -->
+```css
+.counter {
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+
+.value {
+  font-size: var(--font-size-value);
+  font-variant-numeric: tabular-nums;
+}
+
+.actions {
+  gap: var(--space-2);
+}
+
+.step {
+  width: var(--icon-button-size);
+  height: var(--icon-button-size);
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+}
+
+.step:hover {
+  background: var(--color-surface-hover);
+}
+```
+
+The file is optional. Without it, a widget takes the defaults: a `box` lays
+its children out in a row, text has the theme's colour and size.
+
+## Rules and selectors
+
+A rule is a list of selectors, then declarations between braces. Each
+property appears at most once in a rule; the last `;` is optional.
+Comments are `/* … */`.
+
+<!-- generated:selectors -->
+| Selector | Meaning |
+| --- | --- |
+| `text` | Element type; specificity (0, 1). |
+| `.name` | Class; specificity (1, 0). |
+| `:hover :active :focus :disabled :checked` | State resolved by the host; specificity (1, 0). `:checked` applies to `toggle` and `checkbox`. |
+| `a b` | Descendant combinator. |
+| `a > b` | Child combinator. |
+| `a, b` | Selector list; each selector keeps its own specificity. |
+<!-- /generated:selectors -->
+
+A compound selector is an optional element name followed by classes and
+states: `button.primary:hover`. Compounds are joined by a space
+(descendant) or `>` (child).
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.clear:focus,
+.result:focus,
+.copy:focus,
+.back:focus,
+.refresh:focus {
+  border-color: var(--color-accent);
+}
+```
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.clear:disabled .clear-text {
+  color: var(--color-text-muted);
+}
+```
+
+The states are resolved by OverCrow, not by your logic: `:hover` and
+`:active` follow the pointer, `:focus` the keyboard focus, `:disabled` the
+`disabled` attribute, and `:checked` the state of a `toggle` or
+`checkbox`. A widget is not told about pointer moves: a hover effect costs
+it nothing.
+
+When two rules set the same property, the more specific selector wins:
+classes and states count first, then element names. Between equal
+selectors, the later rule wins. There is no `!important`.
+
+## Layout
+
+Every container is a flex container by default (`display: flex`, in a
+row). `display: grid` makes it a grid, and `display: none` removes the
+element and its children from the layout while keeping them in the view.
+
+<!-- source: templates/list/style.ocss -->
+```css
+.checklist {
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+}
+```
+
+<!-- source: widgets/warframe-market/style.ocss -->
+```css
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-3);
+}
+```
+
+Flex and grid work as in CSS, with the properties of the
+[Layout group](style-properties.md#layout): `flex-direction`, `flex-grow`,
+`gap`, `justify-content`, `align-items`, `grid-template-columns`,
+`grid-column`… An element can also leave the flow with
+`position: absolute`, placed against its parent with `top`, `right`,
+`bottom` and `left`. Two elements in the same grid cell overlap, which is
+how the countdown example puts the time in the middle of its ring:
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+/* The time sits in the middle of the ring: both share one grid cell. */
+.dial {
+  display: grid;
+  grid-template-columns: 72px;
+  grid-template-rows: 72px;
+  justify-content: center;
+  justify-items: center;
+  align-items: center;
+}
+```
+
+A widget cannot draw outside its frame: OverCrow clips it.
+
+## Values
+
+Values are written as in CSS, within bounds: lengths in `px` (`0` may omit
+the unit) and percentages, colours as `#rrggbb`, `#rrggbbaa` or
+`rgb(r g b / a)`, times in `ms` or `s`, angles in `deg` or `turn`, and
+tokens as `var(--name)`. The exact notation of each kind of value is in
+[values](style-properties.md#values).
+
+Lengths are logical pixels: OverCrow multiplies them by the user's content
+scale (50 % to 175 %) and by the screen's density, so `12px` is the same
+physical size on every screen. Shorthands expand as in CSS: one to four
+values for sides and corners, one or two for gaps.
+
+## Design tokens
+
+A token is a value of OverCrow's design system, written `var(--name)`.
+Colour tokens change with the user's theme, light or dark: a widget styled
+with tokens follows the theme without any code. Prefer them to literal
+colours.
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+.start {
+  width: var(--control-height);
+  height: var(--control-height);
+  justify-content: center;
+  align-items: center;
+  border-radius: var(--radius-md);
+  background: var(--color-surface-raised);
+  transition: background-color var(--duration-fast) ease-out;
+}
+```
+
+A token stands for a whole value or for one part of a composite value
+(`padding: var(--space-2) var(--space-4)`), and must have the type the
+property expects: a colour token for a colour, a length token for a
+length. There is no fallback argument, and a widget cannot declare its own
+custom properties. All tokens are listed in
+[design tokens](style-properties.md#design-tokens).
+
+OverCrow draws the panel behind the widget (`--color-surface-panel`), its
+frame and its shadow: start from a transparent background.
+
+## Text
+
+Text properties (`color`, `font-family`, `font-size`, `font-weight`,
+`line-height`, `text-align`…) are inherited, as in CSS: set them on a
+container to style what it holds.
+
+- Three font families exist: `ui` (Noto Sans, the default), `mono` (Noto
+  Sans Mono, for values) and `display` (Space Grotesk, for grades and
+  scores). OverCrow bundles them; system fonts are never used, so a widget
+  looks the same on every machine.
+- `font-variant-numeric: tabular-nums` gives digits one width, so a
+  changing number does not move its neighbours.
+- `text-overflow: ellipsis` cuts an overflowing line with `…`;
+  `text-overflow: marquee` scrolls it back and forth, pausing at each end.
+  `line-clamp` limits a text to a number of lines.
+- An `icon` takes the `color` and the `font-size` of its place, unless
+  `width` and `height` are set. In a line of text, `vertical-align: middle`
+  centres an inline `icon` or `image` on the line.
+
+Keep text at 11 px or more (`--font-size-small`): smaller text is hard to
+read over a game.
+
+## Transitions and animations
+
+`transition` animates a change of an animatable property; `animation`
+plays a `@keyframes` block of the same sheet.
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+.ring.done {
+  color: var(--color-success);
+  animation: countdown-pulse 800ms ease-in-out 3 alternate;
+}
+```
+
+<!-- source: docs/content/examples/countdown/style.ocss -->
+```css
+@keyframes countdown-pulse {
+  from { opacity: 1; }
+  to { opacity: 0.4; }
+}
+```
+
+Only properties that change paint, not layout, can be animated:
+`opacity`, `color`, `background-color`, `border-color` and `transform`.
+A `@keyframes` block holds only those. OverCrow runs the animation itself:
+no timer and no code of the widget run while it plays, and nothing is
+repainted when nothing changes. A widget that is hidden does not animate.
+
+`@keyframes` is the only at-rule. Its name is an identifier that is not an
+animation keyword, unique in the sheet.
+
+## What is refused
+
+Any of these rejects the whole sheet:
+
+- `!important`, `@media`, `@import`, `@font-face` and every other at-rule;
+- `url()`, `calc()` and the other CSS functions; strings and escapes;
+- custom property declarations (`--name: …`);
+- ID, attribute and universal (`*`) selectors, pseudo-elements, functional
+  pseudo-classes (`:not()`, `:nth-child()`), sibling combinators;
+- named colours (`red`), exponents, units other than `px`, `%`, `fr`,
+  `ms`, `s`, `deg` and `turn`;
+- characters outside ASCII, except in comments.
+
+There is no media query because there is nothing to query: the widget's
+size is the user's, and the logic reads it from `host.viewport` when the
+view must change with it.
+
+## When the style is wrong
+
+| Code | Problem |
+| --- | --- |
+| `style.syntax`, `style.encoding`, `style.size` | The file is not a well-formed sheet. |
+| `style.unsupported` | A construct of CSS outside the subset (see above). |
+| `style.unknown_element`, `style.unknown_pseudo_class`, `style.invalid_selector` | A selector that names no element or state, or is not in the subset. |
+| `style.unknown_property`, `style.duplicate_property` | A property outside the subset, or set twice in one rule. |
+| `style.invalid_value`, `style.unknown_token` | A value the property does not accept, or a token that does not exist or has another type. |
+| `style.not_animatable` | A transition or a keyframe on a property that cannot be animated. |
+| `style.unknown_keyframes`, `style.duplicate_keyframes`, `style.invalid_keyframes` | An `animation` that names no block, a name used twice, or an invalid block. |
+| `style.too_many_rules`, `style.too_many_selectors`, `style.too_many_compounds`, `style.too_many_simple_selectors`, `style.too_many_declarations`, `style.too_many_keyframes`, `style.too_many_stops` | A [limit](limits.md) of the style is exceeded. |
+
+Unknown names come with the closest name of the schema as a suggestion.
+Every property, its values and its initial value are in
+[style properties and tokens](style-properties.md).