lsd-pi 1.2.0 → 1.2.2

package/dist/resources/skills/react-best-practices/rules/server-auth-actions.md

@@ -1,96 +0,0 @@
----
-title: Authenticate Server Actions Like API Routes
-impact: CRITICAL
-impactDescription: prevents unauthorized access to server mutations
-tags: server, server-actions, authentication, security, authorization
----
-
-## Authenticate Server Actions Like API Routes
-
-**Impact: CRITICAL (prevents unauthorized access to server mutations)**
-
-Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
-
-Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
-
-**Incorrect (no authentication check):**
-
-```typescript
-'use server'
-
-export async function deleteUser(userId: string) {
-  // Anyone can call this! No auth check
-  await db.user.delete({ where: { id: userId } })
-  return { success: true }
-}
-```
-
-**Correct (authentication inside the action):**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { unauthorized } from '@/lib/errors'
-
-export async function deleteUser(userId: string) {
-  // Always check auth inside the action
-  const session = await verifySession()
-  
-  if (!session) {
-    throw unauthorized('Must be logged in')
-  }
-  
-  // Check authorization too
-  if (session.user.role !== 'admin' && session.user.id !== userId) {
-    throw unauthorized('Cannot delete other users')
-  }
-  
-  await db.user.delete({ where: { id: userId } })
-  return { success: true }
-}
-```
-
-**With input validation:**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { z } from 'zod'
-
-const updateProfileSchema = z.object({
-  userId: z.string().uuid(),
-  name: z.string().min(1).max(100),
-  email: z.string().email()
-})
-
-export async function updateProfile(data: unknown) {
-  // Validate input first
-  const validated = updateProfileSchema.parse(data)
-  
-  // Then authenticate
-  const session = await verifySession()
-  if (!session) {
-    throw new Error('Unauthorized')
-  }
-  
-  // Then authorize
-  if (session.user.id !== validated.userId) {
-    throw new Error('Can only update own profile')
-  }
-  
-  // Finally perform the mutation
-  await db.user.update({
-    where: { id: validated.userId },
-    data: {
-      name: validated.name,
-      email: validated.email
-    }
-  })
-  
-  return { success: true }
-}
-```
-
-Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)

package/dist/resources/skills/react-best-practices/rules/server-cache-lru.md

@@ -1,41 +0,0 @@
----
-title: Cross-Request LRU Caching
-impact: HIGH
-impactDescription: caches across requests
-tags: server, cache, lru, cross-request
----
-
-## Cross-Request LRU Caching
-
-`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
-
-**Implementation:**
-
-```typescript
-import { LRUCache } from 'lru-cache'
-
-const cache = new LRUCache<string, any>({
-  max: 1000,
-  ttl: 5 * 60 * 1000  // 5 minutes
-})
-
-export async function getUser(id: string) {
-  const cached = cache.get(id)
-  if (cached) return cached
-
-  const user = await db.user.findUnique({ where: { id } })
-  cache.set(id, user)
-  return user
-}
-
-// Request 1: DB query, result cached
-// Request 2: cache hit, no DB query
-```
-
-Use when sequential user actions hit multiple endpoints needing the same data within seconds.
-
-**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
-
-**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
-
-Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/dist/resources/skills/react-best-practices/rules/server-cache-react.md

@@ -1,76 +0,0 @@
----
-title: Per-Request Deduplication with React.cache()
-impact: MEDIUM
-impactDescription: deduplicates within request
-tags: server, cache, react-cache, deduplication
----
-
-## Per-Request Deduplication with React.cache()
-
-Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
-
-**Usage:**
-
-```typescript
-import { cache } from 'react'
-
-export const getCurrentUser = cache(async () => {
-  const session = await auth()
-  if (!session?.user?.id) return null
-  return await db.user.findUnique({
-    where: { id: session.user.id }
-  })
-})
-```
-
-Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
-
-**Avoid inline objects as arguments:**
-
-`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
-
-**Incorrect (always cache miss):**
-
-```typescript
-const getUser = cache(async (params: { uid: number }) => {
-  return await db.user.findUnique({ where: { id: params.uid } })
-})
-
-// Each call creates new object, never hits cache
-getUser({ uid: 1 })
-getUser({ uid: 1 })  // Cache miss, runs query again
-```
-
-**Correct (cache hit):**
-
-```typescript
-const getUser = cache(async (uid: number) => {
-  return await db.user.findUnique({ where: { id: uid } })
-})
-
-// Primitive args use value equality
-getUser(1)
-getUser(1)  // Cache hit, returns cached result
-```
-
-If you must pass objects, pass the same reference:
-
-```typescript
-const params = { uid: 1 }
-getUser(params)  // Query runs
-getUser(params)  // Cache hit (same reference)
-```
-
-**Next.js-Specific Note:**
-
-In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
-
-- Database queries (Prisma, Drizzle, etc.)
-- Heavy computations
-- Authentication checks
-- File system operations
-- Any non-fetch async work
-
-Use `React.cache()` to deduplicate these operations across your component tree.
-
-Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/dist/resources/skills/react-best-practices/rules/server-dedup-props.md

@@ -1,65 +0,0 @@
----
-title: Avoid Duplicate Serialization in RSC Props
-impact: LOW
-impactDescription: reduces network payload by avoiding duplicate serialization
-tags: server, rsc, serialization, props, client-components
----
-
-## Avoid Duplicate Serialization in RSC Props
-
-**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
-
-RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
-
-**Incorrect (duplicates array):**
-
-```tsx
-// RSC: sends 6 strings (2 arrays × 3 items)
-<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
-```
-
-**Correct (sends 3 strings):**
-
-```tsx
-// RSC: send once
-<ClientList usernames={usernames} />
-
-// Client: transform there
-'use client'
-const sorted = useMemo(() => [...usernames].sort(), [usernames])
-```
-
-**Nested deduplication behavior:**
-
-Deduplication works recursively. Impact varies by data type:
-
-- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
-- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
-
-```tsx
-// string[] - duplicates everything
-usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
-
-// object[] - duplicates array structure only
-users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
-```
-
-**Operations breaking deduplication (create new references):**
-
-- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
-- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
-
-**More examples:**
-
-```tsx
-// ❌ Bad
-<C users={users} active={users.filter(u => u.active)} />
-<C product={product} productName={product.name} />
-
-// ✅ Good
-<C users={users} />
-<C product={product} />
-// Do filtering/destructuring in client
-```
-
-**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/dist/resources/skills/react-best-practices/rules/server-parallel-fetching.md

@@ -1,83 +0,0 @@
----
-title: Parallel Data Fetching with Component Composition
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, composition
----
-
-## Parallel Data Fetching with Component Composition
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect (Sidebar waits for Page's fetch to complete):**
-
-```tsx
-export default async function Page() {
-  const header = await fetchHeader()
-  return (
-    <div>
-      <div>{header}</div>
-      <Sidebar />
-    </div>
-  )
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-```
-
-**Correct (both fetch simultaneously):**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-export default function Page() {
-  return (
-    <div>
-      <Header />
-      <Sidebar />
-    </div>
-  )
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-function Layout({ children }: { children: ReactNode }) {
-  return (
-    <div>
-      <Header />
-      {children}
-    </div>
-  )
-}
-
-export default function Page() {
-  return (
-    <Layout>
-      <Sidebar />
-    </Layout>
-  )
-}
-```

package/dist/resources/skills/react-best-practices/rules/server-serialization.md

@@ -1,38 +0,0 @@
----
-title: Minimize Serialization at RSC Boundaries
-impact: HIGH
-impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
----
-
-## Minimize Serialization at RSC Boundaries
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect (serializes all 50 fields):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()  // 50 fields
-  return <Profile user={user} />
-}
-
-'use client'
-function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>  // uses 1 field
-}
-```
-
-**Correct (serializes only 1 field):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()
-  return <Profile name={user.name} />
-}
-
-'use client'
-function Profile({ name }: { name: string }) {
-  return <div>{name}</div>
-}
-```

package/dist/resources/skills/userinterface-wiki/SKILL.md

@@ -1,253 +0,0 @@
----
-name: userinterface-wiki
-description: UI/UX best practices for interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.
-license: MIT
-metadata:
-  author: raphael-salaja
-  version: "3.0.0"
----
-
-# User Interface Wiki
-
-Comprehensive UI/UX best practices guide for interfaces. Contains 152 rules across 12 categories, prioritized by impact to guide automated code review and generation.
-
-## When to Apply
-
-Reference these guidelines when:
-- Implementing or reviewing animations (CSS transitions, Motion/Framer Motion)
-- Choosing between springs, easing curves, or no animation
-- Working with AnimatePresence and exit animations
-- Writing CSS with pseudo-elements or View Transitions API
-- Adding audio feedback or procedural sound to UI
-- Building morphing icon components
-- Animating container width/height with dynamic content
-- Designing UI that respects cognitive psychology (Fitts's, Hick's, Miller's laws)
-- Implementing predictive prefetching for perceived performance
-- Setting up typography, OpenType features, or numeric formatting
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefixes |
-|----------|----------|--------|----------|
-| 1 | Animation Principles | CRITICAL | `timing-`, `physics-`, `staging-` |
-| 2 | Timing Functions | HIGH | `spring-`, `easing-`, `duration-`, `none-` |
-| 3 | Exit Animations | HIGH | `exit-`, `presence-`, `mode-`, `nested-` |
-| 4 | CSS Pseudo Elements | MEDIUM | `pseudo-`, `transition-`, `native-` |
-| 5 | Audio Feedback | MEDIUM | `a11y-`, `appropriate-`, `impl-`, `weight-` |
-| 6 | Sound Synthesis | MEDIUM | `context-`, `envelope-`, `design-`, `param-` |
-| 7 | Morphing Icons | LOW | `morphing-` |
-| 8 | Container Animation | MEDIUM | `container-` |
-| 9 | Laws of UX | HIGH | `ux-` |
-| 10 | Predictive Prefetching | MEDIUM | `prefetch-` |
-| 11 | Typography | MEDIUM | `type-` |
-| 12 | Visual Design | HIGH | `visual-` |
-
-## Quick Reference
-
-### 1. Animation Principles (CRITICAL)
-
-- `timing-under-300ms` - User animations must complete within 300ms
-- `timing-consistent` - Similar elements use identical timing values
-- `timing-no-entrance-context-menu` - Context menus: no entrance animation, exit only
-- `easing-natural-decay` - Use exponential ramps for natural decay, not linear
-- `easing-no-linear-motion` - Linear easing only for progress indicators
-- `physics-active-state` - Interactive elements need :active scale transform
-- `physics-subtle-deformation` - Squash/stretch in 0.95-1.05 range
-- `physics-spring-for-overshoot` - Springs for overshoot-and-settle, not easing
-- `physics-no-excessive-stagger` - Stagger delays under 50ms per item
-- `staging-one-focal-point` - One prominent animation at a time
-- `staging-dim-background` - Dim modal/dialog backgrounds
-- `staging-z-index-hierarchy` - Animated elements respect z-index layers
-
-### 2. Timing Functions (HIGH)
-
-- `spring-for-gestures` - Gesture-driven motion (drag, flick) must use springs
-- `spring-for-interruptible` - Interruptible motion must use springs
-- `spring-preserves-velocity` - Springs preserve input energy on release
-- `spring-params-balanced` - Avoid excessive oscillation in spring params
-- `easing-for-state-change` - System state changes use easing curves
-- `easing-entrance-ease-out` - Entrances use ease-out
-- `easing-exit-ease-in` - Exits use ease-in
-- `easing-transition-ease-in-out` - View transitions use ease-in-out
-- `easing-linear-only-progress` - Linear only for progress/time representation
-- `duration-press-hover` - Press/hover: 120-180ms
-- `duration-small-state` - Small state changes: 180-260ms
-- `duration-max-300ms` - User-initiated max 300ms
-- `duration-shorten-before-curve` - Fix slow feel with shorter duration, not curve
-- `none-high-frequency` - No animation for high-frequency interactions
-- `none-keyboard-navigation` - Keyboard navigation instant, no animation
-- `none-context-menu-entrance` - Context menus: no entrance, exit only
-
-### 3. Exit Animations (HIGH)
-
-- `exit-requires-wrapper` - Conditional motion elements need AnimatePresence wrapper
-- `exit-prop-required` - Elements in AnimatePresence need exit prop
-- `exit-key-required` - Dynamic lists need unique keys, not index
-- `exit-matches-initial` - Exit mirrors initial for symmetry
-- `presence-hook-in-child` - useIsPresent in child, not parent
-- `presence-safe-to-remove` - Call safeToRemove after async cleanup
-- `presence-disable-interactions` - Disable interactions on exiting elements
-- `mode-wait-doubles-duration` - Mode "wait" doubles duration; halve timing
-- `mode-sync-layout-conflict` - Mode "sync" causes layout conflicts
-- `mode-pop-layout-for-lists` - Use popLayout for list reordering
-- `nested-propagate-required` - Nested AnimatePresence needs propagate prop
-- `nested-consistent-timing` - Coordinate parent-child exit durations
-
-### 4. CSS Pseudo Elements (MEDIUM)
-
-- `pseudo-content-required` - ::before/::after need content property
-- `pseudo-over-dom-node` - Pseudo-elements over extra DOM nodes for decoration
-- `pseudo-position-relative-parent` - Parent needs position: relative
-- `pseudo-z-index-layering` - Z-index for correct pseudo-element layering
-- `pseudo-hit-target-expansion` - Negative inset for larger hit targets
-- `pseudo-marker-styling` - Use ::marker for custom list bullet styles
-- `pseudo-first-line-styling` - Use ::first-line for typographic treatments
-- `transition-name-required` - View transitions need view-transition-name
-- `transition-name-unique` - Each transition name unique during transition
-- `transition-name-cleanup` - Remove transition name after completion
-- `transition-over-js-library` - Prefer View Transitions API over JS libraries
-- `transition-style-pseudo-elements` - Style ::view-transition-group for custom animations
-- `native-backdrop-styling` - Use ::backdrop for dialog backgrounds
-- `native-placeholder-styling` - Use ::placeholder for input styling
-- `native-selection-styling` - Use ::selection for text selection styling
-
-### 5. Audio Feedback (MEDIUM)
-
-- `a11y-visual-equivalent` - Every sound must have a visual equivalent
-- `a11y-toggle-setting` - Provide toggle to disable sounds
-- `a11y-reduced-motion-check` - Respect prefers-reduced-motion for sound
-- `a11y-volume-control` - Allow independent volume adjustment
-- `appropriate-no-high-frequency` - No sound on typing or keyboard nav
-- `appropriate-confirmations-only` - Sound for payments, uploads, submissions
-- `appropriate-errors-warnings` - Sound for errors that can't be overlooked
-- `appropriate-no-decorative` - No sound on hover or decorative moments
-- `appropriate-no-punishing` - Inform, don't punish with harsh sounds
-- `impl-preload-audio` - Preload audio files to avoid delay
-- `impl-default-subtle` - Default volume subtle (0.3), not loud
-- `impl-reset-current-time` - Reset currentTime before replay
-- `weight-match-action` - Sound weight matches action importance
-- `weight-duration-matches-action` - Sound duration matches action duration
-
-### 6. Sound Synthesis (MEDIUM)
-
-- `context-reuse-single` - Reuse single AudioContext, don't create per sound
-- `context-resume-suspended` - Resume suspended AudioContext before playing
-- `context-cleanup-nodes` - Disconnect audio nodes after playback
-- `envelope-exponential-decay` - Exponential ramps for natural decay
-- `envelope-no-zero-target` - Exponential ramps target 0.001, not 0
-- `envelope-set-initial-value` - Set initial value before ramping
-- `design-noise-for-percussion` - Filtered noise for clicks/taps
-- `design-oscillator-for-tonal` - Oscillators with pitch sweep for tonal sounds
-- `design-filter-for-character` - Bandpass filter to shape percussive sounds
-- `param-click-duration` - Click sounds: 5-15ms duration
-- `param-filter-frequency-range` - Click filter: 3000-6000Hz
-- `param-reasonable-gain` - Gain under 1.0 to prevent clipping
-- `param-q-value-range` - Filter Q: 2-5 for focused but natural
-
-### 7. Morphing Icons (LOW)
-
-- `morphing-three-lines` - Every icon uses exactly 3 SVG lines
-- `morphing-use-collapsed` - Unused lines use collapsed constant
-- `morphing-consistent-viewbox` - All icons share same viewBox (14x14)
-- `morphing-group-variants` - Rotational variants share group and base lines
-- `morphing-spring-rotation` - Spring physics for grouped icon rotation
-- `morphing-reduced-motion` - Respect prefers-reduced-motion
-- `morphing-jump-non-grouped` - Instant rotation jump between non-grouped icons
-- `morphing-strokelinecap-round` - Round stroke line caps
-- `morphing-aria-hidden` - Icon SVGs are aria-hidden
-
-### 8. Container Animation (MEDIUM)
-
-- `container-two-div-pattern` - Outer animated div, inner measured div; never same element
-- `container-guard-initial-zero` - Guard bounds === 0 on initial render, fall back to "auto"
-- `container-use-resize-observer` - Use ResizeObserver for measurement, not getBoundingClientRect
-- `container-overflow-hidden` - Set overflow: hidden on animated container during transitions
-- `container-no-excessive-use` - Use sparingly: buttons, accordions, interactive elements
-- `container-callback-ref` - Use callback ref (not useRef) for measurement hooks
-- `container-transition-delay` - Add small delay for natural catching-up feel
-
-### 9. Laws of UX (HIGH)
-
-- `ux-fitts-target-size` - Size interactive targets for easy clicking (min 32px)
-- `ux-fitts-hit-area` - Expand hit areas with invisible padding or pseudo-elements
-- `ux-hicks-minimize-choices` - Minimize choices to reduce decision time
-- `ux-millers-chunking` - Chunk data into groups of 5-9 for scannability
-- `ux-doherty-under-400ms` - Respond within 400ms to feel instant
-- `ux-doherty-perceived-speed` - Fake speed with skeletons, optimistic UI, progress indicators
-- `ux-postels-accept-messy-input` - Accept messy input, output clean data
-- `ux-progressive-disclosure` - Show what matters now, reveal complexity later
-- `ux-jakobs-familiar-patterns` - Use familiar UI patterns users know from other sites
-- `ux-aesthetic-usability` - Visual polish increases perceived usability
-- `ux-proximity-grouping` - Group related elements spatially with tighter spacing
-- `ux-similarity-consistency` - Similar elements should look alike
-- `ux-common-region-boundaries` - Use boundaries to group related content
-- `ux-von-restorff-emphasis` - Make important elements visually distinct
-- `ux-serial-position` - Place key items first or last in sequences
-- `ux-peak-end-finish-strong` - End experiences with clear success states
-- `ux-teslers-complexity` - Move complexity to the system, not the user
-- `ux-goal-gradient-progress` - Show progress toward completion
-- `ux-zeigarnik-show-incomplete` - Show incomplete state to drive completion
-- `ux-pragnanz-simplify` - Simplify complex visuals into clear forms
-- `ux-pareto-prioritize-features` - Prioritize the critical 20% of features
-- `ux-cognitive-load-reduce` - Minimize extraneous cognitive load
-- `ux-uniform-connectedness` - Visually connect related elements with lines or frames
-
-### 10. Predictive Prefetching (MEDIUM)
-
-- `prefetch-trajectory-over-hover` - Trajectory prediction over hover; reclaims 100-200ms
-- `prefetch-not-everything` - Prefetch by intent, not viewport; avoid wasted bandwidth
-- `prefetch-hit-slop` - Use hitSlop to trigger predictions earlier
-- `prefetch-touch-fallback` - Fall back gracefully on touch devices (no cursor)
-- `prefetch-keyboard-tab` - Prefetch on keyboard navigation when focus approaches
-- `prefetch-use-selectively` - Use predictive prefetching where latency is noticeable
-
-### 11. Typography (MEDIUM)
-
-- `type-tabular-nums-for-data` - Tabular numbers for columns, dashboards, pricing
-- `type-oldstyle-nums-for-prose` - Oldstyle numbers blend into body text
-- `type-slashed-zero` - Slashed zero in code-adjacent UIs
-- `type-opentype-contextual-alternates` - Keep calt enabled for contextual glyph adjustment
-- `type-disambiguation-stylistic-set` - Enable ss02 to distinguish I/l/1 and 0/O
-- `type-optical-sizing-auto` - Leave font-optical-sizing auto for size-adaptive glyphs
-- `type-antialiased-on-retina` - Antialiased font smoothing on retina displays
-- `type-text-wrap-balance-headings` - text-wrap: balance on headings for even lines
-- `type-underline-offset` - Offset underlines below descenders
-- `type-no-font-synthesis` - Disable font-synthesis to prevent faux bold/italic
-- `type-font-display-swap` - Use font-display: swap to avoid invisible text during load
-- `type-variable-weight-continuous` - Use continuous weight values (100-900) with variable fonts
-- `type-text-wrap-pretty` - text-wrap: pretty for body text to reduce orphans
-- `type-justify-with-hyphens` - Pair text-align: justify with hyphens: auto
-- `type-letter-spacing-uppercase` - Add letter-spacing to uppercase and small-caps text
-- `type-proper-fractions` - Use diagonal-fractions for proper typographic fractions
-
-### 12. Visual Design (HIGH)
-
-- `visual-concentric-radius` - Inner radius = outer radius minus padding for nested elements
-- `visual-layered-shadows` - Layer multiple shadows for realistic depth
-- `visual-shadow-direction` - All shadows share same offset direction (single light source)
-- `visual-no-pure-black-shadow` - Use neutral colors, not pure black, for shadows
-- `visual-shadow-matches-elevation` - Shadow size indicates elevation in consistent scale
-- `visual-animate-shadow-pseudo` - Animate shadow via pseudo-element opacity for performance
-- `visual-consistent-spacing-scale` - Use a consistent spacing scale, not arbitrary values
-- `visual-border-alpha-colors` - Semi-transparent borders adapt to any background
-- `visual-button-shadow-anatomy` - Six-layer shadow anatomy for polished buttons
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/timing-under-300ms.md
-rules/spring-for-gestures.md
-rules/ux-doherty-under-400ms.md
-rules/type-tabular-nums-for-data.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`