contextos-agents 2.0.0 → 2.1.1

package/catalog/skills/ui-design/EXAMPLES.md

@@ -0,0 +1,21 @@
+# ui-design Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Component Token Consistency
+
+### Anti-pattern: Hardcoded Arbitrary Tailwind Utilities
+
+```tsx
+// BAD: Inconsistent spacing, arbitrary colors, unmaintainable styling
+<div className="p-[13px] bg-[#1a1b2e] rounded-[7px] text-[#99aab5] border border-[#2b2d42]">
+  <button className="px-[15px] py-[7px] bg-[#5865f2] hover:bg-[#4752c4]">Action</button>
+</div>
+```
+
+### Best practice: ContextOS Standard (Semantic Theme Tokens)
+
+```tsx
+// GOOD: Consistent scale utilities driven by Tailwind v4 @theme design tokens
+<div className="p-4 bg-card rounded-lg text-muted-foreground border border-border">
+  <Button variant="primary" size="md">Action</Button>
+</div>
+```

package/catalog/skills/ui-design/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: UI Design
+description: >
+  ContextOS skill for UI Design
+---
+
+# UI Design
+
+## Overview
+
+Modern component library and design system engineering. Enforces design token hierarchies (spacing, radii, elevation), accessible component primitives (shadcn/ui, Radix), and responsive layout constraints.
+
+## When to Use
+
+Activate when designing design systems, reusable UI component libraries, navigation bars, modals, data tables, and interactive dashboards.
+
+## Rules & Patterns
+<!-- Source: ui.md -->
+
+## UI Design - Best Practices
+
+## Design System Foundations
+
+### Color
+
+- **Never use generic colors** - curate a harmonious palette
+- **Always tint** - no pure black (#000), no pure gray. Add a subtle warm or cool tint
+- **Color roles**: primary (action), secondary (accent), neutral (text, borders), semantic (error, success, warning, info)
+- **Dark mode**: design intentionally, not just invert. Surface hierarchy: background < surface < elevated
+- **Contrast**: 4.5:1 minimum for body text, 3:1 for large text
+
+### Typography
+
+- **Never use browser defaults** - choose a curated font (Inter, Outfit, Geist, Sora)
+- **Type scale**: use a modular scale (1.25 ratio) - 12, 14, 16, 20, 24, 32, 40, 48
+- **Font weights**: Regular (400), Medium (500), Semibold (600), Bold (700). Don't use all of them - pick 2-3
+- **Line height**: 1.5 for body, 1.2 for headings, 1.6 for long-form text
+- **Max line width**: 65-75 characters for readability
+
+### Spacing
+
+- **Use a 4px grid** - all spacing should be multiples of 4
+- **Spacing scale**: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96
+- **Consistency** - same spacing between similar elements
+- **Whitespace is design** - don't fill every pixel
+
+### Layout
+
+- **Grid system**: 12-column grid for desktop, 4-column for mobile
+- **Visual hierarchy**: size, weight, color, spacing, position
+- **F-pattern/Z-pattern** - for content-heavy pages
+- **Group related items** - use proximity and boundaries
+
+## Component Patterns
+
+### Buttons
+
+- Clear hierarchy: Primary > Secondary > Ghost/Text
+- Consistent sizing: sm (32px), md (40px), lg (48px)
+- States: default, hover, active, disabled, loading
+- Always accessible: sufficient contrast, focus indicator
+
+### Forms
+
+- Labels above inputs (not floating labels for critical forms)
+- Clear error states with inline messages
+- Logical tab order
+- Progressive disclosure - don't show all fields at once
+
+### Cards
+
+- Don't nest cards inside cards
+- Clear visual hierarchy within the card
+- Consistent padding and spacing
+- Interactive cards need hover state
+
+### Navigation
+
+- Maximum 7±2 items in primary nav
+- Clear active state
+- Mobile: bottom nav or hamburger (not both)
+- Breadcrumbs for deep hierarchies
+
+## Animation Principles
+
+- **Purpose**: guide attention, show relationships, provide feedback
+- **Duration**: 150-300ms for micro-interactions, 300-500ms for transitions
+- **Easing**: `ease-out` for entrances, `ease-in` for exits. Never `bounce` or `elastic`
+- **Reduce motion**: respect `prefers-reduced-motion`
+
+## Anti-Patterns (from Impeccable)
+
+- [FAIL] Gray text on colored backgrounds - destroys readability
+- [FAIL] Pure black text on white (#000 on #fff) - too harsh, tint the black
+- [FAIL] Cards nested inside cards - visual noise
+- [FAIL] Bounce/elastic easing - feels dated
+- [FAIL] Icon tile above every heading - SaaS template tell
+- [FAIL] Purple-to-blue gradient on everything - overused
+- [FAIL] Using Inter for everything - pick a font that matches your brand
+- [FAIL] Rounded-square icons everywhere - lack of visual variety
+
+## Dark Mode
+
+- Surface elevation through subtle lightening (not colored backgrounds)
+- Reduce white contrast - use #E0E0E0, not #FFFFFF
+- Shadows become less visible - use subtle borders or elevation changes
+- Test all states in both modes
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/ui-design/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# ui-design Troubleshooting & Common Mistakes
+
+## 1. Z-Index Chaos
+
+- **Symptom**: Tooltips rendered underneath dialog overlays, or dropdowns hidden behind sticky headers.
+- **Root Cause**: Ad-hoc hardcoded values (z-50, z-[999], z-[9999]).
+- **Fix**: Use Radix / shadcn Portals for floating elements so they render at root DOM level, or declare strict z-index tokens.
+
+## 2. Inconsistent Component States
+
+- **Symptom**: Buttons have hover states but lack focus-visible rings or disabled states.
+- **Root Cause**: Styling only the default and hover states.
+- **Fix**: Standardize state matrices for every interactive element: default, hover, focus-visible, active, disabled, loading.
+
+## 3. Ignoring Empty and Error Component States
+
+- **Symptom**: Tables or list views show a blank white box when there are 0 records.
+- **Root Cause**: Developers only design for the "ideal data" case.
+- **Fix**: Every data component must explicitly render designed EmptyState and ErrorState fallbacks.

package/catalog/skills/ui-design/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/ui-design/skill.yaml

@@ -0,0 +1,16 @@
+schemaVersion: 2
+id: ui-design
+name: UI Design
+category: design
+type: instruction-only
+requires: []
+optional: [react, tailwind, web-accessibility]
+conflicts: []
+weight: 7
+deprecated: true
+canonical: ui-ux-pro
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/ui-ux-pro/EXAMPLES.md

@@ -0,0 +1,62 @@
+# UI/UX Pro Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Accessible Icon Button with Visible Focus States
+
+### Anti-pattern: Anti-pattern (Missing accessible name and arbitrary color values)
+
+```tsx
+// BAD: inaccessible to screen readers, missing focus ring, arbitrary hex
+<button className="bg-[#5a4fcf] p-[7px] rounded-[5px]" onClick={onClose}>
+  <XIcon />
+</button>
+```
+
+### Best practice: ContextOS Standard (Semantic token scales & ARIA label)
+
+```tsx
+// GOOD: full keyboard accessibility, semantic tokens, focus-visible ring
+<button
+  type="button"
+  aria-label="Close modal dialog"
+  onClick={onClose}
+  className="inline-flex items-center justify-center rounded-lg p-2 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+>
+  <X className="h-4 w-4" aria-hidden="true" />
+</button>
+```
+
+---
+
+## Example 2: Stat Card Hierarchy
+
+### Anti-pattern: Anti-pattern (Flat low-contrast layout with purple-gradient cliche)
+
+```tsx
+// BAD: cliche AI gradient, poor typographic hierarchy
+<div className="bg-gradient-to-r from-purple-500 to-blue-500 p-4 rounded-xl text-white">
+  <div>Total Revenue</div>
+  <div className="text-xl">$45,231.89</div>
+</div>
+```
+
+### Best practice: ContextOS Standard (Refined editorial typography & subtle depth)
+
+```tsx
+// GOOD: high contrast, monospace numerical accent, subtle border
+<div className="rounded-xl border border-border/50 bg-card p-6 shadow-sm transition-all hover:shadow-md">
+  <div className="flex items-center justify-between">
+    <span className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+      Total Revenue
+    </span>
+    <TrendingUp className="h-4 w-4 text-emerald-500" aria-hidden="true" />
+  </div>
+  <div className="mt-3 flex items-baseline gap-2">
+    <span className="font-mono text-3xl font-semibold tracking-tight text-foreground">
+      $45,231.89
+    </span>
+    <span className="font-mono text-xs font-medium text-emerald-600 dark:text-emerald-400">
+      +14.2%
+    </span>
+  </div>
+</div>
+```

package/catalog/skills/ui-ux-pro/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: ui-ux-pro
+description: >
+  Professional UI/UX design skill. Enforces accessibility, semantic color palettes,
+  proper spacing, and bans all common AI design anti-patterns and clichés.
+  Adapted for Tailwind CSS v4, shadcn/ui, and Framer Motion stacks.
+---
+
+# ui-ux-pro
+
+## Overview
+
+Professional UI/UX design standard banning AI clichés (pure black #000000, purple-blue gradients, card-in-card nesting). Enforces Tailwind CSS v4 @theme, semantic HSL palettes, and refined micro-interactions.
+
+## When to Use
+
+Activate during planning and implementation of modern web user interfaces, landing pages, SaaS dashboards, and consumer-facing web apps.
+
+## Rules & Patterns
+
+Inspired by [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill).
+
+## Core Principle
+
+> Great design is invisible. Bad design is obvious. You will never produce obvious AI design.
+
+## Pre-flight Check & Brief Inference
+
+Before starting a design implementation:
+
+1. Infer the unwritten constraints of the domain (e.g., if it's a dev tool, assume dark mode, monospaced numbers, dense layout).
+2. Propose a "Design Brief Inference" summarizing the intended aesthetic.
+
+---
+
+## [FAIL] Absolute Prohibitions (Never Do These)
+
+### Typography Anti-Patterns
+
+- **NEVER** use Arial, Helvetica, or system-ui defaults as primary fonts
+- **NEVER** use Inter as the ONLY font - it is the #1 "AI-generated" visual tell when used alone
+  - [PASS] **CORRECT**: If using Inter for primary UI text, ALWAYS pair it with a strong monospace font like `JetBrains Mono` for numbers, code blocks, and technical accents to create a premium SaaS aesthetic (see Vercel, Linear)
+  - [FAIL] **WRONG**: Inter for headings, body, labels, numbers, captions - everything
+- **NEVER** mix more than 2 font families
+- **ALWAYS** import proper fonts from Google Fonts or similar
+
+### Color Anti-Patterns
+
+- **NEVER** use pure black `#000000` - always tint toward brand hue (e.g. `#0A0A0F`)
+- **NEVER** use pure gray `#808080` - tint it (e.g. `#6B7280` has blue undertones)
+- **NEVER** use purple-to-blue gradients - it is the #1 "AI generated" visual tell
+- **NEVER** use neon colors for primary UI (only accents, sparingly)
+- **ALWAYS** use HSL-based semantic palettes with clear naming
+
+### Layout Anti-Patterns
+
+- **NEVER** nest cards inside cards (card-in-card = instant slop flag)
+- **NEVER** put a rounded-square icon tile above every heading
+- **NEVER** center-align long paragraphs (> 2 lines)
+- **NEVER** use gray text on colored backgrounds (contrast failure)
+
+### Animation Anti-Patterns
+
+- **NEVER** use bounce or elastic easing in raw CSS - it feels dated (circa 2014)
+- **NEVER** add animations just to show they work
+- **ALWAYS** use `ease-out` for enter, `ease-in` for exit, `ease-in-out` for continuous
+
+---
+
+## Component Architecture & Colocation Standards
+
+### Colocated File Structure
+Colocate everything belonging to a component in a dedicated directory:
+```
+src/components/TaskList/
+  TaskList.tsx          # Pure presentation component
+  TaskList.test.tsx     # Unit & interaction tests
+  use-task-list.ts      # Custom hook for state & handlers (if complex)
+  types.ts              # Component-specific interfaces & contracts
+```
+
+### Composition over Configuration
+Avoid large "prop-bag" configurations. Prefer composable slots and child components:
+
+```tsx
+// [PASS] Composable, flexible, predictable:
+<Card>
+  <CardHeader>
+    <CardTitle>Tasks</CardTitle>
+  </CardHeader>
+  <CardBody>
+    <TaskList tasks={tasks} />
+  </CardBody>
+</Card>
+
+// [FAIL] Over-configured prop bag (inflexible, brittle):
+<Card
+  title="Tasks"
+  headerVariant="large"
+  bodyPadding="md"
+  content={<TaskList tasks={tasks} />}
+/>
+```
+
+### Container vs Presentation Separation
+Separate network side effects from UI rendering:
+- **Container**: Handles `useQuery`, loading skeletons, error states, and empty states.
+- **Presentation**: Pure component receiving typed data and callbacks, easy to test and render in Storybook.
+
+---
+
+## [PASS] Required Standards
+
+
+### Accessibility Checklist
+
+Before shipping any UI, verify:
+
+- [ ] Text contrast ratio ≥ 4.5:1 for normal text (WCAG AA)
+- [ ] Text contrast ratio ≥ 3:1 for large text (≥ 18px bold or ≥ 24px)
+- [ ] All interactive elements have `aria-label` or visible text
+- [ ] Touch targets are minimum 44×44px (48×48px recommended)
+- [ ] Focus states are visible and styled (not just browser default)
+- [ ] Images have meaningful `alt` text (or `alt=""` if decorative)
+- [ ] Form fields have associated `<label>` elements
+- [ ] Keyboard navigation works without mouse
+- [ ] No color alone conveys information (use icons + text too)
+
+### Semantic Color Palette - shadcn/ui & Tailwind CSS v4 Format
+
+Generate palettes in the format compatible with shadcn/ui's `globals.css`. Always support both light and dark themes as this is the de-facto standard:
+
+```css
+@layer base {
+  :root {
+    --background: 220 13% 98%;
+    --foreground: 220 13% 9%;
+    --card: 220 13% 100%;
+    --card-foreground: 220 13% 9%;
+    --muted: 220 13% 95%;
+    --muted-foreground: 220 9% 46%;
+    --border: 220 13% 90%;
+    --input: 220 13% 90%;
+    --primary: 258 90% 56%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 13% 94%;
+    --secondary-foreground: 220 13% 9%;
+    --accent: 258 90% 56%;
+    --accent-foreground: 0 0% 100%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --ring: 258 90% 56%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 220 13% 9%;
+    --foreground: 210 40% 98%;
+    --card: 220 11% 13%;
+    --card-foreground: 210 40% 98%;
+    --muted: 220 11% 16%;
+    --muted-foreground: 215 16% 65%;
+    --border: 217 19% 22%;
+    --input: 217 19% 22%;
+    --primary: 258 90% 66%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 11% 18%;
+    --secondary-foreground: 210 40% 98%;
+    --accent: 258 90% 66%;
+    --accent-foreground: 0 0% 100%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --ring: 258 90% 66%;
+  }
+}
+```
+
+> **Rule**: NEVER define colors as raw hex/rgb. ALWAYS use HSL space values so Tailwind opacity modifiers (`text-primary/80`) work correctly.
+
+### Spacing System (Tailwind)
+
+Use Tailwind spacing utilities. **Never use arbitrary values** like `gap-[17px]`:
+
+- `gap-1` / `p-1` - 4px micro gaps
+- `gap-2` / `p-2` - 8px component internal
+- `gap-4` / `p-4` - 16px standard padding
+- `gap-6` / `p-6` - 24px section gaps
+- `gap-8` / `p-8` - 32px block separators
+- `gap-12` / `py-12` - 48px section separators
+- `gap-20` / `py-20` - 80px hero spacing
+
+### Typography Scale
+
+Use a modular type scale (1.25 or 1.333 ratio):
+
+```
+xs:  11px / 0.688rem  (text-xs)
+sm:  13px / 0.813rem  (text-sm)
+base: 16px / 1rem     (text-base)
+lg:  20px / 1.25rem   (text-lg)
+xl:  24px / 1.5rem    (text-xl)
+2xl: 32px / 2rem      (text-2xl)
+3xl: 40px / 2.5rem    (text-3xl)
+4xl: 56px / 3.5rem    (text-4xl)
+```
+
+Typography utilities:
+
+- Long headlines: use `text-balance` (prevents orphan words)
+- Body paragraphs: use `text-pretty` (smart line breaks)
+- Number tables: use `tabular-nums` class (not custom CSS)
+
+---
+
+## Design Parameters (Taste Equalizers)
+
+Always set and document the following three parameters (1-10 scale) before starting any design task, to escape generic AI defaults:
+
+- **DESIGN_VARIANCE (1-10)**: Grid and Layout structures.
+  - 1-3 = Clean, centered layouts, standard grids (Enterprise, Docs).
+  - 4-7 = Asymmetric containers, off-grid elements, sticky sidebars (SaaS, Creative tools).
+  - 8-10 = Broken grids, overlapping items, editorial style (Portfolios, Agencies).
+- **MOTION_INTENSITY (1-10)**: Animation depth.
+  - 1-3 = Basic hover states and micro-interactions only.
+  - 4-7 = Page transitions, enter/exit animations, list staggers.
+  - 8-10 = Magnetic elements, complex scroll-triggered animations (GSAP territory).
+- **VISUAL_DENSITY (1-10)**: Information architecture.
+  - 1-3 = Luxury, airy, massive whitespace (Landing pages).
+  - 4-7 = Standard product density (Consumer apps).
+  - 8-10 = Dense, compact, dashboard-style (Pro tools, IDEs, Trading platforms).
+
+## Adaptive Aesthetics (Project Mapping)
+
+Select the base aesthetic based on the project domain:
+
+- **Fintech / Enterprise**: Swiss Minimalism, Neumorphism (High trust, clean, DESIGN_VARIANCE: 2-4).
+- **AI Tools / DevTools**: Dark OLED Luxury, Glassmorphism (Modern, tech-forward, DESIGN_VARIANCE: 5-7).
+- **Creative / Portfolios**: Brutalism, Maximalist, Aurora (Bold, expressive, DESIGN_VARIANCE: 8-10).
+
+## Design Memory & Consistency
+
+**CRITICAL**: You must preserve design decisions between sessions to avoid stylistic drift.
+Whenever you establish core UI tokens (fonts, color scales, border radii, equalizers), write them to `.interface-design/system.md`. In subsequent sessions, ALWAYS read this file before generating new components.
+
+---
+
+## Design Domains
+
+### Product UI (SaaS / Dashboard / App)
+
+- Functional over decorative
+- Dense information where needed (use compact variants)
+- Table zebra striping: use `5%` opacity, not hard borders
+- Data visualization: prefer Chart.js or Recharts, label all axes
+- Loading states: skeleton screens, never spinners alone
+- **Empty States**: ALWAYS design the empty state for every list/table/feed. Never leave a blank screen. Include:
+  1. An illustration or meaningful icon
+  2. A helpful, context-aware message ("No results yet" not "No data")
+  3. A clear primary action CTA ("Create your first project →")
+
+### Marketing / Landing Pages
+
+- Hero: full viewport height, one clear CTA
+- Social proof above the fold when possible
+- CTA buttons: filled primary + ghost secondary (never two filled)
+- Testimonials: real photos, full name, company
+
+### Forms
+
+- Label above field (not placeholder-as-label)
+- Inline validation (show errors on blur, not on submit)
+- Group related fields visually
+- Progress indicator for multi-step flows
+
+---
+
+## Image-First Pipeline (Design Sprints)
+
+If you have access to image generation tools (e.g., DALL-E, Midjourney integrations) and the task involves creating a net-new UI page or component, follow the **Image-First Pipeline**:
+
+1. **Generate**: Create 1-3 reference images ("mockups", "brand boards") of the desired UI using image generation.
+2. **Analyze**: Review the generated images for layout, spacing, and typography choices.
+3. **Implement**: Write the code to match the aesthetic of the generated reference images.
+
+_Do not skip straight to code for major UI overhauls without a visual reference if generation is available._
+
+---
+
+## UI Style Toolkit
+
+### Glassmorphism (Use Sparingly)
+
+```css
+background: rgba(255, 255, 255, 0.05);
+backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 255, 255, 0.1);
+```
+
+### Subtle Shadows (Dark UI)
+
+```css
+/* Card elevation */
+box-shadow: 0 1px 3px rgba(0,0,0,0.4), 0 1px 2px rgba(0,0,0,0.6);
+/* Floating element */
+box-shadow: 0 10px 40px rgba(0,0,0,0.5), 0 0 0 1px rgba(255,255,255,0.05);
+```
+
+### Micro-animations
+
+**CSS (for simple, lightweight elements):**
+
+```css
+/* Standard transition */
+transition: all 0.15s ease-out;
+/* Hover lift */
+transform: translateY(-2px);
+/* Button press */
+transform: scale(0.97);
+/* Fade in */
+@keyframes fadeIn { from { opacity: 0; transform: translateY(8px); } }
+```
+
+**Framer Motion (for complex layout transitions and orchestration):**
+
+For complex UI like modals, popovers, layout shifts, and multi-element orchestration, prefer Framer Motion over raw CSS keyframes. Keep animations quick and purposeful:
+
+```tsx
+// [GOOD] Modal entrance - use highly damped spring for physical feel (like Vercel/Linear)
+<motion.div
+  initial={{ opacity: 0, scale: 0.96, y: 8 }}
+  animate={{ opacity: 1, scale: 1, y: 0 }}
+  exit={{ opacity: 0, scale: 0.96, y: 8 }}
+  transition={{ type: "spring", stiffness: 400, damping: 30 }}
+/>
+
+// [GOOD] List item stagger
+<motion.li
+  initial={{ opacity: 0, x: -8 }}
+  animate={{ opacity: 1, x: 0 }}
+  transition={{ duration: 0.2, ease: "easeOut" }}
+/>
+
+// [BAD] Never use low damping (bouncy feel)
+transition={{ type: "spring", stiffness: 200, damping: 8 }} // WRONG
+```
+
+**Rule**: `duration` must always be `< 0.3s` for micro-interactions. Respect `prefers-reduced-motion`.
+
+---
+
+## Domain Search Guide
+
+When choosing styles, reference these domains:
+
+- `style` - UI style options (glassmorphism, neobrutalism, minimalism)
+- `typography` - Font pairing recommendations  
+- `color` - Color palettes by product type
+- `ux` - Best practices and anti-patterns
+- `gsap` - Animation patterns by intensity (hover, scroll, transition)
+
+## Role Integration
+
+---
+
+## Tailwind CSS v4 (CSS-First Modern Architecture)
+
+In Tailwind CSS v4, styling configuration is native CSS without `tailwind.config.js`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #3b82f6;
+  --color-primary-foreground: #ffffff;
+  --color-surface: #0f172a;
+  --color-surface-muted: #1e293b;
+  --font-sans: "Inter", -apple-system, sans-serif;
+  --font-mono: "JetBrains Mono", monospace;
+}
+```
+
+- **Zero JavaScript Config**: Define theme variables directly in CSS `@theme`.
+- **Native CSS Variables**: Use `var(--color-...)` for dynamic runtime theming and dark mode.
+- **Dynamic Viewports**: Use `h-dvh` and `min-h-dvh` for full-height layouts that behave properly on mobile browsers.
+
+---
+
+## Core Web Vitals 2026: INP (Interaction to Next Paint)
+
+- **Target**: INP < 200ms (replaces legacy FID).
+- **Rule**: Never block the main thread for > 50ms during click, keypress, or tap event handlers.
+- Wrap heavy UI updates in `startTransition`:
+
+  ```tsx
+  startTransition(() => {
+    setFilter(newFilter);
+  });
+  ```
+
+- Use Web Workers or chunks for heavy client-side filtering and data processing.
+
+---
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.

package/catalog/skills/ui-ux-pro/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# ui-ux-pro Troubleshooting & Common Mistakes
+
+## 1. Obvious AI Design Tells
+
+- **Symptom**: The interface immediately looks like a generic AI prototype.
+- **Root Cause**: Using Inter alone, pure black (#000000), purple-blue gradients, and rounded icon squares above every title.
+- **Fix**: Use tinted backgrounds (#090A0F), pair primary font with JetBrains Mono for code/numbers, use subtle border highlights.
+
+## 2. Contrast Failures in Secondary Elements
+
+- **Symptom**: Captions, timestamps, and borders are invisible or impossible to read.
+- **Root Cause**: Using flat #666 or #444 grays without testing against actual background luminance.
+- **Fix**: Always test contrast ratios (minimum 4.5:1 for body, 3:1 for graphical boundaries) using semantic theme tokens.
+
+## 3. Nesting Cards Inside Cards
+
+- **Symptom**: Visual claustrophobia and slop aesthetic.
+- **Root Cause**: Putting bordered cards inside other bordered cards.
+- **Fix**: Flatten the hierarchy. Use background surface contrast and negative space instead of border-in-border nesting.