docs(sushi): polish package documentation

README.md

@@ -1,6 +1,12 @@
-# Sushi in Angular
+# Sushi Kit for Angular
 
-Sushi is the Angular component library in Ramen Suite, published as `@sushi-kit/angular`. It provides accessible, themeable components with typed signal APIs. Application state stays in Angular; interactions use native HTML semantics, Angular Aria, and the CDK.
+[![License: MIT](https://img.shields.io/badge/license-MIT-7a0712?labelColor=282a36)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/%40sushi-kit%2Fangular?labelColor=282a36&color=7a0712)](https://www.npmjs.com/package/@sushi-kit/angular)
+[![npm downloads](https://img.shields.io/npm/dm/%40sushi-kit%2Fangular?labelColor=282a36&color=7a0712)](https://www.npmjs.com/package/@sushi-kit/angular)
+[![CI](https://img.shields.io/github/actions/workflow/status/ramen-suite/sushi-angular/ci.yml?branch=main&label=CI&labelColor=282a36)](https://github.com/ramen-suite/sushi-angular/actions/workflows/ci.yml?query=branch%3Amain)
+[![Playground](https://img.shields.io/badge/docs-Playground-996400?labelColor=282a36)](https://ramen-suite.github.io/sushi-angular/)
+
+Sushi Kit is an open-source component library for Angular applications, published as `@sushi-kit/angular`. It provides accessible, themeable components with typed signal APIs. Interactions build on native HTML semantics, Angular Aria, and the CDK.
 
 ## Compatibility
 
@@ -14,10 +20,6 @@ Sushi ships the compiled CSS required by its components.
 
 ## Install
 
-The [Getting started guide](docs/getting-started.md) contains the same setup as the Playground and is the maintained setup reference.
-
-See [Styling and themes](docs/styling-and-themes.md) for theme tokens, component tokens, recommended Tailwind usage, and custom themes.
-
 ```bash
 npm install @sushi-kit/angular
 ```
@@ -30,6 +32,8 @@ Import the public stylesheet from the application's global `src/styles.css`:
 
 No Sushi-specific PostCSS or Tailwind configuration is required.
 
+Continue with [Getting started](docs/getting-started.md) for the complete setup. See [Styling and themes](docs/styling-and-themes.md) for component tokens, recommended Tailwind usage, and custom themes. All built-in values are listed in the [theme token reference](docs/theme-tokens.md).
+
 ## Use a component
 
 Every public declaration is standalone. Import only what the consuming component uses:

docs/getting-started.md

@@ -6,17 +6,17 @@
 
 The package peer dependencies are the source of truth for the supported Angular range.
 
-# Getting started
+## Getting started
 
-## 1. Install
+### 1. Install
 
 ```bash
 npm install @sushi-kit/angular
 ```
 
 npm also installs the required peer dependencies, including [Lucide Angular](https://lucide.dev) and [PhotoSwipe](https://photoswipe.com/). Lucide uses the ISC license; PhotoSwipe uses MIT.
 
-## 2. Load the styles
+### 2. Load the styles
 
 Import the compiled stylesheet once in `src/styles.css`:
 
@@ -44,7 +44,7 @@ Alternatively, add it before the application stylesheet in `angular.json`:
 
 Choose one method. The consumer does not need a Sushi-specific PostCSS configuration.
 
-## 3. Use a component
+### 3. Use a component
 
 Import each standalone declaration used by a component:
 

playground/src/styles.css

@@ -227,10 +227,6 @@ pg-example-code {
   margin-top: 0;
 }
 
-.pg-markdown__prose > h1:not(:first-child) {
-  margin-top: 3rem;
-}
-
 .pg-markdown h2 {
   margin-top: 2.75rem;
   font-size: 1.45rem;

sushi/README.md

@@ -1,6 +1,14 @@
-# Sushi in Angular
+# Sushi Kit for Angular
 
-Accessible, themeable Angular components for Ramen Suite, published as `@sushi-kit/angular`.
+[![License: MIT](https://img.shields.io/badge/license-MIT-7a0712?labelColor=282a36)](https://github.com/ramen-suite/sushi-angular/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/%40sushi-kit%2Fangular?labelColor=282a36&color=7a0712)](https://www.npmjs.com/package/@sushi-kit/angular)
+[![npm downloads](https://img.shields.io/npm/dm/%40sushi-kit%2Fangular?labelColor=282a36&color=7a0712)](https://www.npmjs.com/package/@sushi-kit/angular)
+[![CI](https://img.shields.io/github/actions/workflow/status/ramen-suite/sushi-angular/ci.yml?branch=main&label=CI&labelColor=282a36)](https://github.com/ramen-suite/sushi-angular/actions/workflows/ci.yml?query=branch%3Amain)
+[![Playground](https://img.shields.io/badge/docs-Playground-996400?labelColor=282a36)](https://ramen-suite.github.io/sushi-angular/)
+
+Sushi Kit is an open-source UI component library for Angular applications, published as `@sushi-kit/angular`. It provides standalone components for forms, navigation, data display, and overlays, with typed signal APIs and customizable light and dark themes.
+
+Interactions build on native HTML semantics, Angular Aria, and the CDK. Component styles are included; customize their appearance with CSS tokens to match your application.
 
 ## Compatibility
 
@@ -22,6 +30,8 @@ Load the component styles once in the application's global stylesheet:
 @import '@sushi-kit/angular/styles.css';
 ```
 
+See [Getting started](https://ramen-suite.github.io/sushi-angular/getting-started) for the complete setup.
+
 ## Use a component
 
 Sushi declarations are standalone. Import only what the consuming component uses:
@@ -46,8 +56,8 @@ export class Checkout {}
 <html data-theme="sushi-dark"></html>
 ```
 
-Theme tokens, component APIs, and examples are documented in the [Sushi Playground](https://ramen-suite.github.io/sushi-angular/).
+Browse component examples and APIs in the [Sushi Playground](https://ramen-suite.github.io/sushi-angular/). See [Styling and themes](https://ramen-suite.github.io/sushi-angular/styling-and-themes) for customization and the [theme token reference](https://ramen-suite.github.io/sushi-angular/theme-tokens) for built-in values.
 
 ## License
 
-[MIT](https://github.com/ramen-suite/sushi-angular/blob/main/LICENSE)
+[MIT](https://github.com/ramen-suite/sushi-angular/blob/main/LICENSE). Third-party notices are included with the published package.