菜单
Use when writing, reviewing, or refactoring Slint (.slint) UI files — covers component design, property bindings, callbacks, state management, layouts, accessibility, translations, theming, and integration with Rust backend
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jpfaria/OpenRig --skill slint-best-practices命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | slint-best-practices |
| description | Use when writing, reviewing, or refactoring Slint (.slint) UI files — covers component design, property bindings, callbacks, state management, layouts, accessibility, translations, theming, and integration with Rust backend |
Sources:
Antes de escrever/alterar qualquer .slint, invoque TAMBÉM claude-plugin:ux-ui (design/UX). Esta skill cobre a MECÂNICA do Slint (bindings, layouts, @tr, globals); ela não diz nada sobre hierarquia visual, densidade, contraste, estados vazio/erro, ou se a tela funciona pro usuário. As duas são gate, não uma ou outra.
Why: invocar só a de Slint produz tela que compila e renderiza, mas com decisão visual inventada por mim — exatamente o que a LEI de UI/Slint do CLAUDE.md proíbe ("PROIBIDO supor/inventar layout"). Já aconteceu: overlay inteiro construído com slint-best-practices só, sem a skill de UX.
How to apply: trabalho de tela → claude-plugin:ux-ui + slint:slint + esta skill, ANTES da primeira linha; depois renderize com tools/slint-render e confira o PNG antes de dizer "pronto".
Princípios gerais de UI (responsividade, separação business/presentation, zero coupling) vivem em openrig-code-quality. As regras Slint-específicas do projeto:
xgodev/quality-gateGate único mantido fora do repo (igual local e CI). Compara 6 métricas do PR vs origin/develop — se algum erro de compilação Slint novo entrar, build errors aumentam e o gate falha. Antes de qualquer git push (ou via skill claude-plugin:quality-gate):
git -C ~/.quality-gate pull --ff-only \
|| git clone --depth 1 https://github.com/xgodev/quality-gate.git ~/.quality-gate
~/.quality-gate/qg --base origin/develop
Falha em CI vira sticky comment + request-changes formal. Detalhes em docs/development/quality-gate.md.
.slint (hard cap)./scripts/validate.sh enforces ≤ 500 lines for every .slint. Se um arquivo passa, dividir antes de adicionar mais qualquer coisa. Esta é a operacionalização Slint do princípio "one responsibility per file" do openrig-code-quality.
sed -i em arquivos .slintsed -i em macOS/BSD pode esvaziar um .slint por causa de issues de encoding/locale (vimos isso quebrar arquivos de UI em outras issues). Use o Edit tool sempre.
❌ sed -i '' 's/old/new/g' app.slint
// PERIGO: pode esvaziar o arquivo
✅ Edit tool com old_string/new_string
@image-url() é compile-time — sem strings dinâmicas@image-url() resolve no momento da compilação Slint. Não aceita variável runtime. Para selecionar imagem por model_id ou brand, use ternary chain:
✅ Image {
source: root.brand == BRAND_MARSHALL
? @image-url("../assets/brands/marshall/logo.svg")
: root.brand == BRAND_VOX
? @image-url("../assets/brands/vox/logo.svg")
: @image-url("../assets/brands/openrig/logo.svg");
}
❌ Image {
source: @image-url("../assets/brands/" + root.brand + "/logo.svg");
// FALHA: @image-url precisa string literal compile-time
}
A consequência prática para o catálogo OpenRig: cada novo brand exige tocar a chain de ternários nos componentes que renderizam a logo. Isso é uma exceção autorizada ao "zero coupling" — Slint não tem outra forma. Centralize a chain em UM componente (BrandLogo.slint) para minimizar pontos de toque.
model_id em SlintPrincípio em openrig-code-quality (separation of concerns). Operacionalização Slint:
❌ if root.model_id == "marshall_jcm_800": Rectangle { background: #6c2a1a; }
// WRONG: cor hardcoded no Slint por model_id
✅ private property <color> panel-bg:
root.block-model-options[index].panel_bg;
// CORRETO: cor vem de visual_config (UI layer Rust), exposto como property Slint
O BlockEditorPanel deve renderizar qualquer effect_type baseado no schema, não em if effect_type == "preamp". Adicionar um effect_type novo NÃO deve exigir mudança no Panel.
Separar código, UI e assets em diretórios distintos:
my-project/
├── src/ # lógica de negócio (Rust)
├── ui/
│ ├── app-window.slint # entry point
│ └── components/ # componentes reutilizáveis
└── images/ # SVGs, PNGs, assets
Regra: Nenhuma lógica de negócio dentro de .slint. Slint é declarativo — computações pertencem ao Rust.
Sempre declarar acesso explícito em componentes:
| Modificador | Uso |
|---|---|
in | Dado vem de fora (pai → filho) |
out | Dado vai para fora (filho → pai) |
in-out | Bidirecional (usar com cautela) |
private | Interno ao componente (default) |
component MyButton {
in property <string> label; // pai configura
out property <bool> pressed; // pai observa
private property <bool> hovered; // interno
}
Evitar in-out sem necessidade — bidirecionalidade cria acoplamento difícil de rastrear.
Bindings se re-avaliam automaticamente quando dependências mudam. Nunca atribuir manualmente o que pode ser um binding.
// ✅ Binding reativo — atualiza automaticamente
Text { text: root.count > 0 ? "Items: \{root.count}" : "Empty"; }
// ❌ Evitar — imperativo, perde reatividade
Text {
text: "Items";
// lógica imperativa via callback para atualizar text = ...
}
Regra: Prefira expressões ternárias e bindings declarativos sobre callbacks que modificam estado.
component SearchBar {
callback search-requested(string); // filho notifica pai
callback clear-requested();
// ❌ Evitar: callback que retorna dado para o filho
// callback fetch-data() -> [DataModel]; // acoplamento invertido
}
in)<=> para two-way binding entre propriedades de mesmo nívelcomponent Toggle {
in-out property <bool> checked;
private property <brush> bg: #444;
animate bg { duration: 200ms; easing: ease-in-out; }
states [
on when root.checked: { bg: #4CAF50; }
]
}
animate deve ser declarado fora do bloco states (aplica-se à transição)// ✅ Use componentes de layout semânticos
VerticalBox {
HorizontalBox {
Button { text: "Cancel"; }
Button { text: "OK"; }
}
}
// ❌ Evitar posicionamento manual com x/y para layouts
Rectangle {
Button { x: 10px; y: 200px; } // frágil, não responsivo
}
VerticalBox / HorizontalBox para layout semânticoGridLayout + Row para gridsx, y) apenas para overlays e elementos decorativospreferred-width/preferred-height em vez de valores fixos quando possívelDeclarar em todo componente interativo customizado:
component CustomButton {
in property <string> text;
accessible-role: button;
accessible-label: self.text;
accessible-action-default => { clicked(); }
}
accessible-role é obrigatórioaccessible-label deve ser texto legível por humanos// ✅ Correto — permite reordenação pelo tradutor
Text { text: @tr("Hello, {}", name); }
// ❌ Errado — concatenação dificulta tradução
Text { text: @tr("Hello, ") + name; }
// ❌ Esqueceu o @tr
Text { text: "Save Project"; }
Toda string visível ao usuário deve usar @tr("...").
Use global para estado compartilhado entre componentes sem prop-drilling:
export global AppTheme {
out property <color> accent: #4CAF50;
out property <length> spacing: 8px;
}
// Uso em qualquer componente
Rectangle { background: AppTheme.accent; }
export para uso no Rust// Rust: ler propriedade
let val = ui.get_my_property();
// Rust: definir propriedade
ui.set_my_property(42);
// Rust: conectar callback
ui.on_button_clicked(|| { /* handler */ });
my-prop → my_prop)let ui_weak = ui.as_weak();
ui.on_clicked(move || {
let ui = ui_weak.upgrade().unwrap();
ui.set_count(ui.get_count() + 1);
});
@image-url() é resolvido em compile-time — não aceita strings dinâmicas.
// ✅ Ternário para seleção condicional
Image {
source: root.model-id == "amp_a"
? @image-url("../assets/amp_a/controls.svg")
: @image-url("../assets/generic/controls.svg");
}
// ❌ Impossível — @image-url não aceita variável
// Image { source: @image-url(root.model-id + "/controls.svg"); }
Para muitos modelos, use if/else encadeado ou componentes separados por tipo.
| Elemento | Convenção | Exemplo |
|---|---|---|
| Componentes | PascalCase | BlockEditorPanel |
| Propriedades | kebab-case | block-type-index |
| Callbacks | kebab-case | block-selected |
| Globals | PascalCase | AppTheme |
| Estados | kebab-case | is-hovered |
| Anti-padrão | Correto |
|---|---|
Lógica de negócio em .slint | Computar no Rust, expor via propriedade |
Strings literais sem @tr | @tr("string") |
x/y absolutos para layout | VerticalBox/HorizontalBox |
in-out desnecessário | in ou out conforme direção |
String dinâmica em @image-url | Ternários encadeados em compile-time |
| Callbacks que retornam dados | Propriedades out para dados, callbacks para eventos |
| Closures Rust sem weak ref | ui.as_weak() + upgrade() |