devflow-kit 1.8.3 → 2.0.0

package/src/assets/skills/ui-design/references/patterns.md

@@ -0,0 +1,341 @@
+# UI Design Correct Patterns
+
+Extended correct patterns for UI design. Reference from main SKILL.md.
+Sources in `references/sources.md`.
+
+---
+
+## Typography Patterns [6][7][10][19]
+
+### Intentional Font Selection [6][7]
+
+Font personality must match product context. [6][27]
+
+```css
+/* Developer tools — monospace conveys precision, code-first [6][27] */
+:root {
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+  --font-sans: 'Inter', system-ui, sans-serif;
+}
+
+/* Documentation — optimized for long-form reading [7][19] */
+:root {
+  --font-body:    'Source Serif Pro', Georgia, serif;
+  --font-heading: 'Source Sans Pro', system-ui, sans-serif;
+  --font-code:    'Source Code Pro', monospace;
+}
+
+/* Brand-forward — distinctive personality [27] */
+:root {
+  --font-display: 'Fraunces', serif;  /* Distinctive headlines */
+  --font-body:    'DM Sans', sans-serif;
+}
+```
+
+### Mathematical Type Scale [10]
+
+Modular scale with 1.25 (major third) ratio — all sizes relate harmonically. [10]
+
+```css
+/* CORRECT: 1.25 ratio scale [10] */
+:root {
+  --text-xs:  0.64rem;   /* 10.24px */
+  --text-sm:  0.8rem;    /* 12.8px  */
+  --text-base: 1rem;     /* 16px    */
+  --text-lg:  1.25rem;   /* 20px    */
+  --text-xl:  1.563rem;  /* 25px    */
+  --text-2xl: 1.953rem;  /* 31.25px */
+  --text-3xl: 2.441rem;  /* 39px    */
+  --text-4xl: 3.052rem;  /* 48.8px  */
+}
+
+/* CORRECT: Weight + tracking differentiate heading levels [7][15] */
+h1 { font-size: var(--text-4xl); font-weight: 800; letter-spacing: -0.03em; line-height: 1.1; }
+h2 { font-size: var(--text-2xl); font-weight: 700; letter-spacing: -0.02em; line-height: 1.2; }
+h3 { font-size: var(--text-xl);  font-weight: 600; letter-spacing: -0.01em; line-height: 1.3; }
+```
+
+### Optimized Readability [6][7][19]
+
+```css
+/* CORRECT: Optimal line length 45–75 characters [6][7] */
+.prose {
+  max-width: 65ch;     /* ~65 characters per line */
+  line-height: 1.7;
+  font-size: 1.125rem; /* Slightly larger for comfortable reading */
+}
+
+.ui-text {
+  max-width: none;
+  line-height: 1.4;
+  font-size: 0.875rem;
+}
+
+/* Fluid type with clamp() — no layout breakpoints needed [28] */
+.heading-fluid {
+  font-size: clamp(var(--text-2xl), 5vw, var(--text-4xl));
+}
+```
+
+---
+
+## Color System Patterns [1][9][12][14]
+
+### Three-Layer Token Architecture [1][9]
+
+Material Design 3 [1] and W3C Design Tokens spec [9] both recommend this layering:
+
+```css
+:root {
+  /* Layer 1 — Primitives: raw named values */
+  --blue-50:  #eff6ff;
+  --blue-500: #3b82f6;
+  --blue-600: #2563eb;
+  --blue-700: #1d4ed8;
+
+  /* Layer 2 — Semantic: meaning-based aliases */
+  --color-primary:        var(--blue-600);
+  --color-primary-hover:  var(--blue-700);
+  --color-primary-subtle: var(--blue-50);
+
+  /* Layer 3 — Component: specific usage */
+  --button-primary-bg:       var(--color-primary);
+  --button-primary-bg-hover: var(--color-primary-hover);
+  --link-color:              var(--color-primary);
+}
+
+/* Dark mode swaps semantic layer only [1][23] */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-primary:        var(--blue-500);
+    --color-primary-hover:  var(--blue-400);
+    --color-primary-subtle: var(--blue-900);
+  }
+}
+```
+
+### Designed Dark Surfaces [1][12][23]
+
+Elevation in dark mode is expressed through lightness (lighter = higher), not shadows. [1][12]
+
+```css
+/* CORRECT: Elevation via lightness in dark mode [1] */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --surface-0:        #0a0a0a;  /* Base */
+    --surface-1:        #141414;  /* Cards */
+    --surface-2:        #1f1f1f;  /* Sidebars */
+    --surface-elevated: #262626;  /* Modals */
+
+    --text-primary:   #f9fafb;
+    --text-secondary: #d1d5db;
+    --text-muted:     #6b7280;
+
+    --border-default: #2e2e2e;
+    --border-strong:  #404040;
+  }
+}
+```
+
+### Accessible Contrast [14][26]
+
+```css
+/* CORRECT: All text verified against WCAG 2.2 AA [14][26] */
+:root {
+  /* 4.5:1 minimum for normal text */
+  --text-on-primary:  #ffffff;  /* White on blue-600:  4.6:1 ✓ */
+  --text-on-surface:  #111827;  /* Gray-900 on white: 15.8:1 ✓ */
+  --text-secondary:   #4b5563;  /* Gray-600 on white:  5.7:1 ✓ */
+  --text-link:        #2563eb;  /* Blue-600 on white:  4.5:1 ✓ */
+}
+/* 3:1 minimum for large text (18pt+) and UI components [14] */
+```
+
+---
+
+## Spacing Patterns [1][13][15]
+
+### 4px/8px Base Grid [1][13]
+
+Müller-Brockmann's grid mathematics [13], adopted by Material Design as 4dp grid. [1]
+
+```css
+/* CORRECT: Base-4 spacing system [1][13] */
+:root {
+  --space-0:   0;
+  --space-px:  1px;
+  --space-0-5: 0.125rem; /* 2px  */
+  --space-1:   0.25rem;  /* 4px  */
+  --space-2:   0.5rem;   /* 8px  */
+  --space-3:   0.75rem;  /* 12px */
+  --space-4:   1rem;     /* 16px */
+  --space-5:   1.25rem;  /* 20px */
+  --space-6:   1.5rem;   /* 24px */
+  --space-8:   2rem;     /* 32px */
+  --space-10:  2.5rem;   /* 40px */
+  --space-12:  3rem;     /* 48px */
+  --space-16:  4rem;     /* 64px */
+  --space-20:  5rem;     /* 80px */
+  --space-24:  6rem;     /* 96px */
+}
+```
+
+### Hierarchical Spacing [5][15]
+
+Gestalt proximity: elements close together are perceived as related. [5]
+
+```css
+/* CORRECT: Larger gaps between sections, smaller within [5][15] */
+.section        { padding-block: var(--space-16); }
+.section-header { margin-bottom: var(--space-8); }
+.card           { padding: var(--space-6); }
+.card-header    { margin-bottom: var(--space-4); }
+.card-title     { margin-bottom: var(--space-2); }
+.card-actions   { margin-top: var(--space-6); display: flex; gap: var(--space-3); }
+```
+
+---
+
+## Motion Patterns [4][11][24]
+
+### Purposeful State Transitions [4][11]
+
+Animation communicates function — each state change tells the user what happened. [11]
+
+```css
+/* CORRECT: System-defined timing [1] */
+:root {
+  --duration-instant: 50ms;   /* Opacity, color changes */
+  --duration-fast:   100ms;   /* Hover, active states — Fitts feedback [4] */
+  --duration-normal: 200ms;   /* Dropdowns, tooltips */
+  --duration-slow:   300ms;   /* Modals, drawers */
+  --duration-slower: 500ms;   /* Page/layout transitions */
+  --ease-out:     cubic-bezier(0, 0, 0.2, 1);
+  --ease-in-out:  cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* CORRECT: Specific properties only — never "all" */
+.button {
+  transition:
+    background-color var(--duration-fast) var(--ease-out),
+    transform var(--duration-instant) var(--ease-out);
+}
+.button:active { transform: scale(0.98); } /* "I received your click" [11] */
+```
+
+### Reduced Motion Support [24][26]
+
+```css
+/* CORRECT: Required accessibility accommodation [24][26] */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+---
+
+## Component Patterns [1][3][5][15]
+
+### Atomic Design Hierarchy [3]
+
+Atoms (token) → Molecules (input + label) → Organisms (form) → Templates → Pages. [3]
+Build atoms with tokens; compose molecules without re-specifying primitives.
+
+### Contextual Radius and Elevation [1][15]
+
+```css
+/* CORRECT: Radius and shadow signal interactivity level [1][15] */
+:root {
+  --radius-sm:   4px;
+  --radius-md:   6px;
+  --radius-lg:   8px;
+  --radius-xl:   12px;
+  --radius-full: 9999px;
+
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1);
+  --shadow-xl: 0 20px 25px -5px rgba(0,0,0,0.1);
+}
+
+.badge             { border-radius: var(--radius-sm); box-shadow: none; }
+.button            { border-radius: var(--radius-md); box-shadow: none; }
+.card              { border-radius: var(--radius-lg); box-shadow: var(--shadow-sm); }
+.card-interactive:hover { box-shadow: var(--shadow-md); }
+.dropdown          { border-radius: var(--radius-lg); box-shadow: var(--shadow-lg); }
+.modal             { border-radius: var(--radius-xl); box-shadow: var(--shadow-xl); }
+.avatar            { border-radius: var(--radius-full); }
+```
+
+### Token-Driven Components [9][17]
+
+```tsx
+// CORRECT: Components use tokens, not raw values [9][17]
+const Button = styled.button`
+  padding: var(--space-2) var(--space-4);
+  font-size: var(--text-sm);
+  font-weight: 500;
+  border-radius: var(--radius-md);
+  background: var(--button-primary-bg);
+  color: var(--text-on-primary);
+  transition: background var(--duration-fast) var(--ease-out);
+
+  &:hover  { background: var(--button-primary-bg-hover); }
+  &:active { transform: scale(0.98); }
+`;
+```
+
+### Responsive Breakpoints [8][22]
+
+Container queries (CSS Level 5 [22]) for component-level responsiveness:
+
+```css
+/* CORRECT: Minimal, purposeful breakpoints [8] */
+.container {
+  width: 100%;
+  max-width: 1280px;
+  margin-inline: auto;     /* Logical properties [29] */
+  padding-inline: var(--space-4);
+}
+
+@media (min-width: 768px)  { .container { padding-inline: var(--space-6); } }
+@media (min-width: 1024px) { .container { padding-inline: var(--space-8); } }
+
+/* Container query for component-level responsive [22] */
+@container (min-width: 400px) {
+  .card { flex-direction: row; }
+}
+```
+
+---
+
+## Design System Documentation [9][15]
+
+```css
+/* CORRECT: Self-documenting design tokens [9] */
+:root {
+  /*
+   * COLOR SYSTEM [1][9]
+   * Primitives: Raw hue+shade values (--blue-600)
+   * Semantic:   Meaning aliases (--color-primary)
+   * Component:  Specific usage (--button-primary-bg)
+   */
+
+  /*
+   * SPACING SYSTEM [1][13]
+   * Base unit: 4px (0.25rem) — Müller-Brockmann 4-column grid
+   * Scale: 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24
+   */
+
+  /*
+   * TYPOGRAPHY SYSTEM [6][10]
+   * Scale ratio: 1.25 (major third) — Modular Scale
+   * Base: 16px; Weights: 400, 500, 600, 700, 800
+   */
+}
+```

package/src/assets/skills/ui-design/references/sources.md

@@ -0,0 +1,41 @@
+# UI Design — Sources
+
+## Primary References
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 1 | Material Design 3 | Google | 2024 | [Free](https://m3.material.io) | Components, design tokens, color system, theming, typography scale |
+| 2 | Apple Human Interface Guidelines | Apple | 2024 | [Free](https://developer.apple.com/design/) | Platform design principles, affordances, visual hierarchy |
+| 3 | "Atomic Design" | Brad Frost | 2016 | [Free](https://atomicdesign.bradfrost.com) | Component hierarchy (atoms → molecules → organisms → templates → pages) |
+| 4 | Laws of UX | Jon Yablonski | 2024 | [Free](https://lawsofux.com) | Psychology-backed UX principles: Fitts, Hick, Miller, Jakob, Doherty |
+| 5 | Gestalt Principles | Interaction Design Foundation | 2024 | [Free](https://www.interaction-design.org/literature/topics/gestalt-principles) | Proximity, similarity, closure, continuity, figure-ground |
+| 6 | "Practical Typography" | Matthew Butterick | 2024 | [Free](https://practicaltypography.com) | Typography fundamentals, font selection, line length, line spacing |
+| 7 | "The Elements of Typographic Style" | Robert Bringhurst | 2012 | Purchase | Canonical typography reference: optical sizing, rhythm, grid |
+| 8 | CSS Grid Specification | W3C | 2024 | [Free](https://www.w3.org/TR/css-grid-1/) | Grid layout, named areas, auto-placement |
+| 9 | Design Tokens W3C Community Group | W3C | 2024 | [Free](https://design-tokens.github.io/community-group/format/) | Token format spec: primitives, semantic, component layers |
+| 10 | Modular Scale | Tim Brown | 2024 | [Free](https://modularscale.com) | Type scale mathematics: ratios, base sizes, harmonic scales |
+| 11 | "The Design of Everyday Things" | Don Norman | 2013 | Purchase | Affordances, signifiers, feedback, mental models, mapping |
+| 12 | "Interaction of Color" | Josef Albers | 1963 | Purchase | Color relativity, simultaneous contrast, temperature, perception |
+| 13 | "Grid Systems in Graphic Design" | Josef Müller-Brockmann | 1996 | Purchase | Grid mathematics, column systems, spatial order |
+| 14 | WCAG 2.2 — Color Contrast | W3C | 2023 | [Free](https://www.w3.org/TR/WCAG22/#contrast-minimum) | Contrast ratios: 4.5:1 normal text, 3:1 large text, 3:1 UI components |
+| 15 | "Refactoring UI" | Adam Wathan & Steve Schoger | 2018 | Purchase | Practical UI design for developers: hierarchy, color, spacing, typography |
+| 16 | "Don't Make Me Think" | Steve Krug | 2014 | Purchase | Cognitive load, visual weight, scanning behavior, usability principles |
+| 17 | Tailwind CSS Documentation | Tailwind Labs | 2024 | [Free](https://tailwindcss.com/docs) | Utility-first CSS, design system tokens via config, responsive prefixes |
+| 18 | CSS-Tricks Complete Guides | Chris Coyier et al. | 2024 | [Free](https://css-tricks.com/guides/) | Flexbox, Grid, modern CSS patterns |
+| 19 | "Web Typography" | Richard Rutter | 2017 | Free excerpts | Web-specific type: variable fonts, line length, optical adjustments |
+| 20 | Open Props | Adam Argyle | 2024 | [Free](https://open-props.style) | Modern CSS custom property patterns, design token baseline |
+
+## Standards & Specifications
+
+| # | Source | Org | Access | Topics |
+|---|--------|-----|--------|--------|
+| 21 | CSS Custom Properties | W3C | [Free](https://www.w3.org/TR/css-variables-1/) | CSS variables, cascade, inheritance, design token implementation |
+| 22 | CSS Container Queries | W3C | [Free](https://www.w3.org/TR/css-contain-3/) | Container-based responsive design, component-level breakpoints |
+| 23 | `prefers-color-scheme` | MDN/W3C | [Free](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) | Dark mode media query, OS-level preference detection |
+| 24 | `prefers-reduced-motion` | MDN/W3C | [Free](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) | Motion reduction accessibility requirement |
+| 25 | CSS Flexbox | W3C | [Free](https://www.w3.org/TR/css-flexbox-1/) | One-dimensional layout, alignment, distribution |
+| 26 | Web Content Accessibility Guidelines (WCAG) 2.2 | W3C | [Free](https://www.w3.org/TR/WCAG22/) | Accessibility requirements: contrast, focus, motion |
+| 27 | Google Fonts Knowledge | Google | [Free](https://fonts.google.com/knowledge) | Typeface selection, variable fonts, font pairing |
+| 28 | "Fluid Typography" — CSS `clamp()` | MDN | [Free](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp) | Viewport-based fluid scales, min/max constraints |
+| 29 | CSS Logical Properties | W3C | [Free](https://www.w3.org/TR/css-logical-1/) | Writing-mode-agnostic spacing: `padding-inline`, `margin-block` |
+| 30 | Nielsen Norman Group — Visual Hierarchy | NN/g | [Free](https://www.nngroup.com/articles/visual-hierarchy-ux-definition/) | Hierarchy principles: size, contrast, alignment, whitespace |

package/src/assets/skills/ui-design/references/violations.md

@@ -0,0 +1,312 @@
+# UI Design Violations
+
+Extended violation patterns for UI design reviews. Reference from main SKILL.md.
+Sources in `references/sources.md`.
+
+---
+
+## Typography Violations [6][7][10]
+
+### No Rationale for Font Choice [6][27]
+
+```css
+/* VIOLATION: Default sans-serif without justification [6] */
+body { font-family: 'Inter', 'Helvetica Neue', Arial, sans-serif; }
+/* Why Inter? What personality does it convey for this product? */
+
+/* VIOLATION: Trend-following font choice */
+body { font-family: 'Poppins', sans-serif; }
+/* Poppins is everywhere — is it right for YOUR product? [6] */
+```
+
+### Flat Type Hierarchy [7][10][15]
+
+```css
+/* VIOLATION: Minimal size difference, identical weight [10][15] */
+h1 { font-size: 24px; font-weight: 600; }
+h2 { font-size: 22px; font-weight: 600; }
+h3 { font-size: 20px; font-weight: 600; }
+h4 { font-size: 18px; font-weight: 600; }
+/* Not a mathematical scale; users cannot scan content hierarchy [7] */
+
+/* VIOLATION: No type variation beyond size */
+.title    { font-size: 2rem; }
+.subtitle { font-size: 1.5rem; }
+.body     { font-size: 1rem; }
+/* Weight, tracking, and color are hierarchy tools too [7][15] */
+```
+
+### Poor Readability [6][7][19]
+
+```css
+/* VIOLATION: Too tight for body text — strains eyes [6] */
+p { font-size: 16px; line-height: 1.2; }
+
+/* VIOLATION: Line too long — exceeds 75ch optimal range [6][7] */
+.content { max-width: 1200px; font-size: 16px; }
+/* 150+ characters per line; readers lose their place [7] */
+
+/* VIOLATION: Inconsistent line heights — no system [10] */
+.card-title  { line-height: 1.1; }
+.card-body   { line-height: 1.8; }
+.card-footer { line-height: 1.4; }
+/* Random values without ratio-based scale [10] */
+```
+
+---
+
+## Color Violations [1][9][12][14]
+
+### Random Hex Values [1][9][15]
+
+```css
+/* VIOLATION: Colors without three-layer token system [1][9] */
+.button-primary   { background: #4f46e5; }
+.button-secondary { background: #6366f1; }
+.link             { color: #3b82f6; }
+.error            { color: #ef4444; }
+/* Multiple blues with no semantic meaning or relationship [12] */
+
+/* VIOLATION: Inline color overrides break system [9] */
+<span style={{ color: '#8b5cf6' }}>Special text</span>
+/* One-off values outside the token system cannot be themed */
+```
+
+### AI Slop Gradients [15]
+
+```css
+/* VIOLATION: Template gradient with no brand relevance [15] */
+.hero { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); }
+
+/* VIOLATION: Purple-pink gradient copied from templates [15] */
+.button { background: linear-gradient(to right, #ec4899, #8b5cf6); }
+/* Seen on thousands of sites — communicates nothing specific */
+
+/* VIOLATION: Gradient on text without semantic purpose */
+.heading {
+  background: linear-gradient(90deg, #f97316, #ec4899);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+/* Eye-catching, but what does the gradient communicate? [11] */
+```
+
+### Dark Mode Afterthoughts [1][23]
+
+```css
+/* VIOLATION: Invert filter hack — inverts images, ruins UI [23] */
+@media (prefers-color-scheme: dark) {
+  body { filter: invert(1) hue-rotate(180deg); }
+  img  { filter: invert(1) hue-rotate(180deg); }
+}
+
+/* VIOLATION: Only swapping background — text/border/shadow remain broken */
+.dark { background: #1a1a1a; }
+
+/* VIOLATION: Inconsistent design language across modes */
+.card { background: white; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+.dark .card {
+  background: #2d2d2d;
+  border: 1px solid #444; /* Shadows become borders — no consistency [1] */
+}
+```
+
+### Contrast Failures [14][26]
+
+```css
+/* VIOLATION: Same primary blue on dark background — poor contrast [14] */
+:root        { --primary: #0066cc; }
+.dark .link  { color: var(--primary); } /* Unverified on dark surface */
+
+/* VIOLATION: Shadow invisible on dark background [14] */
+.dark .card { box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+/* Near-black on black — effectively no elevation cue */
+```
+
+---
+
+## Motion Violations [4][11][24]
+
+### Decorative Animation [4][11]
+
+```css
+/* VIOLATION: Animation without state communication [11] */
+.logo { animation: float 3s ease-in-out infinite; }
+/* Why is the logo floating? What does it tell the user? */
+
+/* VIOLATION: Pulsing CTA — Hick's Law: noise slows decisions [4] */
+.cta-button { animation: pulse 2s infinite; }
+
+/* VIOLATION: Spinners for instant operations */
+.loading { animation: spin 1s linear infinite; }
+/* Users experience false latency on sub-100ms operations */
+```
+
+### Inconsistent Timing [1][4]
+
+```css
+/* VIOLATION: Random durations — no timing system [1] */
+.modal   { transition: opacity 0.35s ease, transform 0.4s cubic-bezier(0.4, 0, 0.2, 1); }
+.dropdown { transition: all 0.2s linear; }
+.tooltip { transition: opacity 150ms; }
+.button  { transition: background 0.1s, transform 0.15s, box-shadow 0.2s; }
+/* Inconsistent rhythm; UI feels unpolished [4] */
+
+/* VIOLATION: "all" transition — animates layout properties [18] */
+.card { transition: all 0.3s ease; }
+/* Causes width/height layout shifts on resize */
+```
+
+### Missing Reduced Motion [24][26]
+
+```css
+/* VIOLATION: No @media (prefers-reduced-motion) declaration [24][26] */
+/* Affects users with vestibular disorders, epilepsy, motion sensitivity */
+/* WCAG 2.2 Success Criterion 2.3.3 (AAA) and 2.3.1 (A for flashing) */
+```
+
+---
+
+## Spacing Violations [1][13][15]
+
+### Magic Numbers [13][15]
+
+```css
+/* VIOLATION: Values outside 4px grid — no relationship [13] */
+.card   { padding: 18px 22px; margin-bottom: 13px; }
+.header { padding: 14px 20px; margin-bottom: 27px; }
+/* Arbitrary numbers; cannot be reasoned about as a system */
+
+/* VIOLATION: Non-grid pixel values scattered throughout [1] */
+.section { margin: 47px 0; }
+.title   { margin-bottom: 11px; }
+.button  { padding: 9px 17px; }
+```
+
+### No Spatial Hierarchy [5][13][15]
+
+```tsx
+// VIOLATION: Uniform spacing ignores Gestalt proximity [5]
+* + * { margin-top: 1rem; }
+/* Everything equally spaced — no grouping cues */
+
+// VIOLATION: Same gap regardless of relationship [5][15]
+.grid   { gap: 16px; }
+.stack  { gap: 16px; }
+.inline { gap: 16px; }
+```
+
+---
+
+## Layout Violations [5][11][15][30]
+
+### Everything Centered [5][30]
+
+```css
+/* VIOLATION: Centered layout everywhere — no reading flow [30] */
+.page    { text-align: center; }
+.card    { text-align: center; }
+.section { text-align: center; }
+/* Centered text works for headings; body text needs left-aligned flow [6] */
+```
+
+### Border Radius Overuse [1][15]
+
+```css
+/* VIOLATION: Identical radius on all components — no scale signal [1][15] */
+.button { border-radius: 12px; }
+.card   { border-radius: 12px; }
+.input  { border-radius: 12px; }
+.avatar { border-radius: 12px; } /* Should be 9999px — full circle */
+.badge  { border-radius: 12px; } /* Should be 4px — small element */
+```
+
+### Shadow Abuse [1][11][15]
+
+```css
+/* VIOLATION: Same shadow on everything — elevation loses meaning [11] */
+.card   { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+.button { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+.input  { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+.header { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+/* If everything is elevated, nothing is [1] */
+
+/* VIOLATION: Deep shadow on micro element */
+.badge { box-shadow: 0 10px 25px rgba(0,0,0,0.2); }
+```
+
+---
+
+## Component Violations [3][4][15]
+
+### Generic Hero Sections [11][15]
+
+```tsx
+// VIOLATION: Template hero — seen on thousands of sites [15]
+<section className="hero bg-gradient-to-r from-purple-600 to-pink-500">
+  <div className="container mx-auto text-center text-white">
+    <h1 className="text-5xl font-bold mb-4">Welcome to Our Platform</h1>
+    <p className="text-xl mb-8">The best solution for your needs</p>
+    <button className="bg-white text-purple-600 rounded-full px-8 py-3">
+      Get Started
+    </button>
+  </div>
+</section>
+/* What product is this? What does the gradient communicate? [11] */
+```
+
+### Glassmorphism Everywhere [15]
+
+```css
+/* VIOLATION: Blur on every surface — decorative, not functional [15] */
+.card  { background: rgba(255,255,255,0.2); backdrop-filter: blur(10px); }
+.modal { background: rgba(255,255,255,0.15); backdrop-filter: blur(20px); }
+.nav   { background: rgba(255,255,255,0.1); backdrop-filter: blur(8px); }
+/* Performance cost; legibility risk; trend not purpose [4] */
+```
+
+### Trend-Following Layouts [4][5]
+
+```css
+/* VIOLATION: Bento grid because it's trendy — not because it serves content [4] */
+.features { display: grid; grid-template-columns: repeat(4, 1fr); }
+.feature-1 { grid-column: span 2; grid-row: span 2; }
+/* Does this layout aid comprehension or just look "cool"? [5] */
+
+/* VIOLATION: Scroll animations on everything — Miller's Law: cognitive overload [4] */
+.section {
+  opacity: 0;
+  transform: translateY(50px);
+  transition: all 0.6s ease; /* Blocks content consumption */
+}
+```
+
+---
+
+## Responsive Violations [8][22]
+
+### Desktop-First with Broken Mobile [8]
+
+```css
+/* VIOLATION: Mobile treatment is "hide everything" [8] */
+.sidebar { width: 300px; }
+.content { margin-left: 300px; }
+
+@media (max-width: 768px) {
+  .sidebar { display: none; } /* Content hidden, not adapted */
+  .content { margin-left: 0; }
+}
+```
+
+### Breakpoint Chaos [8][22]
+
+```css
+/* VIOLATION: Too many breakpoints — impossible to reason about [8] */
+@media (max-width: 1200px) { ... }
+@media (max-width: 992px)  { ... }
+@media (max-width: 768px)  { ... }
+@media (max-width: 576px)  { ... }
+@media (max-width: 480px)  { ... }
+@media (max-width: 375px)  { ... }
+/* Use 2–3 intentional breakpoints; prefer container queries [22] */
+```