OpenParable
Skip to content
← Back to skills

Rezi Add Widget

Development
rezi-add-widget

Rezi Add Widget is an Agent Skill for development published in the RtlZeroMemory/Rezi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add a new widget type to the Rezi framework. Use when creating new ui.* factory functions with layout, rendering, and tests.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RtlZeroMemory/Rezi/blob/HEAD/.claude/skills/rezi-add-widget/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rezi-add-widget, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Response Format (IMPORTANT)

  1. Confirm the widget name, behavior, and props before writing code
  2. Follow the steps below in order — each step depends on the previous
  3. Run tests after implementation to verify correctness
  4. Keep total response concise — show key code, not boilerplate

When to use

Use this skill when:

  • Adding a new widget type to @rezi-ui/core
  • Creating a new ui.* factory function
  • User asks for a new visual element not covered by existing widgets

Source of truth

  • packages/core/src/widgets/types.ts — all widget prop types and VNode union
  • packages/core/src/widgets/ui.ts — all ui.* factory functions
  • packages/core/src/layout/kinds/ — layout handlers by category
  • packages/core/src/renderer/renderToDrawlist/widgets/ — render handlers by category
  • packages/core/src/index.ts — public exports
  • packages/core/src/ui/ — design tokens, recipes, and capabilities
  • docs/guide/widget-authoring.md — widget authoring guide with design system integration

Steps

  1. Add props type to packages/core/src/widgets/types.ts:

    • Use the Readonly<{...}> pattern
    • Include key?: string if the widget can appear in lists
  2. Add VNode kind to the VNode discriminated union in types.ts

  3. Add factory function to packages/core/src/widgets/ui.ts:

    • Add JSDoc with @example tag
    • Return a VNode with the correct kind
  4. Add layout handler in packages/core/src/layout/kinds/:

    • leaf.ts for non-container widgets
    • box.ts / stack.ts for containers
    • collections.ts for data widgets
    • overlays.ts for layered widgets
  5. Add render handler in packages/core/src/renderer/renderToDrawlist/widgets/:

    • basic.ts, containers.ts, collections.ts, editors.ts, overlays.ts, navigation.ts, or files.ts
  6. Add design system support (if the widget is interactive):

    • Register the new widget kind in packages/core/src/widgets/protocol.ts
    • Add optional DS props as needed (dsVariant?, dsTone?, dsSize?) for advanced customization
    • Wire recipe-based rendering so baseline DS styling auto-activates when ThemeDefinition semantic tokens are available; DS props override defaults when specified
    • See docs/guide/widget-authoring.md for the full pattern
  7. Export both props type and factory from packages/core/src/index.ts

  8. Add JSX wrapper (if needed) in packages/jsx/src/components.ts

  9. Write tests in packages/core/src/widgets/__tests__/

  10. Add docs in docs/widgets/{widget-name}.md

Verification

node scripts/run-tests.mjs
  • Widget + props exported from packages/core/src/index.ts
  • Renders correctly via createTestRenderer
  • Layout produces expected dimensions
  • Widget supports ds* props for design-system-based styling (if interactive)
  • Widget renders correctly with at least 2 themes