ui Design.instructions

---
description: Glitch Payment Gateway admin UI design rules — mandatory element & component reference for WooCommerce settings
applyTo: 'admin/**'
---

# Glitch Payment Gateway — UI Design Instructions

## MANDATORY: Follow task.instructions.md

Before starting any UI work, you **MUST** also follow all rules in `.github/instructions/task.instructions.md`.

## MANDATORY: Read Before Any Admin UI Work

Before writing or modifying **any** UI element in the WooCommerce admin settings or custom admin views, you **MUST** read:

- `docs/plugin/features/3-admin-settings.md` — the settings field reference
- The matching split doc for the surface you're changing

## Strict Rules

1. **NEVER invent new CSS classes for admin pages.** Use WordPress core admin classes (`form-table`, `widefat`, `button`, `button-primary`, `notice`, `notice-success`, `notice-error`, etc.) and WooCommerce settings classes.

2. **NEVER hardcode colors, spacing, or sizing values.** Use WordPress admin CSS custom properties and WooCommerce's existing spacing conventions. Reference `wp-admin/css/common.css` patterns.

3. **Use the correct button variants:**
   - Primary action: `button button-primary`
   - Secondary action: `button`
   - Destructive: `button button-link-delete`
   - Small: add `button-small`

4. **Use WooCommerce Settings API for all settings fields.** Define fields via `init_form_fields()` — never render raw HTML form inputs for gateway settings. Valid field types: `text`, `textarea`, `select`, `multiselect`, `checkbox`, `password`, `title`, `decimal`.

5. **Use WordPress notice classes for admin messages:**
   - Success: `<div class="notice notice-success"><p>...</p></div>`
   - Error: `<div class="notice notice-error"><p>...</p></div>`
   - Warning: `<div class="notice notice-warning"><p>...</p></div>`
   - Info: `<div class="notice notice-info"><p>...</p></div>`

6. **No inline styles.** All custom styling goes in `assets/css/glitch-admin.css` and is enqueued via `admin_enqueue_scripts`.

7. **Use WordPress Dashicons for icons.** Reference via `<span class="dashicons dashicons-{name}"></span>`. Common ones: `dashicons-admin-generic`, `dashicons-shield`, `dashicons-warning`, `dashicons-yes-alt`, `dashicons-no-alt`.

8. **Escape all output in admin views.** Use `esc_html()`, `esc_attr()`, `wp_kses_post()` — never output raw HTML from user/API data.

## Quick Reference: Key Element Classes

| Element | Classes |
|---|---|
| Settings table | `form-table` |
| Primary button | `button button-primary` |
| Secondary button | `button` |
| Delete/destructive | `button button-link-delete` |
| Admin notice (success) | `notice notice-success is-dismissible` |
| Admin notice (error) | `notice notice-error` |
| Description text | `description` |
| Input field wrapper | `forminp forminp-{type}` |
| Section title | WooCommerce `title` field type |
| Tooltip | `woocommerce-help-tip` |