specforge-mcp 0.1.0

package/src/config/supply-chain-tools.json

@@ -0,0 +1,107 @@
+{
+  "_description": "Supply chain security tool catalog for SPEC-046. Used by supply-chain-catalog.ts",
+  "cisaMinimumElements": ["supplier", "author", "timestamp", "name", "version", "serialNumber", "dependencies"],
+  "sbomTools": {
+    "nodejs": {
+      "name": "@cyclonedx/cyclonedx-npm",
+      "alternative": "syft",
+      "command": "npx @cyclonedx/cyclonedx-npm --output-format JSON --output-file sbom.json",
+      "docsUrl": "https://github.com/CycloneDX/cyclonedx-node-npm"
+    },
+    "python": {
+      "name": "cyclonedx-bom",
+      "alternative": "syft",
+      "command": "cyclonedx-py environment --of JSON -o sbom.json",
+      "docsUrl": "https://github.com/CycloneDX/cyclonedx-python"
+    },
+    "go": {
+      "name": "syft",
+      "alternative": "cyclonedx-gomod",
+      "command": "syft . -o cyclonedx-json=sbom.json",
+      "docsUrl": "https://github.com/CycloneDX/cyclonedx-gomod"
+    },
+    "java": {
+      "name": "cyclonedx-maven-plugin",
+      "alternative": "syft",
+      "command": "mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom",
+      "docsUrl": "https://github.com/CycloneDX/cyclonedx-maven-plugin"
+    },
+    "rust": {
+      "name": "cargo-sbom",
+      "alternative": "syft",
+      "command": "cargo sbom --output-format cyclone_dx_json_1_4 > sbom.json",
+      "docsUrl": "https://github.com/psastras/sbom-rs"
+    },
+    "dotnet": {
+      "name": "CycloneDX.BOM",
+      "alternative": "syft",
+      "command": "dotnet CycloneDX <project> -o . -j",
+      "docsUrl": "https://github.com/CycloneDX/cyclonedx-dotnet"
+    },
+    "generic": {
+      "name": "syft",
+      "alternative": null,
+      "command": "syft . -o cyclonedx-json=sbom.json",
+      "docsUrl": "https://github.com/anchore/syft"
+    }
+  },
+  "slsaTools": {
+    "githubActions": {
+      "name": "actions/attest-build-provenance",
+      "level": "L2",
+      "docsUrl": "https://github.com/actions/attest-build-provenance"
+    },
+    "slsaGenerator": {
+      "name": "slsa-framework/slsa-github-generator",
+      "level": "L3",
+      "docsUrl": "https://github.com/slsa-framework/slsa-github-generator"
+    },
+    "cosign": {
+      "name": "sigstore/cosign-installer",
+      "level": "L2",
+      "docsUrl": "https://github.com/sigstore/cosign"
+    }
+  },
+  "monitoringTools": {
+    "dependencyTrack": {
+      "name": "OWASP Dependency-Track",
+      "description": "Self-hosted, CycloneDX native, continuous SBOM monitoring",
+      "docsUrl": "https://dependencytrack.org/"
+    },
+    "socketDev": {
+      "name": "Socket.dev",
+      "description": "npm/PyPI/Go — detects behavior anomalies in dependencies",
+      "docsUrl": "https://socket.dev/"
+    },
+    "dependabot": {
+      "name": "Dependabot",
+      "description": "Automated dependency update PRs via GitHub",
+      "docsUrl": "https://docs.github.com/en/code-security/dependabot"
+    },
+    "renovate": {
+      "name": "Renovate",
+      "description": "Automated dependency updates — more configurable than Dependabot",
+      "docsUrl": "https://docs.renovatebot.com/"
+    }
+  },
+  "reproducibleBuildTools": {
+    "nix": {
+      "name": "Nix/NixOS",
+      "level": "advanced",
+      "description": "Hermetic, reproducible builds for any language",
+      "docsUrl": "https://nixos.org/"
+    },
+    "bazel": {
+      "name": "Bazel",
+      "level": "advanced",
+      "description": "Hermetic build system by Google — bit-for-bit reproducible",
+      "docsUrl": "https://bazel.build/"
+    },
+    "dockerBuildkit": {
+      "name": "Docker BuildKit",
+      "level": "standard",
+      "description": "Use `--reproducible` flag and SOURCE_DATE_EPOCH for deterministic timestamps",
+      "docsUrl": "https://docs.docker.com/build/buildkit/"
+    }
+  }
+}

package/src/config/ui-frameworks.json

@@ -0,0 +1,335 @@
+{
+  "_description": "CSS/UI framework catalog for SPEC-017a — Styling Contract generation",
+  "tailwind": {
+    "name": "Tailwind CSS",
+    "packageNames": ["tailwindcss"],
+    "configFiles": ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.cjs"],
+    "importSignals": ["@tailwind base", "@tailwind components", "@tailwind utilities"],
+    "breakpoints": {
+      "sm": "640px",
+      "md": "768px",
+      "lg": "1024px",
+      "xl": "1280px",
+      "2xl": "1536px"
+    },
+    "darkMode": "dark: class prefix (e.g. dark:bg-gray-900)",
+    "responsive": "Mobile-first: prefix breakpoint before utility (md:flex, lg:grid)",
+    "conventions": [
+      "Use utility classes directly in JSX/HTML — no custom class names needed",
+      "Responsive: prefix with breakpoint (sm:, md:, lg:, xl:)",
+      "Dark mode: prefix with dark: (dark:bg-gray-900)",
+      "Group hover: group/group-hover: for parent-triggered states",
+      "Custom tokens: defined in tailwind.config.ts under theme.extend"
+    ],
+    "components": [
+      "No built-in components — compose from utility classes",
+      "Use shadcn/ui or Headless UI for prebuilt accessible components"
+    ],
+    "plugins": ["@tailwindcss/forms", "@tailwindcss/typography", "@tailwindcss/aspect-ratio"]
+  },
+  "bootstrap": {
+    "name": "Bootstrap",
+    "packageNames": ["bootstrap"],
+    "configFiles": [],
+    "importSignals": ["bootstrap/dist/css", "bootstrap.min.css", "from 'bootstrap'"],
+    "breakpoints": {
+      "sm": "576px",
+      "md": "768px",
+      "lg": "992px",
+      "xl": "1200px",
+      "xxl": "1400px"
+    },
+    "darkMode": "data-bs-theme=\"dark\" attribute on root element",
+    "responsive": "Grid: col-{breakpoint}-{size} (e.g. col-md-6 col-lg-4)",
+    "conventions": [
+      "Use Bootstrap component classes (btn, card, modal, table, navbar)",
+      "Grid: container > row > col-* for layout",
+      "Spacing utilities: m-{size}, p-{size}, mx-auto, py-4",
+      "Color variants: btn-primary, btn-danger, alert-success",
+      "Utility classes: d-flex, align-items-center, justify-content-between"
+    ],
+    "components": [
+      "Card: .card > .card-header + .card-body + .card-footer",
+      "Modal: .modal > .modal-dialog > .modal-content > .modal-header + .modal-body + .modal-footer",
+      "Table: .table .table-striped .table-hover .table-responsive",
+      "Navbar: .navbar .navbar-expand-lg .navbar-brand .nav-link",
+      "Form: .form-control .form-label .form-check .form-select"
+    ],
+    "plugins": []
+  },
+  "css-modules": {
+    "name": "CSS Modules",
+    "packageNames": [],
+    "configFiles": [],
+    "importSignals": ["*.module.css", "*.module.scss", "styles from '"],
+    "breakpoints": {
+      "mobile": "480px",
+      "tablet": "768px",
+      "desktop": "1024px",
+      "wide": "1280px"
+    },
+    "darkMode": "CSS custom properties with [data-theme='dark'] selector",
+    "responsive": "Media queries within module file: @media (min-width: 768px)",
+    "conventions": [
+      "Naming: camelCase class names (styles.primaryButton, styles.cardContainer)",
+      "Composing: composes: from './shared.module.css'",
+      "Scoping: classes are locally scoped by default — no collision risk",
+      "Global override: :global(.third-party-class) for external styles",
+      "CSS custom properties: --color-primary, --spacing-unit for theming"
+    ],
+    "components": [
+      "No predefined components — define component-specific module files",
+      "Convention: one .module.css per component file"
+    ],
+    "plugins": []
+  },
+  "styled-components": {
+    "name": "Styled Components",
+    "packageNames": ["styled-components"],
+    "configFiles": [".babelrc", "babel.config.js"],
+    "importSignals": ["styled-components", "from 'styled-components'", "styled.div`"],
+    "breakpoints": {},
+    "darkMode": "ThemeProvider with dark/light theme object",
+    "responsive": "Template literals with media query helpers: ${media.md`flex-direction: column`}",
+    "conventions": [
+      "Define styled components outside render functions to avoid re-creation",
+      "Use ThemeProvider for consistent design tokens across the app",
+      "Use attrs() for static HTML attributes",
+      "Use .withConfig({ displayName }) for better DevTools debugging",
+      "Extend styles: styled(BaseComponent)`additional styles`"
+    ],
+    "components": [
+      "No built-in components — wrap any HTML element or React component",
+      "Pattern: const Button = styled.button`...` — export as normal component"
+    ],
+    "plugins": []
+  },
+  "sass": {
+    "name": "Sass/SCSS",
+    "packageNames": ["sass", "node-sass"],
+    "configFiles": [".sassrc", ".sassrc.js"],
+    "importSignals": ["*.scss", "*.sass", "@import", "@use"],
+    "breakpoints": {
+      "mobile": "480px",
+      "tablet": "768px",
+      "desktop": "1024px"
+    },
+    "darkMode": "@media (prefers-color-scheme: dark) or [data-theme='dark']",
+    "responsive": "Mixins: @mixin respond-to($breakpoint) { @content }",
+    "conventions": [
+      "Use BEM naming: .block__element--modifier",
+      "SMACSS layers: base, layout, modules, state, theme",
+      "Variables: $color-primary, $spacing-unit",
+      "Nesting: limit to 3 levels to avoid specificity issues",
+      "Use @use instead of deprecated @import"
+    ],
+    "components": [
+      "Partial files: _button.scss, _card.scss — imported via @use",
+      "Mixins for reusable patterns: @mixin flex-center, @mixin card-shadow"
+    ],
+    "plugins": []
+  },
+  "material-ui": {
+    "name": "Material UI (MUI)",
+    "packageNames": ["@mui/material", "@emotion/react", "@emotion/styled"],
+    "configFiles": [],
+    "importSignals": ["@mui/material", "from '@mui/material'", "@mui/icons-material"],
+    "breakpoints": {
+      "xs": "0px",
+      "sm": "600px",
+      "md": "900px",
+      "lg": "1200px",
+      "xl": "1536px"
+    },
+    "darkMode": "createTheme({ palette: { mode: 'dark' } }) via ThemeProvider",
+    "responsive": "sx prop: { display: { xs: 'none', md: 'flex' } } or useMediaQuery",
+    "conventions": [
+      "Use sx prop for one-off styles: <Box sx={{ p: 2, bgcolor: 'primary.main' }}>",
+      "Theme overrides: createTheme({ components: { MuiButton: { styleOverrides } } })",
+      "Styled API: styled(Button)({ color: 'red' }) — extends MUI components",
+      "Use theme.spacing(n) for consistent 8px-based spacing",
+      "Import individual components to enable tree-shaking"
+    ],
+    "components": [
+      "Layout: Box, Container, Grid, Stack, Paper",
+      "Navigation: AppBar, Drawer, Tabs, Breadcrumbs, Menu",
+      "Input: TextField, Select, Checkbox, Radio, Switch, Autocomplete",
+      "Display: Typography, Avatar, Chip, Badge, Tooltip, Divider",
+      "Feedback: Alert, Snackbar, Dialog, CircularProgress, Skeleton",
+      "Data: DataGrid (separate @mui/x-data-grid package), Table"
+    ],
+    "plugins": []
+  },
+  "chakra-ui": {
+    "name": "Chakra UI",
+    "packageNames": ["@chakra-ui/react"],
+    "configFiles": [],
+    "importSignals": ["@chakra-ui/react", "from '@chakra-ui/react'", "ChakraProvider"],
+    "breakpoints": {
+      "base": "0px",
+      "sm": "480px",
+      "md": "768px",
+      "lg": "992px",
+      "xl": "1280px",
+      "2xl": "1536px"
+    },
+    "darkMode": "useColorMode() + ColorModeProvider — automatic dark/light toggle",
+    "responsive": "Responsive array syntax: <Box fontSize={['sm', 'md', 'lg']} />",
+    "conventions": [
+      "Responsive array syntax: [mobile, tablet, desktop] values per prop",
+      "Extend theme: extendTheme({ colors: { brand: { 500: '#...' } } })",
+      "useColorModeValue for light/dark specific values",
+      "StyleProps: m, p, bg, color, fontWeight directly on components",
+      "forwardRef pattern for custom components to support Chakra props"
+    ],
+    "components": [
+      "Layout: Box, Flex, Grid, Stack, HStack, VStack, Center, Container",
+      "Navigation: Breadcrumb, Tabs, Menu, Drawer, Accordion",
+      "Form: Input, Select, Checkbox, Radio, Switch, FormControl, FormLabel",
+      "Overlay: Modal, AlertDialog, Popover, Tooltip, Drawer",
+      "Feedback: Alert, Toast (useToast), Progress, Spinner, Skeleton",
+      "Typography: Heading, Text, Code, Kbd"
+    ],
+    "plugins": []
+  },
+  "shadcn-ui": {
+    "name": "shadcn/ui",
+    "packageNames": ["shadcn"],
+    "configFiles": ["components.json"],
+    "importSignals": ["@/components/ui", "from '@/components/ui'", "cn("],
+    "breakpoints": {
+      "sm": "640px",
+      "md": "768px",
+      "lg": "1024px",
+      "xl": "1280px",
+      "2xl": "1536px"
+    },
+    "darkMode": "dark class on <html> element — CSS custom properties approach",
+    "responsive": "Tailwind responsive prefixes (same as Tailwind — built on top of it)",
+    "conventions": [
+      "Copy components into your repo with `npx shadcn@latest add <component>`",
+      "Use cn() utility from lib/utils for conditional class merging",
+      "Variants defined via class-variance-authority (CVA): buttonVariants({ variant: 'destructive' })",
+      "Customize via CSS variables in globals.css — override --primary, --secondary",
+      "Components live in src/components/ui/ — modify directly as needed"
+    ],
+    "components": [
+      "Core: Button (variant: default/destructive/outline/secondary/ghost/link)",
+      "Form: Input, Textarea, Select, Checkbox, RadioGroup, Switch, Slider",
+      "Layout: Card, Separator, ScrollArea, AspectRatio, Resizable",
+      "Navigation: NavigationMenu, Tabs, Breadcrumb, Pagination",
+      "Overlay: Dialog, AlertDialog, Sheet, Popover, Tooltip, ContextMenu",
+      "Data: Table, DataTable (with TanStack Table), Badge, Avatar"
+    ],
+    "plugins": ["class-variance-authority", "tailwind-merge", "clsx"]
+  },
+  "ant-design": {
+    "name": "Ant Design",
+    "packageNames": ["antd", "@ant-design/icons"],
+    "configFiles": [],
+    "importSignals": ["antd", "from 'antd'", "@ant-design/icons"],
+    "breakpoints": {
+      "xs": "480px",
+      "sm": "576px",
+      "md": "768px",
+      "lg": "992px",
+      "xl": "1200px",
+      "xxl": "1600px"
+    },
+    "darkMode": "ConfigProvider theme={{ algorithm: theme.darkAlgorithm }}",
+    "responsive": "Grid system: <Col xs={24} md={12} lg={8}> within <Row gutter={[16,16]}>",
+    "conventions": [
+      "Wrap app in <ConfigProvider theme={...}> for global theme customization",
+      "Use theme tokens: token.colorPrimary, token.borderRadius",
+      "Form validation: Form.useForm() + Form.Item rules prop",
+      "Use antd Table with columns definition (not native table)",
+      "Icon import: import { SearchOutlined } from '@ant-design/icons'"
+    ],
+    "components": [
+      "Navigation: Menu, Breadcrumb, Tabs, Pagination, Steps",
+      "Data Entry: Form, Input, Select, DatePicker, Checkbox, Radio, Upload, Transfer",
+      "Data Display: Table, List, Card, Collapse, Tree, Timeline, Badge, Avatar",
+      "Feedback: Alert, Message, Notification, Modal, Drawer, Spin, Progress",
+      "Layout: Layout (Header/Sider/Content/Footer), Grid (Row/Col), Space, Divider"
+    ],
+    "plugins": []
+  },
+  "flutter-styles": {
+    "name": "Flutter (Dart)",
+    "packageNames": [],
+    "configFiles": ["pubspec.yaml"],
+    "importSignals": ["package:flutter/material.dart", "ThemeData", "ColorScheme"],
+    "breakpoints": {
+      "mobile": "600px",
+      "tablet": "900px",
+      "desktop": "1200px"
+    },
+    "darkMode": "MaterialApp(themeMode: ThemeMode.dark, darkTheme: ThemeData.dark())",
+    "responsive": "MediaQuery.of(context).size.width — LayoutBuilder for adaptive UI",
+    "conventions": [
+      "ThemeData: define colorScheme, textTheme, buttonTheme centrally",
+      "ColorScheme.fromSeed(seedColor: Colors.blue) for Material 3",
+      "TextTheme: titleLarge, bodyMedium, labelSmall for typography hierarchy",
+      "Use Theme.of(context).colorScheme.primary — never hardcode colors",
+      "Responsive: LayoutBuilder + ConstrainedBox or AdaptiveScaffold"
+    ],
+    "components": [
+      "Layout: Container, Column, Row, Stack, Expanded, Flexible, SizedBox",
+      "Navigation: Scaffold, AppBar, BottomNavigationBar, NavigationRail, Drawer",
+      "Input: TextField, DropdownButton, Checkbox, Radio, Switch, Slider",
+      "Display: Text, Icon, Image, Card, ListTile, Chip, Avatar",
+      "Feedback: SnackBar, AlertDialog, CircularProgressIndicator, LinearProgressIndicator"
+    ],
+    "plugins": []
+  },
+  "react-native-styles": {
+    "name": "React Native",
+    "packageNames": ["react-native", "expo"],
+    "configFiles": [],
+    "importSignals": ["react-native", "StyleSheet", "from 'react-native'"],
+    "breakpoints": {},
+    "darkMode": "useColorScheme() hook — Appearance.getColorScheme()",
+    "responsive": "Dimensions.get('window').width — useWindowDimensions() hook",
+    "conventions": [
+      "StyleSheet.create({ container: { flex: 1, padding: 16 } }) for all styles",
+      "No CSS classes — use JavaScript objects with React Native style properties",
+      "Platform.OS === 'ios' / 'android' for platform-specific adjustments",
+      "Flexbox is default layout model (flex: 1, flexDirection: 'column')",
+      "useWindowDimensions() for responsive sizing instead of hardcoded values"
+    ],
+    "components": [
+      "Core: View, Text, Image, ScrollView, FlatList, SectionList",
+      "Input: TextInput, TouchableOpacity, Pressable, Switch",
+      "Navigation: @react-navigation/native (Stack, Tab, Drawer navigators)",
+      "Platform-specific: SafeAreaView, StatusBar, KeyboardAvoidingView",
+      "Expo-specific: expo-image, expo-camera, expo-location (if using Expo)"
+    ],
+    "plugins": []
+  },
+  "css-pure": {
+    "name": "Vanilla CSS",
+    "packageNames": [],
+    "configFiles": [],
+    "importSignals": ["*.css", "import './styles.css'"],
+    "breakpoints": {
+      "mobile": "480px",
+      "tablet": "768px",
+      "desktop": "1024px",
+      "wide": "1440px"
+    },
+    "darkMode": "@media (prefers-color-scheme: dark) or [data-theme='dark'] attribute",
+    "responsive": "Mobile-first media queries: @media (min-width: 768px)",
+    "conventions": [
+      "BEM methodology: .block__element--modifier",
+      "CSS custom properties: --color-primary, --font-size-base, --spacing-4",
+      "Define :root variables for theme tokens",
+      "Mobile-first: base styles for mobile, enhance with min-width media queries",
+      "Avoid !important — use specificity correctly"
+    ],
+    "components": [
+      "No built-in components — define reusable classes per component",
+      "Pattern: one CSS file per component (button.css, card.css)"
+    ],
+    "plugins": []
+  }
+}

package/src/config/ux-principles.json

@@ -0,0 +1,190 @@
+{
+  "_description": "UX principles catalog for SPEC-017a — included in every UI contract",
+  "principles": [
+    {
+      "category": "Accessibility (WCAG 2.1 AA)",
+      "title": "ARIA Roles and Semantic HTML",
+      "rules": [
+        "Use semantic HTML elements before adding ARIA roles (button > div[role=button])",
+        "All interactive elements must have accessible names (aria-label or visible label)",
+        "Images must have alt text; decorative images use alt=''",
+        "Landmark roles: main, nav, header, footer, aside, search for page structure",
+        "Form inputs must be associated with labels via htmlFor/id or aria-labelledby"
+      ],
+      "examples": [
+        "<button aria-label='Close dialog'>X</button>",
+        "<img src='...' alt='User avatar for John Doe' />",
+        "<input id='email' /><label htmlFor='email'>Email</label>"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "Accessibility (WCAG 2.1 AA)",
+      "title": "Keyboard Navigation",
+      "rules": [
+        "All interactive elements reachable and operable via keyboard Tab/Enter/Space/Escape",
+        "Visible focus indicator on all focusable elements (not outline: none without replacement)",
+        "Modal dialogs must trap focus inside while open, release on close",
+        "Dropdowns, date pickers, and menus follow ARIA Authoring Practices Guide (APG) patterns",
+        "Skip navigation link as first focusable element for repeated navigation"
+      ],
+      "examples": [
+        "Modal: focus trapped inside, Escape closes, focus returns to trigger",
+        "Dropdown: Arrow keys navigate options, Enter selects, Escape closes",
+        "<a href='#main-content' class='skip-link'>Skip to main content</a>"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "Accessibility (WCAG 2.1 AA)",
+      "title": "Color Contrast",
+      "rules": [
+        "Normal text (< 18pt / 14pt bold): minimum contrast ratio 4.5:1",
+        "Large text (>= 18pt / 14pt bold): minimum contrast ratio 3:1",
+        "UI components and graphical objects: minimum contrast ratio 3:1 against adjacent colors",
+        "Never convey information through color alone — use icons, patterns, or labels",
+        "Error states must not rely solely on red color"
+      ],
+      "examples": [
+        "White text (#FFFFFF) on brand blue (#1565C0): ratio 7.04:1 (passes AA)",
+        "Error message: red icon + 'Error:' label prefix + descriptive message"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas", "mobile"]
+    },
+    {
+      "category": "Accessibility (WCAG 2.1 AA)",
+      "title": "ARIA Live Regions",
+      "rules": [
+        "Form validation errors: aria-live='assertive' — announced immediately",
+        "Success/info notifications (toasts): aria-live='polite' — queued announcement",
+        "Loading spinners: aria-busy='true' on the loading region, aria-label='Loading...'",
+        "Dynamic content updates (search results, filtered lists): aria-live='polite'",
+        "Progress indicators: role='progressbar' with aria-valuenow, aria-valuemin, aria-valuemax"
+      ],
+      "examples": [
+        "<div role='alert' aria-live='assertive'>{errorMessage}</div>",
+        "<div aria-live='polite' aria-atomic='true'>{successMessage}</div>",
+        "<div role='status' aria-busy={isLoading} aria-label='Loading content'>..."
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "Responsive Design",
+      "title": "Mobile-First Layout",
+      "rules": [
+        "Design base styles for mobile viewport first, enhance with min-width breakpoints",
+        "Minimum touch target size: 48x48px (Android/WCAG) or 44x44pt (iOS HIG)",
+        "Adequate spacing between touch targets: minimum 8px gap",
+        "Avoid hover-only interactions — all hover states must have touch/focus equivalents",
+        "Text must be readable without horizontal scrolling at 320px viewport width"
+      ],
+      "examples": [
+        "Button min-height: 48px — not just padding-dependent",
+        "Navigation: hamburger menu on mobile, full nav on desktop",
+        "Cards: full-width on mobile, 2-column on tablet, 3-column on desktop"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas", "mobile"]
+    },
+    {
+      "category": "Performance UX",
+      "title": "Perceived Performance",
+      "rules": [
+        "Show skeleton screens instead of blank space during data loading (maintain layout)",
+        "Implement optimistic updates for immediate user feedback on mutations",
+        "Lazy load below-the-fold images and non-critical components",
+        "Debounce search/filter inputs: 300ms delay before triggering requests",
+        "First Contentful Paint (FCP) target: < 1.8s — prioritize above-the-fold content"
+      ],
+      "examples": [
+        "List skeleton: grey rectangles matching item dimensions — no layout shift",
+        "Optimistic: add item to list immediately, revert on API error with toast",
+        "Image: loading='lazy' + Intersection Observer for custom lazy loading"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "UX Patterns",
+      "title": "Empty States and Error Recovery",
+      "rules": [
+        "Empty state: illustration + clear message + primary CTA (not just 'No data')",
+        "Error states: explain what went wrong + provide recovery action (retry/back)",
+        "Progressive disclosure: show advanced options behind 'Advanced settings' toggle",
+        "Inline validation: validate on blur, not on every keystroke",
+        "Confirmation dialogs: only for destructive or irreversible actions"
+      ],
+      "examples": [
+        "Empty list: 'No projects yet. Create your first project →' with button",
+        "API error: 'Failed to load data. Try again.' + Retry button",
+        "Delete confirmation: 'Delete Project X? This cannot be undone.' with red Delete button"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "Microinteractions",
+      "title": "Motion and State Transitions",
+      "rules": [
+        "Transition duration: 150-300ms for UI elements — perceptible but not slow",
+        "Use ease-in-out or ease-out timing functions for natural motion",
+        "Hover state: subtle background color change or shadow lift",
+        "Active state: scale(0.98) or slight color darkening for press feedback",
+        "Respect prefers-reduced-motion: wrap animations in @media (prefers-reduced-motion: no-preference)"
+      ],
+      "examples": [
+        "Button hover: background-color 200ms ease transition",
+        "Card hover: box-shadow 0 4px 12px rgba(0,0,0,0.15) with 200ms transition",
+        "@media (prefers-reduced-motion: reduce) { * { transition: none !important } }"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas"]
+    },
+    {
+      "category": "Typography",
+      "title": "Typographic Scale and Hierarchy",
+      "rules": [
+        "Use a modular type scale (1.25x or 1.333x ratio) for consistent hierarchy",
+        "Body text line-height: 1.5-1.6 for readability",
+        "Heading line-height: 1.1-1.3 for compact display",
+        "Minimum body font size: 16px (1rem) — never below 12px for any readable text",
+        "Font weight hierarchy: 400 body, 500 labels, 600 subheadings, 700 headings"
+      ],
+      "examples": [
+        "Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48px",
+        "H1: 48px/1.1 font-weight:700, H2: 32px/1.2 font-weight:600, body: 16px/1.5 font-weight:400"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas", "mobile"]
+    },
+    {
+      "category": "Spacing System",
+      "title": "8px Grid System",
+      "rules": [
+        "All spacing values must be multiples of 4px (4, 8, 12, 16, 24, 32, 48, 64)",
+        "Prefer 8px as base unit for consistency with most design systems",
+        "Component padding: 12-16px internal, 24-32px section separators",
+        "Never use arbitrary spacing values like 7px, 11px, 17px",
+        "Use design tokens for spacing instead of hardcoded pixel values"
+      ],
+      "examples": [
+        "Card padding: 16px (2 × 8px)",
+        "Section gap: 32px (4 × 8px)",
+        "Tailwind: p-4=16px, p-6=24px, gap-8=32px all follow 4px grid"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas", "mobile"]
+    },
+    {
+      "category": "Color System",
+      "title": "Semantic Colors and Accessibility",
+      "rules": [
+        "Use semantic color names: --color-success, --color-error, --color-warning, --color-info",
+        "Never use color as the only differentiator — add icon, label, or pattern",
+        "Provide color-blind safe palettes: avoid red/green as sole indicator",
+        "Dark mode: maintain contrast ratios — auto-generate with CSS color-mix() or design tokens",
+        "Minimum contrast: 4.5:1 for normal text, 3:1 for large text and UI components"
+      ],
+      "examples": [
+        "Success: green icon + 'Success' label (not just green text)",
+        "Error: red icon + 'Error: ' prefix + description",
+        "CSS: --color-error: oklch(50% 0.2 25) for HDR-ready semantic color"
+      ],
+      "applicableTo": ["web", "webapp", "dashboard", "saas", "mobile"]
+    }
+  ]
+}