---
name: zc-ui-dev
description: "Zync UI development rules. Use before creating, editing, or reviewing any Zync frontend UI, design-system component, screenshot-derived screen, primitive, layout, style, or app shell work."
---

# Zync UI Development

## Non-Negotiable Rules

- Mockups in `screenshots/` are the visual source of truth for UI screens.
- First create and maintain a design-system page that shows every UI element available in the system.
- Create primitives first.
- Build product screens only from registered primitives and reusable design-system components.
- No raw HTML composition in product screens. Screens must be assembled from reusable components like lego bricks.
- Load `/componentizer` when writing/building new UI or changing the design system so the work follows componentized design-system patterns.
- Do not hardcode colors in CSS or component styles. Use design tokens/CSS variables only.
- When a new primitive is needed:
  - Build the primitive in the shared UI library.
  - Register it on the design-system page before using it in product screens.
  - Add usage guidance to this skill so future agents know when to use it.
- Screenshot matching never overrides accessibility, responsive behavior, tenant permissions, or design-system consistency.

## Required Workflow

1. Open the target screenshot or identify the missing screenshot.
2. Break the UI into regions: shell, toolbar, filters, content, detail panel, modal, table, form, empty state, loading state, and error state.
3. Map every region to an existing primitive or design-system component.
4. If a primitive/component is missing, create it first.
5. Register the primitive/component on the design-system page.
6. Compose the screen using only registered primitives/components.
7. Apply `/componentizer` guidance while composing the UI.
8. Verify desktop and mobile screenshots.
9. Update this skill with any new durable UI rule or primitive usage guidance.

## Primitive Expectations

The shared UI library should provide primitives for:

- Button and icon button.
- Input, textarea, select, combobox.
- Checkbox, radio, switch, segmented control.
- Tooltip, popover, dropdown menu.
- Dialog, drawer, sheet.
- Tabs.
- Badge, status pill, alert.
- Table/data-grid shell and pagination.
- Form field, label, help text, error text.
- File upload/dropzone.
- Empty, loading, skeleton, and error states.
- Toolbar, filter bar, active filter chips.
- Page header, settings section, detail panel.
- Activity timeline, comment composer, attachment list.
- Kanban column/card shell.

## Design-System Page Requirements

The design-system page must include:

- Tokens: colors, typography, spacing, radius, shadows, focus rings, motion.
- Every primitive in normal, hover, focus, disabled, loading, error, and compact states where relevant.
- Composite components with realistic Zync examples.
- White-label theme preview.
- RTL examples for Hebrew.
- Mobile and desktop examples for dense operational UI.

## Screenshot Rules

- Do not implement a screen from memory when a screenshot exists.
- Do not copy screenshot visuals by writing one-off markup.
- If the screenshot requires a new visual pattern, componentize it first.
- If the screenshot conflicts with accessibility or responsive layout, preserve accessibility/responsiveness and document the deviation.
- If text overflows or overlaps at any supported viewport, the UI is not done.

## Componentizer Skill Usage

Load `/componentizer` when working on:

- New screens.
- Screen rewrites from screenshots.
- Design-system changes.

Treat these as blocking design issues when found:

- Raw table/form/button/card markup where shared components exist.
- Repeated UI structure across 3+ files that should become a primitive/composite.
- Hardcoded colors or styles that bypass tokens.
- New primitive used in product UI but missing from the design-system page.
- Component added but not documented in this skill.

## Current Registered Primitive Guidance

No project primitives have been implemented yet. Before the first app screen, create the initial primitive set and the design-system page.