@harness-engineering/cli 1.6.1 → 1.7.0

package/dist/agents/skills/shared/design-knowledge/platform-rules/android.yaml

@@ -0,0 +1,125 @@
+description: "Android platform design rules — Jetpack Compose/Material 3 patterns, Material Design compliance, and platform-specific constraints"
+
+platform: android
+frameworks: ["Jetpack Compose", "XML Views"]
+minimum_version: "API 26 (Android 8.0+)"
+design_system: "Material Design 3 (Material You)"
+
+token_binding:
+  description: "How design tokens map to Android platform primitives"
+  methods:
+    - name: "Material 3 ColorScheme"
+      priority: 1
+      example: "MaterialTheme.colorScheme.primary"
+      usage: "Map design tokens to Material 3 color roles via custom Theme composable"
+    - name: "Compose Theme Extension"
+      priority: 2
+      example: "AppTheme.colors.primary"
+      usage: "Custom theme object extending MaterialTheme for tokens that don't map to M3 roles"
+    - name: "XML Resource Values"
+      priority: 3
+      example: "@color/primary, @dimen/spacing_md"
+      usage: "For XML Views compatibility — define in res/values/colors.xml and dimens.xml"
+
+component_patterns:
+  - name: "Material 3 components first"
+    rule: "Use Material 3 Compose components before building custom ones"
+    reason: "M3 components implement accessibility, theming, and state handling correctly out of the box"
+    exceptions: ["When the design token system requires visual customization beyond M3 theming", "When no M3 equivalent exists"]
+
+  - name: "Token-bound styling"
+    rule: "All colors, typography, and spacing must reference design tokens via the theme"
+    detect: "Search for Color(0xFF...), hardcoded sp/dp values, and fontFamily literals in composables"
+    example: |
+      // Correct:
+      Text(color = MaterialTheme.colorScheme.primary, style = MaterialTheme.typography.bodyLarge)
+      // Wrong:
+      Text(color = Color(0xFF2563EB), fontSize = 16.sp)
+
+  - name: "Adaptive layout"
+    rule: "Support phones, foldables, and tablets using window size classes"
+    approach: "Use WindowSizeClass (compact/medium/expanded) instead of hardcoded breakpoints"
+
+material_compliance:
+  dynamic_color:
+    rule: "Support Material You dynamic color on Android 12+"
+    implementation: "Use dynamicLightColorScheme()/dynamicDarkColorScheme() with fallback to custom scheme"
+    fallback: "Devices below API 31 use the static token-based color scheme"
+
+  elevation:
+    rule: "Use tonal elevation (surface tint) instead of drop shadows for Material 3"
+    implementation: "Surface(tonalElevation = X.dp) instead of shadow-based elevation"
+    levels:
+      - level: 0
+        dp: 0
+        usage: "Default surface"
+      - level: 1
+        dp: 1
+        usage: "Cards, navigation rail"
+      - level: 2
+        dp: 3
+        usage: "Bottom sheets, FAB (lowered)"
+      - level: 3
+        dp: 6
+        usage: "Navigation drawer, FAB"
+      - level: 4
+        dp: 8
+        usage: "Top app bar (scrolled)"
+      - level: 5
+        dp: 12
+        usage: "Modal bottom sheet"
+
+  navigation:
+    rule: "Follow Material 3 navigation patterns based on window size class"
+    patterns:
+      compact: "Bottom navigation bar (NavigationBar) with 3-5 destinations"
+      medium: "Navigation rail (NavigationRail) with labels"
+      expanded: "Persistent navigation drawer (PermanentNavigationDrawer)"
+    avoid: "Hamburger menus on compact screens, custom tab implementations"
+
+  touch_targets:
+    rule: "All interactive elements must have minimum 48x48dp touch target"
+    implementation: "Use Modifier.minimumInteractiveComponentSize() or explicit Modifier.size(48.dp)"
+    reason: "Material Design and WCAG require minimum 48dp touch targets for accessibility"
+
+accessibility:
+  talkback:
+    rule: "All interactive elements must be accessible to TalkBack"
+    requirements:
+      - "Set contentDescription on all Image and Icon composables"
+      - "Use semantics {} modifier for custom accessible descriptions"
+      - "Merge child semantics with Modifier.semantics(mergeDescendants = true) for grouped content"
+      - "Set Role.Button, Role.Checkbox, etc. in semantics blocks"
+
+  font_scaling:
+    rule: "All text must scale with system font size settings"
+    implementation: "Use MaterialTheme.typography styles (uses sp units). Never hardcode px text sizes."
+    testing: "Test at font scale 1.0, 1.3, and 2.0 (maximum system setting)"
+    constraints:
+      - "Layouts must not clip or overlap at 2.0x font scale"
+      - "Scrollable containers must accommodate expanded text"
+
+  color:
+    rule: "Support high contrast theme and ensure color is not the sole indicator"
+    implementation: "Test with Android high contrast text enabled in accessibility settings"
+
+performance:
+  - rule: "Compose recomposition — avoid unnecessary recompositions"
+    implementation: "Use remember, derivedStateOf, and stable/immutable annotations"
+    measurement: "Use Layout Inspector recomposition counts"
+  - rule: "Startup time under 2 seconds (cold start to interactive)"
+    measurement: "Use Android Vitals and Macrobenchmark"
+  - rule: "LazyColumn/LazyRow for lists over 20 items"
+    reason: "Eager Column/Row with many children causes frame drops"
+  - rule: "Images loaded with Coil or Glide with proper caching"
+    reason: "Synchronous image loading causes jank and OOM on large images"
+
+testing:
+  - type: "Screenshot"
+    tools: ["Roborazzi", "Paparazzi"]
+    rule: "Screenshot all component variants in light/dark mode and at 1.0x/2.0x font scale"
+  - type: "Accessibility"
+    tools: ["Accessibility Scanner", "Espresso accessibility checks"]
+    rule: "Run accessibility scanner on all screens"
+  - type: "Device matrix"
+    rule: "Test on small phone (360dp width), standard phone (412dp), foldable (inner: 600dp), and tablet (840dp+)"

package/dist/agents/skills/shared/design-knowledge/platform-rules/flutter.yaml

@@ -0,0 +1,144 @@
+description: "Flutter platform design rules — cross-platform patterns, Material/Cupertino adaptation, and platform-specific constraints"
+
+platform: flutter
+frameworks: ["Flutter"]
+minimum_version: "Flutter 3.19+ / Dart 3.3+"
+design_systems: ["Material 3", "Cupertino (adaptive)"]
+
+token_binding:
+  description: "How design tokens map to Flutter platform primitives"
+  methods:
+    - name: "ThemeData / ColorScheme"
+      priority: 1
+      example: "Theme.of(context).colorScheme.primary"
+      usage: "Map design tokens to Material 3 ColorScheme and TextTheme via custom ThemeData"
+    - name: "App Theme Extension"
+      priority: 2
+      example: "context.appColors.primary"
+      usage: "ThemeExtension<T> for tokens that don't map to Material roles"
+    - name: "Generated Token Constants"
+      priority: 3
+      example: "AppTokens.colorPrimary"
+      usage: "Build-time generated Dart constants from tokens.json for type-safe access"
+
+component_patterns:
+  - name: "Platform-adaptive components"
+    rule: "Use platform-adaptive widgets that render Material on Android and Cupertino on iOS"
+    approach: |
+      Use .adaptive constructors where available:
+      - Switch.adaptive()
+      - Slider.adaptive()
+      - CircularProgressIndicator.adaptive()
+      For complex components, use Platform.isIOS checks with CupertinoTheme wrapping.
+    reason: "Users expect platform-native interaction patterns — Android users expect Material, iOS users expect Cupertino"
+
+  - name: "Token-bound styling"
+    rule: "All colors, typography, and spacing must reference design tokens via the theme"
+    detect: "Search for Color(0xFF...), hardcoded fontSize doubles, and literal EdgeInsets values"
+    example: |
+      // Correct:
+      Text('Hello', style: Theme.of(context).textTheme.bodyLarge)
+      Container(color: Theme.of(context).colorScheme.surface)
+      // Wrong:
+      Text('Hello', style: TextStyle(fontSize: 16, color: Color(0xFF2563EB)))
+
+  - name: "Responsive layout"
+    rule: "Support phones, tablets, foldables, and web using LayoutBuilder and MediaQuery"
+    approach: "Define breakpoints matching the design system and use LayoutBuilder to switch between compact/expanded layouts"
+
+platform_adaptation:
+  ios:
+    navigation: "Use CupertinoNavigationBar and swipe-to-go-back gesture"
+    scroll_physics: "BouncingScrollPhysics (iOS default)"
+    haptics: "HapticFeedback.lightImpact() for selections"
+    safe_area: "Use SafeArea widget for notch/Dynamic Island"
+    typography: "SF Pro via .cupertino text theme"
+
+  android:
+    navigation: "Use NavigationBar (M3 bottom nav) and predictive back gesture"
+    scroll_physics: "ClampingScrollPhysics (Android default)"
+    haptics: "HapticFeedback.mediumImpact() for confirmations"
+    edge_to_edge: "Use SystemChrome.setEnabledSystemUIMode for edge-to-edge"
+    typography: "Roboto via Material text theme"
+
+  web:
+    navigation: "Use NavigationRail or permanent drawer for wider layouts"
+    scroll_physics: "ClampingScrollPhysics with mouse wheel support"
+    hover_states: "Add MouseRegion and hover feedback for pointer devices"
+    text_selection: "Enable SelectionArea for text content"
+    font_loading: "Use GoogleFonts package with preloading"
+
+material3:
+  color_roles:
+    rule: "Map design tokens to M3 color roles, not arbitrary colors"
+    mapping:
+      primary: "Brand primary — buttons, FAB, active indicators"
+      secondary: "Brand secondary — chips, filters, less prominent actions"
+      tertiary: "Complementary accent — badges, highlights"
+      surface: "Card and container backgrounds"
+      error: "Error states, destructive actions"
+      outline: "Borders, dividers"
+
+  elevation:
+    rule: "Use M3 tonal elevation via Surface widget"
+    implementation: "Set elevation in Material() or Card() — Flutter M3 auto-applies surface tint"
+
+  shape:
+    rule: "Use ShapeTheme for consistent corner radii"
+    scale:
+      extraSmall: 4
+      small: 8
+      medium: 12
+      large: 16
+      extraLarge: 28
+      full: 1000
+
+accessibility:
+  semantics:
+    rule: "All interactive elements must have semantic labels"
+    requirements:
+      - "Set Semantics(label:) on all Icon and Image widgets"
+      - "Use Semantics(button: true) for custom tappable widgets"
+      - "Use MergeSemantics to group related content"
+      - "Use ExcludeSemantics for decorative elements"
+
+  text_scaling:
+    rule: "All text must scale with system accessibility settings"
+    implementation: "Use Theme textTheme styles. Never hardcode fontSize without textScaleFactor awareness."
+    testing: "Test at textScaleFactor 1.0, 1.5, and 2.0"
+    constraints:
+      - "Layouts must not overflow at 2.0x text scale"
+      - "Use Flexible/Expanded to accommodate variable text size"
+
+  touch_targets:
+    rule: "Minimum 48x48 logical pixels for all interactive elements"
+    implementation: "Use MaterialTapTargetSize.padded (default) or explicit SizedBox constraints"
+
+  screen_readers:
+    rule: "Test with TalkBack (Android) and VoiceOver (iOS)"
+    implementation: "Use semanticsLabel, Semantics widget, and SemanticsService.announce for dynamic content"
+
+performance:
+  - rule: "Build with --release for performance testing (debug mode is 10x slower)"
+  - rule: "Use const constructors wherever possible to reduce widget rebuilds"
+    detect: "Lint rule prefer_const_constructors"
+  - rule: "ListView.builder for lists over 20 items (never ListView with children:[])"
+    reason: "ListView with children builds all items eagerly, causing jank and memory pressure"
+  - rule: "Cache images with CachedNetworkImage or precacheImage"
+  - rule: "Avoid rebuilds — use const, final, ValueListenableBuilder, and Selector for granular rebuilds"
+    measurement: "Use DevTools widget rebuild tracker"
+  - rule: "Shader compilation jank — use SkSL warmup for known animations"
+
+testing:
+  - type: "Widget tests"
+    tools: ["flutter_test"]
+    rule: "All components must have widget tests covering default state, interactions, and edge cases"
+  - type: "Golden tests"
+    tools: ["golden_toolkit", "alchemist"]
+    rule: "Screenshot all component variants in light/dark mode, LTR/RTL, and at multiple text scales"
+  - type: "Integration"
+    tools: ["integration_test"]
+    rule: "Key user flows must have integration tests on both Android and iOS"
+  - type: "Accessibility"
+    tools: ["flutter_test Semantics matchers"]
+    rule: "Verify semantics tree for all screens using find.bySemanticsLabel and semantics matchers"

package/dist/agents/skills/shared/design-knowledge/platform-rules/ios.yaml

@@ -0,0 +1,106 @@
+description: "iOS platform design rules — SwiftUI patterns, Human Interface Guidelines compliance, and platform-specific constraints"
+
+platform: ios
+frameworks: ["SwiftUI", "UIKit"]
+minimum_version: "iOS 16+"
+
+token_binding:
+  description: "How design tokens map to iOS platform primitives"
+  methods:
+    - name: "Asset Catalog Colors"
+      priority: 1
+      example: "Color('primary')"
+      usage: "Named colors in Assets.xcassets with light/dark variants"
+    - name: "SwiftUI Color Extension"
+      priority: 2
+      example: "Color.primary, Color.surface"
+      usage: "Static Color extension mapping token names to asset catalog entries"
+    - name: "UIKit UIColor Extension"
+      priority: 3
+      example: "UIColor.primary"
+      usage: "For UIKit compatibility layers"
+
+component_patterns:
+  - name: "Native controls first"
+    rule: "Use standard UIKit/SwiftUI controls before building custom ones"
+    reason: "Native controls inherit accessibility, Dynamic Type, and platform behaviors automatically"
+    exceptions: ["When the design system explicitly defines a custom variant", "When the native control cannot be styled to match tokens"]
+
+  - name: "Token-bound styling"
+    rule: "All colors, fonts, and spacing must reference design tokens, never hardcoded values"
+    detect: "Search for Color(red:green:blue:), UIColor(red:green:blue:), and literal CGFloat spacing values"
+    example: |
+      // Correct:
+      .foregroundColor(.primary)
+      .font(.custom("Inter", size: Typography.body))
+      // Wrong:
+      .foregroundColor(Color(red: 0.15, green: 0.38, blue: 0.92))
+
+  - name: "Adaptive layout"
+    rule: "Support all device sizes from iPhone SE to iPad Pro"
+    approach: "Use GeometryReader sparingly, prefer native layout (VStack/HStack/LazyGrid) with size classes"
+
+hig_compliance:
+  safe_areas:
+    rule: "Content must respect safe area insets on all devices"
+    context: "Notch, Dynamic Island, home indicator, status bar"
+    implementation: "Use .safeAreaInset() modifiers, never hardcode top/bottom padding"
+
+  navigation:
+    rule: "Follow iOS navigation patterns — push for drill-down, modal for focused tasks"
+    patterns:
+      - "NavigationStack for hierarchical content"
+      - ".sheet() for focused tasks that don't require full context"
+      - ".fullScreenCover() for immersive experiences (photo viewer, video player)"
+    avoid: "Custom hamburger menus, bottom tab bars with more than 5 items"
+
+  dynamic_type:
+    rule: "All text must scale with Dynamic Type settings"
+    implementation: "Use .font(.body), .font(.title) semantic styles, or .dynamicTypeSize() modifier"
+    testing: "Test at all Dynamic Type sizes, especially accessibility sizes (AX1-AX5)"
+    constraints:
+      - "Layouts must not break at the largest accessibility size"
+      - "Minimum touch target remains 44x44pt regardless of text size"
+
+  haptics:
+    rule: "Use appropriate haptic feedback for interactions"
+    patterns:
+      - "UIImpactFeedbackGenerator(.light) for toggles and selections"
+      - "UINotificationFeedbackGenerator for success/error/warning"
+      - "UISelectionFeedbackGenerator for picker scrolling"
+    avoid: "Haptics on every tap — reserve for meaningful state changes"
+
+accessibility:
+  voiceover:
+    rule: "All interactive elements must be accessible to VoiceOver"
+    requirements:
+      - "Set .accessibilityLabel() on all images and icons"
+      - "Use .accessibilityHint() for non-obvious interactions"
+      - "Group related elements with .accessibilityElement(children: .combine)"
+      - "Set .accessibilityAddTraits() correctly (.isButton, .isHeader, etc.)"
+
+  color:
+    rule: "Support Increase Contrast and Differentiate Without Color settings"
+    implementation: "Check UIAccessibility.isDifferentiateWithoutColorEnabled and provide shape/icon alternatives"
+
+  motion:
+    rule: "Respect Reduce Motion setting"
+    implementation: "Check UIAccessibility.isReduceMotionEnabled; replace animations with crossfade or instant transitions"
+
+performance:
+  - rule: "App launch to interactive in under 2 seconds"
+    measurement: "Use Instruments Time Profiler and MetricKit"
+  - rule: "Scroll at 60fps minimum (120fps on ProMotion devices)"
+    implementation: "Use LazyVStack/LazyHStack for long lists, avoid onAppear heavy work"
+  - rule: "Images loaded asynchronously with AsyncImage or custom cache"
+    reason: "Synchronous image loading blocks the main thread and causes scroll jank"
+
+testing:
+  - type: "Snapshot"
+    tools: ["swift-snapshot-testing"]
+    rule: "Snapshot all component variants in light/dark mode and at standard/accessibility type sizes"
+  - type: "Accessibility audit"
+    tools: ["Xcode Accessibility Inspector", "XCUITest"]
+    rule: "Run accessibility audit on all screens"
+  - type: "Device matrix"
+    rule: "Test on iPhone SE, iPhone 15, iPhone 15 Pro Max, and iPad minimum"

package/dist/agents/skills/shared/design-knowledge/platform-rules/web.yaml

@@ -0,0 +1,102 @@
+description: "Web platform design rules — CSS, Tailwind, React/Vue/Svelte component patterns and constraints"
+
+platform: web
+frameworks: ["React", "Vue", "Svelte", "vanilla"]
+styling: ["Tailwind CSS", "CSS Modules", "CSS-in-JS", "vanilla CSS"]
+
+token_binding:
+  description: "How design tokens map to web platform primitives"
+  methods:
+    - name: "CSS Custom Properties"
+      priority: 1
+      example: "var(--color-primary)"
+      usage: "Default binding — works in all CSS contexts"
+    - name: "Tailwind Theme Extension"
+      priority: 2
+      example: "text-primary, bg-surface"
+      usage: "When project uses Tailwind — extend tailwind.config with token values"
+    - name: "CSS-in-JS Theme Object"
+      priority: 3
+      example: "theme.colors.primary"
+      usage: "When project uses styled-components, Emotion, or similar"
+
+component_patterns:
+  - name: "Composition over configuration"
+    rule: "Prefer composable child components over prop-heavy monolithic components"
+    example: |
+      // Prefer:
+      <Card><CardHeader /><CardBody /><CardFooter /></Card>
+      // Over:
+      <Card header="..." body="..." footer="..." />
+    reason: "Composable components are more flexible, easier to test, and align with framework idioms"
+
+  - name: "Token-bound styling"
+    rule: "All visual properties must reference design tokens, never hardcoded values"
+    detect: "Grep for hex colors, px font sizes, and raw spacing values in component files"
+    example: |
+      // Correct:
+      className="text-primary bg-surface p-4"
+      // Wrong:
+      style={{ color: '#2563eb', padding: '16px' }}
+
+  - name: "Responsive-first"
+    rule: "Components must work at all breakpoints defined in the design system"
+    approach: "Mobile-first: base styles for mobile, progressive enhancement for larger screens"
+
+  - name: "Accessible by default"
+    rule: "Interactive components must include ARIA attributes, keyboard handlers, and focus management"
+    requirements:
+      - "All buttons and links have accessible names"
+      - "Focus is visible and follows a logical order"
+      - "Dynamic content changes are announced to screen readers"
+      - "Color is never the sole indicator of state"
+
+css_guidelines:
+  custom_properties:
+    rule: "Define all design tokens as CSS custom properties on :root"
+    example: |
+      :root {
+        --color-primary: #2563eb;
+        --color-surface: #f8fafc;
+        --font-display: 'Inter', system-ui, sans-serif;
+        --spacing-4: 1rem;
+      }
+
+  tailwind:
+    rule: "Extend Tailwind config with token values rather than using arbitrary values"
+    example: |
+      // tailwind.config.js
+      theme: {
+        extend: {
+          colors: {
+            primary: 'var(--color-primary)',
+            surface: 'var(--color-surface)',
+          }
+        }
+      }
+    avoid: "Arbitrary value syntax like bg-[#2563eb] when a token exists"
+
+  dark_mode:
+    rule: "Support dark mode via CSS custom property overrides, not duplicate stylesheets"
+    approach: "Redefine token values inside a [data-theme='dark'] or @media (prefers-color-scheme: dark) block"
+
+performance:
+  - rule: "Limit CSS bundle to 50KB gzipped"
+    reason: "CSS blocks rendering — large stylesheets delay first paint"
+  - rule: "Use content-visibility: auto for below-fold sections"
+    reason: "Reduces initial layout cost for long pages"
+  - rule: "Lazy-load web fonts with font-display: swap"
+    reason: "Prevents invisible text (FOIT) during font download"
+  - rule: "Prefer CSS transitions over JavaScript animations"
+    reason: "CSS animations run on the compositor thread, avoiding main thread jank"
+
+testing:
+  - type: "Visual regression"
+    tools: ["Chromatic", "Percy", "Playwright screenshots"]
+    rule: "All component variants must have visual regression coverage"
+  - type: "Accessibility"
+    tools: ["axe-core", "Lighthouse", "pa11y"]
+    rule: "Run axe-core in CI on all component stories"
+  - type: "Responsive"
+    tools: ["Playwright", "Cypress"]
+    rule: "Test at 320px, 768px, 1024px, and 1440px viewports minimum"