# 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.

- Skill name: `rezi-add-widget`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/RtlZeroMemory/Rezi/blob/HEAD/.claude/skills/rezi-add-widget/SKILL.md
- Repository: RtlZeroMemory/Rezi (655 GitHub stars when collected)

## SKILL.md

## 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

```bash
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

---

Source: https://www.openparable.com/skill/development/rezi-add-widget (OpenParable). Cite the canonical URL above.
