android-sdd 1.0.0

package/skills/UI System/Material 3/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: material3
+description: >
+  Material Design 3 theming, components, and color system for Android/Compose.
+  Load this skill when setting up M3 theme, using M3 components, defining
+  custom color schemes, typography, or shapes, or supporting dynamic color.
+---
+
+# Material 3
+
+## Overview
+Material Design 3 (M3) is Google's latest design system, built into Jetpack Compose via `androidx.compose.material3`. It provides a comprehensive color system, typography scale, shape system, and a full set of UI components. M3 supports dynamic color (Android 12+) and dark/light themes natively.
+
+---
+
+## Core Principles
+
+- Always use **M3 semantic color tokens** — never hardcode colors
+- Define **one MaterialTheme** at the root — never nest multiple themes
+- Use M3 components before building custom — they handle accessibility and state
+- Support **dark mode** from day one — design the color scheme for both
+- Use **dynamic color** where available (API 31+) with a fallback palette
+
+---
+
+## Theme Setup
+
+```kotlin
+// ✅ Theme definition
+@Composable
+fun AppTheme(
+    darkTheme: Boolean = isSystemInDarkTheme(),
+    dynamicColor: Boolean = true,
+    content: @Composable () -> Unit
+) {
+    val colorScheme = when {
+        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
+            val context = LocalContext.current
+            if (darkTheme) dynamicDarkColorScheme(context)
+            else dynamicLightColorScheme(context)
+        }
+        darkTheme -> DarkColorScheme
+        else      -> LightColorScheme
+    }
+
+    MaterialTheme(
+        colorScheme = colorScheme,
+        typography = AppTypography,
+        shapes = AppShapes,
+        content = content
+    )
+}
+
+// ✅ Apply at root
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            AppTheme {
+                AppNavHost()
+            }
+        }
+    }
+}
+```
+
+---
+
+## Color Scheme
+
+```kotlin
+// ✅ Define light and dark color schemes
+private val LightColorScheme = lightColorScheme(
+    primary = Purple40,
+    onPrimary = Color.White,
+    primaryContainer = Purple90,
+    onPrimaryContainer = Purple10,
+    secondary = PurpleGrey40,
+    onSecondary = Color.White,
+    secondaryContainer = PurpleGrey90,
+    onSecondaryContainer = PurpleGrey10,
+    tertiary = Pink40,
+    background = Color(0xFFFFFBFE),
+    surface = Color(0xFFFFFBFE),
+    onBackground = Color(0xFF1C1B1F),
+    onSurface = Color(0xFF1C1B1F),
+    error = Color(0xFFB3261E)
+)
+
+private val DarkColorScheme = darkColorScheme(
+    primary = Purple80,
+    onPrimary = Purple20,
+    primaryContainer = Purple30,
+    onPrimaryContainer = Purple90,
+    // ...
+)
+```
+
+---
+
+## Color Token Usage
+
+```kotlin
+// ✅ Always use MaterialTheme.colorScheme tokens
+@Composable
+fun PrimaryButton(text: String, onClick: () -> Unit) {
+    Button(
+        onClick = onClick,
+        colors = ButtonDefaults.buttonColors(
+            containerColor = MaterialTheme.colorScheme.primary,
+            contentColor = MaterialTheme.colorScheme.onPrimary
+        )
+    ) {
+        Text(text)
+    }
+}
+
+// ✅ Surface with correct tonal elevation
+Surface(
+    color = MaterialTheme.colorScheme.surface,
+    tonalElevation = 2.dp
+) { ... }
+
+// ❌ Never hardcode colors
+Text(text = "Hello", color = Color(0xFF6200EE))
+```
+
+### M3 Color Roles Reference
+
+| Role | On Role | Use For |
+|------|---------|---------|
+| `primary` | `onPrimary` | Main action, FAB |
+| `primaryContainer` | `onPrimaryContainer` | Selected state, chips |
+| `secondary` | `onSecondary` | Supporting actions |
+| `tertiary` | `onTertiary` | Contrasting accents |
+| `surface` | `onSurface` | Cards, sheets, dialogs |
+| `surfaceVariant` | `onSurfaceVariant` | Input fields, chips |
+| `background` | `onBackground` | Screen background |
+| `error` | `onError` | Error states |
+
+---
+
+## Typography
+
+```kotlin
+// ✅ Define custom typography
+val AppTypography = Typography(
+    displayLarge = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 57.sp,
+        lineHeight = 64.sp
+    ),
+    titleLarge = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 22.sp,
+        lineHeight = 28.sp
+    ),
+    bodyLarge = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Normal,
+        fontSize = 16.sp,
+        lineHeight = 24.sp
+    ),
+    labelSmall = TextStyle(
+        fontFamily = FontFamily.Default,
+        fontWeight = FontWeight.Medium,
+        fontSize = 11.sp,
+        lineHeight = 16.sp
+    )
+)
+
+// ✅ Use typography tokens
+Text(text = "Title", style = MaterialTheme.typography.titleLarge)
+Text(text = "Body text", style = MaterialTheme.typography.bodyMedium)
+Text(text = "Label", style = MaterialTheme.typography.labelSmall)
+```
+
+---
+
+## Shapes
+
+```kotlin
+// ✅ Define shape scale
+val AppShapes = Shapes(
+    extraSmall = RoundedCornerShape(4.dp),
+    small       = RoundedCornerShape(8.dp),
+    medium      = RoundedCornerShape(12.dp),
+    large       = RoundedCornerShape(16.dp),
+    extraLarge  = RoundedCornerShape(28.dp)
+)
+
+// ✅ Use shape tokens
+Card(shape = MaterialTheme.shapes.medium) { ... }
+Button(shape = MaterialTheme.shapes.extraLarge) { ... }  // pill shape
+```
+
+---
+
+## Key M3 Components
+
+```kotlin
+// ✅ Buttons
+Button(onClick = {}) { Text("Filled") }
+OutlinedButton(onClick = {}) { Text("Outlined") }
+TextButton(onClick = {}) { Text("Text") }
+FilledTonalButton(onClick = {}) { Text("Tonal") }
+ElevatedButton(onClick = {}) { Text("Elevated") }
+
+// ✅ FAB
+FloatingActionButton(onClick = {}) {
+    Icon(Icons.Default.Add, contentDescription = "Add")
+}
+ExtendedFloatingActionButton(
+    text = { Text("New item") },
+    icon = { Icon(Icons.Default.Add, contentDescription = null) },
+    onClick = {}
+)
+
+// ✅ Cards
+Card(modifier = Modifier.fillMaxWidth()) { ... }
+ElevatedCard { ... }
+OutlinedCard { ... }
+
+// ✅ Top App Bar
+TopAppBar(
+    title = { Text("Screen Title") },
+    navigationIcon = {
+        IconButton(onClick = onBack) {
+            Icon(Icons.Default.ArrowBack, contentDescription = "Back")
+        }
+    },
+    actions = {
+        IconButton(onClick = {}) {
+            Icon(Icons.Default.MoreVert, contentDescription = "More")
+        }
+    }
+)
+
+// ✅ Navigation Bar
+NavigationBar {
+    items.forEach { item ->
+        NavigationBarItem(
+            icon = { Icon(item.icon, contentDescription = null) },
+            label = { Text(item.label) },
+            selected = currentRoute == item.route,
+            onClick = { onNavigate(item.route) }
+        )
+    }
+}
+
+// ✅ Snackbar
+val snackbarHostState = remember { SnackbarHostState() }
+Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { padding ->
+    // content
+}
+LaunchedEffect(Unit) {
+    snackbarHostState.showSnackbar("Item deleted", actionLabel = "Undo")
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Hardcoding colors instead of using `MaterialTheme.colorScheme` tokens
+- Nesting multiple `MaterialTheme` composables — causes inconsistent theming
+- Using `androidx.compose.material` (M2) components mixed with M3 — conflicts
+- Not providing a non-dynamic fallback color scheme for API < 31
+- Using `Color.White`/`Color.Black` directly — breaks dark mode
+
+---
+
+## Related Skills
+- `compose` — Compose fundamentals
+- `design-system` — extending M3 with custom design tokens
+- `resources` — color and style resources for XML interop
+- `rtl` — RTL support in M3 components

package/skills/UI System/RTL/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: rtl
+description: >
+  Right-to-Left (RTL) layout support in Android and Jetpack Compose.
+  Load this skill when building layouts that must support RTL languages
+  (Arabic, Persian, Hebrew), mirroring icons and directions, handling
+  bidirectional text, or ensuring correct layout mirroring behavior.
+---
+
+# RTL
+
+## Overview
+RTL (Right-to-Left) support ensures layouts mirror correctly for languages like Persian, Arabic, and Hebrew. In Compose, this is handled via `LayoutDirection` and logical layout modifiers. Correct RTL support requires using directional-agnostic APIs throughout — never hardcode left/right values.
+
+---
+
+## Core Principles
+
+- Always use **logical layout modifiers** — never physical (`start/end`, not `left/right`)
+- Set `android:supportsRtl="true"` in the manifest
+- Use `Arrangement.Start`/`Alignment.Start` — not `Left`/`Right`
+- Mirror directional icons explicitly using `autoMirrored = true`
+- Test in both LTR and RTL using the developer options toggle
+
+---
+
+## Manifest Setup
+
+```xml
+<!-- ✅ Required in AndroidManifest.xml -->
+<application
+    android:supportsRtl="true"
+    ... >
+```
+
+---
+
+## Compose Layout Direction
+
+```kotlin
+// ✅ Read current layout direction
+@Composable
+fun DirectionAwareIcon() {
+    val layoutDirection = LocalLayoutDirection.current
+    val isRtl = layoutDirection == LayoutDirection.Rtl
+}
+
+// ✅ Force RTL for a subtree
+CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Rtl) {
+    MyLayout()
+}
+
+// ✅ Force LTR for specific content (e.g. phone numbers, codes)
+CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Ltr) {
+    Text(text = "+98 912 000 0000")
+}
+```
+
+---
+
+## Logical Modifiers
+
+```kotlin
+// ✅ Use padding start/end — not left/right
+Modifier.padding(start = 16.dp, end = 8.dp)
+
+// ✅ Use absolutePadding only when truly position-fixed
+Modifier.absolutePadding(left = 0.dp)  // rare — only for non-mirrored content
+
+// ✅ Row arrangement
+Row(horizontalArrangement = Arrangement.Start) { ... }  // ✅
+Row(horizontalArrangement = Arrangement.End) { ... }    // ✅
+
+// ❌ Never use physical directions in layout
+Modifier.padding(left = 16.dp)   // breaks RTL
+Modifier.padding(right = 8.dp)   // breaks RTL
+```
+
+---
+
+## Icon Mirroring
+
+```kotlin
+// ✅ Use autoMirrored for directional icons (arrows, back, forward)
+Icon(
+    painter = painterResource(R.drawable.ic_arrow_forward),
+    contentDescription = null,
+    modifier = Modifier.scale(
+        scaleX = if (LocalLayoutDirection.current == LayoutDirection.Rtl) -1f else 1f,
+        scaleY = 1f
+    )
+)
+
+// ✅ Better — use autoMirrored in vector drawable XML
+// In ic_arrow_forward.xml:
+// android:autoMirrored="true"
+
+// ✅ Icons that should NOT be mirrored
+Icon(Icons.Default.PlayArrow, contentDescription = null)   // media control — don't mirror
+Icon(Icons.Default.Search, contentDescription = null)      // symmetric — don't mirror
+```
+
+---
+
+## Bidirectional Text
+
+```kotlin
+// ✅ Let the system handle bidi text automatically
+Text(text = "Hello سلام")  // system resolves direction per paragraph
+
+// ✅ Force text direction when needed
+Text(
+    text = userInput,
+    textDirection = TextDirection.Content  // auto-detect per content
+)
+
+// ✅ Force LTR for codes, emails, URLs
+Text(
+    text = "user@example.com",
+    textDirection = TextDirection.Ltr
+)
+
+// ✅ TextField with explicit direction for mixed input
+TextField(
+    value = value,
+    onValueChange = onValueChange,
+    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
+    modifier = Modifier.semantics { textDirection = TextDirection.Content }
+)
+```
+
+---
+
+## Alignment Helpers
+
+```kotlin
+// ✅ Alignment.Start mirrors automatically
+Box(contentAlignment = Alignment.TopStart) { ... }  // top-left in LTR, top-right in RTL
+Box(contentAlignment = Alignment.TopEnd) { ... }    // top-right in LTR, top-left in RTL
+
+// ✅ Column horizontal alignment
+Column(horizontalAlignment = Alignment.Start) { ... }
+Column(horizontalAlignment = Alignment.End) { ... }
+```
+
+---
+
+## Previewing RTL
+
+```kotlin
+// ✅ Always add an RTL preview alongside LTR
+@Preview(name = "LTR", locale = "en")
+@Preview(name = "RTL", locale = "fa")
+@Composable
+fun MyComponentPreview() {
+    AppTheme {
+        MyComponent()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `Modifier.padding(left/right)` — breaks RTL mirroring
+- Using `Arrangement.AbsoluteLeft` or `AbsoluteRight` in normal layouts
+- Hardcoding `LayoutDirection.Ltr` at the root — prevents RTL support
+- Not setting `android:supportsRtl="true"` in manifest
+- Mirroring media/playback icons (play, pause, record) — they are universal
+- Using `Column { Modifier.align(Alignment.AbsoluteLeft) }` — physical alignment
+
+---
+
+## Related Skills
+- `compose` — Compose layout fundamentals
+- `material3` — M3 component RTL behavior
+- `resources` — string direction and locale resources
+- `design-system` — design tokens with directional awareness

package/src/index.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+const inquirer = require("inquirer");
+
+/**
+ * GitHub Remote Skills Repo (ZIP)
+ */
+const REMOTE_SKILLS_ZIP =
+    "https://github.com/mozhdehnoury-byte/android-agent-skills/archive/refs/heads/main.zip";
+
+/**
+ * ورود برنامه
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+
+    if (command === "init") {
+        await initRemote();
+        return;
+    }
+
+    if (command === "install") {
+        const selectedSkills = await wizard(skillsPath());
+        await install(selectedSkills, skillsPath());
+        return;
+    }
+
+    await wizard(skillsPath());
+}
+
+/**
+ * مسیر skills (local fallback)
+ */
+function skillsPath() {
+    return path.join(__dirname, "../skills");
+}
+
+/**
+ * wizard: انتخاب skill ها
+ */
+async function wizard(basePath: string): Promise<Record<string, string[]>> {
+
+    const selectedSkills: Record<string, string[]> = {};
+
+    const parentFolders = fs.readdirSync(basePath);
+
+    for (const parent of parentFolders) {
+
+        const children = fs.readdirSync(
+            path.join(basePath, parent)
+        );
+
+        const answer = await inquirer.prompt([
+            {
+                type: "checkbox",
+                name: "selected",
+                message: `Select ${parent} skills`,
+                choices: children
+            }
+        ]);
+
+        selectedSkills[parent] = answer.selected;
+    }
+
+    console.log("Selected Skills:");
+    console.log(selectedSkills);
+
+    return selectedSkills;
+}
+
+/**
+ * install: ساخت .agent + کپی skill ها + ساخت config
+ */
+async function install(
+    selectedSkills: Record<string, string[]>,
+    basePath: string
+) {
+
+    console.log("🚀 Installing Android SDD skills...");
+
+    const agentRoot = path.join(process.cwd(), ".agent");
+    fs.mkdirSync(agentRoot, { recursive: true });
+
+    for (const [parent, skills] of Object.entries(selectedSkills)) {
+
+        for (const skill of skills) {
+
+            const source = path.join(
+                basePath,
+                parent,
+                skill,
+                "SKILL.md"
+            );
+
+            const targetDir = path.join(
+                agentRoot,
+                parent,
+                skill
+            );
+
+            fs.mkdirSync(targetDir, { recursive: true });
+
+            fs.copyFileSync(
+                source,
+                path.join(targetDir, "SKILL.md")
+            );
+
+            console.log(`Installed: ${parent}/${skill}`);
+        }
+    }
+
+    const config = {
+        version: "1.0.0",
+        installedAt: new Date().toISOString(),
+        skills: selectedSkills
+    };
+
+    fs.writeFileSync(
+        path.join(agentRoot, "config.json"),
+        JSON.stringify(config, null, 2)
+    );
+
+    console.log("\n🎉 Done! Skills installed in .agent/");
+}
+
+/**
+ * Remote init (GitHub ZIP → auto-detect folder → wizard)
+ */
+async function initRemote() {
+
+    console.log("🌍 Downloading skills from GitHub...");
+
+    const fetch = (await import("node-fetch")).default;
+    const unzipper = await import("unzipper");
+
+    const res = await fetch(REMOTE_SKILLS_ZIP);
+
+    const buffer = Buffer.from(await res.arrayBuffer());
+
+    const zipPath = path.join(process.cwd(), "skills.zip");
+
+    fs.writeFileSync(zipPath, buffer);
+
+    console.log("📦 Extracting skills...");
+
+    await fs.createReadStream(zipPath)
+        .pipe(unzipper.Extract({ path: process.cwd() }))
+        .promise();
+
+    /**
+     * 🔥 AUTO DETECT extracted skills path
+     * چون GitHub همیشه یک wrapper folder می‌سازه
+     */
+    const extractedBase = process.cwd();
+
+    const possiblePaths = [
+ path.join(extractedBase, "android-agent-skills-main"),
+    ];
+
+    let extractedPath: string | null = null;
+
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            extractedPath = p;
+            break;
+        }
+    }
+
+    if (!extractedPath) {
+        throw new Error("❌ Could not find skills folder after extraction");
+    }
+
+    console.log("🧠 Running wizard...");
+
+    const selectedSkills = await wizard(extractedPath);
+    await install(selectedSkills, extractedPath);
+}
+
+main();

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+
+    "rootDir": "src",
+    "outDir": "dist",
+
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+
+    "types": ["node"],
+
+    "strict": false,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}