Write phase 3 articles by MartinBozhilov-coh · Pull Request #8 · CoherentLabs/StarterGuide

MartinBozhilov-coh · 2026-05-12T13:19:10Z

No description provided.

…e 4 and Phase 5 articles

alien1976

Part 1

alien1976 · 2026-05-18T14:07:32Z

+title: Alternative Frameworks
+description: Learn about alternative frameworks that you can use to build your Gameface projects.
+sidebar:


Suggested change

title: Alternative Frameworks

description: Learn about alternative frameworks that you can use to build your Gameface projects.

sidebar:

title: Alternative Frameworks

draft: true

description: Learn about alternative frameworks that you can use to build your Gameface projects.

sidebar:

alien1976 · 2026-05-19T08:36:05Z

+
+Gameface's internal layout engine is highly optimized and incredibly fast. However, the environment it runs in is extremely demanding. If a game targets 60 frames per second, the entire game engine has exactly <Highlight>16.6 milliseconds</Highlight> to render a single frame. The UI is usually allocated only a tiny fraction of that time (often 1-2ms). 
+
+In a standard web browser, a 15ms layout recalculation goes completely unnoticed. In a game engine, it blows your entire frame budget. To ensure your UI runs at peak performance and leaves plenty of CPU room for the game itself, we need to architect our layouts following a few core rules.


Maybe? :D Using architect is fine but for me is kind of weird when reading the text. You can also use build, develop or other word.

Suggested change

In a standard web browser, a 15ms layout recalculation goes completely unnoticed. In a game engine, it blows your entire frame budget. To ensure your UI runs at peak performance and leaves plenty of CPU room for the game itself, we need to architect our layouts following a few core rules.

In a standard web browser, a 15ms layout recalculation goes completely unnoticed. In a game engine, it blows your entire frame budget. To ensure your UI runs at peak performance and leaves plenty of CPU room for the game itself, we need to design our layouts following a few core rules.

alien1976 · 2026-05-19T08:38:02Z

+
+## High-Performance Layout Rules
+
+Before we look at the screen structure, here are the practical "Do's and Don'ts" for styling your elements in Gameface.


Suggested change

Before we look at the screen structure, here are the practical "Do's and Don'ts" for styling your elements in Gameface.

Before we look at the screen structure, here are the practical "Good" and "Bad" practices for styling your elements in Gameface.

alien1976 · 2026-05-19T08:40:38Z

+
+Before we look at the screen structure, here are the practical "Do's and Don'ts" for styling your elements in Gameface.
+
+### Define explicit dimensions


For the next headings you can add badges for "Good" and "Bad" or add X and checkmark emojis so the reader knows which is bad and which is good before starting to read the section.

For example:

Suggested change

### Define explicit dimensions

### [Good badge/checkmark icon] Define explicit dimensions

or

Suggested change

### Define explicit dimensions

### Define explicit dimensions [Good badge/checkmark icon]

alien1976 · 2026-05-19T08:42:51Z

+
+Try to use `align-items: center` or `flex-start` and rely on explicit dimensions instead.
+
+:::danger[Default property]


IMO this should be marked as caution and not danger

alien1976 · 2026-05-19T13:02:48Z

+
+This algorithm can only be used inside `<p>` elements and is enabled by adding the special `cohinline` attribute.
+
+Here is how you use `cohinline` to resolve the issuue mentioned above:


Suggested change

Here is how you use `cohinline` to resolve the issuue mentioned above:

Here is how you use `cohinline` to resolve the issue mentioned above:

alien1976 · 2026-05-19T13:26:03Z

+
+However, `cohinline` handles vertical space differently than a web browser, which often leads to misaligned icons if you aren't expecting it.
+
+### The Problem: Ignored Image Heights


Suggested change

### The Problem: Ignored Image Heights

### Image heights are ignored

alien1976 · 2026-05-19T13:27:10Z

+
+![](../../../../assets/phase-3/text-and-fonts/vertical-align-wrong.png)
+
+### The Solution: Explicit Line Heights


Suggested change

### The Solution: Explicit Line Heights

### Setting explicit line heights to fit the image

I am suggesting these changes because personally I don't like the The problem and The solution texts :D

alien1976 · 2026-05-19T13:37:11Z

+**Actionable Rule:** Always explicitly define a base `font-size` on the element that is as close to the expected final rendering size as possible. This minimizes the iterations required by the engine's calculation loop.
+
+```css title="optimized-fit.css" ins="font-size: 24px;"
+.button-text {
+    coh-font-fit-mode: shrink;
+    coh-font-fit-min-size: 14px;
+
+    /* Providing a starting point near the expected final size minimizes calculation overhead */
+    font-size: 24px; 
+}
+```


Make this aside. For example tip

alien1976 · 2026-05-19T13:50:03Z

+
+## The Asset Format Problem 
+
+In a browser prototype, it is common to pick an image format based mainly on visual quality and file size. In a gameface UI, that decision also affects how much work the UI layer performs during layout, rendering, and invalidation.


I am confused about the In a gameface UI what exactly means? Is it the Gameface UI or not? :D

Maybe just In Gameface is enough?

alien1976 · 2026-05-19T14:40:27Z

+
+### Practical Format Rules 
+
+For most Gameface UI work, the format decision can be made with a few direct rules:


Suggested change

For most Gameface UI work, the format decision can be made with a few direct rules:

Making a decision which format fits the best for your UI in Gameface you can follow these rules:

Or something else but different from the original text because it does not make sense written in that way.

alien1976 · 2026-05-19T14:41:59Z

+* Use **JPEG** only when the asset does not need transparency and compression artifacts are acceptable, such as some large background images (although the use case is very rare).
+
+:::caution[SVG Usage Gotcha]
+Avoid converting complex painted art into SVG only to make it scalable. If the SVG contains many paths, the visual flexibility may not justify the rendering cost


Suggested change

Avoid converting complex painted art into SVG only to make it scalable. If the SVG contains many paths, the visual flexibility may not justify the rendering cost

Avoid converting complex painted art into SVG only to make it scalable. If the SVG contains many paths, the visual flexibility may not justify the rendering cost.

alien1976 · 2026-05-19T14:44:13Z

+
+#### `<img>` element
+
+Use when the SVG is meaningful to the content or needs to participate in layout like an image. For example, as a button with an Xbox A glyph icon.


Use when the SVG is meaningful to the content - what does this mean? :D

alien1976 · 2026-05-20T08:29:17Z

+
+#### CSS `background-image`
+
+Use when the SVG is purely decorative and part of the component's styles. For example, a panel frame with a border.


Maybe we can simplify both sections here for the external SVGs. Instead of explaining the differences between img and background-image, we can just list both as valid approaches. The only strict rule we need to highlight is that external SVGs are for graphics that won't be manipulated at runtime, regardless of how they are used.

alien1976 · 2026-05-20T09:02:46Z

+
+Changing `viewBox` on a complex SVG can still trigger redraw work. This is usually appropriate for controlled interactions, such as opening a map
+screen or dragging a minimap, but you should avoid unnecessary **per-frame** updates on very large SVG maps. If the SVG contains many moving paths,
+labels, and decorative layers, <Highlight>profile the interaction in the target UI</Highlight>.


Maybe? Or something similar? profile the interaction in the target UI is kind of weird for me :D

Suggested change

labels, and decorative layers, <Highlight>profile the interaction in the target UI</Highlight>.

labels, and decorative layers, <Highlight>make sure to profile the performance of the UI</Highlight>.

alien1976 · 2026-05-20T14:43:53Z

+rules (`opacity: 1; transform: translateY(0)`). Because a `transition` is declared on both properties, the engine
+
+<Highlight>interpolates between them</Highlight>, producing a smooth fade and slide with no JavaScript animation code.


Suggested change

rules (`opacity: 1; transform: translateY(0)`). Because a `transition` is declared on both properties, the engine

<Highlight>interpolates between them</Highlight>, producing a smooth fade and slide with no JavaScript animation code.

rules (`opacity: 1; transform: translateY(0)`). Because a `transition` is declared on both properties, the engine <Highlight>interpolates between them</Highlight>, producing a smooth fade and slide with no JavaScript animation code.

alien1976 · 2026-05-20T14:44:57Z

+:::caution[Other Limitations]
+
+- `@starting-style` does not work with out-of-line SVGs.
+- Custom expressions are not supported inside `@starting-style` rules. :::


Suggested change

:::caution[Other Limitations]

- `@starting-style` does not work with out-of-line SVGs.

- Custom expressions are not supported inside `@starting-style` rules. :::

:::caution[Other Limitations]

- `@starting-style` does not work with out-of-line SVGs.

- Custom expressions are not supported inside `@starting-style` rules.

:::

alien1976 · 2026-05-20T14:52:20Z

+- `@starting-style` does not work with out-of-line SVGs.
+- Custom expressions are not supported inside `@starting-style` rules. :::
+
+## Controlling Animations with JavaScript


I am no sure if this is the place but maybe it is good to add a short example/topic of controlling something with transtionend and transitionstart because they are not documented but are useful in some scenarios

alien1976 · 2026-05-20T14:56:09Z

+Not all CSS properties work on SVG child elements the way they do on HTML elements. Properties like `filter` (e.g., `drop-shadow`) and `box-shadow`
+
+<Highlight>will not produce any visible effect</Highlight> when applied directly to a `<path>`, `<rect>`, or other SVG shape. The declaration is


Suggested change

Not all CSS properties work on SVG child elements the way they do on HTML elements. Properties like `filter` (e.g., `drop-shadow`) and `box-shadow`

<Highlight>will not produce any visible effect</Highlight> when applied directly to a `<path>`, `<rect>`, or other SVG shape. The declaration is

Not all CSS properties work on SVG child elements the way they do on HTML elements. Properties like `filter` (e.g., `drop-shadow`) and `box-shadow` <Highlight>will not produce any visible effect</Highlight> when applied directly to a `<path>`, `<rect>`, or other SVG shape. The declaration is

alien1976 · 2026-05-20T15:12:00Z

+The `mask-image` variant flips the relationship between shape and color. Instead of the sprite sheet carrying the finished visual, it carries only
+
+<Highlight>silhouette frames</Highlight> that define which pixels are visible. The actual color comes from `background-color` on the same element.


Suggested change

The `mask-image` variant flips the relationship between shape and color. Instead of the sprite sheet carrying the finished visual, it carries only

<Highlight>silhouette frames</Highlight> that define which pixels are visible. The actual color comes from `background-color` on the same element.

The `mask-image` variant flips the relationship between shape and color. Instead of the sprite sheet carrying the finished visual, it carries only <Highlight>silhouette frames</Highlight> that define which pixels are visible. The actual color comes from `background-color` on the same element.

MartinBozhilov-coh added 9 commits May 5, 2026 15:02

Add most of phase 1 & 2 articles and drafts

47c700f

Complete structure for phase 2 with drafts

a0e5b89

Add first four articles of phase 3

2362e6e

Add dynamic styling and variables articles

54ad931

Add text & font articles

167ba34

Add Graphics and Shapes articles

589b3cd

Update dependencies and guide structure

c89cbe8

Add animation section articles

43ba0fd

Add animation libraries article

20e966c

MartinBozhilov-coh requested review from MihailTodorov and alien1976 May 12, 2026 13:19

MartinBozhilov-coh self-assigned this May 12, 2026

Remove 'Mocking Data' section and update links in content.ts for Phas…

d6fdf8f

…e 4 and Phase 5 articles

alien1976 reviewed May 19, 2026

View reviewed changes

alien1976 approved these changes May 20, 2026

View reviewed changes


		Gameface's internal layout engine is highly optimized and incredibly fast. However, the environment it runs in is extremely demanding. If a game targets 60 frames per second, the entire game engine has exactly <Highlight>16.6 milliseconds</Highlight> to render a single frame. The UI is usually allocated only a tiny fraction of that time (often 1-2ms).

		In a standard web browser, a 15ms layout recalculation goes completely unnoticed. In a game engine, it blows your entire frame budget. To ensure your UI runs at peak performance and leaves plenty of CPU room for the game itself, we need to architect our layouts following a few core rules.


		## High-Performance Layout Rules

		Before we look at the screen structure, here are the practical "Do's and Don'ts" for styling your elements in Gameface.


		Before we look at the screen structure, here are the practical "Do's and Don'ts" for styling your elements in Gameface.

		### Define explicit dimensions

	### Define explicit dimensions
	### [Good badge/checkmark icon] Define explicit dimensions

	### Define explicit dimensions
	### Define explicit dimensions [Good badge/checkmark icon]


		Try to use `align-items: center` or `flex-start` and rely on explicit dimensions instead.

		:::danger[Default property]


		This algorithm can only be used inside `<p>` elements and is enabled by adding the special `cohinline` attribute.

		Here is how you use `cohinline` to resolve the issuue mentioned above:


		However, `cohinline` handles vertical space differently than a web browser, which often leads to misaligned icons if you aren't expecting it.

		### The Problem: Ignored Image Heights

	### The Problem: Ignored Image Heights
	### Image heights are ignored


		![](../../../../assets/phase-3/text-and-fonts/vertical-align-wrong.png)

		### The Solution: Explicit Line Heights

	### The Solution: Explicit Line Heights
	### Setting explicit line heights to fit the image


		## The Asset Format Problem

		In a browser prototype, it is common to pick an image format based mainly on visual quality and file size. In a gameface UI, that decision also affects how much work the UI layer performs during layout, rendering, and invalidation.


		### Practical Format Rules

		For most Gameface UI work, the format decision can be made with a few direct rules:

	For most Gameface UI work, the format decision can be made with a few direct rules:
	Making a decision which format fits the best for your UI in Gameface you can follow these rules:

	Avoid converting complex painted art into SVG only to make it scalable. If the SVG contains many paths, the visual flexibility may not justify the rendering cost
	Avoid converting complex painted art into SVG only to make it scalable. If the SVG contains many paths, the visual flexibility may not justify the rendering cost.


		#### `<img>` element

		Use when the SVG is meaningful to the content or needs to participate in layout like an image. For example, as a button with an Xbox A glyph icon.


		#### CSS `background-image`

		Use when the SVG is purely decorative and part of the component's styles. For example, a panel frame with a border.

	labels, and decorative layers, <Highlight>profile the interaction in the target UI</Highlight>.
	labels, and decorative layers, <Highlight>make sure to profile the performance of the UI</Highlight>.

		rules (`opacity: 1; transform: translateY(0)`). Because a `transition` is declared on both properties, the engine

		<Highlight>interpolates between them</Highlight>, producing a smooth fade and slide with no JavaScript animation code.

		Not all CSS properties work on SVG child elements the way they do on HTML elements. Properties like `filter` (e.g., `drop-shadow`) and `box-shadow`

		<Highlight>will not produce any visible effect</Highlight> when applied directly to a `<path>`, `<rect>`, or other SVG shape. The declaration is

Conversation

MartinBozhilov-coh commented May 12, 2026

Uh oh!

alien1976 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		The `mask-image` variant flips the relationship between shape and color. Instead of the sprite sheet carrying the finished visual, it carries only

		<Highlight>silhouette frames</Highlight> that define which pixels are visible. The actual color comes from `background-color` on the same element.