feat(sushi): polish components and playground design

README.md

@@ -2,10 +2,13 @@
 
 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.
 
-## Requirements
+## Compatibility
 
-- Angular 22.x
-- A modern browser
+| Sushi Kit | Angular |
+| --------- | ------- |
+| `0.1.x`   | `22.x`  |
+
+The package peer dependencies are the source of truth for the supported Angular range.
 
 Sushi ships the compiled CSS required by its components.
 

docs/component-styling.md

@@ -38,7 +38,7 @@ The generator places documented `--sui-*` properties on the feature's Theming pa
 The global theme reference is generated from `sushi.themes.css`. Document every token in the light theme and define the same token in the dark theme:
 
 ```css
-/** @group Brand | Primary actions and selection. */
+/** @group Brand | Primary actions and emphasis. */
 --color-primary: #7a0712;
 ```
 
@@ -57,6 +57,9 @@ The package build compiles this source into the published `styles.css`. The play
 - Prefer a Sushi component, then a DaisyUI primitive, then Tailwind utilities, then feature CSS.
 - Keep the public API independent of DaisyUI and Tailwind class names.
 - Put consumer-layout utilities on consumer-owned elements.
+- Use neutral surfaces for ordinary hover and selection states; reserve the primary color for actions and emphasis.
+- Keep option height, padding, borders, and radii consistent with adjacent controls. Make stable component dimensions overridable through documented tokens.
+- Show the component by itself in the first Playground example; demonstrate composition separately.
 - Avoid `!important`, broad selectors, duplicated theme colors, and fixed overlay positioning.
 - Respect `prefers-reduced-motion`.
 - Check light and dark themes, long content, zoom, and narrow viewports.

docs/getting-started.md

@@ -1,14 +1,20 @@
-# Getting started
+## Compatibility
+
+| Sushi Kit | Angular |
+| --------- | ------- |
+| `0.1.x`   | `22.x`  |
 
-Sushi requires Angular 22.x.
+The package peer dependencies are the source of truth for the supported Angular range.
+
+# Getting started
 
 ## 1. Install
 
 ```bash
 npm install @sushi-kit/angular
 ```
 
-npm installs the Angular, CDK, Aria, Router, RxJS, Lucide, and PhotoSwipe peer dependencies required by the package.
+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
 

docs/styling-and-themes.md

@@ -1,15 +1,15 @@
 # Styling and themes
 
-Sushi ships compiled component CSS and two themes. Its styling implementation builds on DaisyUI, but DaisyUI is not part of the Sushi consumer API. The stylesheet does not include Tailwind's global Preflight reset.
+Sushi ships compiled component CSS and two themes. Its styling implementation builds on [DaisyUI](https://daisyui.com/), but DaisyUI is not part of the Sushi consumer API. The stylesheet does not include Tailwind's global Preflight reset.
 
 ## Choose the right styling level
 
 1. Use a component input for a supported state or appearance.
 2. Use a documented `--sui-*` token to change one component.
 3. Change semantic theme tokens for an application-wide design decision.
-4. Use Tailwind utilities for consumer-owned layout and responsive composition.
+4. Use [Tailwind CSS](https://tailwindcss.com/) utilities for consumer-owned layout and responsive composition.
 
-Do not target a Sushi component's internal elements or classes.
+We do not recommend targeting a Sushi component's internal elements or classes.
 
 ## Customize one component
 
@@ -64,7 +64,7 @@ A nested `data-theme` applies another theme to that region. Keep foreground and
 
 ## Theme contract
 
-Use the DaisyUI color roles for the application palette. Every background color has a matching `*-content` foreground.
+Sushi exposes semantic color roles for the application palette. They follow [DaisyUI's color system](https://daisyui.com/docs/colors/); pair each background role with its matching `*-content` foreground.
 
 | Role                                                                  | Purpose                                           |
 | --------------------------------------------------------------------- | ------------------------------------------------- |
@@ -90,9 +90,11 @@ Sushi derives shared interaction and overlay styles from these semantic tokens.
 
 Component tokens remain the correct choice for a local exception. For example, `--sui-popover-shadow` defaults to `--sui-shadow-overlay` but can be changed on one popover.
 
+See the [theme token reference](theme-tokens.md) for every built-in light and dark value.
+
 ## Tailwind recommendation
 
-Tailwind is the recommended way to compose application layout around Sushi components. Install it when the application needs utilities:
+[Tailwind CSS](https://tailwindcss.com/docs/installation/framework-guides/angular) is the recommended way to compose application layout around Sushi components. Install it when the application needs utilities:
 
 ```bash
 npm install --save-dev tailwindcss @tailwindcss/postcss postcss

docs/theme-tokens.md

@@ -0,0 +1 @@
+The reference is generated from the built-in light and dark themes. Set related background and content tokens together to preserve contrast.