readme

Author: sacrosanctic

docs/content/2.guide/3.storybook.md

@@ -4,15 +4,15 @@ Storybook is a development environment for UI components that helps catch UI cha
 
 - **Accessibility tests** - Built-in a11y checks
 - **Visual tests** - Compare JPG screenshots
-- **Vitest tests** - Use stories directly in your unit tests
+- **Vitest tests** - Use stories directly in the unit tests
 
 ## Component Categories
 
 The plan is to organize components into 3 categories.
 
 ### UI Library Components
 
-Generic and reusable components used throughout your application.
+Generic and reusable components used throughout the application.
 
 - Examples: Button, Input, Modal, Card
 - **Testing focus:** Props, variants, accessibility
@@ -42,9 +42,9 @@ TBD
 
 ## Project Conventions
 
-### Place a `.stories.ts` file next to your component
+### Place `.stories.ts` files next to the component
 
-```
+```sh
 components/
 ├── Button.vue
 └── Button.stories.ts
@@ -70,6 +70,27 @@ export const Default: Story = {
 }
 ```
 
+### JSDocs Annotation
+
+The component should include descriptive comments.
+
+```ts
+// Button.vue
+<script setup lang="ts">
+const props = withDefaults(
+  defineProps<{
+    /** Whether the button is disabled */
+    disabled?: boolean
+    /**
+     * HTML button type attribute
+     * @default "button"
+- `autodocs` usage is discouraged at this time, as it is buggy.
+    type?: 'button' | 'submit'
+    // ...
+  }>)
+</script>
+```
+
 ## Configuration
 
 Stories can be configured at three levels:
@@ -84,6 +105,6 @@ Global application settings are added to the Storybook toolbar for easy testing
 
 ## Known Limitations
 
-- `autodocs` usage is discouraged as it is buggy.
 - Changing `i18n` in the toolbar doesn't update the language. A manual story reload is required.
-- `storybook` fails to build.
+- `autodocs` currently is non-functional due bugs, its usage is discouraged at this time.
+- `storybook` currently fails to build and must be viewed in the dev environment.