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="replyTo" type="email" required>A syntactically valid email address.</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>

The type-expression syntax

A type attribute is a grammar for one value. HTML Next adopts CSS's readable operators, but defines its own profile: it adds HTML-derived and structured types, does not import CSS property references or implicit CSS-wide keywords, and uses required to control whether the prop itself may be absent.

<prop name="size" type="small | medium | large">
<prop name="inset" type="<length>{1,4}">
<prop name="stops" type="<color>#">
<prop name="placement" type="[ block-start | block-end ] && [ inline-start | inline-end ]?">

Component forms

Combinators

Multipliers

Precedence

From strongest to weakest: multipliers, juxtaposition, &&, ||, then |. Thus small | <length>+ means either the keyword small or a non-empty list of lengths. Brackets override that order. A parser must consume the entire value; an unmatched token makes the value invalid.

type-expression = alternative
alternative     = options [ "|" options ]*
options         = any-order [ "||" any-order ]*
any-order       = sequence [ "&&" sequence ]*
sequence        = term+
term            = atom multiplier? | group [ multiplier | "!" ]
atom            = built-in | keyword | css-type
group           = "[" type-expression "]"
css-type        = "<" css-type-name ">"
multiplier      = "?" | "*" | "+" | "#" | range | "#" range
range           = "{" integer [ "," integer? ] "}"

HTML Next profile

• Level 1 includes the bare scalar types, literal keyword alternatives, and |.
• Level 2 adds angle-bracketed CSS types, grouping, the remaining combinators, and all multipliers.
• ? makes a component inside a composite value optional. It does not make the prop optional; absence is controlled by the required attribute.
• CSS property references such as <'border-width'> are excluded because a component prop is not a CSS property. CSS-wide keywords such as inherit are accepted only when written as explicit alternatives.
• A CSS type name is available only when this specification lists it. HTML Next uses that type's token grammar and value semantics, not the set of properties on which CSS happens to use it.
• A literal default must satisfy the declared type. A literal prop value that fails is a conformance error; a bound value that fails produces the validity result defined by the Validation module.

The operators and their precedence come from CSS Value Definition Syntax.¹⁶ The profile above is HTML Next's definition; referring to CSS does not add unlisted CSS grammar or types.

CSS value types included by this level

Angle brackets select one of the CSS token grammars listed here. They do not mean “any CSS type,” and they do not turn the value into a CSS declaration. Parsing uses CSS tokenization, must consume the complete attribute value, and preserves the original serialization for reflection.

HTML-native types and constraints

CSS does not define every useful web value. HTML already specifies parsers and intrinsic validity rules for email addresses, absolute URLs, numbers, and date/time strings. HTML Next exposes those as bare types and applies the same rules to component props and data values.¹⁵¹⁶¹⁷

<defs>
  <prop name="replyTo" type="email" required>
  <prop name="website" type="url">
  <prop name="starts" type="datetime-local" min="2026-01-01T00:00">
  <prop name="quantity" type="number" min="1" max="100" step="1">
  <prop name="handle" type="string" minlength="3" maxlength="32" pattern="[a-z0-9-]+">
</defs>

Constraint attributes narrow a type; they never replace it. Their values are themselves parsed according to the declared type, and incompatible constraints are conformance errors. The Validation module defines when validity is recomputed, how failures are reported, and how native form controls interoperate.

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. W3C CSS Values and Units Level 4, value definition syntax and component value types, including numeric and dimension types such as <length>, <percentage>, <angle>, and <time>.
2. W3C CSS Color Module Level 4, the <color> type.
3. W3C CSS Properties and Values API Level 1, registered custom properties and their type syntax strings.
4. W3C CSS Typed OM Level 1, typed representations of CSS values.
5. MDN, CSS data types (an index spanning quantities, colors, images, positions, and other value domains).
6. MDN, CSS value definition syntax (keywords, data types, combinators, and multipliers).
7. MDN, the @property syntax descriptor (typed custom properties, lists, keywords, and the universal * syntax).
8. MDN, CSS Typed Object Model API (CSS values exposed as typed objects rather than undifferentiated strings).
9. IETF, JSON Schema (the standard shape language for structured data).
10. WHATWG HTML, data-* attributes and boolean attributes.
11. W3C XML Schema Part 1, attribute defaulting (the default attribute).
12. W3C, Trusted Types (the trusted-content type model HTML Next mirrors for raw markup via $html).
13. Zod and Valibot (userland schema validation, the parse/validate/infer pattern this makes DOM-native).
14. 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.
15. WHATWG HTML, states of the input type attribute, including the email, URL, numeric, and date/time value syntaxes.
16. WHATWG HTML, the Constraint Validation API and its required, type, pattern, length, range, and step constraints.
17. MDN, Using HTML form validation and the Constraint Validation API (native type and constraint behavior with examples).
18. MDN, Date and time formats used in HTML.