Skip to content

Commit da8fd7d

Browse files
mohdaquibmohdaquib
authored
Merge pull request #16 from mohdaquib/update-readme
Update README with Quick Start and configuration guides
2 parents ae7b57e + bb946b1 commit da8fd7d

1 file changed

Lines changed: 95 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 95 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -8,92 +8,113 @@ Runtime accessibility scanner that overlays issues directly on your Compose UI
88

99
![Annotated GIF showing the Compose A11y Scanner issue summary, view highlights, and issue detail sheet in the sample app](docs/overlay-demo.gif)
1010

11-
## Architecture
11+
## Quick start
1212

13-
```mermaid
14-
flowchart LR
15-
SemanticsTree["SemanticsTree"] --> Extractor[":scanner-ui<br/>A11yNodeExtractor"]
16-
Extractor --> ColorExtractor["ColorExtractor"]
17-
ColorExtractor --> Nodes["A11yNode list"]
18-
Extractor --> Nodes
19-
Nodes --> Core[":scanner-core<br/>A11yScanEngine"]
20-
Rules[":scanner-rules<br/>Built-in A11yRule implementations"] --> Core
21-
Core --> Result["ScanResult / ScannerState"]
22-
Result --> Overlay[":scanner-ui<br/>Overlay, summary, report sheet"]
23-
```
24-
25-
`:scanner-core` owns the scan engine, models, result state, and `A11yRule` contract. `:scanner-rules` contains the built-in rules. `:scanner-ui` reads the Compose semantics tree, samples colors through `ColorExtractor`, runs scans, and draws issue overlays on top of the host UI.
26-
27-
## Installation
13+
Add JitPack and the debug-only scanner dependency:
2814

2915
```kotlin
30-
repositories { maven("https://jitpack.io") }
31-
dependencies { debugImplementation("com.github.mohdaquib.ComposeA11yScanner:scanner-ui:v1.0.0") }
16+
// settings.gradle.kts
17+
dependencyResolutionManagement {
18+
repositories {
19+
google()
20+
mavenCentral()
21+
maven("https://jitpack.io")
22+
}
23+
}
24+
25+
// app/build.gradle.kts
26+
dependencies {
27+
debugImplementation("com.github.mohdaquib.ComposeA11yScanner:scanner-ui:v1.0.0")
28+
}
3229
```
3330

34-
Use a debug-only dependency because the scanner is intended for development builds. `:scanner-ui` brings `:scanner-core` and `:scanner-rules` transitively.
31+
That is all the integration required. AndroidX Startup automatically attaches the overlay and runs an initial scan for each `ComponentActivity` in a debuggable app. Release builds do not package the scanner when it is added with `debugImplementation`.
32+
33+
To request another scan, call the API from a debug source set (for example, `src/debug/java/.../ScannerActions.kt`):
3534

36-
## Integration
35+
```kotlin
36+
import com.composea11yscanner.ComposeA11yScanner
3737

38-
### A11yScannerScaffold
38+
ComposeA11yScanner.triggerScan()
39+
```
3940

40-
Wrap the screen you want to inspect with `A11yScannerScaffold`. Provide an `A11yScannerController` that can extract nodes from your current Compose semantics tree.
41+
For shake-to-scan, add one call to a debug-only composable that is active while the screen is visible:
4142

4243
```kotlin
43-
@Composable
44-
fun DebugScannerScreen(
45-
scannerController: A11yScannerController,
46-
content: @Composable () -> Unit,
47-
) {
48-
val config = remember {
49-
ScannerConfig(
50-
enabledRules = ScannerRules.allRuleIds().toSet(),
51-
autoScan = false,
52-
)
53-
}
44+
import com.composea11yscanner.triggers.scanOnShake
5445

55-
A11yScannerScaffold(
56-
scannerController = scannerController,
57-
config = config,
58-
modifier = Modifier.fillMaxSize(),
59-
) {
60-
content()
61-
}
46+
@Composable
47+
fun App() {
48+
scanOnShake()
49+
AppContent()
6250
}
6351
```
6452

65-
The scaffold renders your content first, then draws issue highlight boxes, the scan summary bar, and the issue detail sheet above it.
53+
The scanner enables all built-in rules by default. The overlay is removed automatically when its activity is destroyed. Keep direct scanner imports in `src/debug`; a `debugImplementation` dependency is intentionally unavailable while compiling release sources.
6654

67-
### Shake To Scan
55+
## Configuration
6856

69-
Call `scanOnShake()` from a composable that is active while the scanned screen is visible.
57+
Optional manifest metadata configures the auto-installed scanner:
7058

71-
```kotlin
72-
scanOnShake(
73-
enabled = true,
74-
onScanRequested = {
75-
scannerController.startScan()
76-
},
77-
)
59+
```xml
60+
<application>
61+
<meta-data
62+
android:name="a11y_scanner_min_contrast"
63+
android:value="4.5" />
64+
<meta-data
65+
android:name="a11y_scanner_auto_scan"
66+
android:value="false" />
67+
</application>
7868
```
7969

80-
### Manual Trigger
70+
### Manual installation
71+
72+
Use manual installation only when you need a programmatic `ScannerConfig`. First disable the automatic initializer in the app manifest:
73+
74+
```xml
75+
<manifest xmlns:tools="http://schemas.android.com/tools">
76+
<application>
77+
<provider
78+
android:name="androidx.startup.InitializationProvider"
79+
android:authorities="${applicationId}.androidx-startup"
80+
tools:node="merge">
81+
<meta-data
82+
android:name="com.composea11yscanner.A11yScannerInitializer"
83+
tools:node="remove" />
84+
</provider>
85+
</application>
86+
</manifest>
87+
```
8188

82-
Wire a debug menu item, toolbar button, or test-only action directly to the controller.
89+
Then install after `setContent`:
8390

8491
```kotlin
85-
IconButton(onClick = { scannerController.startScan() }) {
86-
Icon(
87-
imageVector = Icons.Default.Search,
88-
contentDescription = "Scan accessibility",
89-
)
90-
}
92+
setContent { App() }
93+
94+
ComposeA11yScanner.install(
95+
activity = this,
96+
config = ScannerConfig(
97+
enabledRules = ScannerRules.allRuleIds().toSet(),
98+
minContrastRatio = 4.5f,
99+
autoScan = false,
100+
),
101+
)
91102
```
92103

93-
If you use the top-level activity overlay API, call `ComposeA11yScanner.triggerScan()` instead.
104+
Do not combine automatic and manual installation. Repeated installation on the same activity is ignored, but keeping one ownership path makes configuration predictable.
105+
106+
### Embedded scaffold
107+
108+
`A11yScannerScaffold` is the advanced API for apps that want the scanner UI inside their own Compose hierarchy or need a custom node provider. It requires an `A11yScannerController`; most integrations should use the automatic activity overlay above.
94109

95110
```kotlin
96-
ComposeA11yScanner.triggerScan()
111+
A11yScannerScaffold(
112+
scannerController = scannerController,
113+
config = config,
114+
modifier = Modifier.fillMaxSize(),
115+
) {
116+
AppContent()
117+
}
97118
```
98119

99120
## Built-In Rules
@@ -149,3 +170,17 @@ val scannerController = A11yScannerController(
149170
```
150171

151172
Custom rule IDs are automatically enabled by `A11yScannerController.withRules(...)` before each scan.
173+
174+
## Architecture
175+
176+
```mermaid
177+
flowchart LR
178+
SemanticsTree["SemanticsTree"] --> Extractor[":scanner-ui<br/>A11yNodeExtractor"]
179+
Extractor --> Nodes["A11yNode list"]
180+
Nodes --> Core[":scanner-core<br/>A11yScanEngine"]
181+
Rules[":scanner-rules<br/>Built-in and custom rules"] --> Core
182+
Core --> Result["ScanResult / ScannerState"]
183+
Result --> Overlay[":scanner-ui<br/>Overlay and issue details"]
184+
```
185+
186+
`:scanner-core` owns the scan engine and public models. `:scanner-rules` contains built-in rules. `:scanner-ui` handles Android/Compose integration, node extraction, triggers, and the overlay.

0 commit comments

Comments
 (0)