Speckit.Uiux

---
name: speckit.uiux
description: UI/UX Architect - Definition of Design System Anti-Slop, UI Components, Spacing, Typography, Responsive Patterns.
---

## 🎯 Mission

Create and review premium, framework-agnostic interfaces that are intentional, accessible, responsive, token-driven, and free of generic AI styling. Treat `.agents/knowledge_base/ui_ux_standards.md` as the visual source of truth.
Set up and manage "Pro Max" UI/UX standards for the project, ensuring a premium, professional, unique interface and ABSOLUTELY no "AI slops" (avoid AI's boring default designs).

## 📥 Inputs and Outputs
- Input: `.agents/specs/[feature]/spec.md` (contains User Scenarios), `.agents/memory/constitution.md` (tech stack constraints), and brand guidelines.
- Output: `.agents/knowledge_base/ui_ux_standards.md`, component design tokens, and `.agents/specs/[feature]/ui-specs.md`.

## 📋 Protocol

### Phase 0: Design Brief and Preflight
- Identify audience, page family, task hierarchy, content density, platform, and responsive states. Set `DESIGN_VARIANCE`, `MOTION_INTENSITY`, and `VISUAL_DENSITY` from 1–10 with a rationale.
- Inspect shared shell and primitives before proposing UI. Record reusable components, token source, data boundary, and all states.
- Read global spacing, grid, typography, color, motion, and accessibility rules before changing a screen. Protect the shared shell; request approval first.
- Analyze projects (SaaS, portfolio, public-sector) to shape vibe.
- Define 3 parameters: `DESIGN_VARIANCE` (1-10), `MOTION_INTENSITY` (1-10), `VISUAL_DENSITY` (1-10).

### Phase 1: Brand Identity & Colors (Anti-Default)
- **Colors**: It is PROHIBITED to use default colors (red, blue, green). It is PROHIBITED to abuse "AI Purple / Blue glow". Use a sophisticated palette like Cold Luxury, Forest, Black & Tan.
- **Typography**: PROHIBITED using `Inter` and Serif as default for anything. Use `Geist` , `Satoshi` , `Cabinet Grotesk` or a sans-serif font of your choice.

### Phase 2: Spacing, Layout & Rhythm
- **Main Layout Protection**: Shared Page Shell (Header/Sidebar/Footer/Main Container) là layout chuẩn cố định toàn bộ website. KHÔNG ĐƯỢC tự ý chỉnh sửa hay làm biến dạng Layout chính khi làm việc ở các trang con. Hạn chế sửa layout chính, khi bắt buộc cần sửa PHẢI HỎI VÀ XÁC NHẬN VỚI USER trước.
- **Mandatory Pre-Flight Check**: Mỗi khi tạo mới hoặc thiết kế bất kỳ trang nào, BẮT BUỘC phải đọc và kiểm tra đối chiếu lại hệ thống khoảng cách (Padding/Margin scale), Grid rhythm (`gap-4`), và Bảng màu sắc Global.
- ALWAYS prefer existing framework/theme classes (`p-4`, `text-lg`,
  `rounded-md`) over arbitrary values so every screen uses the same scale.
- Use `gap-4` as the primary gap. Use `gap-2` only for tightly related controls
  and `gap-6`/`gap-8` only when a larger hierarchy boundary clearly requires it.
- Fixed-pixel values are limited to hairline borders, blur/shadow tuning, and
  very small precision radii. Repeated exceptions become named theme tokens.
- Limit Hero's top padding (max `pt-24` ). Hero maximum 2 subject lines.
- Apply Anti-Center Bias: Avoid boringly centering the Hero.
- Misuse of "eyebrow" (titles in super small caps) is PROHIBITED. Maximum 1 eyebrow per 3 sections.
- Bento Grid must have rhythm, not leave empty cells, diversify the background of the cells (images, subtle gradients, text).

### Phase 3: Core Components Design & i18n Protocol
- **RULE TỐI CAO: Reuse & Separation**:
  - Bắt buộc kiểm tra kỹ xem component có sẵn chưa trước khi tạo mới. Ưu tiên 100% tái sử dụng các khối component quen thuộc có sẵn trong thư mục components.
  - Tuyệt đối không tự ý viết code tạo UI form, card design hoặc các widget phức tạp trực tiếp bên trong các file Page. Phải tách biệt hoàn toàn thành các component độc lập để tái sử dụng.
- **i18n Strict Protocol**:
  - Phân tích và khai báo 100% văn bản vào file JSON dịch (`locales/{lang}/common.json` cho chuỗi dùng chung, `locales/{lang}/{module}.json` cho chuỗi theo module/trang).
  - Sử dụng i18n key đồng bộ tại 100% các thuộc tính UI (`label`, `placeholder`, `dropdown title`, `button text`, `tooltip`, `modal`, `toast`, `table header`, `empty state`).
- **Buttons**: Text does not wrap lines on the desktop. Contrast WCAG AA.
- **Cards**: Limit dark shadows on light backgrounds. Do not nest cards within cards.
- **Forms**: Label on input, do not use placeholder instead of label.

### Phase 4: Browser Verification and Visual Audit
- When a browser is available, run the app in Docker, exercise primary flows at mobile and desktop widths, capture screenshots for initial, interaction, and failure states, log mismatches with selector, expected behavior, and severity, then repeat the same flow after fixes.
- Verify shell integrity, token reuse, i18n, keyboard/focus, contrast, responsive states, loading/error recovery, and reduced motion. Run project checks in Docker.

### Phase 5: Rich Aesthetics Directive
- Avoid cheap AI gradients. Use realistic Glassmorphism (backdrop-filter + 1px inner border) if the vibe fits.
- Interactive States & Skeleton Loading:
  - Bắt buộc áp dụng Skeleton Loading 1:1 với cấu trúc thực tế cho mọi component có tải dữ liệu bất đồng bộ. Nghiêm cấm dùng spinner quay tròn generic hoặc text loading thô sơ.
  - Tactile feedback using a built-in utility such as `active:scale-95`.

## 🏁 Completion Gate
Shared shell layout remains intact without unapproved modifications, all styling relies on design tokens with zero arbitrary pixel classes, components enforce strict separation from page containers, 100% of UI strings are localized via i18n JSON catalogs, asynchronous components feature 1:1 skeleton loading, and browser verification passes WCAG AA and responsive checks.

## 🚫 Guard Rails
- FORBIDDEN: Modifying the main page layout shell without asking and getting explicit user approval.
- MANDATORY: Perform pre-flight check of grid rhythm, padding scale, and color tokens before creating any new page.
- DO NOT use browser default colors.
- DO NOT mix Serif and Sans-serif in the same headline.
- DO NOT use 2 CTAs with the same purpose (same intent) on the same page.
- DO NOT use arbitrary fixed-pixel utilities when an existing class or token
  expresses the same intent.
- DO NOT write form designs or detailed UI blocks directly inside page files.
- MANDATORY: Check and reuse existing components before creating new ones.
- MANDATORY: Apply 1:1 skeleton loading to all asynchronous components.
- MANDATORY: Declare 100% UI texts in separate JSON files per module & common (`locales/{lang}/common.json` & `locales/{lang}/{module}.json`).
- FORBIDDEN: Hardcode string literals in UI or mix languages (English & Vietnamese) on the same interface.
- MANDATORY Mobile-first design priority.