Imported from maheshpcse/chat-app (.agents/skills/luxury-ui-system/SKILL.md). Install upstream with npx skills add maheshpcse/chat-app --skill luxury-ui-system. Copyright stays with the author.

Luxury Interface Design System

Principle: Luxury is restraint. Every pixel, every animation, every shadow earns its place. If removing an element makes the design worse, it stays. If removing it changes nothing, it goes.

Persona

You are an award-winning product designer. You make decisions, not suggestions. When you produce output from this skill:

• Declare the design intent before the code — one sentence on why each token or spec exists.
• Justify every effect. No glass, no shadow, no animation without a stated reason.
• Deliver finished work. No placeholders. No "you could also try...". Output is ready to implement.
• Enforce the rules. If a request violates §4 (Glass Rules), §6 (Accessibility), or the motion system, flag it and correct it before delivering.

When to Use

• Building a new design system from scratch
• Auditing existing components against a token-based luxury standard
• Generating CSS/SCSS tokens for a project
• Specifying a component (button, card, form, nav) with all states
• Defining the motion/animation language for an interface
• Answering "where does glassmorphism belong" questions

Procedure

Step 1 — Determine Scope

If the user provides an argument, parse it to identify:

• Full system → deliver all sections (tokens + all components)
• Tokens only → §1 Design Tokens only
• Specific component → relevant component spec(s) from §3
• Motion only → §2 Motion Language only
• Glass audit → §4 Glassmorphism rules + verdict on their current use

If no argument, default to: tokens first, then ask which components to spec.

Step 2 — Deliver Tokens First

Always begin output with the CSS custom properties block from §1 (Color, Typography, Spacing, Grid, Radius). This is the single source of truth. Components reference these tokens — no raw values.

Step 3 — Spec Components

For each component in scope:

1. State the variant table (which variants exist and when to use each)
2. Output the CSS spec (all states: resting, hover, focus, active, disabled, loading)
3. Note any glassmorphism verdict (justified / not justified + alternative if not)
4. List any accessibility requirements from §6 that apply

Step 4 — Deliver Motion Language

Include the Transition Matrix from §2.3. Confirm every component spec above uses only the defined timing tokens. Flag any deviation.

Step 5 — Validate Against Checklist

Before final output, run the §6 Accessibility Checklist mentally:

• Focus rings on all interactive elements
• Contrast ratios verified (body ≥ 4.5:1, large text ≥ 3:1)
• prefers-reduced-motion handled
• Touch targets 44×44px minimum
• No color-only error states

If any item fails, fix it before delivering.

Step 6 — Output Format

Deliver in this order:

1. Design Tokens — one CSS :root {} block
2. Component Specs — one code block per component with all states
3. Motion Summary — one-paragraph recap of the unified motion language
4. Glassmorphism Verdict — explicit list of where glass is / isn't justified
5. Accessibility Notes — anything non-obvious

Dependencies

• premium-3d-website — Overall architecture, implementation roadmap, accessibility strategy.
• cinematic-3d-scenes — 3D layer. This skill owns everything outside the <Canvas>.

1. Design Tokens

Tokens are the single source of truth. Components consume tokens, never raw values.

1.1 Color System

:root {
  /* ─── Surfaces ─── */
  --surface-void:       #08080D;   /* Deepest background — app shell */
  --surface-ground:     #0E0E14;   /* Page background */
  --surface-raised:     #16161F;   /* Cards, panels */
  --surface-overlay:    #1E1E2A;   /* Modals, dropdowns, popovers */
  --surface-hover:      #252533;   /* Interactive surface on hover */
  --surface-active:     #2C2C3D;   /* Pressed/active state */

  /* ─── Borders ─── */
  --border-subtle:      rgba(255, 255, 255, 0.06);  /* Resting card edges */
  --border-default:     rgba(255, 255, 255, 0.10);  /* Input borders */
  --border-strong:      rgba(255, 255, 255, 0.16);  /* Focused inputs */
  --border-accent:      rgba(108, 99, 255, 0.30);   /* Active/selected borders */

  /* ─── Text ─── */
  --text-hero:          #FFFFFF;   /* Display headings only — use sparingly */
  --text-primary:       #E4E4ED;   /* Body text, labels */
  --text-secondary:     #8E8EA0;   /* Descriptions, metadata */
  --text-tertiary:      #5A5A6E;   /* Placeholders, disabled */
  --text-inverse:       #08080D;   /* Text on accent backgrounds */

  /* ─── Accent ─── */
  --accent-primary:     #6C63FF;   /* Primary actions, focus rings */
  --accent-primary-hover: #7B73FF; /* Hovered primary */
  --accent-primary-active: #5B52E0;/* Pressed primary */
  --accent-secondary:   #00D4FF;   /* Links, secondary highlights */
  --accent-gradient:    linear-gradient(135deg, #6C63FF 0%, #00D4FF 100%);

  /* ─── Semantic ─── */
  --semantic-success:   #34D399;
  --semantic-warning:   #FBBF24;
  --semantic-error:     #F87171;
  --semantic-info:      #60A5FA;

  /* ─── Glass ─── */
  --glass-bg:           rgba(255, 255, 255, 0.03);
  --glass-border:       rgba(255, 255, 255, 0.08);
  --glass-blur:         12px;

  /* ─── Shadows ─── */
  --shadow-sm:          0 1px 2px rgba(0, 0, 0, 0.3);
  --shadow-md:          0 4px 12px rgba(0, 0, 0, 0.4);
  --shadow-lg:          0 8px 32px rgba(0, 0, 0, 0.5);
  --shadow-glow:        0 0 24px rgba(108, 99, 255, 0.15);
  --shadow-glow-strong: 0 0 40px rgba(108, 99, 255, 0.25);
}

When to Use Each Surface

1.2 Typography

:root {
  /* ─── Font Stacks ─── */
  --font-display:   'Space Grotesk', 'Inter', system-ui, sans-serif;
  --font-body:      'Inter', 'Segoe UI', system-ui, sans-serif;
  --font-mono:      'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;

  /* ─── Scale (Major Third — 1.250 ratio) ─── */
  --text-xs:     0.64rem;     /* 10.24px  — Fine print, badges */
  --text-sm:     0.8rem;      /* 12.8px   — Labels, captions */
  --text-base:   1rem;        /* 16px     — Body text */
  --text-md:     1.25rem;     /* 20px     — Lead paragraphs */
  --text-lg:     1.563rem;    /* 25px     — Section subtitles */
  --text-xl:     1.953rem;    /* 31.25px  — Section headings */
  --text-2xl:    2.441rem;    /* 39.06px  — Page headings */
  --text-3xl:    3.052rem;    /* 48.83px  — Hero subheading */
  --text-display: 4.5rem;    /* 72px     — Hero display heading */

  /* ─── Weights ─── */
  --fw-regular:   400;
  --fw-medium:    500;
  --fw-semibold:  600;
  --fw-bold:      700;
  --fw-black:     900;        /* Display headings only */

  /* ─── Line Heights ─── */
  --lh-tight:     1.15;       /* Headings */
  --lh-snug:      1.3;        /* Subheadings */
  --lh-normal:    1.5;        /* Body text */
  --lh-relaxed:   1.7;        /* Long-form reading */

  /* ─── Letter Spacing ─── */
  --ls-tight:    -0.02em;     /* Large display text */
  --ls-normal:    0;          /* Body */
  --ls-wide:      0.04em;     /* Uppercase labels */
  --ls-ultra:     0.08em;     /* Badges, overlines */
}

Typography Rules

1.3 Spacing

:root {
  /* ─── 4px base, 8px grid ─── */
  --space-1:    4px;     --space-2:    8px;
  --space-3:    12px;    --space-4:    16px;
  --space-5:    20px;    --space-6:    24px;
  --space-7:    32px;    --space-8:    40px;
  --space-9:    48px;    --space-10:   64px;
  --space-11:   80px;    --space-12:   96px;
  --space-section: 120px;

  /* ─── Named spacing (semantic) ─── */
  --gap-inline:   var(--space-2);    /* Between inline elements */
  --gap-stack:    var(--space-4);    /* Between stacked elements */
  --gap-group:    var(--space-6);    /* Between grouped items */
  --gap-section:  var(--space-section); /* Between page sections */
  --pad-card:     var(--space-7);    /* Card internal padding */
  --pad-input:    var(--space-3) var(--space-4); /* Input padding */
  --pad-button:   var(--space-3) var(--space-6); /* Button padding */
}

1.4 Layout Grid

:root {
  --grid-columns:    12;
  --grid-gutter:     var(--space-6);   /* 24px */
  --grid-margin:     var(--space-7);   /* 32px */
  --container-sm:    640px;
  --container-md:    768px;
  --container-lg:    1024px;
  --container-xl:    1200px;
  --container-2xl:   1400px;
}

.container {
  width: 100%;
  max-width: var(--container-xl);
  margin: 0 auto;
  padding: 0 var(--grid-margin);
}

.grid {
  display: grid;
  grid-template-columns: repeat(var(--grid-columns), 1fr);
  gap: var(--grid-gutter);
}

1.5 Border Radius

:root {
  --radius-xs:    4px;     /* Badges, tags */
  --radius-sm:    6px;     /* Inputs, small buttons */
  --radius-md:    10px;    /* Cards, panels */
  --radius-lg:    16px;    /* Modals, large cards */
  --radius-xl:    24px;    /* Hero cards, image containers */
  --radius-pill:  9999px;  /* Pills, toggles */
  --radius-circle: 50%;   /* Avatars */
}

2. Motion Language

One motion system for every interaction. Consistency makes an interface feel like a single, crafted object rather than assembled parts.

2.1 Timing

:root {
  /* ─── Durations ─── */
  --duration-instant:   80ms;    /* Color change, opacity */
  --duration-fast:      150ms;   /* Hover effects, tooltips */
  --duration-base:      250ms;   /* Transitions, menus */
  --duration-slow:      400ms;   /* Modals, panels, page transitions */
  --duration-dramatic:  700ms;   /* Hero entrance — first load only */

  /* ─── Easings ─── */
  --ease-out:      cubic-bezier(0.16, 1, 0.3, 1);       /* Enter: fast start, gentle settle */
  --ease-in:       cubic-bezier(0.7, 0, 0.84, 0);       /* Exit: slow start, fast disappear */
  --ease-spring:   cubic-bezier(0.22, 1.36, 0.36, 1);   /* Interactive: slight overshoot */
  --ease-smooth:   cubic-bezier(0.4, 0, 0.2, 1);        /* General purpose */
}

2.2 Motion Rules

2.3 Transition Matrix

Every state change follows this matrix:

3. Component Specs

3.1 Button

Variants

States

.btn-primary {
  /* Resting */
  background: var(--accent-gradient);
  color: var(--text-inverse);
  padding: var(--pad-button);
  border-radius: var(--radius-sm);
  font-family: var(--font-body);
  font-size: var(--text-sm);
  font-weight: var(--fw-semibold);
  letter-spacing: var(--ls-wide);
  box-shadow: var(--shadow-glow);
  transition:
    transform var(--duration-fast) var(--ease-spring),
    box-shadow var(--duration-fast) var(--ease-smooth),
    opacity var(--duration-instant);

  /* Hover: glow intensifies, subtle lift */
  &:hover:not(:disabled) {
    box-shadow: var(--shadow-glow-strong);
    transform: translateY(-1px);
  }

  /* Active: press down, glow snaps */
  &:active:not(:disabled) {
    transform: scale(0.97);
    box-shadow: var(--shadow-glow);
  }

  /* Focus: accessibility ring */
  &:focus-visible {
    outline: 2px solid var(--accent-primary);
    outline-offset: 2px;
  }

  /* Disabled: no glow, reduced opacity */
  &:disabled {
    opacity: 0.4;
    cursor: not-allowed;
    box-shadow: none;
  }

  /* Loading: spinner replaces text */
  &[data-loading] {
    pointer-events: none;
    color: transparent;
    /* Spinner pseudo-element centered */
  }
}

Sizes

3.2 Card

When to Use Glass vs Solid

Solid Card Spec

.card {
  background: var(--surface-raised);
  border: 1px solid var(--border-subtle);
  border-radius: var(--radius-md);
  padding: var(--pad-card);
  transition:
    border-color var(--duration-fast) var(--ease-smooth),
    box-shadow var(--duration-fast) var(--ease-smooth),
    transform var(--duration-fast) var(--ease-spring);

  /* Hover: border brightens, subtle lift */
  &:hover {
    border-color: var(--border-strong);
    box-shadow: var(--shadow-md);
    transform: translateY(-2px);
  }

  /* Interactive card: cursor pointer */
  &[data-clickable] {
    cursor: pointer;
  }

  /* Card sections */
  &__header { margin-bottom: var(--space-5); }
  &__body   { margin-bottom: var(--space-5); }
  &__footer {
    padding-top: var(--space-5);
    border-top: 1px solid var(--border-subtle);
  }
}

Glass Card Spec

.card-glass {
  background: var(--glass-bg);
  backdrop-filter: blur(var(--glass-blur));
  -webkit-backdrop-filter: blur(var(--glass-blur));
  border: 1px solid var(--glass-border);
  border-radius: var(--radius-lg);
  padding: var(--pad-card);

  /* Glass must NEVER have: */
  /* - Small body text (below --text-md) */
  /* - Dense content (more than 3 lines) */
  /* - Data tables or forms */
}

3.3 Navigation

Header (Glass — justified because it's a persistent overlay)

.nav-header {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  z-index: 50;
  height: 64px;
  display: flex;
  align-items: center;
  padding: 0 var(--grid-margin);
  background: var(--glass-bg);
  backdrop-filter: blur(16px);
  border-bottom: 1px solid var(--glass-border);
  transition: background var(--duration-base) var(--ease-smooth);

  /* Scrolled state: slightly more opaque */
  &[data-scrolled] {
    background: rgba(8, 8, 13, 0.85);
  }
}

Nav Link States

.nav-link {
  font-family: var(--font-body);
  font-size: var(--text-sm);
  font-weight: var(--fw-medium);
  color: var(--text-secondary);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius-sm);
  position: relative;
  transition: color var(--duration-fast) var(--ease-smooth);

  /* Hover: text brightens */
  &:hover {
    color: var(--text-primary);
  }

  /* Active: accent underline slides in */
  &[data-active] {
    color: var(--text-hero);

    &::after {
      content: '';
      position: absolute;
      bottom: -2px;
      left: var(--space-4);
      right: var(--space-4);
      height: 2px;
      background: var(--accent-primary);
      border-radius: 1px;
      animation: slideInFromLeft var(--duration-base) var(--ease-out);
    }
  }
}

@keyframes slideInFromLeft {
  from { transform: scaleX(0); transform-origin: left; }
  to   { transform: scaleX(1); transform-origin: left; }
}

Side Navigation

.nav-side {
  width: 240px;
  background: var(--surface-ground);
  border-right: 1px solid var(--border-subtle);
  padding: var(--space-4);
  transition: width var(--duration-base) var(--ease-out);

  /* Collapsed */
  &[data-collapsed] {
    width: 64px;
    .nav-side__label { opacity: 0; width: 0; }
  }
}

.nav-side__item {
  display: flex;
  align-items: center;
  gap: var(--space-3);
  padding: var(--space-3) var(--space-4);
  border-radius: var(--radius-sm);
  color: var(--text-secondary);
  transition:
    background var(--duration-fast) var(--ease-smooth),
    color var(--duration-fast) var(--ease-smooth);

  &:hover {
    background: var(--surface-hover);
    color: var(--text-primary);
  }

  &[data-active] {
    background: rgba(108, 99, 255, 0.08);
    color: var(--accent-primary);
    font-weight: var(--fw-semibold);
  }
}

3.4 Form Inputs

.input {
  width: 100%;
  height: 44px;
  padding: var(--pad-input);
  background: var(--surface-ground);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-sm);
  font-family: var(--font-body);
  font-size: var(--text-base);
  color: var(--text-primary);
  transition:
    border-color var(--duration-fast) var(--ease-smooth),
    box-shadow var(--duration-fast) var(--ease-smooth);

  &::placeholder {
    color: var(--text-tertiary);
  }

  /* Focus: border accent + glow ring */
  &:focus {
    outline: none;
    border-color: var(--accent-primary);
    box-shadow: 0 0 0 3px rgba(108, 99, 255, 0.12);
  }

  /* Error */
  &[data-error] {
    border-color: var(--semantic-error);
    box-shadow: 0 0 0 3px rgba(248, 113, 113, 0.12);
  }

  /* Disabled */
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
    background: var(--surface-void);
  }
}

/* Floating label */
.input-group {
  position: relative;

  .input-label {
    position: absolute;
    left: var(--space-4);
    top: 50%;
    transform: translateY(-50%);
    font-size: var(--text-base);
    color: var(--text-tertiary);
    pointer-events: none;
    transition:
      transform var(--duration-fast) var(--ease-out),
      font-size var(--duration-fast) var(--ease-out),
      color var(--duration-fast) var(--ease-smooth);
  }

  .input:focus ~ .input-label,
  .input:not(:placeholder-shown) ~ .input-label {
    transform: translateY(-28px);
    font-size: var(--text-xs);
    color: var(--accent-primary);
  }
}

Textarea

.textarea {
  /* Inherits .input styles + overrides: */
  height: auto;
  min-height: 120px;
  resize: vertical;
  line-height: var(--lh-normal);
  padding: var(--space-4);

  /* Icon alignment: top-aligned, not centered */
  & ~ .input-icon {
    align-self: flex-start;
    margin-top: var(--space-4);
  }
}

3.5 Loading Sequences

Skeleton Shimmer

.skeleton {
  background: var(--surface-raised);
  border-radius: var(--radius-sm);
  position: relative;
  overflow: hidden;

  &::after {
    content: '';
    position: absolute;
    inset: 0;
    background: linear-gradient(
      90deg,
      transparent 0%,
      rgba(255, 255, 255, 0.04) 40%,
      rgba(255, 255, 255, 0.04) 60%,
      transparent 100%
    );
    animation: shimmer 1.5s ease-in-out infinite;
  }
}

@keyframes shimmer {
  0%   { transform: translateX(-100%); }
  100% { transform: translateX(100%); }
}

Loading Sequence (page level)

T+0ms     Skeleton placeholders visible (immediate)
          PURPOSE: Prevents layout shift. User sees structure before content.

T+200ms   Skeleton shimmer begins
          PURPOSE: Indicates activity. Without shimmer, skeletons look broken.

T+data    Content fades in, replacing skeleton (250ms, ease-out)
          PURPOSE: Smooth swap prevents jarring content pop.
          RULE: Never show skeleton for less than 300ms.
                Too-fast skeleton flash is worse than no skeleton.

Spinner (inline actions)

.spinner {
  width: 20px;
  height: 20px;
  border: 2px solid var(--border-subtle);
  border-top-color: var(--accent-primary);
  border-radius: 50%;
  animation: spin 600ms linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

3.6 Hover States — Complete Reference

3.7 Micro-Interactions

4. Glassmorphism — Where It Earns Its Place

Glass is NOT a decoration. It has exactly three justified uses.

4.1 Justified Uses

4.2 Where Glass Must NOT Be Used

4.3 Glass Implementation Rules

/* ✅ CORRECT: Glass header */
.header-glass {
  background: rgba(8, 8, 13, 0.6);         /* Semi-transparent, NOT fully clear */
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
}

/* ❌ WRONG: Glass card with body text */
.card-glass-bad {
  background: rgba(255, 255, 255, 0.03);   /* Too transparent */
  backdrop-filter: blur(8px);               /* Body text unreadable */
}

5. Responsive Behavior

5.1 Breakpoint Adjustments

5.2 Touch Adaptations

6. Accessibility Checklist

Common Mistakes

1. Using glass everywhere. Glass is a special effect. If everything is glass, nothing is. Reserve it for the 3 justified cases in §4.1.
2. Over-animating hover states. A card that scales 1.1x, rotates, glows, and lifts 8px on hover is a circus. Maximum hover transform: 2px lift + border brighten + shadow deepen.
3. Inconsistent easing. If buttons use ease-spring but cards use ease-in-out and modals use ease-linear, the interface feels assembled, not designed. Use the motion tokens from §2 everywhere.
4. Font size soup. If one viewport has 7 different font sizes, the hierarchy is broken. Limit to 3 per viewport: heading + body + caption.
5. Ignoring disabled states. A disabled button that looks clickable generates frustrated clicks. Always: opacity 0.4 + cursor: not-allowed + no hover effects.

Quick Reference — Section Index