feat(css): generate opt-in @property registrations with validated initial values

[Hebilicious]

Goal

Allow CSS Forge to emit native CSS @property registrations for selected generated custom properties, adding browser-understood syntax, inheritance, defaults, and interpolation without introducing a styling runtime.

Registration must be opt-in. Existing configurations and generated CSS should remain unchanged when the feature is disabled.

Initial API direction

Start with explicit, serializable metadata for a token; the final placement in the schema is a design choice:

{
  syntax: "<color>",
  inherits: true,
  initialValue: "transparent",
}

Generate a stylesheet-level registration such as:

@property --semantic-action-background {
  syntax: "<color>";
  inherits: true;
  initial-value: transparent;
}

:root {
  --semantic-action-background: var(--palette-blue-600);
}

The registration's initial value is distinct from the token's normal declaration value. Keeping the latter as var(...) preserves native theme composition.

Mixed-type primitive bags need per-token metadata; do not assume that every property in one primitive variant shares a syntax or initial value.

Platform constraints

The CSS Properties and Values API specification requires syntax and inherits. For non-universal syntax, initial-value must be present, match that syntax, and be computationally independent. var(...) and font-dependent values such as 3em cannot be blindly copied into a typed registration's initial value. syntax: "*" has distinct initial-value rules.

Registration also changes default/fallback behavior, so this is not merely type annotation. Document and test behavior with unset or invalid token values and var(--token, fallback).

Acceptance criteria

• Registration is explicit and disabled by default; existing snapshots/output remain unchanged without it.
• Define and document the supported metadata placement and initial syntax set, including explicit color, length, and number cases.
• Emit registrations at stylesheet level, not inside the generated :root declaration block.
• Deduplicate identical registrations by final generated custom-property name and diagnose conflicting metadata across themes/groups.
• Validate syntax and initial values with actionable token-path diagnostics; follow the special universal-syntax rules.
• Do not silently replace an invalid initial value with an invented default or flatten a token alias into a constant.
• Keep ordinary alias values and scoped/theme declarations intact.
• Browser tests cover valid/invalid values, inheritance, registered defaults versus var() fallbacks, and interpolation for at least one registered color or number.
• Describe progressive behavior when a consumer browser ignores @property; ordinary declarations still exist, but registration-specific behavior is not guaranteed.
• Coordinate metadata with Add Style Dictionary token output #20, primitive references in feat(primitives): support primitive-to-primitive references with forward-reference and cycle diagnostics #31, and naming validation in bug(validation): reject or correctly escape token names that produce invalid CSS identifiers #29.

Deferred

Automatic inference for every token, arbitrary primitive-string type inference, a new component-style API, and JavaScript runtime registration. Safe inference for selected categories can be a later extension.