diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4aedc890f..324dd28a4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,6 +11,7 @@ General app structure is: This file contains general guidelines for contributing to the SD.Next codebase, including conventions, tools, and project structure. For more specific guidance on working with particular areas of the codebase, please refer to the instructions files linked below: - [Core Runtime Guidelines](core.instructions.md): Use when editing Python core runtime code, startup flow, model loading, API internals, backend/device logic, or shared state in modules and pipelines. - [UI And Frontend Guidelines](ui.instructions.md): Use when editing frontend UI code, JavaScript, HTML, CSS, localization files, or built-in UI extensions including modernui and kanvas. +- [Hint Typography Guidelines](hints.instructions.md): Use when editing hint text or other UI strings in localization JSON files (`html/locale_*.json`, `html/override_*.json`). ## Agent Guidelines diff --git a/.github/instructions/hints.instructions.md b/.github/instructions/hints.instructions.md new file mode 100644 index 000000000..8243bdb53 --- /dev/null +++ b/.github/instructions/hints.instructions.md @@ -0,0 +1,50 @@ +--- +description: "Use when editing hint text or other UI strings in localization JSON files." +name: "Hint Typography Guidelines" +applyTo: "html/locale_*.json, html/override_*.json" +--- +# Hint Typography Guidelines + +Hint strings render as HTML. Use this small set of inline tags to keep hints scannable: + +- `` for values: defaults, dropdown enums, specific numerics. Examples: `0.30`, `Karras`, `v_prediction`, `UniPC`. +- `...` for cross-references to other UI controls by their exact visible label. Examples: `Denoising strength`, `Use init image`, `Images tab. +- `` for proper nouns: model families, datasets, technique names. Examples: `SDXL`, `Flux`, `ControlNet`, `YOLO`. +- `` for literals: paths, filename tokens, command-line snippets to type or use verbatim. Examples: `models/yolo`, `-seg`, `[PROMPT]`. + +## Cross-references + +- Use `...` whenever a hint refers to another control by its exact visible label. This includes setting names, tab names, and named buttons. +- Match the label exactly, including capitalization and spacing; readers look for the same string in the UI. +- Do not use `` and `` separately for cross-references; always combine them. +- Generic concept references (`the model`, `the prompt`, `the scheduler`) stay unstyled. + +## Tab naming + +- Refer to the unified generation tab as `Images` (the ModernUI label). Do not write "Control tab"; that label only exists in legacy Standard UI. +- "Control" remains valid as a setting value (`No: Control only`) or as part of a UI element name (`Control input` pane), just not as a tab name. + +## Structure + +- `
` for a line break within a paragraph. +- `

` for a paragraph break. +- `
- key: description` for a keyed bullet list, used for short enumerations of dropdown values, modes, or numeric brackets. Each bullet's key is bolded; descriptions stay plain. +- Do not use `
    `, `
  • `, Markdown asterisks, or unicode bullets. + +## Common pitfalls + +- Do not bold ad-hoc emphasis; `` is reserved for values and, combined with ``, for cross-references. +- Do not use `` for filenames, paths, or command tokens; those are literals and use ``. +- Do not reword the inside of `` blocks; they are literal user-facing strings. +- Stay ASCII; prefer semicolons or two sentences over em-dashes. The locale file convention is ASCII-only. + +## Translation propagation + +- `html/locale_en.json` is the source of truth. Other `html/locale_*.json` files are auto-generated by `cli/localize.js`; edit only the English file. +- Per-locale corrections live in `html/override_{locale}.json`. + +## Validation + +- Validate JSON syntax with `jq empty html/locale_en.json`. +- Lint with `pnpm eslint -- html/locale_en.json` (silent success). +- See `wiki/Hints.md` for the wiki-facing version of these rules.