@rosetears/aili-pi 0.1.0

package/skills/android-native-dev/references/accessibility.md

@@ -0,0 +1,209 @@
+# Accessibility Guidelines
+
+Comprehensive accessibility requirements for Android applications.
+
+## Core Requirements
+
+### Minimum Standards
+
+| Requirement | Specification |
+|-------------|---------------|
+| Color contrast (text) | 4.5:1 minimum |
+| Color contrast (large text) | 3:1 minimum |
+| Color contrast (UI components) | 3:1 minimum |
+| Touch targets | 48 × 48dp minimum |
+| Content descriptions | All interactive elements |
+| Focus indicators | Clearly visible |
+| Screen reader support | Proper semantics |
+
+## Content Labels
+
+### contentDescription
+
+Use for non-text interactive elements.
+
+**When to use:**
+- ImageView, ImageButton
+- CheckBox, Switch (state description)
+- Custom drawable views
+- Icons that convey meaning
+
+**When NOT to use:**
+- TextView (uses text content automatically)
+- Decorative images (set to null)
+- Elements with labelFor relationship
+
+### android:hint
+
+Use for editable text fields to show placeholder text.
+
+**Important**: Don't use contentDescription on EditText—it interferes with accessibility services.
+
+### android:labelFor
+
+Link labels to input fields by setting labelFor on the TextView to reference the EditText ID.
+
+## Label Best Practices
+
+### Do's
+
+| Practice | Example |
+|----------|---------|
+| Be concise | "Save" not "Click here to save" |
+| Describe action/purpose | "Delete message" |
+| Be unique in context | "Delete item 3" not just "Delete" |
+| Update dynamically | "Pause" ↔ "Play" based on state |
+
+### Don'ts
+
+| Avoid | Reason |
+|-------|--------|
+| Include element type | TalkBack announces "button" automatically |
+| Say "button", "image", etc. | Redundant with accessibility info |
+| Use "click" or "tap" | Input method varies |
+| Leave empty/generic | "Button" or "Image" is unhelpful |
+
+### Examples
+
+| Bad | Good |
+|-----|------|
+| "Save button" | "Save" |
+| "Click here to submit" | "Submit" |
+| "Image" | "Profile photo of John" |
+| "Button 1" | "Add to cart" |
+
+## Focus and Navigation
+
+### Focus Groups
+
+Group related elements using `screenReaderFocusable="true"` on the container and `focusable="false"` on child elements. TalkBack will announce all children's content in a single utterance.
+
+### Headings
+
+Mark section headers with `accessibilityHeading="true"`. Users can navigate between headings for quick scanning.
+
+### Pane Titles
+
+Identify screen regions with `accessibilityPaneTitle`. Accessibility services announce pane changes.
+
+### Focus Order
+
+- Natural reading order (top-to-bottom, start-to-end)
+- Use `accessibilityTraversalBefore/After` for custom order
+- Ensure all interactive elements are focusable
+- Skip decorative elements
+
+## Decorative Elements
+
+Skip elements that don't convey information:
+- Set `contentDescription="@null"`
+- Or set `importantForAccessibility="no"`
+
+## Custom Accessibility Actions
+
+### Adding Actions
+
+Provide alternatives for gesture-based interactions using `ViewCompat.addAccessibilityAction()`. This exposes swipe actions to accessibility services.
+
+### Replacing Action Labels
+
+Make default actions more descriptive using `ViewCompat.replaceAccessibilityAction()`. Example: "Double tap and hold to add to favorites" instead of generic "long press".
+
+## Color and Visual Cues
+
+### Don't Rely on Color Alone
+
+Combine color with other indicators:
+
+| Information | Color + Alternative |
+|-------------|---------------------|
+| Error state | Red + error icon + text |
+| Success | Green + checkmark + text |
+| Required field | Red asterisk + "Required" label |
+| Selected item | Highlight + checkmark + bold |
+| Link text | Blue + underline |
+
+### Contrast Testing
+
+Use tools to verify contrast:
+- Android Accessibility Scanner
+- Contrast Checker plugins
+- Manual calculation: (L1 + 0.05) / (L2 + 0.05)
+
+## Touch Targets
+
+### Minimum Sizes
+
+| Element | Minimum | Recommended |
+|---------|---------|-------------|
+| Standard | 48 × 48dp | 48 × 48dp |
+| Primary actions | 48 × 48dp | 56 × 56dp |
+| Kids apps | 56 × 56dp | 64 × 64dp |
+
+### Spacing
+
+- Minimum 8dp between adjacent touch targets
+- Visual element can be smaller if touch area is adequate (use padding)
+
+## Screen Reader Announcements
+
+### Live Regions
+
+Announce dynamic content changes using `accessibilityLiveRegion`:
+
+| Mode | Usage |
+|------|-------|
+| polite | Announces when user is idle |
+| assertive | Interrupts current speech |
+| none | No automatic announcements |
+
+### Custom Announcements
+
+Use `announceForAccessibility()` sparingly—prefer live regions.
+
+## Keyboard and Hardware Navigation
+
+### Focus Indicators
+
+- Visible focus state for all interactive elements
+- Don't remove default focus indicators
+- Custom focus: 2dp+ border or background change
+
+### Keyboard Shortcuts
+
+- Support Tab navigation
+- Enter/Space for activation
+- Arrow keys for lists/grids
+- Escape for dismissal
+
+## Testing Accessibility
+
+### Manual Testing
+
+1. **TalkBack**: Navigate entire app with screen reader
+2. **Switch Access**: Test with switch navigation
+3. **Keyboard**: Navigate with external keyboard only
+4. **Magnification**: Test with zoom enabled
+5. **Large text**: Test with 200% font scale
+6. **High contrast**: Test with high contrast mode
+
+### Automated Testing
+
+| Tool | Purpose |
+|------|---------|
+| Accessibility Scanner | On-device scanning |
+| Espresso Accessibility Checks | Automated UI tests |
+| Lint checks | Static analysis |
+
+### Checklist
+
+- [ ] All interactive elements have descriptions
+- [ ] Touch targets are 48dp minimum
+- [ ] Color contrast meets requirements
+- [ ] Focus order is logical
+- [ ] Headings are properly marked
+- [ ] Custom actions have descriptive labels
+- [ ] Live regions announce important changes
+- [ ] Keyboard navigation works
+- [ ] Works with TalkBack enabled
+- [ ] Works with large text (200%)

package/skills/android-native-dev/references/adaptive-screens.md

@@ -0,0 +1,231 @@
+# Adaptive Screens Guidelines
+
+Requirements for large screens, tablets, foldables, and multi-window support.
+
+## Adaptive Quality Tiers
+
+Google defines three progressive quality tiers for adaptive apps:
+
+### Tier 3: Adaptive Ready (Basic)
+
+Minimum requirements for all apps:
+
+| Requirement | Description |
+|-------------|-------------|
+| Full screen | App fills display, no letterboxing |
+| Configuration changes | Handles rotation, folding, resizing |
+| Multi-window | Supports split-screen mode |
+| Basic input | Keyboard, mouse, trackpad support |
+
+### Tier 2: Adaptive Optimized (Better)
+
+Enhanced experience:
+
+| Requirement | Description |
+|-------------|-------------|
+| Layout optimization | Responsive layouts for all sizes |
+| Enhanced input | Full keyboard shortcuts, mouse hover states |
+| Continuity | Seamless state preservation |
+
+### Tier 1: Adaptive Differentiated (Best)
+
+Device-specific excellence:
+
+| Requirement | Description |
+|-------------|-------------|
+| Multitasking | Drag and drop, activity embedding |
+| Foldable postures | Table-top mode, book mode support |
+| Stylus | Full stylus input support |
+| Desktop | Windowed mode optimization |
+
+## Screen Size Classes
+
+### Width-Based Classes
+
+| Class | Width | Typical Devices |
+|-------|-------|-----------------|
+| Compact | < 600dp | Phone portrait |
+| Medium | 600-840dp | Tablet portrait, phone landscape |
+| Expanded | > 840dp | Tablet landscape, desktop |
+
+### Layout Strategies
+
+| Screen Class | Navigation | Content Layout |
+|--------------|------------|----------------|
+| Compact | Bottom nav | Single pane |
+| Medium | Nav rail | List-detail (optional) |
+| Expanded | Nav drawer/rail | List-detail, multi-pane |
+
+## Configuration Changes
+
+### Must Handle
+
+| Change | Trigger |
+|--------|---------|
+| Rotation | Device rotated |
+| Fold/Unfold | Foldable state change |
+| Window resize | Multi-window adjustment |
+| Split screen | Enter/exit split mode |
+| Keyboard | External keyboard attach/detach |
+
+### Configuration Handling
+
+| Approach | Description |
+|----------|-------------|
+| Let system handle | Default, activity recreated |
+| Handle manually | Declare configChanges, implement onConfigurationChanged |
+
+### State Preservation
+
+- Use ViewModel for UI state
+- Use SavedStateHandle for process death
+- Test with "Don't keep activities" enabled
+
+## Multi-Window Support
+
+### Requirements
+
+| Feature | Status |
+|---------|--------|
+| resizeableActivity | true (default API 24+) |
+| Minimum size | Support 220dp width |
+| State handling | Preserve across resize |
+
+### Best Practices
+
+- Don't assume full-screen ownership
+- Handle onConfigurationChanged gracefully
+- Test at minimum supported size
+- Support free-form windows (desktop mode)
+
+## Foldable Devices
+
+### Postures
+
+| Posture | Description | Use Case |
+|---------|-------------|----------|
+| Flat | Fully open | Normal tablet use |
+| Half-opened (tabletop) | Hinged at ~90° horizontal | Video calls, media |
+| Half-opened (book) | Hinged at ~90° vertical | Reading, productivity |
+| Folded | Closed | Compact phone mode |
+
+### Design Considerations
+
+- Avoid placing interactive elements on the fold
+- Consider separate content for each screen segment
+- Support continuity when fold state changes
+- Use WindowInfoTracker to detect fold state
+
+## External Input Devices
+
+### Keyboard Support
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Tab navigation | Focusable elements in order |
+| Enter/Space | Activates focused element |
+| Arrow keys | Navigate lists, grids |
+| Shortcuts | Common actions (Ctrl+S, etc.) |
+| Focus indicators | Visible focus states |
+
+### Mouse/Trackpad Support
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Hover states | Visual feedback on hover |
+| Right-click | Context menu support |
+| Scroll | Smooth scrolling |
+| Pointer cursor | Appropriate cursor types |
+
+### Stylus Support
+
+| Feature | Implementation |
+|---------|----------------|
+| Pressure sensitivity | Variable stroke width |
+| Palm rejection | Ignore palm touches |
+| Tilt detection | Shading effects |
+| Hover preview | Show cursor before touch |
+
+## Navigation Patterns
+
+### By Screen Width
+
+| Width | Primary Nav | Secondary Nav |
+|-------|-------------|---------------|
+| < 600dp | Bottom nav (3-5 items) | Hamburger menu |
+| 600-840dp | Navigation rail | Drawer on demand |
+| > 840dp | Permanent drawer or rail | Drawer or none |
+
+### Navigation Rail Specs
+
+| Property | Value |
+|----------|-------|
+| Width | 80dp |
+| Icon size | 24dp |
+| Touch target | 56dp |
+| Items | 3-7 destinations |
+| FAB | Optional, at top |
+
+### Permanent Navigation Drawer
+
+| Property | Value |
+|----------|-------|
+| Width | 256-360dp |
+| Position | Left edge (LTR) |
+| Behavior | Always visible |
+| Content | Full labels, icons |
+
+## Responsive Layouts
+
+### Breakpoints
+
+| Class | Width Range |
+|-------|-------------|
+| COMPACT | < 600dp |
+| MEDIUM | 600-840dp |
+| EXPANDED | > 840dp |
+
+Use WindowSizeClass to determine current breakpoint and adapt layout accordingly.
+
+## Content Considerations
+
+### Text Readability
+
+- Line length: 45-75 characters max
+- Use multiple columns on wide screens
+- Maintain hierarchy with consistent spacing
+
+### Media
+
+- Support multiple aspect ratios
+- Provide high-resolution assets
+- Consider picture-in-picture for video
+
+### Touch vs. Precise Input
+
+- Large screens often use mouse/keyboard
+- Don't assume touch-only interaction
+- Provide hover states and tooltips
+
+## Testing
+
+### Device Matrix
+
+| Device Type | Test Priority |
+|-------------|---------------|
+| Phone (portrait) | Required |
+| Phone (landscape) | Required |
+| Tablet (both orientations) | Required |
+| Foldable (all postures) | High |
+| Desktop/Chromebook | Medium |
+
+### Test Cases
+
+- [ ] App fills screen in all configurations
+- [ ] No letterboxing or black bars
+- [ ] State preserved across configuration changes
+- [ ] Multi-window works at minimum size
+- [ ] Keyboard navigation functional
+- [ ] Mouse hover states present
+- [ ] Foldable postures handled (if applicable)
+- [ ] Navigation adapts to screen width