ui-mirror-skill 1.0.0

package/skill/references/analysis-dimensions.md

@@ -0,0 +1,382 @@
+# UI Mirror: 7-Axis Analysis Rubric
+
+> This rubric defines how to systematically compare a benchmark website's UI against the current project's design system.
+> Each axis includes extraction targets, mapping conventions, scoring criteria, and key comparison questions.
+
+---
+
+## Axis 1: Layout
+
+**Description**: Analyze the overall page structure -- grid system, column count, max-width constraints, sidebar/main/aside arrangement, header/footer positioning, and responsive breakpoints.
+
+### CSS Properties to Extract
+- `display` (grid | flex | block)
+- `grid-template-columns`, `grid-template-rows`, `grid-template-areas`
+- `max-width`, `min-width`, `width` (container)
+- `position` (sticky | fixed | relative) for header/footer
+- `@media` breakpoint values
+- `gap`, `column-gap`, `row-gap`
+- `flex-direction`, `flex-wrap`, `flex-basis`
+- `overflow`, `min-height`, `height` (viewport units)
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent |
+|---|---|
+| `max-width: 1280px` | `max-w-7xl` (1280px) |
+| `grid-template-columns: 1fr 3fr` | `grid grid-cols-[1fr_3fr]` or sidebar pattern |
+| `position: sticky; top: 0` | `sticky top-0` |
+| 2-column sidebar+main | `SidebarProvider` + `Sidebar` + `SidebarInset` |
+| `@media (min-width: 768px)` | `md:` prefix |
+| `@media (min-width: 1024px)` | `lg:` prefix |
+| `@media (min-width: 1280px)` | `xl:` prefix |
+| `min-height: 100svh` | `min-h-svh` |
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Completely different layout paradigm (e.g., benchmark uses CSS Grid areas vs project's flex column) |
+| 2 | Same general approach but different column ratios, breakpoints, or container widths |
+| 3 | Similar structure; minor differences in gap sizes, max-width, or breakpoint triggers |
+| 4 | Nearly identical; only 1-2 minor property differences (e.g., slightly different sidebar width) |
+| 5 | Identical layout system, breakpoints, and spatial relationships |
+
+### Key Comparison Questions
+1. Does the benchmark use a sidebar layout? If so, how does its width compare to the project's `--sidebar-width: 16rem`?
+2. What is the main content max-width? Does it match any Tailwind `max-w-*` value?
+3. Are headers sticky or fixed? What z-index layer?
+4. What breakpoints trigger layout shifts? Do they align with Tailwind's default `sm/md/lg/xl/2xl`?
+5. Is the layout a 1-column, 2-column, or 3-column system? Does it collapse responsively?
+6. Does the benchmark use CSS Grid areas or Flexbox for its primary layout?
+7. Is there an inset/floating sidebar variant like the project's `SidebarInset`?
+
+---
+
+## Axis 2: Color
+
+**Description**: Analyze the complete color palette -- primary, secondary, accent, background, text, muted, destructive, gradients, and opacity values. All extracted colors MUST be converted to OKLCH format for direct comparison with project tokens.
+
+### CSS Properties to Extract
+- `color`, `background-color`, `background` (gradients)
+- `border-color`, `outline-color`
+- `box-shadow` color components
+- `opacity`, `rgba()`/`oklch()` alpha channels
+- `--custom-property` color definitions
+- `fill`, `stroke` (SVG elements)
+- `accent-color`, `caret-color`
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent |
+|---|---|
+| Primary brand color | `--primary: oklch(0.575 0.215 276)` / `bg-primary` |
+| Light background | `--background: oklch(0.97 0.003 276)` / `bg-background` |
+| Card/surface white | `--card: oklch(1 0 0)` / `bg-card` |
+| Muted/secondary bg | `--muted: oklch(0.955 0.005 276)` / `bg-muted` |
+| Faint text | `--muted-foreground: oklch(0.52 0.01 276)` / `text-muted-foreground` |
+| Error/danger red | `--destructive: oklch(0.577 0.245 27.325)` / `bg-destructive` |
+| Border gray | `--border: oklch(0.91 0.005 276)` / `border-border` |
+| Opacity variants | Slash notation: `bg-primary/10`, `shadow-primary/20` |
+| Success state | `bg-emerald-50 text-emerald-700` |
+| Warning state | `bg-amber-50 text-amber-700` |
+| Error state | `bg-red-50 text-red-700` |
+
+### Color Conversion Formula
+```
+HEX -> sRGB -> Linear RGB -> OKLCH
+Use: https://oklch.com/ or CSS `oklch()` spec
+Format: oklch(L C H) where L=[0,1], C=[0,0.4], H=[0,360]
+```
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Entirely different palette (different hue family, different lightness strategy) |
+| 2 | Same general warmth/coolness but different hues; significant lightness/chroma gaps |
+| 3 | Similar palette family; 2-3 tokens need remapping; minor hue/chroma differences |
+| 4 | Very close; 1 token difference (e.g., primary hue shifted 10-20 degrees) |
+| 5 | Identical palette within OKLCH delta-E < 0.02 across all tokens |
+
+### Key Comparison Questions
+1. What is the benchmark's primary hue? How far is it from the project's purple hue (276)?
+2. Does the benchmark use a warm or cool neutral palette? typical shadcn/ui uses cool-purple-tinted neutrals.
+3. Are there gradients? many projects avoid gradients in the core system.
+4. How many semantic color roles does the benchmark define? Does it exceed the project's token set?
+5. Does the benchmark use opacity/alpha for layering? At what values vs the project's `/10`, `/20`, `/50`?
+6. Is dark mode present? check if project is light-mode only per design rules.
+7. Are state colors (success/warning/error) from the same family as the project's emerald/amber/red?
+
+---
+
+## Axis 3: Typography
+
+**Description**: Analyze font families, size scale, weight distribution, line-height, letter-spacing, and any special text treatments (uppercase, truncation, monospace usage).
+
+### CSS Properties to Extract
+- `font-family` (identify Google Fonts or system fonts)
+- `font-size` (build the complete type scale)
+- `font-weight` (identify which weights are used)
+- `line-height` (per font-size pairing)
+- `letter-spacing`
+- `text-transform` (uppercase, capitalize)
+- `text-overflow`, `overflow`, `white-space` (truncation patterns)
+- `font-feature-settings`, `font-variant-numeric`
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent |
+|---|---|
+| Sans-serif primary | `font-sans` (Pretendard + Inter) |
+| Monospace code | `font-mono` |
+| 12px | `text-xs` (0.75rem) |
+| 14px | `text-sm` (0.875rem) |
+| 16px | `text-base` (1rem) |
+| 18px | `text-lg` (1.125rem) |
+| 20px | `text-xl` (1.25rem) |
+| 24px | `text-2xl` (1.5rem) |
+| 30px | `text-3xl` (1.875rem) |
+| 36px | `text-4xl` (2.25rem) |
+| weight 400 | `font-normal` |
+| weight 500 | `font-medium` |
+| weight 600 | `font-semibold` |
+| weight 700 | `font-bold` |
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Different font family category (serif vs sans-serif), wildly different scale |
+| 2 | Same category but different specific fonts; scale has 3+ mismatches |
+| 3 | Similar fonts (both geometric sans); scale mostly aligns with 1-2 off-steps |
+| 4 | Very similar; same font category, same scale, minor line-height/spacing differences |
+| 5 | Identical font stack, matching size scale, weights, and line-heights |
+
+### Key Comparison Questions
+1. What is the primary font family? Is it available on Google Fonts? How does its x-height compare to Pretendard/Inter?
+2. Does the benchmark use the same 4-weight system (400/500/600/700) or more/fewer weights?
+3. What is the body text size? typical shadcn/ui uses `text-sm` (14px) for most body content.
+4. Are there any hardcoded pixel sizes that don't map to Tailwind's scale?
+5. Does the benchmark use `letter-spacing`? default Tailwind rarely adjusts letter-spacing.
+6. Is there a distinct heading scale? How does it map to `text-lg` through `text-4xl`?
+7. Does the benchmark use tabular numbers (`font-variant-numeric: tabular-nums`) for data displays?
+
+---
+
+## Axis 4: Icons & Graphics
+
+**Description**: Identify the icon library, icon sizing conventions, color treatment, illustration/graphic style, and any decorative elements (gradients, patterns, blobs).
+
+### CSS Properties to Extract
+- `width`, `height` on SVG/icon elements
+- `stroke-width`
+- `color`/`fill`/`stroke` on icons
+- `viewBox` dimensions (to identify icon set)
+- Background decorative patterns/images
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent |
+|---|---|
+| 16x16 icons | `size-4` (Lucide default) |
+| 20x20 icons | `size-5` |
+| 24x24 icons | `size-6` |
+| Icon color inherits text | `className="size-4"` (inherits `currentColor`) |
+| Icon + text gap | `gap-2` (8px) in flex container |
+| Lucide icons | `lucide-react` (the project's icon library - CP3) |
+
+### Icon Library Identification
+| Library | Identifiers |
+|---------|-------------|
+| **Lucide** | `viewBox="0 0 24 24"`, stroke-based, `stroke-width="2"`, `stroke-linecap="round"` |
+| **Heroicons** | `viewBox="0 0 24 24"` (outline) or `viewBox="0 0 20 20"` (solid), Tailwind ecosystem |
+| **Font Awesome** | `viewBox="0 0 512 512"` or similar large viewBox, filled style |
+| **Phosphor** | `viewBox="0 0 256 256"`, multiple weights (thin/light/regular/bold/fill/duotone) |
+| **Material Icons** | `viewBox="0 0 24 24"`, filled or outlined variants, Google design |
+| **Custom/SVG sprites** | Non-standard viewBox, inline SVG without library wrapper |
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Different icon library category (filled vs stroke), different default size, no overlap |
+| 2 | Different library but similar style; sizes mostly align |
+| 3 | Same style family (stroke-based); some icons have equivalents, some need custom SVG |
+| 4 | Same or compatible library; minor size/stroke-width differences |
+| 5 | Identical icon library and conventions |
+
+### Key Comparison Questions
+1. What icon library does the benchmark use? Is it Lucide (the project's library)?
+2. What is the default icon size? typical shadcn/ui uses `size-4` (16px) per CP3.
+3. Are icons stroke-based or filled? typical shadcn/ui uses Lucide's stroke style.
+4. Does the benchmark use icon-only buttons? the project may have `size="icon"` variant.
+5. Are there decorative illustrations or graphics beyond icons? What style?
+6. Does the benchmark use emoji as pseudo-icons?
+7. Is there an icon color system independent of text color?
+
+---
+
+## Axis 5: Spacing
+
+**Description**: Analyze padding, margin, and gap patterns across all page sections, cards, buttons, and inline elements. Map all values to Tailwind's 4px-based spacing scale.
+
+### CSS Properties to Extract
+- `padding`, `padding-top/right/bottom/left`
+- `margin`, `margin-top/right/bottom/left`
+- `gap`, `row-gap`, `column-gap`
+- `inset`, `top/right/bottom/left` (for positioned elements)
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent | Rule |
+|---|---|---|
+| 4px | `gap-1`, `p-1` | S1 |
+| 8px | `gap-2`, `p-2` | S1 |
+| 12px | `gap-3`, `p-3` | S1 |
+| 16px | `gap-4`, `p-4` | S1, S2 (card padding) |
+| 24px | `gap-6`, `p-6` | S2 (page padding) |
+| Page-level padding | `p-6` (24px) | S2 |
+| Card header padding | `px-4 pt-4` | S2 |
+| Card content padding | `px-4 pb-4` | S2 |
+| Section gap (between cards) | `gap-4` (16px) | S3 |
+| Internal element gap | `gap-2` (8px) | S3 |
+| Card internal gap | `gap-2` (8px) | Card component |
+
+### Spacing Scale Reference (Tailwind 4px base)
+```
+0    = 0px       0.5 = 2px       1   = 4px       1.5 = 6px
+2    = 8px       2.5 = 10px      3   = 12px      3.5 = 14px
+4    = 16px      5   = 20px      6   = 24px      7   = 28px
+8    = 32px      9   = 36px      10  = 40px      11  = 44px
+12   = 48px      14  = 56px      16  = 64px      20  = 80px
+24   = 96px      28  = 112px     32  = 128px     36  = 144px
+40   = 160px     44  = 176px     48  = 192px     52  = 208px
+56   = 224px     60  = 240px     64  = 256px     72  = 288px
+80   = 320px     96  = 384px
+```
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Completely different spacing philosophy (e.g., 5px base, irregular increments) |
+| 2 | Some 4px-aligned values but many off-grid spacings (7px, 13px, 18px) |
+| 3 | Mostly 4px-aligned; a few off-grid values that need rounding |
+| 4 | All values map to Tailwind scale; minor differences in which specific steps are used |
+| 5 | Identical spacing patterns (same page padding, card padding, gap hierarchy) |
+
+### Key Comparison Questions
+1. Does the benchmark use a 4px or 8px base grid? typical shadcn/ui uses 4px (Tailwind default).
+2. What is the page-level padding? typical shadcn/ui uses `p-6` (24px) per S2.
+3. What is the card internal padding? typical shadcn/ui uses `px-4 pt-4` / `px-4 pb-4` per S2.
+4. Is the section-to-section gap consistent? typical shadcn/ui uses `gap-4` per S3.
+5. Are there any arbitrary pixel values that don't fall on the 4px grid?
+6. Does the benchmark have tighter or looser spacing than the current project overall?
+7. What is the gap between icon and text label? typical shadcn/ui uses `gap-2` (8px).
+
+---
+
+## Axis 6: Components
+
+**Description**: Compare the styling of major UI components -- Card, Button, Input, Navigation, Table, Modal/Dialog, and Badge. Focus on structural CSS differences, not behavioral logic.
+
+### CSS Properties to Extract (per component)
+
+**Card**: `border-radius`, `border`, `box-shadow`, `background`, `padding`
+**Button**: `border-radius`, `height`, `padding`, `font-size`, `font-weight`, `box-shadow`, `background`, hover/active/disabled states
+**Input**: `border-radius`, `height`, `border`, `box-shadow`, `padding`, `font-size`, focus states
+**Navigation/Nav**: `background`, `width`, `height`, active/hover item styles
+**Table**: `border`, `padding`, header background, row hover, stripe pattern
+**Modal/Dialog**: `border-radius`, `box-shadow`, overlay color, `max-width`, `padding`
+**Badge**: `border-radius`, `padding`, `font-size`, `font-weight`, `background`
+
+### Mapping to Tailwind Conventions
+| Component | shadcn/ui Reference | Key Classes |
+|---|---|---|
+| Card | `<Card>` (shadcn) | `bg-card border rounded-lg shadow-sm` |
+| Button (default) | `<Button>` CVA | `bg-primary text-primary-foreground shadow-md shadow-primary/20 rounded-md h-9 px-4` |
+| Button (outline) | `<Button variant="outline">` | `border bg-background shadow-xs rounded-md` |
+| Button (ghost) | `<Button variant="ghost">` | `hover:bg-accent hover:text-accent-foreground rounded-md` |
+| Input | `<Input>` | `border-input rounded-md shadow-sm h-9 px-3 text-sm` |
+| Dialog | `<DialogContent>` | `bg-background rounded-lg border shadow-lg p-6 max-w-lg` |
+| Badge (default) | `<Badge>` CVA | `bg-primary text-primary-foreground rounded-full px-2 py-0.5 text-xs` |
+| Badge (outline) | `<Badge variant="outline">` | `border-border text-foreground rounded-full` |
+| Table | `<Table>` | `w-full text-sm`, row: `hover:bg-muted/50 border-b`, head: `h-10 px-2 font-medium` |
+| Sidebar | `<Sidebar>` | `bg-sidebar w-[16rem]`, item: `rounded-md p-2 text-sm` |
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Fundamentally different component design language (e.g., Material vs shadcn) |
+| 2 | Same general concept but different radius, shadow, padding, and color application |
+| 3 | Similar feel; 3-4 property overrides needed per component |
+| 4 | Very close; 1-2 CSS property tweaks bring them into alignment |
+| 5 | Identical component styling |
+
+### Key Comparison Questions
+1. Does the benchmark use `rounded-lg` for cards and `rounded-md` for buttons/inputs like the current project?
+2. What shadow depth does the benchmark use for cards? typical shadcn/ui uses `shadow-sm` (SH2).
+3. Are buttons the same height (`h-9`)? Same padding (`px-4`)?
+4. Does the benchmark's dialog use `shadow-lg` like the current project?
+5. Are badges `rounded-full` or `rounded-md`? typical shadcn/ui uses `rounded-full`.
+6. Does the table have row hover states? What color?
+7. Are there component variants (default/outline/ghost/destructive) similar to the project's CVA pattern?
+8. Does the benchmark separate `CardHeader`/`CardContent` or use a flat div structure?
+
+---
+
+## Axis 7: Interaction
+
+**Description**: Analyze hover states, focus indicators, transitions, animations, micro-interactions, and motion design. the project may have strict animation rules (tw-animate-css only, no framer-motion).
+
+### CSS Properties to Extract
+- `transition`, `transition-property`, `transition-duration`, `transition-timing-function`
+- `animation`, `animation-name`, `animation-duration`, `@keyframes`
+- `:hover` state changes (color, background, shadow, transform)
+- `:focus-visible` ring/outline styles
+- `:active` state changes
+- `transform` (scale, translate, rotate on interaction)
+- `cursor` values
+- `will-change`, `backface-visibility` (performance hints)
+
+### Mapping to Tailwind Conventions
+| Benchmark Pattern | Tailwind / shadcn Equivalent | Rule |
+|---|---|---|
+| `transition: all 200ms` | `transition-all duration-200` | A2 |
+| `transform: scale(0.98)` on active | Not common in shadcn/ui | -- |
+| Focus ring | `focus-visible:ring-ring/50 focus-visible:ring-[3px]` | AC1 |
+| Hover bg change | `hover:bg-accent hover:text-accent-foreground` | -- |
+| Button hover | `hover:bg-primary/90` (default variant) | -- |
+| Enter/exit animations | `animate-in`/`animate-out` (tw-animate-css) | A1 |
+| Fade in | `animate-fade-in` or `data-[state=open]:fade-in-0` | A1 |
+| No framer-motion | `tw-animate-css` classes only | A1 |
+| Dialog enter | `zoom-in-95 fade-in-0` | Dialog component |
+| Reduced motion | `@media (prefers-reduced-motion: reduce)` | -- |
+
+### 5-Point Scoring Rubric
+| Score | Description |
+|-------|-------------|
+| 1 | Heavy animation library (GSAP/framer-motion), complex choreographed transitions |
+| 2 | Uses CSS animations but with different timing, easing, or interaction patterns |
+| 3 | Similar approach (CSS transitions); minor timing/easing differences |
+| 4 | Nearly identical; same transition properties, similar durations |
+| 5 | Identical interaction patterns and animation library |
+
+### Key Comparison Questions
+1. Does the benchmark use a CSS animation library or framer-motion? check project design rules for animation constraints.
+2. What is the standard transition duration? typical shadcn/ui uses `duration-200` as default.
+3. How are focus indicators styled? typical shadcn/ui uses `ring-ring/50 ring-[3px]` (AC1).
+4. Are there hover shadows or transforms? typical shadcn/ui uses `hover:bg-primary/90` for buttons.
+5. Does the benchmark have page transition animations?
+6. Are there scroll-triggered animations? check if project uses scroll-based animations.
+7. Does the benchmark respect `prefers-reduced-motion`?
+8. What micro-interactions exist (tooltip delays, dropdown easing, skeleton shimmer)?
+
+---
+
+## Aggregate Scoring
+
+After scoring all 7 axes, compute the aggregate:
+
+```
+Overall Similarity = (Layout + Color + Typography + Icons + Spacing + Components + Interaction) / 7
+```
+
+| Range | Interpretation | Migration Effort |
+|-------|---------------|-----------------|
+| 1.0 - 1.9 | Fundamentally different design system | Full redesign required |
+| 2.0 - 2.9 | Different but some structural overlap | Major token remapping + component overhaul |
+| 3.0 - 3.9 | Moderately similar, clear migration path | Token adjustments + targeted component overrides |
+| 4.0 - 4.9 | Very similar, minimal gaps | Minor CSS variable tweaks |
+| 5.0 | Identical | No migration needed |