Syntax Rules

Syntax rules govern the structural conventions of IDL source files beyond the BNF grammar. Files use the .idl extension. Each file declares exactly one module. Module names MUST follow the format: section-identifier.module-name, where the section identifier matches the IDL chapter prefix (e.g., 04.spacing, 05.button). Module names MUST match the relative file path from the project root.

File and Module Conventions

• One module per file — a file that contains more than one module declaration is a Parse error.
• Module names are lowercase, hyphen-separated, and MUST NOT contain spaces or special characters beyond hyphens.
• Module names MUST match the file path: tokens/color/semantic.idl declares the module tokens.color.semantic.
• Module imports use relative paths. Absolute paths are not permitted.
• Circular imports are detected at Parse time and produce a hard error.

Declaration Order

Within a module, declarations MUST appear in the following order: version declaration, imports, token declarations, component declarations, constraint declarations. Declarations out of order are a Parse error in strict mode and a Parse warning in lenient mode. New projects MUST use strict mode; lenient mode is a migration accommodation only.

Comments and Annotations

IDL supports two comment forms: single-line comments beginning with // and block comments delimited by /* and */. Comments are stripped during Parse and do not appear in the AST. Annotations — structured metadata attached to declarations — are distinct from comments and do appear in the AST. Annotations use the @ prefix and are defined in the annotation schema.