# Afrexai UI Design System > UI/UX Design System — Complete Product Design Engine - Skill: `johnalbertini14-glitch/afrexai-ui-design-system` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add johnalbertini14-glitch/afrexai-ui-design-system` - Raw SKILL.md: https://api.skillmd.com/api/skills/johnalbertini14-glitch/afrexai-ui-design-system/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: johnalbertini14-glitch (https://skillmd.com/u/johnalbertini14-glitch) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/johnalbertini14-glitch/afrexai-ui-design-system --- # UI/UX Design System — Complete Product Design Engine You are a senior product designer. Follow this system for every design task — from user research through pixel-perfect implementation. This is methodology + execution, not just CSS tips. --- ## Phase 1: Design Brief & Discovery Before touching any UI, answer these questions: ```yaml design_brief: project: "" type: "landing_page | dashboard | mobile_app | saas_product | ecommerce | marketing_site" target_users: primary: "" # Who are they? technical_level: "novice | intermediate | advanced" age_range: "" context: "" # Where/when do they use this? devices: "desktop_first | mobile_first | responsive_equal" goals: business: "" # What does the business need? user: "" # What does the user need to accomplish? success_metric: "" # How do we measure success? brand: personality: "" # e.g., "professional but approachable" existing_guidelines: "yes | no" competitors: [] # Who are we compared against? constraints: timeline: "" tech_stack: "" # React, vanilla, etc. accessibility: "WCAG_AA | WCAG_AAA" must_support: [] # e.g., "dark mode", "RTL", "i18n" ``` ### Design Type Decision Matrix | Type | Key Priority | Layout Pattern | Density | |------|-------------|----------------|---------| | Landing page | Conversion | Single column, CTA-focused | Low — lots of whitespace | | Dashboard | Information density | Grid/panels, sidebar nav | High — data-rich | | Mobile app | Thumb-zone, speed | Tab bar, cards, bottom sheets | Medium | | SaaS product | Efficiency, learnability | Sidebar + content area | Medium-high | | Ecommerce | Browse + buy | Grid catalog, sticky cart | Medium | | Marketing site | Brand storytelling | Sections, parallax, media | Low-medium | --- ## Phase 2: Information Architecture ### Content Hierarchy Method 1. **List every piece of content/feature** the page needs 2. **Rank by importance** (must-see, should-see, nice-to-see) 3. **Group related items** into logical sections 4. **Define the flow** — what order does the user encounter things? ### Navigation Architecture ```yaml nav_structure: pattern: "top_bar | sidebar | bottom_tabs | hamburger | command_palette" decision_factors: - item_count: "<7 = top bar, 7-15 = sidebar, >15 = sidebar + groups" - depth: "flat = tabs, 2-level = sidebar with sections, 3+ = breadcrumbs" - frequency: "daily-use actions in primary nav, weekly in secondary" - platform: "mobile = bottom tabs (max 5), desktop = sidebar or top" primary_items: [] # Max 7 secondary_items: [] # Settings, profile, help utility_items: [] # Search, notifications, user menu ``` ### Page Layout Patterns **F-Pattern** (content-heavy pages — blogs, news): ``` ┌─────────────────────────────────┐ │ ████████████████████████████ │ ← Eye scans horizontally │ ████████████████ │ ← Second horizontal scan (shorter) │ ████ │ │ ████ │ ← Vertical scan down left side │ ████ │ └─────────────────────────────────┘ ``` **Z-Pattern** (minimal pages — landing, login): ``` ┌─────────────────────────────────┐ │ LOGO ──────────────────── NAV │ ← Top horizontal │ ╲ │ │ ╲ │ ← Diagonal │ ╲ │ │ IMAGE ──────────────────── CTA │ ← Bottom horizontal └─────────────────────────────────┘ ``` **Dashboard Pattern** (data-heavy): ``` ┌──────┬──────────────────────────┐ │ │ KPI │ KPI │ KPI │ │ NAV ├──────────────────────────┤ │ │ CHART │ │ ├─────────────┬────────────┤ │ │ TABLE │ SIDEBAR │ └──────┴─────────────┴────────────┘ ``` --- ## Phase 3: Design System Foundation ### Color System Architecture #### Step 1: Choose a Color Strategy | Strategy | When to Use | Example | |----------|------------|---------| | Monochromatic | Professional, minimal, SaaS | Stripe, Linear | | Complementary | High contrast, CTAs pop | Slack (purple + green) | | Analogous | Harmonious, warm/cool feel | Instagram gradient | | Split-complementary | Vibrant but balanced | Notion | | Neutral + accent | Safe, professional | GitHub (white + blue accent) | #### Step 2: Build the Palette ```yaml color_system: # Core brand colors primary: 50: "" # Lightest — backgrounds, hover states 100: "" # Light — selected states, badges 200: "" # — borders, dividers 300: "" # — disabled text 400: "" # — placeholder text 500: "" # Base — buttons, links, icons 600: "" # — hover on primary buttons 700: "" # — active/pressed states 800: "" # — headings on light bg 900: "" # Darkest — text on light bg # Semantic colors (DON'T skip these) success: "#22c55e" # Green — confirmations, positive warning: "#f59e0b" # Amber — caution, pending error: "#ef4444" # Red — errors, destructive actions info: "#3b82f6" # Blue — informational, tips # Neutral scale (most used colors in any app) gray: 50: "" # Page background 100: "" # Card background, alternating rows 200: "" # Borders, dividers 300: "" # Disabled elements 400: "" # Placeholder text 500: "" # Secondary text, icons 600: "" # Body text 700: "" # Headings 800: "" # Primary text 900: "" # Highest contrast text # Surface colors background: "" # Page bg surface: "" # Card/panel bg surface_raised: "" # Elevated card bg (modals, popovers) overlay: "rgba(0,0,0,0.5)" # Modal backdrop ``` #### Color Accessibility Rules | Contrast Ratio | Use For | WCAG Level | |---------------|---------|------------| | 4.5:1 minimum | Normal text (<18px) | AA | | 3:1 minimum | Large text (≥18px bold, ≥24px) | AA | | 3:1 minimum | UI components, icons | AA | | 7:1 minimum | Normal text | AAA | **Never rely on color alone** — always pair with icons, labels, or patterns. #### Dark Mode Strategy | Light Mode | Dark Mode | Rule | |-----------|-----------|------| | White bg | NOT pure black — use gray-900 (#111827) | Pure black feels like a hole | | Gray-900 text | Gray-100 text | Reduce contrast slightly — pure white on dark = eye strain | | Primary-500 | Primary-400 | Lighten saturated colors for dark bg | | Gray-200 borders | Gray-700 borders | Invert border scale | | White cards | Gray-800 cards | Slight elevation from bg | | Box shadows | Subtle lighter borders or glow | Shadows invisible on dark bg | ### Typography System #### Type Scale (recommended) ```yaml typography: scale: "1.25" # Major Third — good for most apps # Or: 1.125 (minor second — compact), 1.2 (minor third), 1.333 (perfect fourth — bold) sizes: xs: "0.75rem" # 12px — captions, labels sm: "0.875rem" # 14px — secondary text, metadata base: "1rem" # 16px — body text (NEVER go below 16px for body) lg: "1.125rem" # 18px — emphasized body, intro text xl: "1.25rem" # 20px — section headers, card titles 2xl: "1.5rem" # 24px — page section titles 3xl: "1.875rem" # 30px — page titles 4xl: "2.25rem" # 36px — hero titles 5xl: "3rem" # 48px — landing page hero line_heights: tight: "1.25" # Headings normal: "1.5" # Body text (MINIMUM for readability) relaxed: "1.75" # Long-form reading max_width: "65ch" # Optimal line length for readability (45-75ch range) ``` #### Font Pairing Guide | Vibe | Heading | Body | Example Brand | |------|---------|------|---------------| | Modern SaaS | Inter | Inter | Linear, Vercel | | Premium | Playfair Display | Source Serif Pro | Stripe | | Friendly startup | Poppins | DM Sans | Notion | | Technical/dev | Space Grotesk | IBM Plex Sans | GitHub | | Bold/editorial | Clash Display | Satoshi | Arc Browser | | Clean corporate | Plus Jakarta Sans | Inter | Wise | **Rule: max 2 font families.** One for headings, one for body. Same family for both is fine (Inter does everything). ### Spacing System Use a **4px base unit** (0.25rem): ```yaml spacing: 0: "0" 1: "0.25rem" # 4px — tight gaps 2: "0.5rem" # 8px — between related items 3: "0.75rem" # 12px — form field padding 4: "1rem" # 16px — card padding, standard gap 5: "1.25rem" # 20px 6: "1.5rem" # 24px — section padding 8: "2rem" # 32px — between sections 10: "2.5rem" # 40px 12: "3rem" # 48px — large section gaps 16: "4rem" # 64px — hero padding 20: "5rem" # 80px — page section spacing 24: "6rem" # 96px — major section breaks ``` #### Spacing Rules - **Related items**: 4-8px apart (e.g., icon + label) - **Grouped items**: 12-16px apart (e.g., form fields) - **Sections**: 32-64px apart - **Page sections**: 64-96px apart - **Card internal padding**: 16-24px - **Consistent axis**: if horizontal gap is 16px, vertical should be 16px or a multiple ### Border Radius System ```yaml radius: none: "0" # Sharp — tables, code blocks sm: "0.25rem" # 4px — badges, tags md: "0.375rem" # 6px — inputs, small buttons lg: "0.5rem" # 8px — cards, modals xl: "0.75rem" # 12px — large cards 2xl: "1rem" # 16px — hero sections full: "9999px" # Pills, avatars, circular ``` **Consistency rule:** Pick 2-3 radius values and stick to them. Mixing 5+ different radii looks chaotic. ### Shadow & Elevation System ```yaml elevation: # Level 0: flat (no shadow) sm: "0 1px 2px rgba(0,0,0,0.05)" # Subtle — cards at rest md: "0 4px 6px -1px rgba(0,0,0,0.1)" # Standard — cards, dropdowns lg: "0 10px 15px -3px rgba(0,0,0,0.1)" # Elevated — modals, popovers xl: "0 20px 25px -5px rgba(0,0,0,0.1)" # High — dialogs, toasts # Interaction shadows hover: "transition shadow-sm → shadow-md on hover" focus: "0 0 0 3px rgba(primary, 0.3)" # Focus ring ``` --- ## Phase 4: Component Design Patterns ### Button Hierarchy Every page needs clear button hierarchy. Users should instantly know the primary action. | Level | Style | Use For | Max Per View | |-------|-------|---------|-------------| | Primary | Solid bg, contrasting text | Main CTA, submit, confirm | 1-2 | | Secondary | Outlined or muted bg | Alternative actions | 2-3 | | Tertiary/Ghost | Text only, no bg | Cancel, dismiss, back | Unlimited | | Destructive | Red solid or outlined | Delete, remove | 1 | | Icon-only | Icon + tooltip | Toolbar actions, compact UI | As needed | **Button States Checklist:** - [ ] Default - [ ] Hover (color shift or shadow) - [ ] Active/pressed (slightly darker, scale 0.98) - [ ] Focus (visible ring for keyboard nav) - [ ] Disabled (50% opacity, cursor: not-allowed) - [ ] Loading (spinner, disabled interaction) **Minimum touch target: 44×44px** (even if button looks smaller visually) ### Form Design Rules 1. **Labels above inputs** (not inline/floating — those have accessibility issues) 2. **One column** for forms <6 fields (two-column only for related pairs like first/last name) 3. **Field width = expected input length** (email = full width, zip = short) 4. **Real-time validation** — show errors on blur, not on submit 5. **Error messages below the field** — specific ("Email must include @") not generic ("Invalid input") 6. **Required fields**: mark optional fields with "(optional)" rather than marking required with * 7. **Group related fields** with subtle section dividers or headings 8. **Progressive disclosure** — don't show advanced options by default ```yaml form_field_template: label: "always visible, above input, font-weight: 500" hint: "below label, gray-500, sm text — for context/format hints" input: "border-gray-300, focus:border-primary-500, focus:ring, px-3 py-2" error: "below input, text-error, sm text, icon + message" states: default: "border-gray-300" focus: "border-primary-500, ring-2 ring-primary-100" error: "border-error, ring-2 ring-error-100" disabled: "bg-gray-50, text-gray-400, cursor-not-allowed" success: "border-success (only when validation is helpful)" ``` ### Card Design Patterns ```yaml card_variants: basic: bg: "surface" border: "1px solid gray-200" radius: "lg" padding: "24px" hover: "none" interactive: bg: "surface" border: "1px solid gray-200" radius: "lg" padding: "24px" hover: "shadow-md, border-gray-300, cursor-pointer" active: "shadow-sm, scale-0.99" featured: bg: "primary-50 or gradient" border: "2px solid primary-500" radius: "xl" padding: "32px" badge: "top-right — 'Popular', 'Recommended'" ``` ### Modal & Dialog Design - **Max width**: 480px (small), 640px (medium), 800px (large) - **Overlay**: dark semi-transparent backdrop (close on click) - **Always** include close button (X) top-right - **Focus trap**: keyboard focus stays inside modal - **Animation**: fade + slight scale-up (200-300ms) - **Mobile**: modals → full-screen sheets (slide up from bottom) - **Destructive actions**: require explicit confirmation, red button, describe what happens ### Table Design (Data-Heavy UIs) ```yaml table_design: header: bg: "gray-50" text: "gray-600, sm, uppercase tracking-wide, font-medium" sticky: true rows: hover: "bg-gray-50" selected: "bg-primary-50, border-l-2 border-primary-500" striped: false # Hover is better than stripes for modern look cells: padding: "12px 16px" alignment: "text-left (default), text-right (numbers), text-center (status)" truncation: "ellipsis with tooltip for long content" features: sorting: "click header, arrow indicator" filtering: "above table or inline header dropdowns" pagination: "bottom, 10/25/50/100 per page" empty_state: "illustration + message + CTA, not just 'No data'" loading: "skeleton rows, not spinner" ``` ### Empty States **Never show a blank page.** Every empty state needs: 1. **Illustration or icon** — visual interest 2. **Headline** — what this area is for 3. **Description** — why it's empty 4. **CTA** — what to do next ``` ┌──────────────────────────────┐ │ │ │ 📋 (icon) │ │ │ │ No projects yet │ │ │ │ Create your first project │ │ to get started. │ │ │ │ [ + New Project ] │ │ │ └──────────────────────────────┘ ``` ### Loading States | Pattern | When | Example | |---------|------|---------| | Skeleton screens | Content loading | Gray pulsing shapes matching layout | | Spinner | Short action (<3s) | Submit button, inline operations | | Progress bar | Known duration | File upload, multi-step process | | Optimistic UI | Low-risk actions | Like button, toggle, message send | | Placeholder content | First load | Shimmer effect on cards/lists | **Rule: Skeleton > Spinner.** Skeletons reduce perceived wait time by showing structure. --- ## Phase 5: Interaction Design ### Micro-Interaction Patterns ```yaml animations: # Timing guidelines instant: "0-100ms" # Button press, toggle, checkbox fast: "100-200ms" # Hover, color change, small move normal: "200-400ms" # Panel slide, fade, expand slow: "400-700ms" # Page transition, complex animation # Easing ease_out: "cubic-bezier(0.16, 1, 0.3, 1)" # Elements entering (most common) ease_in: "cubic-bezier(0.55, 0, 1, 0.45)" # Elements leaving ease_in_out: "cubic-bezier(0.65, 0, 0.35, 1)" # Elements moving spring: "cubic-bezier(0.34, 1.56, 0.64, 1)" # Bouncy/playful # Common patterns enter: "opacity 0→1, translateY 8px→0, 300ms ease-out" exit: "opacity 1→0, 200ms ease-in" expand: "height 0→auto, 250ms ease-out" hover_lift: "translateY -2px, shadow-md, 150ms" press: "scale 0.97, 100ms" shake: "translateX -4,4,-4,4,0 over 400ms" # Error feedback # Stagger for lists stagger: "each item delays 50ms from previous" ``` ### Scroll Behavior - **Smooth scroll** for anchor links - **Sticky headers** that shrink on scroll (60px → 48px) - **Infinite scroll** for feeds, **pagination** for search results - **Scroll-triggered animations**: fade-in on intersect, parallax for hero - **Back-to-top button**: appear after 2 viewport heights ### Toast / Notification Design ```yaml toast: position: "top-right (desktop), top-center (mobile)" duration: "success: 3s, info: 5s, error: persistent until dismissed" max_visible: 3 animation: "slide-in from right, fade-out" structure: "icon + title + optional description + optional action + close" types: success: "green accent, checkmark icon" error: "red accent, X icon, persistent" warning: "amber accent, alert icon" info: "blue accent, info icon" ``` --- ## Phase 6: Responsive Design System ### Breakpoint Strategy ```yaml breakpoints: sm: "640px" # Large phones landscape md: "768px" # Tablets lg: "1024px" # Small laptops xl: "1280px" # Desktops 2xl: "1536px" # Large screens approach: "mobile_first" # ALWAYS min-width queries max_content_width: "1280px" # Prevent ultra-wide line lengths container_padding: mobile: "16px" tablet: "24px" desktop: "32px" ``` ### Responsive Patterns | Component | Mobile | Tablet | Desktop | |-----------|--------|--------|---------| | Navigation | Bottom tabs or hamburger | Sidebar collapsed | Sidebar expanded or top bar | | Cards grid | 1 column | 2 columns | 3-4 columns | | Tables | Card layout or horizontal scroll | Visible with fewer columns | Full table | | Sidebar + content | Full-width stacked | Overlay sidebar | Persistent sidebar | | Hero section | Stacked, image below text | Side-by-side | Side-by-side with more padding | | Modal | Full-screen sheet | Centered modal | Centered modal | | Form layout | Single column | Single column | Optional 2-column for related fields | ### Touch-Friendly Rules (Mobile) - Minimum tap target: **44×44px** (Apple) / **48×48px** (Material) - Minimum spacing between targets: **8px** - Thumb zone: primary actions in **bottom 60%** of screen - Swipe gestures: always provide button alternative - No hover-dependent interactions on mobile --- ## Phase 7: Accessibility Checklist ### WCAG AA Compliance (Minimum) **Perceivable:** - [ ] Color contrast ≥ 4.5:1 for normal text, ≥ 3:1 for large text - [ ] Don't use color as the only indicator (add icons, patterns, text) - [ ] All images have alt text (decorative images: alt="") - [ ] Video has captions; audio has transcripts - [ ] Text can be resized to 200% without breaking layout **Operable:** - [ ] All functionality available via keyboard - [ ] Visible focus indicators on all interactive elements - [ ] Skip-to-content link as first focusable element - [ ] No keyboard traps (except intentional modals with escape) - [ ] Sufficient time for timed interactions (or ability to extend) - [ ] No content that flashes more than 3 times per second **Understandable:** - [ ] Language attribute on `` - [ ] Form labels associated with inputs (for/id or wrapping) - [ ] Error messages identify the field and suggest correction - [ ] Consistent navigation across pages - [ ] No unexpected context changes (auto-submit, auto-redirect) **Robust:** - [ ] Valid HTML (semantic elements) - [ ] ARIA attributes used correctly (or not at all — semantic HTML first) - [ ] Tested with screen reader (VoiceOver, NVDA) - [ ] Works with browser zoom at 200% ### Semantic HTML Cheatsheet | Purpose | Use | Not | |---------|-----|-----| | Page header | `
` | `
` | | Navigation | `