chore: clean up docs to make it more structured

Author: amanabiy

AGENTS.md

@@ -15,7 +15,7 @@ npm install
 ## Running Locally
 
 ```
-npm start              # starts watcher + dev server
+npm run start              # starts watcher + dev server for development pages
 npm run start:react18  # starts watcher + dev server (React 18)
 ```
 
@@ -25,7 +25,7 @@ The dev server runs at `http://localhost:8080`. Pages are served from `pages/<co
 
 For component structure, props, events, and refs, see docs/COMPONENT_CONVENTIONS.md.
 For design tokens, CSS rules, and RTL support, see docs/STYLING.md.
-For test commands and configs, see docs/TESTING.md.
+For running tests and configs, see docs/TESTING.md.
 For writing tests and test utils, see docs/WRITING_TESTS.md.
 For prettier, stylelint, and eslint (`npm run lint`), see docs/CODE_STYLE.md.
 For dev/test pages and running in the browser, see docs/DEV_PAGES.md.

docs/API_DOCS.md

@@ -1,32 +1,14 @@
 # API Documentation Comments
 
-Documentation is generated from JSDoc comments in component interface files (`src/<component>/interfaces.ts`).
-
-## Writing Prop Descriptions
-
-Every public prop must have a JSDoc comment. For union/enum props, list available options inline:
-
-```ts
-/** Determines the general styling of the button as follows:
- * * `primary` for primary buttons.
- * * `normal` for secondary buttons.
- * * `link` for tertiary buttons.
- */
-variant?: ButtonProps.Variant;
-```
+This project uses `@cloudscape-design/documenter` to generate API docs from JSDoc comments in component interface files (`src/<component>/interfaces.ts`).
 
 ## Special Tags
 
-- `@displayname` — overrides the display name for children slots (e.g. `children` → `text`)
+- `@i18n` — marks internationalization properties
+- `@analytics` — marks analytics metadata properties
+- `@deprecated` — marks deprecated properties (include replacement info)
+- `@displayname` — overrides the display name (e.g. `children` → `text`)
 
 ## Sub-types
 
-Define union types as named type aliases in the component's namespace, not as inline unions:
-
-```ts
-export namespace ButtonProps {
-  export type Variant = 'normal' | 'primary' | 'link' | 'icon' | 'inline-icon' | 'inline-link';
-}
-```
-
-Then reference them in the interface: `variant?: ButtonProps.Variant`.
+Define union types as named type aliases in the component's namespace, not as inline unions. Then reference them in the interface: `variant?: ButtonProps.Variant`.

docs/DEV_PAGES.md

@@ -2,15 +2,8 @@
 
 Dev and test pages live in `pages/<component-name>/`. They are used for local development, integration tests, and visual regression tests.
 
-## Running Dev Pages
-
-```
-npm run quick-build    # build first (required before starting)
-npm start              # starts watcher + dev server at http://localhost:8080
-```
-
 ## Rules
 
 - Import components via `~components/<name>` (not relative paths to `src/`)
-- For visual regression content, either use `SimplePage` from `pages/app/templates` (handles heading, screenshot area, i18n, and layout) or wrap content in `ScreenshotArea` from `pages/utils/screenshot-area`.
+- For visual regression content, either use `SimplePage` (handles heading, screenshot area, i18n, and layout) or wrap content in `ScreenshotArea`.
 - Use `createPermutations` and `PermutationsView` from `pages/utils/` for permutation pages.

docs/STYLING.md

@@ -2,10 +2,6 @@
 
 Prefer design tokens and custom CSS properties over hardcoded values (colors, spacing, font sizes, etc.). This keeps styles consistent across themes and modes.
 
-## Design Tokens
-
-Tokens are defined in `style-dictionary/` and consumed in SCSS via the `awsui` namespace.
-
 ## Rules
 
 - Root elements must not have outer margins — spacing is managed by parent components

docs/TESTING.md

@@ -1,4 +1,4 @@
-# Testing
+# Running Tests
 
 ## Quick Reference