playbooks

home / skills / zhanghandong / makepad-skills / makepad-reference

makepad-reference skill

/skills/makepad-reference

This skill helps troubleshoot Makepad issues, provides reference guidance, and highlights debugging best practices for responsive layouts and code quality.

npx playbooks add skill zhanghandong/makepad-skills --skill makepad-reference

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.9 KB
---
name: makepad-reference
description: |
  CRITICAL: Use for Makepad troubleshooting and reference. Triggers on:
  troubleshoot, error, debug, fix, problem, issue,
  no matching field, parse error, widget not found, UI not updating,
  code quality, refactor, responsive layout, adaptive,
  api docs, reference, documentation,
  故障排除, 错误, 调试, 问题, 修复
---

# Makepad Reference

This category provides reference materials for debugging, code quality, and advanced layout patterns.

## Quick Navigation

| Topic | File | Use When |
|-------|------|----------|
| [API Documentation](./api-docs.md) | Official docs index, quick API reference | Finding detailed API info |
| [Troubleshooting](./troubleshooting.md) | Common errors and fixes | Build fails, runtime errors |
| [Code Quality](./code-quality.md) | Makepad-aware refactoring | Simplifying code safely |
| [Adaptive Layout](./adaptive-layout.md) | Desktop/mobile responsive | Cross-platform layouts |

## Common Issues Quick Reference

| Error | Quick Fix |
|-------|-----------|
| `no matching field: font` | Use `text_style: <THEME_FONT_*>{}` |
| Color parse error (ends in `e`) | Change last digit (e.g., `#14141e` → `#14141f`) |
| `set_text` missing argument | Add `cx` as first argument |
| UI not updating | Call `redraw(cx)` after changes |
| Widget not found | Check ID spelling, use `ids!()` for paths |

## Debug Tips

```bash
# Run with line info for better error messages
MAKEPAD=lines cargo +nightly run
```

```rust
// Add logging
log!("Value: {:?}", my_value);
log!("State: {} / {}", self.counter, self.is_loading);
```

## Resources

- [Makepad Official Docs](https://publish.obsidian.md/makepad-docs/) - Obsidian-based documentation
- [Makepad Repository](https://github.com/makepad/makepad)
- [Robrix](https://github.com/project-robius/robrix) - Production reference
- [Moly](https://github.com/moxin-org/moly) - Production reference

Overview

This skill is a focused reference and troubleshooting assistant for building apps with Makepad. It provides quick fixes for common errors, debugging tips, and pointers to API and layout patterns to get your UI running correctly across platforms. Use it when you hit build or runtime issues, need layout guidance, or want Makepad-aware refactors.

How this skill works

The skill inspects error messages, common failure patterns, and layout problems specific to Makepad projects and returns targeted fixes or next steps. It leverages a compact quick-reference of common errors and remedies, recommended debug commands, and logging examples to reproduce and resolve issues faster. It also points to authoritative resources for deeper API and pattern guidance.

When to use it

  • You see specific Makepad errors like ‘no matching field’ or color parse failures
  • Your UI is not updating or widgets cannot be found at runtime
  • You need a quick troubleshooting checklist before filing bugs
  • You want Makepad-aware refactoring or code-quality suggestions
  • You need responsive/adaptive layout patterns for cross-platform UI

Best practices

  • Run with line info for clearer error locations: MAKEPAD=lines cargo +nightly run
  • Add log! statements to inspect runtime state and values
  • Use ids!() and consistent ID spelling to resolve widget lookup problems
  • Call redraw(cx) after state changes to force UI updates
  • Prefer theme-aware text styles such as text_style: <THEME_FONT_*>{} for font fields

Example use cases

  • Fix a ‘no matching field: font’ error by switching to theme text_style usage
  • Resolve color parse issues by correcting trailing hex digits (example: #14141e → #14141f)
  • Troubleshoot missing set_text argument by ensuring cx is the first parameter
  • Debug UI not updating by inserting redraw(cx) after mutating state
  • Improve layout for desktop and mobile using adaptive-layout patterns and examples

FAQ

What first step should I take when a Makepad build fails?

Run with line info (MAKEPAD=lines cargo +nightly run) to get precise source locations, then inspect the error and apply the quick fix for that error type.

Why isn’t my widget being found at runtime?

Check ID spelling and hierarchical paths, and prefer ids!() for constructing reliable ID paths; also confirm the widget is actually instantiated before lookup.