Frontend UI Research & Synthesis Designer

Use this skill when building or upgrading frontend UI so the result feels
professional, researched, and product-fit — not like a generic template.

Non-Negotiable Principles

1. Deep context first — understand product, user, workflow, route, API, state, permissions, and risk before design.
2. Research before design — do not start substantial UI coding immediately.
3. Taste through comparison — compare multiple strong products; learn why they work.
4. Synthesize, do not copy — extract principles from several references; never clone one.
5. System before screen — define palette usage, typography, spacing, radius, shadows, cards, tables, forms, charts, and states before polishing isolated pages.
6. Fit the product — beauty must serve the current users, data, and workflows.
7. Function before decoration — routes, auth, permissions, API contracts, CRUD, workflows, backend data, mutations, validation, loading/error states, and side effects must stay wired unless explicitly approved.
8. Smooth UX matters — beautiful UI is not done until user actions are reliable, responsive, accessible, and hard to misuse.
9. Polish matters — spacing, alignment, typography, density, states, contrast, and micro-interactions decide quality.
10. Critique before final — do not accept the first pass; critique structure, visual quality, UX reliability, and technical safety.
11. Product fit over trend — avoid trendy UI that does not fit Viet Eyewear ecommerce, admin, CRM, Blog & SEO, or luxury retail taste.
12. Desktop and mobile are designed together — never treat mobile as an afterthought; layout, image crop, CTA position, nav, and density must be planned and QA'd for desktop, tablet, and mobile in the same pass.
13. Imagery coherence is part of design quality — luxury UI fails if photos do not share compatible subject, crop, lighting, color temperature, scale, and context.

AWA Brand Dependency

For AWA / Viet Eyewear, this skill is subordinate to:

.agents/skills/awa-brand-identity/SKILL.md

Use that file as the single source of truth for palette, typography, spacing,
component taste, navigation constraints, forbidden colors, and quick replacement
rules.

Before any AWA UI work:

1. Read awa-brand-identity first.
2. Apply this skill only for research, synthesis, workflow preservation, UX
   planning, critique, and verification.
3. Do not duplicate or reinterpret brand tokens here.
4. If research references use non-brand colors or SaaS status colors, translate
   the pattern through awa-brand-identity instead of copying the colors.
5. If a needed UI pattern appears to require a palette change, stop and ask the
   user for explicit approval before coding.

Rule of thumb:

awa-brand-identity = brand law
frontend-ui-research-synthesis-designer = design/research/QA process

When To Use

Use for:

• public storefront redesign/polish
• admin console/dashboard redesign
• landing/product/blog/contact visual redesign
• typography/spacing/component system overhaul
• tables, filters, cards, forms, charts, drawers, modals
• Blog & SEO UI polish where workflow must remain stable

Do not use for:

• backend rewrites
• schema/database changes
• API contract changes
• auth/payment/security changes
• changing Blog & SEO workflow without approval

Required Inputs To Audit

Before proposing UI changes, identify:

• product goal and target user
• page/module being improved
• current route and component tree
• real data source, query/fetch path, cache/revalidation behavior, and loading/error states
• backend actions/mutations used by the page: create, update, delete, submit, publish, upload, checkout, login, callback, sync
• current forms, validation rules, disabled states, optimistic updates, success/error feedback, and retry behavior
• auth/session/permission requirements for every visible action
• current actions and protected workflows
• style system and brand constraints
• areas explicitly out of scope
• visible UX pain points

If information is missing, inspect code first. Ask only when the decision risks
breaking workflow, data, auth, or brand direction.

Opus-Style Codebase Intelligence

Before designing, produce an internal map:

Codebase Map:
- Framework:
- Routes:
- Key pages:
- Shared components:
- Style/theme system:
- Data/API services:
- Hooks/data fetching:
- Auth/session:
- Permission/role:
- Forms/validation:
- Upload/import/export:
- Blog & SEO workflow:
- High-risk modules:
- Safe UI refactor zones:

For Viet Eyewear, treat these as protected unless explicitly approved:

• route structure
• API contracts
• database schema/migrations
• auth/session/permission model
• CRUD/business workflow
• media upload flow
• checkout/payment/billing/x402
• Blog & SEO editor, content planner, slug/canonical, metadata, publish/schedule, media, approval, OpenClaw/n8n/Codex contracts

If a UI idea requires changing protected behavior, stop and ask.

Market / UI Research Workflow

1. Classify the Interface

Examples:

• ecommerce admin
• CRM/customer management
• analytics dashboard
• CMS/blog system
• SEO operations tool
• inventory/order management
• marketing campaign console
• public luxury storefront

For Viet Eyewear, common types:

• luxury ecommerce storefront
• ecommerce admin
• CRM/customer management
• Blog & SEO operations
• analytics/finance dashboard
• internal system management

2. Research Quality References

Use several relevant references. Good default sources:

Ecommerce / Admin

• Shopify Admin / Polaris
• WooCommerce Admin
• Square Dashboard
• Lightspeed Retail
• BigCommerce Admin

SaaS / Dashboard

• Stripe Dashboard
• Vercel Dashboard
• Linear
• Supabase Dashboard
• PostHog
• Railway / Render
• Clerk / Resend

CRM / Sales

• HubSpot CRM
• Attio
• Pipedrive
• Folk CRM
• Close CRM

CMS / Blog / SEO

• Webflow CMS
• Framer CMS
• Notion database
• Contentful
• Sanity Studio
• Ghost Admin
• Ahrefs / Semrush
• SurferSEO / Frase / Clearscope

Public Luxury / Ecommerce

For elegant industries such as eyewear, do not research only eyewear websites.
Eyewear sits close to jewelry, fashion, beauty, leather goods, watches, luxury
retail, boutique hospitality, and editorial magazines. Research adjacent luxury
categories to identify the correct visual taste level for the industry.

Required adjacent-industry references for luxury storefront work:

• high-end eyewear and optical maisons
• jewelry maisons and fine jewelry ecommerce
• watches and leather goods
• high fashion / couture / ready-to-wear
• premium beauty and fragrance
• luxury hotel / boutique hospitality editorial sites
• art galleries, auction houses, architecture/interior studios
• editorial fashion magazines and lookbooks

What to learn from adjacent luxury industries:

• how they create desire with restraint, not clutter
• product photography scale and crop discipline
• editorial typography pairing and tight tracking
• whitespace, pacing, and section rhythm
• black/white/gold/gray material language
• boutique appointment and private-service storytelling
• refined microcopy, labels, and CTA hierarchy
• quiet motion and hover states
• premium empty space without looking unfinished

Never copy a luxury brand one-to-one. Extract the taste principles and translate
them into Viet Eyewear's own brand system.

Use Dribbble/Behance/Figma Community only for mood and visual inspiration, not
as the source of UX truth.

3. Capture Patterns

For each source, note:

• overall layout
• sidebar/topbar/nav pattern
• page header pattern
• card/table/filter pattern
• KPI/chart pattern
• form/modal/drawer pattern
• loading/empty/error states
• typography scale
• spacing rhythm
• button/action hierarchy
• badge/status treatment
• responsive behavior: desktop, tablet, mobile, first fold, nav, CTAs, image crop, overflow
• industry taste signal: what makes it feel luxury, refined, or editorial
• imagery system: subject type, crop ratio, lighting, background, product scale, negative space, color temperature
• what is beautiful
• what does not fit this project

4. Research Matrix

Create an internal or artifact table before major UI coding:

Source	Pattern to learn	Why it works	Fit for project	Apply how
Shopify Polaris	Resource index, cards, common actions	Clear merchant workflows	Yes	Product/order/admin tables
Stripe	Contextual actions, constrained components	Consistent, accessible, trustworthy	Yes	Finance/admin forms/actions
Linear	Calm density, typography, sidebar polish	Refined hierarchy	Partial	Spacing/interaction rhythm
Webflow CMS	Visual content workflow, SEO/content controls	Strong CMS mental model	Yes	Blog & SEO UI only
Ahrefs/Semrush	SEO tables and audit statuses	Domain-specific clarity	Yes	SEO ops lists/audits
Jewelry maison	Product desire, macro detail, ceremony, appointment CTAs	Elegant and intimate	High	Public product/detail/contact pages
High fashion	Editorial grid, campaign imagery, typography scale	Creates taste and authority	High	Homepage/lookbook/story sections
Watches/leather goods	Material close-ups, specification hierarchy	Premium product confidence	Medium	Product detail and care sections
Beauty/fragrance	Ritual storytelling, soft product education	Strong service narrative	Medium	Fitting/care/consultation copy
Luxury hospitality/interiors	Calm pacing, private service language	Makes appointments feel premium	Medium	Contact/booking/store experience

Aesthetic Taste Gate

Before choosing a direction for luxury/elegant industries, explicitly answer:

• Does this look like a refined brand, not a generic ecommerce template?
• Does the page feel curated, calm, and editorial?
• Are typography, image crop, spacing, and CTA hierarchy tasteful?
• Is there enough whitespace to feel premium, but not empty or unfinished?
• Are we using restraint instead of decoration?
• Does it match the product category's social expectation: eyewear as accessory,
  fashion object, and precision fitting service?
• Can the design be improved further with one small high-leverage polish pass?
• Do the selected images feel like one collection, not random stock photos?
• Does the page remain equally intentional on desktop, tablet, and mobile?

If the answer is weak, do another research/synthesis loop before coding.

Beauty Filter

A pattern is usable only if it improves most of:

• clarity: user knows where they are and what matters
• hierarchy: title, summary, content, metadata, actions are clear
• spacing: neither cramped nor empty
• alignment: columns, icons, cards, and text line up
• contrast: readable but not harsh
• consistency: buttons, cards, tables, badges share rules
• density: admin pages show enough useful data
• actionability: next action is obvious
• interaction reliability: buttons, forms, filters, pagination, links, modals, drawers, uploads, and submissions work with backend state
• data honesty: no fake metrics or hidden failures
• product fit: matches Viet Eyewear and current workflow

Imagery Coherence Gate

For luxury storefront work, image quality and image selection are first-class UI.
Before implementation, define an image system:

• subject: product close-up, face wearing eyewear, hands/fitting, boutique/studio detail
• crop: consistent ratios per section; avoid random face/body crops
• lighting: calm natural or studio-soft; avoid harsh inconsistent color casts
• background: neutral, porcelain, white, gray, boutique interior; avoid noisy scenes
• scale: eyewear should feel intentional and visible, not accidental decoration
• rhythm: hero, product, craft, and service images should feel like one editorial story
• mobile crop: verify important subject remains visible at narrow widths

Do not rely on color palette alone to make a page feel premium. If images feel mismatched, replace the image strategy or reduce image count before adding more layout decoration.

Synthesis Process

Before implementation, decide:

Layout Backbone

• fixed/collapsible sidebar or top nav
• topbar contents
• content max width vs full width
• dashboard column system
• table-first vs card-first page

Visual Language

• approved palette and accent mapping
• typography scale
• border radius
• border/shadow level
• icon style
• chart style
• density level

Component System

Standardize:

• button
• input/select/textarea
• card/panel
• table/list
• badge/status
• modal/drawer
• tooltip/toast
• skeleton/loading
• empty/error state

Page Pattern

Each page should have:

1. clear page header
2. KPI/summary row when useful
3. filter/search/action bar for lists
4. main content area
5. secondary insight panel if useful
6. loading/empty/error states

Remove What Does Not Fit

Do not import patterns that:

• require data that does not exist
• increase workflow risk
• add visual noise
• violate AWA brand
• make admin too sparse
• copy another product too closely

Viet Eyewear Admin Direction

Default direction:

• warm light
• ivory / cream / warm white surfaces
• beige hairline borders
• black/brown primary action
• gold/brown accent
• calm, premium, reliable, modern retail
• operationally clear
• editorial enough for Blog & SEO
• no dark dashboard by default
• no neon, heavy shadow, noisy gradients, or generic SaaS blue

Recommended layout:

• left sidebar for admin
• slim topbar
• content padding with responsive max width
• active sidebar as subtle ivory/gold/black treatment
• breadcrumb/page title visible
• card/table density tuned for operations

Recommended admin DNA, translated through awa-brand-identity:

• Page title: 28–32px, strong but not loud.
• Section title: 20–22px.
• Card title: 16–18px.
• Body: 14–16px.
• Metadata/labels: 12–13px, muted, optional uppercase for KPI labels.
• Spacing scale: 4, 8, 12, 16, 20, 24, 32, 40, 48. No random spacing.
• Card radius: 18–24px.
• Input/button radius: 12–16px.
• Modal/drawer radius: 20–28px.
• Shadows: soft and low-opacity; avoid heavy template shadows.
• Status color: use brand-safe mapping; do not introduce random bright palette.

Core component expectations:

• Button hierarchy: primary, secondary, ghost, destructive.
• Icon-only buttons need aria-label and preferably tooltip.
• Badges need clear status mapping.
• Tables need row hover, loading, empty, and error states.
• Forms need label, required, disabled, pending, error, success states.
• Destructive actions need confirmation.
• Charts need empty/error states and honest labels.
• Drawers/modals need close/cancel behavior and focus safety.

Page-Level Workflow

For each page:

Audit

Answer:

• what is this page for?
• what task does user complete here?
• what data/actions exist now?
• what must not break?

UX Plan

Decide:

• first information seen
• primary action position
• search/filter needs
• table vs cards
• KPI usefulness
• drawer/modal need
• empty/loading/error handling

Visual Plan

Decide:

• grid/layout
• component hierarchy
• spacing
• typography
• badge/status rules
• responsive behavior

Responsive Plan

For every public storefront redesign, define desktop and mobile together:

• desktop first fold: title, primary CTA, and visual subject visible without awkward scrolling
• mobile first fold: primary CTA reachable/visible where appropriate; no hidden horizontal overflow
• tablet: grid breaks should be intentional, not accidental
• nav: brand/menu/search/cart must fit at 360px, 390px, 500px, and desktop widths
• imagery: mobile object position/crop must preserve the important subject
• density: reduce tile count/height on mobile instead of creating endless scroll
• interaction QA: test primary links/forms/search/sort on at least one desktop and one mobile width

Implementation

• refactor UI only first, but keep all existing data wiring visible and testable
• keep services/API unchanged unless explicitly approved
• use real data when available; never replace production data with static mock
• preserve forms, links, buttons, submit handlers, filters, search, sorting, pagination, modals, drawers, uploads, and mutations
• preserve auth/session/permission gates and server/client boundaries
• add safe loading/empty/error/success/disabled/pending states
• prevent double-submit and confusing stale states on important actions
• preserve actions
• test responsive and test at least the main happy-path interaction

Review

Ask:

• is it visibly more premium?
• is workflow clearer?
• did any route/API/action break?
• is any component inconsistent?
• is there any hard-coded fake data?

Opus-Style Page Algorithm

Every substantial page should pass these steps before implementation:

1. Purpose — page goal, user task, success condition.
2. Existing Function Map — data source, API/service, actions, forms, validation, permissions, loading/error, navigation side effects.
3. Priority Stack — primary data, primary action, secondary data/action, metadata, optional insight.
4. Layout Type — dashboard grid, table-first, form-first, master-detail, split view, calendar, kanban, media grid, settings sections.
5. UI Pattern — header card, KPI row, filter bar, data table, chart card, detail drawer, timeline, status tabs, action menu, empty state.
6. Real Data Binding — API, loading, empty, error, pagination, search/filter, permission state.
7. Polish — spacing, alignment, typography, radius, shadow, border, icon, badge, microcopy, responsive.
8. Safety Test — route/data/action/auth/permission/Blog & SEO workflow still intact.

Three-Pass Build Loop

Major UI work must not stop at the first draft.

Pass 1 — Structure & Safety

• audit route/API/component
• establish layout
• preserve real data and actions
• keep workflow intact
• avoid protected logic changes

Pass 2 — Visual Polish

• refine spacing, typography, cards, tables, buttons, badges, charts, icons
• align with brand tokens
• remove generic template feel
• reduce visual noise

Pass 3 — UX & Reliability

• loading/empty/error/permission states
• pending/disabled states
• confirm destructive actions
• responsive desktop/tablet/mobile
• keyboard/focus/accessibility basics
• typecheck/lint/build
• browser QA for real actions when safe
• verify desktop/tablet/mobile together; if one breakpoint fails, the page is not done

Blog & SEO Special Rule

For Blog & SEO UI, inspiration is limited to:

• Webflow CMS
• Ghost Admin
• Contentful
• Sanity
• Notion database
• Ahrefs
• Semrush
• SurferSEO
• Frase
• Clearscope

Allowed without workflow approval:

• visual list/table/card polish
• status badge styling
• spacing/alignment polish
• filter/search layout
• empty/loading/error state
• responsive improvements
• settings/sidebar visual grouping
• schedule/calendar display only if logic unchanged

Requires explicit user approval:

• Content Planner workflow changes
• Blog Studio editor changes
• SEO field/schema changes
• slug/canonical logic
• keyword/content brief model
• publish/schedule logic
• media upload flow
• approval workflow
• routes or database schema
• permissions

Before touching Blog & SEO, answer:

Blog & SEO Safety Check:
- Module being edited:
- Current workflow:
- Editor involved?
- SEO metadata involved?
- Schedule/publish involved?
- Media upload involved?
- Is this visual-only or logic-changing?
- Need user approval?

If the answer may affect logic, stop and ask.

Required Output Before Major UI Code

For non-trivial UI work, create/update implementation_plan.md with:

1. Codebase Audit Summary

• routes
• key pages
• existing components
• style/theme system
• API/service/data fetching
• auth/permission
• high-risk modules
• safe UI refactor zones

2. UI Research Summary

Source	Pattern	Why useful	Fit	Apply to

Include patterns rejected and why.

3. Design Direction

• mood
• palette within brand constraints
• typography
• layout backbone
• component style
• table/form/card/badge/chart system
• interactions/micro-polish
• responsive behavior

4. Page Safety Plan

Page	Existing functions to preserve	Safe UI improvements	Do not change

5. Implementation Plan

• phases
• page/component order
• files likely touched
• data/API to preserve
• protected modules
• risk notes

6. Test Plan

• typecheck
• lint
• build
• main actions
• browser QA
• responsive screenshots when major UI
• Blog & SEO safety when relevant

Safety Checklist

• routes preserved
• API preserved
• auth preserved
• permissions preserved
• CRUD/actions preserved
• real backend data remains connected
• forms, submit handlers, mutations, filters, search, pagination, uploads, modals, drawers, and links still work
• loading, pending, empty, success, and error states are present where needed
• no static mock replaces real data or hides backend failure
• Blog & SEO workflow preserved
• responsive QA planned

UI Scoring Rubric

Score after implementation. If under 85/100, improve before declaring done.

Area	Points
Visual quality: color, typography, spacing, borders/shadows	20
UX clarity: hierarchy, navigation, action clarity, states	20
Product fit: Viet Eyewear, ecommerce/CRM/SEO, real data fit	15
Industry taste fit: luxury/elegant category signal, restraint, product desire	10
Interaction reliability: forms, buttons, filters, links, pending/error/success states	15
Consistency: components, status, layout	15
Function safety: real data, CRUD/action, route, auth, permission, Blog SEO	25
Responsiveness: desktop/tablet/mobile	10
Code quality: components, no duplication/hard-code, type/lint/build	10

Normalize to 100. Never mark a UI as done if:

• normalized score is under 85
• route/API/auth/permission breaks
• real data was replaced by fake static data
• Blog & SEO workflow changed without approval
• industry taste fit is weak for luxury/elegant UI

Self-Critique Loop

Run at least two critique loops for major UI changes:

Design Critique

• premium enough?
• correct industry taste for eyewear/luxury/accessory retail?
• template-looking sections?
• weak typography, image crop, spacing, or material rhythm?
• too many colors/effects?
• weak hierarchy?

UX Critique

• can user scan quickly?
• is next action clear?
• are tables/forms easy to use?
• are states useful?

Technical Critique

• route/API/auth/permission unchanged?
• all previous backend data fetches still connected?
• forms, buttons, links, search, filters, pagination, uploads, modals, drawers, and mutations still work?
• loading/pending/success/error/empty states are honest and usable?
• no fake data replacing real data?
• no static mock hiding backend errors?
• no Blog & SEO workflow changes?
• TypeScript/lint/build clean?

Continuous Improvement Critique

• what is the single weakest visual detail now?
• what adjacent-industry reference would improve it?
• what one small polish would raise perceived quality most?
• did the implementation create a reusable design rule for future work?
• should that rule be added back to this skill or awa-brand-identity?

Verification Defaults

• git status --short before editing
• typecheck/lint after code changes
• browser QA for visual changes
• desktop + mobile screenshots for major UI changes
• exercise real user flows in browser when possible: navigation, search/filter,
  form input, submit, cancel, retry, pagination, modal/drawer open-close,
  upload/publish/checkout/login where relevant and safe
• verify network/API failures are visible to the user, not silently swallowed
• verify disabled/pending states prevent duplicate or invalid actions
• record blocked browser/auth issues honestly

Verified Blog SEO / Admin Gotchas

• For this repo, ok() in lib/api-response.ts returns raw JSON. Do not assume
  every API response is wrapped as { data: ... }; inspect the route/helper
  before wiring UI state.
• Before polishing Blog SEO/admin UI, prove every visible button works against
  the real route: create/order, generate, approve, create post, audit, retry,
  import, schedule. Visual QA alone is not enough.
• Do not show historical/global records as the primary "pipeline" state. Keep
  current workspace state separate from recent history to avoid misleading users.
• Blog SEO UX must expose the real progression clearly: order topic → generate
  ideas/briefs → approve brief → create post → generate draft → SEO audit →
  final check. Do not hide missing steps behind a prettier card.
• If an action starts a long AI/OpenClaw/Codex task, show honest pending/error
  feedback and verify via smoke/API probe, not just browser screenshots.

Integrated Design Brain v2 From External UI/UX Skills

This section distills reusable ideas from the user-provided UI/UX skill repos into
AWA's existing design process. Use the ideas as workflow and critique aids only;
awa-brand-identity remains the law for palette, typography direction, and brand
restraint.

Source-Informed Scope

Patterns were extracted from:

• awesome-design-skills: design skill structure, token-first rules, do/don't gates
• visual-taste-lab: VI-first audit, archetypes, design-language contract
• ui-ux-pro-max-skill and ui-ux-pro-max-codex: domain search workflow,
  professional UI micro-checklists, product/style/type/color/UX/stack synthesis
• awesome-ux-skills: research strategy, heuristics, cognitive-load, persuasive UX
• ux-audit: component-specific audit depth, accessibility, UI states, psychology
• awesome-ai-tools-for-ui: tool ecosystem map and reference workflow
• protfolio-website-desgin: portfolio/landing visual examples only; do not copy
  implementation or style wholesale

Design Router

Route every UI request before editing:

Signal	Primary method	Output before code
“premium / improve / redesign”	VI-first + archetype	design-language brief
homepage/storefront	editorial brand + catalog	5-second trust + image system
product listing/detail	marketplace catalog	browse/filter/card/detail rules
admin/dashboard	dense operational dashboard	workflow map + table/form states
blog/SEO/report	evidence-led report	source/status/metadata safety map
event/landing	event microsite	offer/date/CTA/trust/schedule hierarchy
form/booking/checkout	transactional utility	task-first flow + error prevention
ambiguous	ask or inspect	do not guess page type

VI-First Gate

Before meaningful UI work, do not ask “how do we make this prettier?” Ask:

1. What visual identity should this product own?
2. What page archetype is this?
3. What should a visitor understand and trust within five seconds?
4. What must this definitely not look like?

For each page, classify:

• brand anchor: logo/wordmark/product/category cue
• color roles: primary, neutral, accent, semantic states
• type attitude: editorial, operational, technical, institutional, commercial
• geometry: sharp, modest radius, rounded, document-like, app-like
• imagery: product, people, craft, screenshots, diagrams, editorial media, none
• site type: company, product, storefront, marketplace/catalog, dashboard,
  transactional utility, event/microsite, report/content, portfolio

If references conflict with current brand, state the conflict and translate the
pattern through AWA brand law instead of copying it.

AWA Archetype Map

Use one primary archetype. Blend only when the business really needs it.

• Public homepage: Editorial Brand System + Marketplace Catalog.
  Editorial rhythm and desire first, but product discovery must stay clear.
• Products listing: Marketplace Catalog.
  Strong filters/search/sort, consistent item cards, clear availability/status.
• Product detail: Editorial Product Detail + Transactional Utility.
  Desire, material/spec hierarchy, confidence, fitting/contact action.
• Contact/booking: Sharp Transactional Utility + Luxury Service.
  Task-first appointment path, trust, location/contact clarity, low friction.
• Admin: Dense Operational Dashboard.
  Tables, filters, compact controls, state honesty, no marketing hero.
• Blog/SEO ops: Evidence-Led Report + Dense Operational Dashboard.
  Metadata/source/status clarity; never hide workflow failures.
• Event pages: Event / Program Microsite.
  Offer/date/CTA/trust/schedule visible early; mobile agenda readable.

Design-Language Output Contract

Before coding a major redesign, produce an internal design-language brief:

• VI anchors and “must not look like” list
• page archetype and audience
• type scale: display, section, card, body, label, mono/meta if needed
• spacing rhythm: section padding, grid gaps, card padding, mobile compression
• surfaces: page background, media panels, content cards, dark sections
• borders/radius/shadows: exact level and anti-patterns
• CTA hierarchy: primary, secondary, text link, disabled/pending
• component rules: nav, card, product tile, form, table/list, badge, modal/drawer
• state rules: loading, empty, error, success, pending, disabled, permission denied
• imagery system: subject, crop, lighting, background, scale, mobile object position
• motion: duration, hover behavior, reduced-motion safety
• accessibility: contrast, focus, labels, alt text, touch targets
• copy rules: tone, claim honesty, placeholder restrictions

Do not let each section invent its own mini-brand.

Multi-Domain Search Workflow

For substantial UI work, gather context across domains before synthesis:

1. product/page type: ecommerce, catalog, admin, SEO ops, event, service
2. style: luxury, editorial, minimal, operational, evidence-led
3. typography: display/body/label attitude and hierarchy
4. color: role mapping only; do not copy non-AWA palettes
5. layout: hero, catalog, detail, table, form, report, event structure
6. UX: accessibility, cognitive load, animation, state handling
7. stack: Next.js/React constraints and existing component system

Search/research until the design direction is specific enough to implement with
rules, not adjectives.

UX Audit Heuristics

Every UI pass must check:

• clarity: page goal and next action obvious
• match: language and structure match user expectations
• hierarchy: primary content/action not competing with secondary modules
• recognition: users should scan labels/options, not remember hidden context
• affordance: clickable cards/buttons look interactive and use cursor-pointer
• feedback: hover/focus/pending/success/error states visible
• prevention: forms prevent double-submit and destructive actions require confirm
• recovery: errors explain next step, not just “failed”
• consistency: repeated elements share the same tokens/states/behavior
• accessibility: labels, alt text, focus, contrast, keyboard basics
• responsiveness: 320, 390/430, 768, 1024, 1440 widths; no horizontal scroll
• honesty: no invented metrics, partners, testimonials, screenshots, or hidden API failures

Cognitive Load + Conversion Rules

Reduce extraneous load before adding decoration:

• one dominant task per viewport region
• progressive disclosure for secondary details
• group related controls; avoid scattered filters/actions
• labels should be concrete, not clever
• primary CTA text should describe the action/result
• preserve user input on validation errors
• show constraints before submission when possible
• make trust signals specific: service, fitting, material, delivery, privacy,
  warranty, source, or operational status

Component Audit Matrix

Use this when reviewing or building components:

Component	Must check
Buttons	label clarity, hierarchy, hover/focus/disabled/loading, touch target
Cards	purpose, click affordance, consistent media crop, not card-inside-card clutter
Forms	labels, help text, validation, pending state, error recovery, no double submit
Modals/drawers	focus, close/cancel, escape/backdrop behavior, mobile height, destructive confirm
Navigation	active state, 360px fit, no hidden primary path, content not hidden behind fixed nav
Tables/lists	scan hierarchy, loading/empty/error, row actions, overflow, mobile fallback
Badges/status	semantic meaning, not color-only, consistent tone and label text
Imagery	subject relevance, crop, lighting, object position, alt text, performance
Motion	purpose, duration 150–300ms, no layout shift, reduced-motion safety

Professional UI Micro-Rules

• Use SVG icon sets consistently; no emoji as UI icons.
• Hover states should not shift layout; prefer color, opacity, border, or very subtle
  transform that does not affect surrounding flow.
• Transitions should usually be 150–300ms; avoid sluggish >500ms UI feedback.
• Fixed/floating nav must account for content offset and edge spacing.
• Containers should use a deliberate max-width system, not random widths per section.
• Light-mode muted text must remain readable; do not use ultra-light gray body copy.
• Glass/transparent surfaces must still be legible in light mode.
• Respect prefers-reduced-motion for non-essential animation when adding motion.
• No rule should depend on vague adjectives alone; anchor to tokens, examples, or
  measurable checks.
• Pair each strong design decision with at least one anti-pattern it prevents.

AI Tool / Reference Usage

Use AI UI tool lists, prompt packs, and design repos for:

• research keywords
• audit checklists
• style vocabulary
• pattern discovery
• critique prompts
• component QA ideas
• alternative explorations when the user is choosing direction

Do not use them to override:

• AWA brand palette
• protected route/API/auth/data contracts
• real data and workflow integrity
• Vietnamese luxury eyewear positioning

Never copy another repo's final visual style wholesale. Extract principles, then
translate into AWA's system.

Luxury Homepage Gate

For AWA homepage, the first fold must pass:

• within five seconds: “premium eyewear maison + private fitting + browse products”
  is understandable
• one dominant visual subject, not random stock collage
• primary CTA visible and reachable on mobile
• headline/copy readable over imagery
• no generic SaaS/AI-template hero
• section rhythm after hero alternates desire, product discovery, craft proof,
  private service, and conversion
• mobile density is intentional; long-scroll fatigue is reduced
• image crops across hero/product/craft/service feel like one editorial story

Verification Gate

Major UI work is not done until:

• design-language brief exists internally or in artifact/docs
• route/API/auth/data behavior is preserved
• component states are checked: loading, empty, error, pending, disabled
• desktop and mobile breakpoints are inspected
• typecheck/lint/build run where relevant
• browser QA covers at least the primary route and primary action
• final self-score is at least 85/100, with the weakest detail identified

Quick Trigger Prompt

Kích hoạt Frontend UI Research & Synthesis Designer + Opus-style Premium UI Brain.
Không code UI ngay. Audit codebase trước, hiểu sản phẩm/workflow/data/risk,
chạy VI-first gate, phân loại archetype, nghiên cứu nhiều UI tốt, lọc pattern phù hợp,
tổng hợp design-language brief, tạo research summary + plan + safety checklist,
rồi mới triển khai an toàn.
Giữ route/API/auth/permission/CRUD/data thật. Blog & SEO không đổi workflow.
Code qua 3 pass: Structure & Safety, Visual Polish, UX & Reliability.
Tự chấm rubric 100 điểm; dưới 85 thì polish tiếp.

Final Rule

Premium UI does not come from adding more colors. It comes from hierarchy,
spacing, alignment, typography, contrast, consistency, density, product fit,
real functionality, and strong self-critique. Visual polish that breaks workflow
is failure.