@kurot/cli 3.2.0 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and CLI command/configuration APIs follow [Semantic Versioning](https://semver.o
 The early KUI XML contract follows the pre-1.0 `ui-document` kernel; authored
 format changes are documented explicitly in each release.
 
+## 3.2.1 — 2026-10-06
+
+### Game Template
+
+- Include fixed style.json and locale.json configuration, English properties,
+  Chakra Petch regular/bold fonts and their SIL Open Font License.
+- Load and publish project fonts before creating any UI, then register preload
+  translations using the URL language or configured default with English/key fallback.
+- Use shared ui-document font/color validation and named disabled text colors;
+  default skins inherit the project font instead of hardcoded Tahoma.
+- Keep the empty template minimal. Existing projects are not rewritten by scaffolding.
+- Create resource/ui/app alongside the reusable component directories so the
+  application Skin workspace is ready for the Editor.
+
+### Dependencies and Compatibility
+
+- New game projects include ui-document for the shared stylesheet parser. The
+  compiler retains its existing ui-document ^0.10.0 dependency.
+- Command/configuration APIs, KUI XML semantics and document format version 2
+  remain unchanged. Existing projects receive no automatic migration.
+
+### Tests
+
+- Validate bundled fonts/licenses, stylesheet colors, translation registration,
+  locale fallback, failed initialization and the unchanged empty template.
+- Compile all bundled default skins with the project palette and verify newly
+  generated projects through strict builds, type checking and browser rendering.
+
 ## 3.2.0 — 2026-10-06
 
 ### Added

package/README.md

@@ -3,7 +3,8 @@
 Build tooling for the Kurot UI Editor workflow. It uses esbuild, emits ES2022
 ESM, and compiles canonical KUI XML skins into runtime theme modules.
 
-> **Current package version: 3.2.0.** Node.js 20 or later is required.
+> **Current version: 3.2.1 (prepared for publication).** Requires `@kurot/ui-document@^0.10.0`
+> and Node.js 20 or later. The CLI runs only at build time.
 
 > **Release scope:** The 3.x line is dedicated to Kurot Editor integration.
 > Existing game projects that use EXML should remain on
@@ -12,6 +13,9 @@ ESM, and compiles canonical KUI XML skins into runtime theme modules.
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
+Version 3.2.1 adds project styles, bundled fonts and English translations to the
+game template. Existing projects are not rewritten. See [game template setup](docs/game-template.md).
+
 ## Label text fitting in 3.1.0
 
 The shared ui-document catalog supports Label `textFit` and `minFontSize`
@@ -37,7 +41,7 @@ See the [compilation contract](docs/label-text-layout.md) and
 The CLI does not require a global install.
 
 ```bash
-npx @kurot/cli create my-game
+npx @kurot/cli@3.2.1 create my-game
 cd my-game
 pnpm install
 pnpm dev
@@ -45,7 +49,7 @@ pnpm dev
 
 Scaffolded projects expose `build`, `dev`, and `clean` scripts. For an
 Editor-managed KUI XML project, install the package with
-`pnpm add -D @kurot/cli@^3.2.0`. Existing EXML projects should keep their current
+`pnpm add -D @kurot/cli@^3.2.1`. Existing EXML projects should keep their current
 1.3.x dependency.
 
 ## Commands
@@ -56,9 +60,11 @@ Editor-managed KUI XML project, install the package with
 kurot create <name> [--template game|empty]
 ```
 
-The `game` template includes `@kurot/core`, `@kurot/game`, `@kurot/ui`, KUI
-skins, resource loading, and an editable HTML template. The `empty` template
-contains a minimal `Sprite` application.
+The `game` template includes `@kurot/core`, `@kurot/game`, `@kurot/ui`,
+`@kurot/ui-document`, KUI skins, project styles/fonts, English translations,
+resource loading, and an editable HTML template. Fonts load before creating UI;
+translations register after preload. The `empty` template contains a minimal
+`Sprite` application without UI/style/language dependencies.
 
 ### `kurot build`
 
@@ -153,7 +159,7 @@ use `property.state` on the affected node, so internal graphics remain unnamed.
 Image sources use their resource key directly, for example
 `source="button_up_png"`.
 
-Version 3.2.0 uses `@kurot/ui-document@^0.10.0` and retains its literal-string XML rules.
+Version 3.2.1 uses `@kurot/ui-document@^0.10.0` and retains its literal-string XML rules.
 For example, `<Label text="100.80" text.down="false" size="48" />` compiles
 the exact strings `100.80` and `false`, while the font size stays numeric.
 String properties no longer add or remove backslash type escapes. Remove old
@@ -206,17 +212,33 @@ my-game/
 ├── kurot.config.ts
 ├── resource/
 │   ├── default.res.json
-│   ├── assets/
+│   ├── config/
+│   │   ├── style.json
+│   │   └── locale.json
+│   ├── lang/lang_en_US.properties
+│   ├── assets/fonts/
+│   │   ├── ChakraPetch-Regular.ttf
+│   │   ├── ChakraPetch-Bold.ttf
+│   │   └── OFL.txt
 │   └── ui/
+│       ├── app/
 │       ├── components/
 │       └── skins/*.kui.xml
 ├── src/
 │   ├── components/
-│   ├── LoadingUI.ts
+│   ├── Preloader.ts
+│   ├── StyleManager.ts
+│   ├── LocaleManager.ts
 │   └── Main.ts
 └── template/web/index.html
 ```
 
+StyleManager uses the same ui-document stylesheet parser as the compiler/Editor.
+`style.json` is read directly, independently of the manifest; locale.json and
+enabled properties files are registered in `preload`. Replace fonts by changing
+the resource-relative files/paths, and add languages through the Editor.
+See [game template setup](docs/game-template.md) for lifecycle and fallback rules.
+
 ## Resource defaults in 3.0.0
 
 KUI builds validate `resource/default.res.json` and inherit image or sheet-frame
@@ -253,7 +275,9 @@ An absent stylesheet is allowed when no Skin references its colors. An existing
 stylesheet must contain valid font definitions even if the build only consumes
 colors; see the shared [project style contract](../ui-document/docs/project-styles.md).
 The CLI does not load fonts, apply runtime CSS or introduce live game theme
-switching. Node.js >= 20 and semantic format version 2 remain unchanged.
+switching. CLI-built skins run directly through `@kurot/ui`; `@kurot/ui-runtime`
+is not required for this compilation path. Node.js >= 20 and semantic format
+version 2 remain unchanged.
 
 The previous `@token:color:<key>` XML prefix is rejected by ui-document 0.10.
 Update those references explicitly before adopting CLI 3.2; ordinary text stays

package/dist/core/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/core/template.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BzF"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/core/template.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BzF"}

package/dist/core/template.js

@@ -33,6 +33,7 @@ export async function scaffoldProject(name, template) {
         await Promise.all([
             ensureDir(path.join(destDir, 'src/components')),
             ensureDir(path.join(destDir, 'resource/ui/components')),
+            ensureDir(path.join(destDir, 'resource/ui/app')),
         ]);
     }
     const pkgPath = path.join(destDir, 'package.json');

package/dist/core/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/core/template.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/core/template.ts"],"names":[],"mappings":"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"}

package/docs/ai-context.md

@@ -1,7 +1,7 @@
 # @kurot/cli — AI context map
 
 Read this before exploring `src/`. [`architecture.md`](./architecture.md)
-explains the plugin pipeline. The package is `@kurot/cli@3.2.0`, runs on
+explains the plugin pipeline. The package is `@kurot/cli@3.2.1`, runs on
 Node.js 20+, and is installed as a project dev dependency.
 
 ## Directory map
@@ -24,6 +24,11 @@ src/
 ```
 
 Project templates are under `templates/game` and `templates/empty`.
+The 3.2.1 game template includes fixed style/locale configuration,
+English properties and licensed regular/bold font files. StyleManager finishes
+font loading before Main creates Player/Preloader; LocaleManager registers
+preload texts before creating the scene. See [game-template.md](game-template.md).
+Version 3.2.1 is prepared for publication; 3.2.0 is already published.
 
 ## KUI compilation
 
@@ -39,7 +44,7 @@ and layout apply to the runtime Skin, and its direct visual children become
 `property.state` attributes. Storage IDs and runtime mapping metadata are not
 authored XML fields.
 
-CLI 3.2.0 requires `@kurot/ui-document@^0.10.0`. Schema-defined strings, including
+CLI 3.2.1 requires `@kurot/ui-document@^0.10.0`. Schema-defined strings, including
 numeric/boolean-looking text and state text, are literal attributes without
 backslash type escaping. Old synthetic prefixes become literal characters;
 do not migrate them silently. Numeric/boolean properties and schema-free
@@ -116,19 +121,20 @@ in `namespace-external-plugin.ts`.
 
 ## Configuration lookup
 
-| Task                             | File                                         |
-| -------------------------------- | -------------------------------------------- |
-| Add or validate a config field   | `src/core/config.ts`                         |
-| Resolve an absolute project path | `src/core/project.ts`                        |
-| Change KUI scanning/theme output | `src/core/plugins/compile-kui.ts`            |
-| Change KUI node code generation  | `src/core/kui/kui-parser.ts`, `codegen.ts`   |
-| Add a built-in component tag     | `src/core/kui/registry.ts`                   |
-| Change generated part types      | `src/core/kui/skin-parts-declaration.ts`     |
-| Change component pairing         | `src/core/components/discover-components.ts` |
-| Change watch behavior            | `src/core/dev-server.ts`                     |
-| Change output HTML/import maps   | `src/core/plugins/generate-html.ts`          |
-| Change scaffolding               | `src/core/template.ts`, `templates/`         |
-| Add a diagnostic code            | `src/core/diagnostics/codes.ts`              |
+| Task                             | File                                                                |
+| -------------------------------- | ------------------------------------------------------------------- |
+| Add or validate a config field   | `src/core/config.ts`                                                |
+| Resolve an absolute project path | `src/core/project.ts`                                               |
+| Change KUI scanning/theme output | `src/core/plugins/compile-kui.ts`                                   |
+| Change KUI node code generation  | `src/core/kui/kui-parser.ts`, `codegen.ts`                          |
+| Add a built-in component tag     | `src/core/kui/registry.ts`                                          |
+| Change generated part types      | `src/core/kui/skin-parts-declaration.ts`                            |
+| Change component pairing         | `src/core/components/discover-components.ts`                        |
+| Change watch behavior            | `src/core/dev-server.ts`                                            |
+| Change output HTML/import maps   | `src/core/plugins/generate-html.ts`                                 |
+| Change scaffolding               | `src/core/template.ts`, `templates/`                                |
+| Change project style/locale boot | `templates/game/src/StyleManager.ts`, `LocaleManager.ts`, `Main.ts` |
+| Add a diagnostic code            | `src/core/diagnostics/codes.ts`                                     |
 
 ## Verification
 

package/docs/architecture.md

@@ -39,7 +39,7 @@ factory variables, property assignments, semantic layout children, and state
 property overrides. Document contracts, reusable instances, data bindings, and
 actions remain `UIDocument` concepts.
 
-CLI 3.2.0 consumes ui-document 0.10.x, retaining Label text-fitting metadata. The
+CLI 3.2.1 consumes ui-document 0.10.x, retaining Label text-fitting metadata. The
 compiler emits `textFit`, `minFontSize`, base font sizes and state overrides;
 native UI owns measurement and derives drawing sizes after layout validation.
 See [Label compilation](label-text-layout.md). The application supplies UI

package/docs/game-template.md

@@ -0,0 +1,60 @@
+# Project styles and languages in the game template
+
+CLI 3.2.1 includes this template update and is prepared for publication. It adds
+project-owned initialization without changing Core/UI APIs or migrating existing
+projects. The empty template stays minimal.
+
+## Files
+
+- resource/config/style.json declares the primary font role and disabled-text color.
+- resource/assets/fonts contains unmodified Chakra Petch regular (400) and bold (700)
+  files, with OFL.txt. Source: [Google Fonts](https://github.com/google/fonts/tree/main/ofl/chakrapetch).
+- resource/config/locale.json enables English and selects en_US by default.
+- resource/lang/lang_en_US.properties contains the scene title, button and descriptions.
+- default.res.json registers locale_json and lang_en_US_properties in preload.
+  style.json and fonts are read directly and need no manifest entries.
+
+## Startup order
+
+1. StyleManager reads and validates the stylesheet through published ui-document.
+2. It loads every configured FontFace; only after all succeed does it register
+   faces and publish the default CSS font family and numeric color palette.
+3. Main sets TextField.default_fontFamily, then creates Player and the Preloader.
+4. Main loads the manifest, theme and preload resources.
+5. LocaleManager registers the enabled text files, selects the language and creates
+   the translated scene. Startup errors are reported through console.error.
+
+This ordering includes loading-screen Labels in the project font. The loading
+screen's startup messages stay in English because translations are not loaded yet.
+Templates do not implement live font/theme/language replacement.
+
+## Change fonts and colors
+
+Font keys such as primary produce stable aliases such as kurot-primary. Replace
+files and update style.json resource-relative paths, retaining weight 400 and
+unique weights. Default skins inherit the configured font; explicit Label fontFamily
+values still override it. Existing stylesheet files must contain valid font definitions.
+Keep the font's applicable license with any replacement distribution.
+
+Label state colors use textColor.disabled="@style:colors:disabled-text". The CLI
+compiles these references into numbers. Dynamic application code reads the same
+palette through StyleManager.getColor('disabled-text'); enabled state behavior and
+restoration of a normal color remain application responsibilities.
+
+## Add languages
+
+Use the Editor's language window to add a code, create its properties file and
+update locale.json/default.res.json together. Only English is initially enabled.
+Manual additions must use lang_<code>_properties text resources in preload.
+
+LocaleManager accepts the project default or URL ?lang=fr / ?lang=fr_FR / ?lang=fr-FR.
+A full code match wins, then a matching base language, then the configured default.
+The default may be empty. Absent configuration or an empty language list clears registrations;
+enabled languages with unavailable text resources or an invalid default fail before
+publishing the new set. The last successful set is retained on initialization failure.
+
+getString(key, ...args) reads the current translation, then English, then the key.
+An explicitly empty translation remains empty. The simple properties format uses
+one key=value per line, #/! comments, common escapes including newline/Unicode,
+and {0}, {1} placeholders. Continuation lines and Java properties' colon-only
+separators are not supported. UI translation is explicit; it is not an engine binding.

package/docs/label-text-layout.md

@@ -1,6 +1,6 @@
 # Label text compilation
 
-CLI 3.2.0 consumes ui-document 0.10.x and compiles KUI text-fitting properties
+CLI 3.2.1 consumes ui-document 0.10.x and compiles KUI text-fitting properties
 through the existing UIDocument → SkinIR → ESM factory pipeline. The semantic
 document format remains version 2.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.2.0",
+	"version": "3.2.1",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",

package/templates/game/package.json

@@ -11,7 +11,8 @@
 	"dependencies": {
 		"@kurot/core": "latest",
 		"@kurot/game": "latest",
-		"@kurot/ui": "latest"
+		"@kurot/ui": "latest",
+		"@kurot/ui-document": "latest"
 	},
 	"devDependencies": {
 		"@kurot/cli": "latest"

package/templates/game/resource/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/game/resource/config/locale.json

@@ -0,0 +1,4 @@
+{
+	"locale": [{ "code": "en_US", "name": "English" }],
+	"defaultLocale": "en_US"
+}

package/templates/game/resource/config/style.json

@@ -0,0 +1,16 @@
+{
+	"schemaVersion": 1,
+	"fonts": {
+		"default": "primary",
+		"families": {
+			"primary": {
+				"fallback": ["Arial", "sans-serif"],
+				"faces": [
+					{ "url": "assets/fonts/ChakraPetch-Regular.ttf", "weight": 400 },
+					{ "url": "assets/fonts/ChakraPetch-Bold.ttf", "weight": 700 }
+				]
+			}
+		}
+	},
+	"colors": { "disabled-text": "#999999" }
+}

package/templates/game/resource/default.res.json

@@ -1,7 +1,7 @@
 {
 	"groups": [
 		{
-			"keys": "eui",
+			"keys": "eui,locale_json,lang_en_US_properties",
 			"name": "preload"
 		}
 	],
@@ -10,6 +10,16 @@
 			"name": "eui",
 			"type": "sheet",
 			"url": "assets/ui/eui/eui.json"
+		},
+		{
+			"name": "locale_json",
+			"type": "json",
+			"url": "config/locale.json"
+		},
+		{
+			"name": "lang_en_US_properties",
+			"type": "text",
+			"url": "lang/lang_en_US.properties"
 		}
 	]
 }

package/templates/game/resource/lang/lang_en_US.properties

@@ -0,0 +1,5 @@
+label.title=Hello Kurot
+label.button=Click Me
+label.description.open_source=Open-source, Free, Multi-platform
+label.description.push_forward=Push Game Forward
+label.description.engine=HTML5 Game Engine

package/templates/game/resource/ui/skins/ButtonSkin.kui.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ButtonSkin" states="disabled,down,up" minHeight="50" minWidth="100">
     <Image height="100%" scale9Grid="1,3,8,8" source="button_up_png" width="100%" alpha.disabled="0.5" source.down="button_down_png" />
-    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" textColor.disabled="@style:colors:disabled-text" top="8" verticalAlign="middle" />
     <Image id="iconDisplay" horizontalCenter="0" verticalCenter="0" />
 </Skin>

package/templates/game/resource/ui/skins/CheckBoxSkin.kui.xml

@@ -5,6 +5,6 @@
             <HorizontalLayout verticalAlign="middle" />
         </layout>
         <Image alpha="1" fillMode="scale" source="checkbox_unselect_png" alpha.disabled="0.5" source.disabledAndSelected="checkbox_select_disabled_png" alpha.down="0.7" source.downAndSelected="checkbox_select_down_png" source.upAndSelected="checkbox_select_up_png" />
-        <Label id="labelDisplay" fontFamily="Tahoma" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
+        <Label id="labelDisplay" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
     </Group>
 </Skin>

package/templates/game/resource/ui/skins/ComboBoxSkin.kui.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ComboBoxSkin" states="disabled,normal,open" minHeight="36" minWidth="100">
     <Rect fillColor="#1A1A2E" height="36" strokeColor="#0F3460" strokeWeight="1" width="100%" fillColor.disabled="#16213E" strokeColor.disabled="#4A5459" fillColor.open="#16213E" strokeColor.open="#6C5CE7" />
-    <Label id="labelDisplay" height="36" left="10" right="36" size="14" textColor="#DFE6E9" top="0" verticalAlign="middle" textColor.disabled="#636E72" />
+    <Label id="labelDisplay" height="36" left="10" right="36" size="14" textColor="#DFE6E9" top="0" verticalAlign="middle" textColor.disabled="@style:colors:disabled-text" />
     <Label height="36" right="4" size="10" text="▼" textAlign="center" textColor="#636E72" top="0" verticalAlign="middle" width="24" textColor.open="#6C5CE7" />
     <Scroller id="dropDown" height="180" left="0" right="0" top="36" visible="false">
         <List id="list" height="180" width="100%" />

package/templates/game/resource/ui/skins/ItemRendererSkin.kui.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ItemRendererSkin" states="disabled,down,up" minHeight="50" minWidth="100">
     <Image height="100%" scale9Grid="1,3,8,8" source="button_up_png" width="100%" alpha.disabled="0.5" source.down="button_down_png" />
-    <Label id="labelDisplay" bottom="8" fontFamily="Tahoma" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
 </Skin>

package/templates/game/resource/ui/skins/PanelSkin.kui.xml

@@ -3,7 +3,7 @@
     <Image bottom="0" left="0" right="0" scale9Grid="2,2,12,12" source="border_png" top="0" />
     <Group id="moveArea" height="45" left="0" right="0" top="0">
         <Image bottom="0" left="0" right="0" scale9Grid="2,2,12,12" source="header_png" top="0" />
-        <Label id="titleDisplay" fontFamily="Tahoma" left="15" right="5" size="20" textColor="#FFFFFF" verticalCenter="0" wordWrap="false" />
+        <Label id="titleDisplay" left="15" right="5" size="20" textColor="#FFFFFF" verticalCenter="0" wordWrap="false" />
     </Group>
     <Button id="closeButton" bottom="5" horizontalCenter="0" label="close" />
 </Skin>

package/templates/game/resource/ui/skins/ProgressBarSkin.kui.xml

@@ -2,5 +2,5 @@
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ProgressBarSkin" minHeight="18" minWidth="30">
     <Image height="100%" scale9Grid="1,1,4,4" source="track_pb_png" verticalCenter="0" width="100%" />
     <Image id="thumb" height="100%" scale9Grid="1,1,4,4" source="thumb_pb_png" width="100%" />
-    <Label id="labelDisplay" fontFamily="Tahoma" horizontalCenter="0" size="15" textAlign="center" textColor="#707070" verticalAlign="middle" verticalCenter="0" />
+    <Label id="labelDisplay" horizontalCenter="0" size="15" textAlign="center" textColor="#707070" verticalAlign="middle" verticalCenter="0" />
 </Skin>

package/templates/game/resource/ui/skins/RadioButtonSkin.kui.xml

@@ -5,6 +5,6 @@
             <HorizontalLayout verticalAlign="middle" />
         </layout>
         <Image alpha="1" fillMode="scale" source="radiobutton_unselect_png" alpha.disabled="0.5" source.disabledAndSelected="radiobutton_select_disabled_png" alpha.down="0.7" source.downAndSelected="radiobutton_select_down_png" source.upAndSelected="radiobutton_select_up_png" />
-        <Label id="labelDisplay" fontFamily="Tahoma" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
+        <Label id="labelDisplay" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
     </Group>
 </Skin>

package/templates/game/resource/ui/skins/TextInputSkin.kui.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.TextInputSkin" states="disabled,disabledWithPrompt,normal,normalWithPrompt" minHeight="40" minWidth="300">
     <Rect fillColor="#FFFFFF" height="100%" width="100%" alpha.disabled="0.5" />
-    <EditableText id="textDisplay" height="24" left="10" right="10" size="20" textColor="#000000" verticalAlign="middle" verticalCenter="0" textColor.disabled="#FF0000" />
+    <EditableText id="textDisplay" height="24" left="10" right="10" size="20" textColor="#000000" verticalAlign="middle" verticalCenter="0" textColor.disabled="@style:colors:disabled-text" />
     <Label id="promptDisplay" height="24" left="10" multiline="false" right="10" size="20" textColor="#A9A9A9" touchEnabled="false" verticalAlign="middle" verticalCenter="0" visible="false" wordWrap="false" visible.disabledWithPrompt="true" visible.normalWithPrompt="true" />
 </Skin>

package/templates/game/resource/ui/skins/ToggleButtonSkin.kui.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ToggleButtonSkin" states="disabled,disabledAndSelected,down,downAndSelected,up,upAndSelected" minHeight="50" minWidth="100">
     <Rect fillColor="#636E72" height="100%" strokeColor="#4A5459" strokeWeight="1" width="100%" fillColor.disabled="#2D3436" fillColor.disabledAndSelected="#2D3436" fillColor.down="#4A5459" fillColor.downAndSelected="#5A4BD1" fillColor.upAndSelected="#6C5CE7" />
-    <Label id="labelDisplay" bottom="8" left="8" right="8" size="16" textAlign="center" textColor="#DFE6E9" top="8" verticalAlign="middle" textColor.disabled="#636E72" textColor.upAndSelected="#FFFFFF" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="16" textAlign="center" textColor="#DFE6E9" top="8" verticalAlign="middle" textColor.disabled="@style:colors:disabled-text" textColor.upAndSelected="#FFFFFF" />
 </Skin>

package/templates/game/src/LocaleManager.ts

@@ -0,0 +1,109 @@
+/**
+ * preload 完成后注册项目翻译。URL 的 lang 优先，缺失翻译回退英语，再回退键名。
+ * 不监听 UI、不自动重写文本；界面创建时主动调用 getString。
+ */
+export class LocaleManager {
+	private static _locales = new Map<string, ReadonlyMap<string, string>>();
+	private static _currentLocale = '';
+
+	public static get currentLocale(): string {
+		return this._currentLocale;
+	}
+
+	/**
+	 * 先验证整份配置及语言资源，成功后一起替换，避免加载失败留下半套翻译。
+	 */
+	public static init(config: unknown, readResource: (name: string) => unknown, requestedLocale = ''): void {
+		const locales = new Map<string, ReadonlyMap<string, string>>();
+		let defaultLocale = '';
+		if (config !== undefined) {
+			if (!isRecord(config) || !Array.isArray(config.locale)) {
+				throw new Error('locale.json must contain a locale array.');
+			}
+			for (const entry of config.locale as unknown[]) {
+				if (
+					!isRecord(entry) ||
+					typeof entry.code !== 'string' ||
+					!/^[a-z]{2}_[A-Z]{2}$/.test(entry.code) ||
+					typeof entry.name !== 'string' ||
+					entry.name.trim() === ''
+				) {
+					throw new Error('Each project language must have a language code and name.');
+				}
+				if (locales.has(entry.code)) {
+					throw new Error(`Duplicate project language: ${entry.code}.`);
+				}
+				const source = readResource(`lang_${entry.code}_properties`);
+				if (typeof source !== 'string') {
+					throw new Error(`Language resource is unavailable: ${entry.code}.`);
+				}
+				locales.set(entry.code, this._parse(source));
+			}
+			const configuredDefault =
+				config.defaultLocale === undefined ? (locales.has('en_US') ? 'en_US' : '') : config.defaultLocale;
+			if (
+				typeof configuredDefault !== 'string' ||
+				(configuredDefault !== '' && !locales.has(configuredDefault))
+			) {
+				throw new Error('defaultLocale must name an enabled language or be empty.');
+			}
+			defaultLocale = configuredDefault;
+		}
+
+		const normalized = requestedLocale.trim().replace(/-/g, '_').toLowerCase();
+		const codes = [...locales.keys()];
+		const exact = codes.find(code => code.toLowerCase() === normalized);
+		const base = normalized.split('_')[0];
+		this._currentLocale = exact ?? codes.find(code => code.toLowerCase().split('_')[0] === base) ?? defaultLocale;
+		this._locales = locales;
+	}
+
+	public static getString(key: string, ...args: Array<string | number>): string {
+		const text = this._locales.get(this._currentLocale)?.get(key) ?? this._locales.get('en_US')?.get(key) ?? key;
+		return text.replace(/\{(\d+)\}/g, (placeholder: string, index: string) => {
+			const argument = args[Number(index)];
+			return argument === undefined ? placeholder : String(argument);
+		});
+	}
+
+	private static _parse(source: string): ReadonlyMap<string, string> {
+		const values = new Map<string, string>();
+		for (const line of source.split(/\r?\n/)) {
+			const content = line.trim();
+			if (!content || content.startsWith('#') || content.startsWith('!')) {
+				continue;
+			}
+			const split = line.indexOf('=');
+			if (split < 0) {
+				continue;
+			}
+			const key = line.slice(0, split).trim();
+			if (key) {
+				values.set(key, this._decodeValue(line.slice(split + 1).trim()));
+			}
+		}
+		return values;
+	}
+
+	private static _decodeValue(value: string): string {
+		return value.replace(/\\(u[0-9a-fA-F]{4}|[nrt\\=: ])/g, (_match: string, escape: string) => {
+			if (escape.startsWith('u')) {
+				return String.fromCharCode(Number.parseInt(escape.slice(1), 16));
+			}
+			switch (escape) {
+				case 'n':
+					return '\n';
+				case 'r':
+					return '\r';
+				case 't':
+					return '\t';
+				default:
+					return escape;
+			}
+		});
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/templates/game/src/Main.ts

@@ -5,15 +5,18 @@
  *
  * Lifecycle: constructor → ADDED_TO_STAGE → $onAddToStage → runGame → load → createGameScene → startAnimation
  */
-import { createPlayer, Event, resource } from '@kurot/core';
+import { createPlayer, Event, resource, TextField } from '@kurot/core';
 import { Button, Label, Rect, Theme, UILayer, setAssetAdapter } from '@kurot/ui';
 import { Tween } from '@kurot/game';
 import { AssetAdapter } from '@/AssetAdapter';
 import { LifecycleHandler } from '@/LifecycleHandler';
 import { Preloader } from '@/Preloader';
+import { LocaleManager } from '@/LocaleManager';
+import { StyleManager } from '@/StyleManager';
 
 class Main extends UILayer {
 	private readonly _preloader = new Preloader();
+	private _description!: Label;
 
 	createChildren(): void {
 		super.createChildren();
@@ -24,25 +27,25 @@ class Main extends UILayer {
 		setAssetAdapter(new AssetAdapter());
 		LifecycleHandler.init(stage);
 
-		void this.runGame().catch(error => {
+		void this._runGame().catch(error => {
 			console.error('[Main] Unable to start game:', error);
 		});
 	}
 
-	private async runGame(): Promise<void> {
-		await this.createPreloader();
-		await this.load();
+	private async _runGame(): Promise<void> {
+		await this._createPreloader();
+		await this._load();
 		this._preloader.destroy();
-		this.createGameScene();
-		this.startAnimation();
+		this._createGameScene();
+		this._startAnimation();
 	}
 
-	private async load(): Promise<void> {
-		await this.updatePreloader('Loading resource configuration...', 1, 2);
+	private async _load(): Promise<void> {
+		await this._updatePreloader('Loading resource configuration...', 1, 2);
 		await resource.loadConfig('resource/default.res.json', 'resource/');
 
-		await this.updatePreloader('Loading theme...', 2, 2);
-		await this.loadTheme();
+		await this._updatePreloader('Loading theme...', 2, 2);
+		await this._loadTheme();
 
 		if (resource.hasGroup('preload')) {
 			this._preloader.updateText('Loading resources...');
@@ -50,39 +53,44 @@ class Main extends UILayer {
 				this._preloader.onProgress(loaded, total);
 			});
 		}
+
+		// 翻译依赖 preload 中的文本资源；加载完毕后再创建业务界面。
+		LocaleManager.init(
+			resource.get('locale_json'),
+			name => resource.get(name),
+			new URLSearchParams(window.location.search).get('lang') ?? '',
+		);
 	}
 
-	private async createPreloader(): Promise<void> {
+	private async _createPreloader(): Promise<void> {
 		await this._preloader.init();
 		this.addChild(this._preloader);
 	}
 
-	private async updatePreloader(message: string, current: number, total: number): Promise<void> {
+	private async _updatePreloader(message: string, current: number, total: number): Promise<void> {
 		this._preloader.updateText(message);
 		this._preloader.updateProgress(current, total);
-		await this.wait(0.1);
+		await this._wait(0.1);
 	}
 
-	private async loadTheme(): Promise<void> {
+	private async _loadTheme(): Promise<void> {
 		// Load the theme and its default UI skin mappings.
 		const theme = new Theme('resource/default.thm.json');
 		await new Promise<void>(resolve => theme.addEventListener(Event.COMPLETE, () => resolve()));
 	}
 
-	private wait(timeout: number): Promise<void> {
+	private _wait(timeout: number): Promise<void> {
 		return new Promise<void>(resolve => {
 			setTimeout(resolve, timeout * 1000);
 		});
 	}
 
-	private textfield!: Label;
-
 	/**
 	 * Create the game scene.
 	 *
 	 * Build a responsive view with EUI components and constraint-based layout.
 	 */
-	private createGameScene(): void {
+	private _createGameScene(): void {
 		// Responsive background
 		const sky = new Rect();
 		sky.left = 0;
@@ -111,7 +119,7 @@ class Main extends UILayer {
 		colorLabel.height = 48;
 		colorLabel.textAlign = 'center';
 		colorLabel.verticalAlign = 'middle';
-		colorLabel.text = 'Hello Kurot';
+		colorLabel.text = LocaleManager.getString('label.title');
 		colorLabel.size = 36;
 		this.addChild(colorLabel);
 
@@ -127,11 +135,11 @@ class Main extends UILayer {
 		textfield.verticalAlign = 'middle';
 		textfield.size = 24;
 		textfield.textColor = 0xffffff;
-		this.textfield = textfield;
+		this._description = textfield;
 
 		// UI button using the default theme
 		const button = new Button();
-		button.label = 'Click Me';
+		button.label = LocaleManager.getString('label.button');
 		button.horizontalCenter = 0;
 		button.top = 200;
 		button.width = 200;
@@ -141,16 +149,20 @@ class Main extends UILayer {
 	/**
 	 * Play a looping text fade animation.
 	 */
-	private startAnimation(): void {
-		const texts = ['Open-source, Free, Multi-platform', 'Push Game Forward', 'HTML5 Game Engine'];
+	private _startAnimation(): void {
+		const texts = [
+			LocaleManager.getString('label.description.open_source'),
+			LocaleManager.getString('label.description.push_forward'),
+			LocaleManager.getString('label.description.engine'),
+		];
 		let count = -1;
 		const change = () => {
 			count++;
 			if (count >= texts.length) {
 				count = 0;
 			}
-			this.textfield.text = texts[count];
-			const tw = Tween.get(this.textfield);
+			this._description.text = texts[count];
+			const tw = Tween.get(this._description);
 			tw.to({ alpha: 1 }, 200);
 			tw.wait(2000);
 			tw.to({ alpha: 0 }, 200);
@@ -161,12 +173,24 @@ class Main extends UILayer {
 }
 
 // ── Bootstrap ─────────────────────────────────────────────────────────────
-const app = createPlayer({
-	canvas: document.getElementById('gameCanvas') as HTMLCanvasElement,
-	contentWidth: 640,
-	contentHeight: 1136,
-	scaleMode: 'showAll',
-	frameRate: 60,
-});
+async function start(): Promise<void> {
+	// 包括 Preloader 在内的所有 Label 首次测量都使用已就绪的项目字体。
+	await StyleManager.init();
+	TextField.default_fontFamily = StyleManager.fontFamily;
+	const canvas = document.getElementById('gameCanvas');
+	if (!(canvas instanceof HTMLCanvasElement)) {
+		throw new Error('Missing gameCanvas.');
+	}
+	const app = createPlayer({
+		canvas,
+		contentWidth: 640,
+		contentHeight: 1136,
+		scaleMode: 'showAll',
+		frameRate: 60,
+	});
+	app.start(new Main());
+}
 
-app.start(new Main());
+void start().catch(error => {
+	console.error('[Main] Unable to start project:', error);
+});

package/templates/game/src/StyleManager.ts

@@ -0,0 +1,57 @@
+import { getUIStyleColor, getUIStyleFontAlias, getUIStyleFontFamily, parseUIStyleSheet } from '@kurot/ui-document';
+import type { UIStyleFontFace } from '@kurot/ui-document';
+
+/**
+ * 项目启动时加载固定样式表，字体全部就绪后再创建 Player 和 UI。
+ * 字体别名保持稳定，换字体文件不需要逐个修改皮肤。
+ */
+export class StyleManager {
+	private static _colors: Readonly<Record<string, number>> = Object.freeze({});
+	private static _fontFamily?: string;
+
+	public static get fontFamily(): string {
+		if (this._fontFamily === undefined) {
+			throw new Error('Project styles are not initialized.');
+		}
+		return this._fontFamily;
+	}
+
+	public static async init(): Promise<void> {
+		const resourceRoot = new URL('resource/', document.baseURI);
+		const response = await fetch(new URL('config/style.json', resourceRoot));
+		if (!response.ok) {
+			throw new Error(`Unable to load resource/config/style.json: HTTP ${response.status}.`);
+		}
+		const stylesheet = parseUIStyleSheet(await response.json());
+		const loading = Object.entries(stylesheet.fonts.families).flatMap(([key, family]) =>
+			family.faces.map(face => this._loadFace(key, face, resourceRoot)),
+		);
+		const faces = await Promise.all(loading);
+
+		// 全部成功后一次性发布，失败时不留下半套字体或新的默认值。
+		for (const face of faces) {
+			document.fonts.add(face);
+		}
+		this._fontFamily = getUIStyleFontFamily(stylesheet);
+		this._colors = stylesheet.colors;
+	}
+
+	/**
+	 * 业务代码需要动态设置文字颜色时，读取与皮肤编译相同的颜色表。
+	 */
+	public static getColor(key: string): number {
+		return getUIStyleColor(this._colors, key);
+	}
+
+	private static async _loadFace(key: string, definition: UIStyleFontFace, resourceRoot: URL): Promise<FontFace> {
+		const url = new URL(definition.url.split('/').map(encodeURIComponent).join('/'), resourceRoot);
+		const face = new FontFace(getUIStyleFontAlias(key), `url("${url.href}")`, {
+			weight: String(definition.weight),
+		});
+		try {
+			return await face.load();
+		} catch (cause) {
+			throw new Error(`Unable to load project font ${key} (${definition.weight}): ${definition.url}.`, { cause });
+		}
+	}
+}