diff --git a/README.md b/README.md
index a0853c5..e8d0df0 100644
--- a/README.md
+++ b/README.md
@@ -1,77 +1,103 @@
 <div align="center">
-    <img src="https://github.com/playwright-php/.github/raw/main/profile/playwright-php.png" alt="Playwright PHP" />
+<a href="https://github.com/playwright-php"><img src="https://github.com/playwright-php/.github/raw/main/profile/playwright-php.png" alt="Playwright PHP" /></a>
 
-&nbsp; ![PHP Version](https://img.shields.io/badge/PHP-8.2-05971B?labelColor=09161E&color=1D8D23&logoColor=FFFFFF)
+&nbsp; ![PHP Version](https://img.shields.io/badge/PHP-8.2+-05971B?labelColor=09161E&color=1D8D23&logoColor=FFFFFF)
 &nbsp; ![CI](https://img.shields.io/github/actions/workflow/status/playwright-php/accessibility/CI.yml?branch=main&label=Tests&color=1D8D23&labelColor=09161E&logoColor=FFFFFF)
-&nbsp; ![Release](https://img.shields.io/github/v/release/playwright-php/accessibility?label=Stable&labelColor=09161E&color=1D8D23&logoColor=FFFFFF)
+&nbsp; [![Release](https://img.shields.io/github/v/release/playwright-php/accessibility?label=Stable&labelColor=09161E&color=1D8D23&logoColor=FFFFFF)](https://packagist.org/packages/playwright-php/accessibility)
 &nbsp; ![License](https://img.shields.io/github/license/playwright-php/accessibility?label=License&labelColor=09161E&color=1D8D23&logoColor=FFFFFF)
 
 </div>
 
-# Playwright PHP - Accessibility
+# Playwright PHP Accessibility
 
-Perform real **accessibility audits** on web pages using [Playwright PHP](https://github.com/playwright-php/playwright) and [axe-core](https://github.com/dequelabs/axe-core),  
-checking for **WCAG**, **ARIA**, color contrast, and best-practice compliance.
+Run [axe-core](https://github.com/dequelabs/axe-core) checks in pages controlled
+by [Playwright PHP](https://github.com/playwright-php/playwright), inspect the
+results as PHP objects, or fail PHPUnit tests when violations are found.
 
 ## Installation
 
-This package relies on **Playwright PHP** - to install it, follow the instructions in [Playwright PHP’s installation guide](https://github.com/playwright-php/playwright#installation).
+The package requires PHP 8.2 or later and Playwright PHP 1.x.
 
 ```bash
 composer require --dev playwright-php/accessibility
-````
+vendor/bin/playwright-install --browsers
+```
 
-## Usage
+## Quick Start
 
-### Basic Analysis
+Use the PHPUnit trait with Playwright PHP's test case:
 
 ```php
-use Playwright\Accessibility\AxeBuilder;
-
-$builder = new AxeBuilder($page);
-$results = $builder->analyze();
+<?php
 
-if ($results->hasViolations()) {
-    foreach ($results->violations as $violation) {
-        echo "{$violation->id}: {$violation->help}\n";
-    }
-}
-```
-
-### PHPUnit Integration
-
-```php
 use Playwright\Accessibility\AssertsAccessibility;
+use Playwright\Testing\PlaywrightTestCase;
 
-class MyTest extends TestCase
+final class AccessibilityTest extends PlaywrightTestCase
 {
     use AssertsAccessibility;
 
-    public function testPageIsAccessible(): void
+    public function test_homepage_has_no_detected_violations(): void
     {
-        $page->goto('https://example.com');
-        $this->assertIsAccessible($page);
+        $this->page->goto('https://example.com');
+
+        $this->assertIsAccessible($this->page);
     }
 }
 ```
 
-### Advanced Configuration
+## Configuring an Audit
+
+`AxeBuilder` can limit the scan to a region, select standards, exclude elements,
+or disable rules:
 
 ```php
-// Scope to specific regions
-$builder->within('#main-content')->analyze();
+use Playwright\Accessibility\AxeBuilder;
+use Playwright\Accessibility\RuleId;
+use Playwright\Accessibility\WcagTag;
+
+$results = (new AxeBuilder($page))
+    ->within('#main-content')
+    ->exclude('.third-party-widget')
+    ->withTags([WcagTag::WCAG_2_1_AA])
+    ->withoutRules([RuleId::COLOR_CONTRAST])
+    ->analyze();
+
+foreach ($results->violations as $violation) {
+    echo $violation->id.': '.$violation->help.PHP_EOL;
+}
+```
+
+`assertIsAccessible()` accepts a page, a configured builder, or an existing
+result object.
+
+## Limits
 
-// Filter by WCAG level
-$builder->withTags([WcagTag::WCAG_2_1_AA])->analyze();
+Automated axe checks detect only part of the accessibility problems a user may
+encounter. A passing result does not establish WCAG conformance and does not
+replace keyboard, screen-reader, zoom, motion, or usability testing.
 
-// Disable specific rules
-$builder->withoutRules([RuleId::COLOR_CONTRAST])->analyze();
+The audit covers the page state at the time it runs. Navigate, authenticate,
+open dialogs, and trigger dynamic states before making the assertion.
 
-// Exclude elements
-$builder->exclude('.advertisement')->analyze();
+## Documentation
+
+- [Playwright PHP Getting Started](https://github.com/playwright-php/playwright/blob/main/docs/guide/getting-started.md)
+- [axe-core rule descriptions](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md)
+
+## Contributing
+
+Install dependencies and browsers, then run code style, static analysis, and
+the test suite:
+
+```bash
+composer install
+vendor/bin/playwright-install --browsers
+vendor/bin/php-cs-fixer fix --dry-run --diff
+vendor/bin/phpstan analyse --memory-limit=-1
+vendor/bin/phpunit
 ```
 
 ## License
 
-This package is released by the [Playwright PHP](https://playwright-php.dev) project
-under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+This package is released under the [MIT License](LICENSE).