A web-native type system

Types are declared, and default to string

Every HTML attribute is already a string, so an undeclared prop is a string, no ceremony, and string-to-string round-trips for free. A type is opt-in: you declare one only to get something other than a string. This is the same line the platform already draws, an unregistered CSS custom property is the universal * syntax (any token stream) until @property gives it syntax: "<length>".

<defs>
  <prop name="label">Any string (the default when no type is given).</prop>
  <prop name="count"   type="number">A parsed number.</prop>
  <prop name="loading" type="boolean">Presence means true.</prop>
  <prop name="variant" type="outline | solid | ghost" default="outline">A keyword set.</prop>
  <prop name="gap"     type="<length>">A CSS length: 8px, 1rem, 2ch.</prop>
  <prop name="accent"  type="<color>">A CSS color.</prop>
  <prop name="tags"    type="<string>#">A comma-separated list of strings.</prop>
  <prop name="rows"    type="array" required>Structured data, bound by reference (shape below).</prop>
</defs>

Notation, borrowed from CSS

Type expressions reuse the CSS value-definition syntax rather than a new grammar: the | bar is “exactly one of”, <type> names a data type, + is a space-separated list, # a comma-separated list, and ? marks optional. default follows XML Schema's attribute defaulting; required is the HTML boolean attribute of the same name; a prop's description is its element text, as with <option>.

Two families: serializable and reference

A type either has a lossless string form or it does not, and that single fact decides everything about how it behaves.

Serialization: the string plus the type is the value

Because a serializable value has a string form and its type is declared, lowering can record every serializable prop on the native root as data-<name>. The invocation is then fully reconstructable from the DOM, replacement loses no information, and reading a value back is unambiguous: take the attribute string, parse it per the contract's type.

<x-badge variant="solid" count="3">New</x-badge>

<!-- lowers to: each serializable prop recorded as data-*, so the invocation
     is fully reconstructable from the DOM -->
<span data-component="x-badge" data-variant="solid" data-count="3">New</span>

<!-- data-count="3" + the contract (count is a number) reads back as the number 3.
     the string plus the declared type is the value; nothing is lost. -->

Structured data: shape, authoring, wire

CSS has no object or array type, so structured data steps outside CSS to the web's other data standards. Three concerns stay separate, and each has its own well-defined form:

• Shape is declared in HTML, recursively, with nested <prop> (the contract's own vocabulary, no data island), or by referencing a JSON Schema for shared or external shapes.
• Authoring a value uses an object expression ({ id: 1, name: 'Ada' }), lighter than JSON and pure, not a JS object. In practice most structured values are a reference to <state> or <data> rather than an inline literal.
• Wire form is JSON: the mandatory-double-quote serialization is a machine concern, used when a value must cross a boundary (SSR payload, network, interop), never the authoring syntax.

<!-- shape described in HTML, recursively, with nested <prop> -->
<prop name="rows" type="array">
  <prop type="object">
    <prop name="id"   type="number">
    <prop name="name" type="string">
  </prop>
</prop>

<!-- or reference a JSON Schema for shared / external shapes -->
<prop name="rows" type="array" schema="/schemas/rows.json">

Keywords and the quoting rule

An enum is just string constrained to a set of keywords. It is written with bare keywords (outline | solid | ghost, never "outline" | "solid") because in attribute position an unquoted identifier and a quoted string are the same token: <foo bar=quiz> equals <foo bar="quiz">, and [bar=quiz] equals [bar="quiz"]. So the string value "solid" satisfies outline | solid | ghost.

That equivalence flips in expression position, which is not attribute position. In the assignment-free expression language a bare word is an identifier (a binding) and quotes make a string literal, exactly as in a CSS selector value versus a scripting expression:

<!-- ATTRIBUTE position: bare and quoted are the same token (as in HTML/CSS) -->
<x-button variant=solid>   is identical to   <x-button variant="solid">
<!-- and the enum type is written bare: outline | solid | ghost -->

<!-- EXPRESSION position: bare is a reference, quotes make a string literal -->
<button class:active="variant = 'solid'">   <!-- 'solid' is the string -->
<button class:active="variant = solid">      <!-- WRONG: solid read as a binding name -->

Web value types

The dimension family is only part of a larger set of value domains the web already defines, which a markup type system should name rather than collapse to string:

Beyond values: layered identity, content, and trust

These are Level 3 directions that a value-only type system does not reach, and where "web-native" means structural, not just scalar.

References

1. CSS Values and Units Level 4, value definition syntax and dimension types (<length>, <color>, |, +, #, ?).
2. IETF, JSON Schema (the standard shape language for structured data).
3. CSS Properties and Values API, @property (registered typed values; universal * syntax when unregistered).
4. WHATWG HTML, data-* attributes and boolean attributes.
5. W3C XML Schema Part 1, attribute defaulting (the default attribute).
6. W3C, Trusted Types (the trusted-content type model HTML Next mirrors for raw markup via $html).
7. Zod and Valibot (userland schema validation, the parse/validate/infer pattern this makes DOM-native).
8. Lit @property converters: typed attribute-to-property reflection with a declared converter, prior art for the three-layer model where an author-facing attribute, a reflected DOM property, and the value it parses to are named separately.