npm - ac-framework - Versions diffs - 2.3.0 → 2.4.0 - Mend

ac-framework 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3038) hide show

package/framework/mobile_development/.antigravity/skills/mobile-design/platform-android.md DELETED Viewed

@@ -1,666 +0,0 @@
-# Android Platform Guidelines
-> Material Design 3 essentials, Android design conventions, Roboto typography, and native patterns.
-> **Read this file when building for Android devices.**
----
-## 1. Material Design 3 Philosophy
-### Core Material Principles
-```
-MATERIAL AS METAPHOR:
-├── Surfaces exist in 3D space
-├── Light and shadow define hierarchy
-├── Motion provides continuity
-└── Bold, graphic, intentional design
-ADAPTIVE DESIGN:
-├── Responds to device capabilities
-├── One UI for all form factors
-├── Dynamic color from wallpaper
-└── Personalized per user
-ACCESSIBLE BY DEFAULT:
-├── Large touch targets
-├── Clear visual hierarchy
-├── Semantic colors
-└── Motion respects preferences
-```
-### Material Design Values
-| Value | Implementation |
-|-------|----------------|
-| **Dynamic Color** | Colors adapt to wallpaper/user preference |
-| **Personalization** | User-specific themes |
-| **Accessibility** | Built into every component |
-| **Responsiveness** | Works on all screen sizes |
-| **Consistency** | Unified design language |
----
-## 2. Android Typography
-### Roboto Font Family
-```
-Android System Fonts:
-├── Roboto: Default sans-serif
-├── Roboto Flex: Variable font (API 33+)
-├── Roboto Serif: Serif alternative
-├── Roboto Mono: Monospace
-└── Google Sans: Google products (special license)
-```
-### Material Type Scale
-| Role | Size | Weight | Line Height | Usage |
-|------|------|--------|-------------|-------|
-| **Display Large** | 57sp | Regular | 64sp | Hero text, splash |
-| **Display Medium** | 45sp | Regular | 52sp | Large headers |
-| **Display Small** | 36sp | Regular | 44sp | Medium headers |
-| **Headline Large** | 32sp | Regular | 40sp | Page titles |
-| **Headline Medium** | 28sp | Regular | 36sp | Section headers |
-| **Headline Small** | 24sp | Regular | 32sp | Subsections |
-| **Title Large** | 22sp | Regular | 28sp | Dialogs, cards |
-| **Title Medium** | 16sp | Medium | 24sp | Lists, navigation |
-| **Title Small** | 14sp | Medium | 20sp | Tabs, secondary |
-| **Body Large** | 16sp | Regular | 24sp | Primary content |
-| **Body Medium** | 14sp | Regular | 20sp | Secondary content |
-| **Body Small** | 12sp | Regular | 16sp | Captions |
-| **Label Large** | 14sp | Medium | 20sp | Buttons, FAB |
-| **Label Medium** | 12sp | Medium | 16sp | Navigation |
-| **Label Small** | 11sp | Medium | 16sp | Chips, badges |
-### Scalable Pixels (sp)
-```
-sp = Scale-independent pixels
-sp automatically scales with:
-├── User font size preference
-├── Display density
-└── Accessibility settings
-RULE: ALWAYS use sp for text, dp for everything else.
-```
-### Font Weight Usage
-| Weight | Use Case |
-|--------|----------|
-| Regular (400) | Body text, display |
-| Medium (500) | Buttons, labels, emphasis |
-| Bold (700) | Rarely, strong emphasis only |
----
-## 3. Material Color System
-### Dynamic Color (Material You)
-```
-Android 12+ Dynamic Color:
-User's wallpaper → Color extraction → App theme
-Your app automatically adapts to:
-├── Primary color (from wallpaper)
-├── Secondary color (complementary)
-├── Tertiary color (accent)
-├── Surface colors (derived)
-└── All semantic colors adjust
-RULE: Implement dynamic color for personalized feel.
-```
-### Semantic Color Roles
-```
-Surface Colors:
-├── Surface → Main background
-├── SurfaceVariant → Cards, containers
-├── SurfaceTint → Elevation overlay
-├── InverseSurface → Snackbars, tooltips
-On-Surface Colors:
-├── OnSurface → Primary text
-├── OnSurfaceVariant → Secondary text
-├── Outline → Borders, dividers
-├── OutlineVariant → Subtle dividers
-Primary Colors:
-├── Primary → Key actions, FAB
-├── OnPrimary → Text on primary
-├── PrimaryContainer → Less emphasis
-├── OnPrimaryContainer → Text on container
-Secondary/Tertiary: Similar pattern
-```
-### Error, Warning, Success Colors
-| Role | Light | Dark | Usage |
-|------|-------|------|-------|
-| Error | #B3261E | #F2B8B5 | Errors, destructive |
-| OnError | #FFFFFF | #601410 | Text on error |
-| ErrorContainer | #F9DEDC | #8C1D18 | Error backgrounds |
-### Dark Theme
-```
-Material Dark Theme:
-├── Background: #121212 (not pure black by default)
-├── Surface: #1E1E1E, #232323, etc. (elevation)
-├── Elevation: Higher = lighter overlay
-├── Reduce saturation on colors
-└── Check contrast ratios
-Elevation overlays (dark mode):
-├── 0dp → 0% overlay
-├── 1dp → 5% overlay
-├── 3dp → 8% overlay
-├── 6dp → 11% overlay
-├── 8dp → 12% overlay
-├── 12dp → 14% overlay
-```
----
-## 4. Android Layout & Spacing
-### Layout Grid
-```
-Android uses 8dp baseline grid:
-All spacing in multiples of 8dp:
-├── 4dp: Component internal (half-step)
-├── 8dp: Minimum spacing
-├── 16dp: Standard spacing
-├── 24dp: Section spacing
-├── 32dp: Large spacing
-Margins:
-├── Compact (phone): 16dp
-├── Medium (small tablet): 24dp
-├── Expanded (large): 24dp+ or columns
-```
-### Responsive Layout
-```
-Window Size Classes:
-COMPACT (< 600dp width):
-├── Phones in portrait
-├── Single column layout
-├── Bottom navigation
-MEDIUM (600-840dp width):
-├── Tablets, foldables
-├── Consider 2 columns
-├── Navigation rail option
-EXPANDED (> 840dp width):
-├── Large tablets, desktop
-├── Multi-column layouts
-├── Navigation drawer
-```
-### Canonical Layouts
-| Layout | Use Case | Window Class |
-|--------|----------|--------------|
-| **List-Detail** | Email, messages | Medium, Expanded |
-| **Feed** | Social, news | All |
-| **Supporting Pane** | Reference content | Medium, Expanded |
----
-## 5. Android Navigation Patterns
-### Navigation Components
-| Component | Use Case | Position |
-|-----------|----------|----------|
-| **Bottom Navigation** | 3-5 top-level destinations | Bottom |
-| **Navigation Rail** | Tablets, foldables | Left side, vertical |
-| **Navigation Drawer** | Many destinations, large screens | Left side, hidden/visible |
-| **Top App Bar** | Current context, actions | Top |
-### Bottom Navigation
-```
-┌─────────────────────────────────────┐
-│                                     │
-│         Content Area                │
-│                                     │
-├─────────────────────────────────────┤
-│  🏠     🔍     ➕     ❤️     👤    │ ← 80dp height
-│ Home   Search  FAB   Saved  Profile│
-└─────────────────────────────────────┘
-Rules:
-├── 3-5 destinations
-├── Icons: Material Symbols (24dp)
-├── Labels: Always visible (accessibility)
-├── Active: Filled icon + indicator pill
-├── Badge: For notifications
-├── FAB can integrate (optional)
-```
-### Top App Bar
-```
-Types:
-├── Center-aligned: Logo apps, simple
-├── Small: Compact, scrolls away
-├── Medium: Title + actions, collapses
-├── Large: Display title, collapses to small
-┌─────────────────────────────────────┐
-│  ☰   App Title              🔔 ⋮  │ ← 64dp (small)
-├─────────────────────────────────────┤
-│                                     │
-│         Content Area                │
-└─────────────────────────────────────┘
-Actions: Max 3 icons, overflow menu ( ⋮ ) for more
-```
-### Navigation Rail (Tablets)
-```
-┌───────┬─────────────────────────────┐
-│  ≡    │                             │
-│       │                             │
-│  🏠   │                             │
-│ Home  │       Content Area          │
-│       │                             │
-│  🔍   │                             │
-│Search │                             │
-│       │                             │
-│  👤   │                             │
-│Profile│                             │
-└───────┴─────────────────────────────┘
-Width: 80dp
-Icons: 24dp
-Labels: Below icon
-FAB: Can be at top
-```
-### Back Navigation
-```
-Android provides system back:
-├── Back button (3-button nav)
-├── Back gesture (swipe from edge)
-├── Predictive back (Android 14+)
-Your app must:
-├── Handle back correctly (pop stack)
-├── Support predictive back animation
-├── Never hijack/override back unexpectedly
-└── Confirm before discarding unsaved work
-```
----
-## 6. Material Components
-### Buttons
-```
-Button Types:
-┌──────────────────────┐
-│    Filled Button     │  ← Primary action
-└──────────────────────┘
-┌──────────────────────┐
-│    Tonal Button      │  ← Secondary, less emphasis
-└──────────────────────┘
-┌──────────────────────┐
-│   Outlined Button    │  ← Tertiary, lower emphasis
-└──────────────────────┘
-    Text Button           ← Lowest emphasis
-Heights:
-├── Small: 40dp (when constrained)
-├── Standard: 40dp
-├── Large: 56dp (FAB size when needed)
-Min touch target: 48dp (even if visual is smaller)
-```
-### Floating Action Button (FAB)
-```
-FAB Types:
-├── Standard: 56dp diameter
-├── Small: 40dp diameter
-├── Large: 96dp diameter
-├── Extended: Icon + text, variable width
-Position: Bottom right, 16dp from edges
-Elevation: Floats above content
-┌─────────────────────────────────────┐
-│                                     │
-│         Content                     │
-│                                     │
-│                              ┌────┐ │
-│                              │ ➕ │ │ ← FAB
-│                              └────┘ │
-├─────────────────────────────────────┤
-│       Bottom Navigation             │
-└─────────────────────────────────────┘
-```
-### Cards
-```
-Card Types:
-├── Elevated: Shadow, resting state
-├── Filled: Background color, no shadow
-├── Outlined: Border, no shadow
-Card Anatomy:
-┌─────────────────────────────────────┐
-│           Header Image              │ ← Optional
-├─────────────────────────────────────┤
-│  Title / Headline                   │
-│  Subhead / Supporting text          │
-├─────────────────────────────────────┤
-│      [ Action ]    [ Action ]       │ ← Optional actions
-└─────────────────────────────────────┘
-Corner radius: 12dp (M3 default)
-Padding: 16dp
-```
-### Text Fields
-```
-Types:
-├── Filled: Background fill, underline
-├── Outlined: Border all around
-┌─────────────────────────────────────┐
-│  Label                              │ ← Floats up on focus
-│  ________________________________________________
-│  │     Input text here...          │ ← Leading/trailing icons
-│  ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
-│  Supporting text or error           │
-└─────────────────────────────────────┘
-Height: 56dp
-Label: Animates from placeholder to top
-Error: Red color + icon + message
-```
-### Chips
-```
-Types:
-├── Assist: Smart actions (directions, call)
-├── Filter: Toggle filters
-├── Input: Represent entities (tags, contacts)
-├── Suggestion: Dynamic recommendations
-┌───────────────┐
-│  🏷️ Filter   │  ← 32dp height, 8dp corner radius
-└───────────────┘
-States: Unselected, Selected, Disabled
-```
----
-## 7. Android-Specific Patterns
-### Snackbars
-```
-Position: Bottom, above navigation
-Duration: 4-10 seconds
-Action: One optional text action
-┌─────────────────────────────────────────────────┐
-│  Archived 1 item                    [ UNDO ]    │
-└─────────────────────────────────────────────────┘
-Rules:
-├── Brief message, single line if possible
-├── Max 2 lines
-├── One action (text, not icon)
-├── Can be dismissed by swipe
-└── Don't stack, queue them
-```
-### Bottom Sheets
-```
-Types:
-├── Standard: Interactive content
-├── Modal: Blocks background (with scrim)
-Modal Bottom Sheet:
-┌─────────────────────────────────────┐
-│                                     │
-│        (Scrim over content)         │
-│                                     │
-├═════════════════════════════════════┤
-│  ─────  (Drag handle, optional)     │
-│                                     │
-│        Sheet Content                │
-│                                     │
-│        Actions / Options            │
-│                                     │
-└─────────────────────────────────────┘
-Corner radius: 28dp (top corners)
-```
-### Dialogs
-```
-Types:
-├── Basic: Title + content + actions
-├── Full-screen: Complex editing (mobile)
-├── Date/Time picker
-├── Confirmation dialog
-┌─────────────────────────────────────┐
-│              Title                  │
-│                                     │
-│       Supporting text that          │
-│       explains the dialog           │
-│                                     │
-│           [ Cancel ]  [ Confirm ]   │
-└─────────────────────────────────────┘
-Rules:
-├── Centered on screen
-├── Scrim behind (dim background)
-├── Max 2 actions aligned right
-├── Destructive action can be on left
-```
-### Pull to Refresh
-```
-Android uses SwipeRefreshLayout pattern:
-┌─────────────────────────────────────┐
-│         ○ (Spinner)                 │ ← Circular progress
-├─────────────────────────────────────┤
-│                                     │
-│         Content                     │
-│                                     │
-└─────────────────────────────────────┘
-Spinner: Material circular indicator
-Position: Top center, pulls down with content
-```
-### Ripple Effect
-```
-Every touchable element needs ripple:
-Touch down → Ripple expands from touch point
-Touch up → Ripple completes and fades
-Color:
-├── On light: Black at ~12% opacity
-├── On dark: White at ~12% opacity
-├── On colored: Appropriate contrast
-This is MANDATORY for Android feel.
-```
----
-## 8. Material Symbols
-### Usage Guidelines
-```
-Material Symbols: Google's icon library
-Styles:
-├── Outlined: Default, most common
-├── Rounded: Softer, friendly
-├── Sharp: Angular, precise
-Variable font axes:
-├── FILL: 0 (outline) to 1 (filled)
-├── wght: 100-700 (weight)
-├── GRAD: -25 to 200 (emphasis)
-├── opsz: 20, 24, 40, 48 (optical size)
-```
-### Icon Sizes
-| Size | Usage |
-|------|-------|
-| 20dp | Dense UI, inline |
-| 24dp | Standard (most common) |
-| 40dp | Larger touch targets |
-| 48dp | Emphasis, standalone |
-### States
-```
-Icon States:
-├── Default: Full opacity
-├── Disabled: 38% opacity
-├── Hover/Focus: Container highlight
-├── Selected: Filled variant + tint
-Active vs Inactive:
-├── Inactive: Outlined
-├── Active: Filled + indicator
-```
----
-## 9. Android Accessibility
-### TalkBack Requirements
-```
-Every interactive element needs:
-├── contentDescription (what it is)
-├── Correct semantics (button, checkbox, etc.)
-├── State announcements (selected, disabled)
-└── Grouping where logical
-Jetpack Compose:
-Modifier.semantics {
-    contentDescription = "Play button"
-    role = Role.Button
-}
-React Native:
-accessibilityLabel="Play button"
-accessibilityRole="button"
-accessibilityState={{ disabled: false }}
-```
-### Touch Target Size
-```
-MANDATORY: 48dp × 48dp minimum
-Even if visual element is smaller:
-├── Icon: 24dp visual, 48dp touch area
-├── Checkbox: 20dp visual, 48dp touch area
-└── Add padding to reach 48dp
-Spacing between targets: 8dp minimum
-```
-### Font Scaling
-```
-Android supports font scaling:
-├── 85% (smaller)
-├── 100% (default)
-├── 115%, 130%, 145%...
-├── Up to 200% (largest)
-RULE: Test your UI at 200% font scale.
-Use sp units and avoid fixed heights.
-```
-### Reduce Motion
-```kotlin
-// Check motion preference
-val reduceMotion = Settings.Global.getFloat(
-    contentResolver,
-    Settings.Global.ANIMATOR_DURATION_SCALE,
-    1f
-) == 0f
-if (reduceMotion) {
-    // Skip or reduce animations
-}
-```
----
-## 10. Android Checklist
-### Before Every Android Screen
-- [ ] Using Material 3 components
-- [ ] Touch targets ≥ 48dp
-- [ ] Ripple effect on all touchables
-- [ ] Roboto or Material type scale
-- [ ] Semantic colors (dynamic color support)
-- [ ] Back navigation works correctly
-### Before Android Release
-- [ ] Dark theme tested
-- [ ] Dynamic color tested (if supported)
-- [ ] All font sizes tested (200% scale)
-- [ ] TalkBack tested
-- [ ] Predictive back implemented (Android 14+)
-- [ ] Edge-to-edge display (Android 15+)
-- [ ] Different screen sizes tested (phones, tablets)
-- [ ] Navigation patterns match platform (back, gestures)
----
-> **Remember:** Android users expect Material Design. Custom designs that ignore Material patterns feel foreign and broken. Use Material components as your foundation, customize thoughtfully.