Text and material

Two families, and no font name

Text is set in one of two bundled typefaces — family="sans" or family="serif" — and both cover Latin and simplified Chinese. There is no font name to pass, and that is a decision rather than an omission: a family with no bundled face would be resolved against whatever fonts the rendering machine happens to have, which is exactly the dependency the render contract exists to remove.

The consequence is a rule with no way around it. A character no bundled face can draw is a check failure, not a fallback (glyph-coverage). Naming another font cannot fix it, because there is no parameter for a font name. What fixes it is rewriting the copy, or setting that text as artwork and placing it with <vf-image>.

Two weights exist, 400 and 700, for the same reason: the renderer bundles exactly two faces, and any other value would be a weight the browser synthesized — which renders differently across Chromium builds.

italic="true" sets Latin in a bundled italic face. There is no italic Chinese face to bundle, so a Chinese run asked to slant would be slanted by the browser rather than drawn, and the synthesized-style check warns about that by name. Emphasise Chinese with a different weight or family instead.

Roles before sizes

role — title, subtitle, body, caption — supplies the type scale: size, weight and line height together. Choose the role first and override only where the design genuinely departs from it. A set whose every text Block carries an explicit size has flattened its own scale.

Vertical setting

For a column of Chinese or Japanese reading top to bottom, set vertical="true" on <vf-text>. Never rotate: a rotation turns the glyphs on their side, and it cannot make successive columns run right to left, which is half of what vertical setting is. With vertical, the glyphs stay upright, punctuation takes its vertical forms, and a Latin word inside the column lies on its side — which is the convention.

Where a line breaks

Line breaks are controllable, so there is no need to binary-search max-width:

• 
 forces a break.
•   keeps two words together.
• ­ permits a break inside a long word.
• wrap="balance" evens out the lines of a heading.

Material the engine does not draw

Photography, textures, brush lettering and logos are source material. The engine never draws them. They are made or fetched outside it, added to the Project's assets, and placed with <vf-image src="asset://…">.

The same is true of shapes the vocabulary cannot draw — arrows, curves, icons. Write the SVG, add it as an asset, place it as an image.

Two things about assets are worth knowing before the first one:

• A parameter carrying an http, file, data, blob or javascript URI is refused (forbidden-uri). Material is addressed as asset://path, and an asset:// that this Project does not hold is a check failure (missing-asset) rather than a hole in the picture.
• Artwork that arrived baked onto its own ground — brushed lettering on white, a paper grain — goes down with blend="multiply", so it composites onto the page instead of covering what is beneath it as a rectangle. multiply keeps the darker of the two, so it only erases a ground that is white: commission the asset on white, or leave blend alone.

An SVG that draws live <text> is a warning (asset-font), not an error: an SVG loaded as an image is an isolated document and cannot see the renderer's bundled faces, so it resolves families against the machine's own font list. The render is not wrong; its reproducibility is narrower than everything around it.