@ -1,23 +1,30 @@
# Alexandria Component Library - AI Agent Guide # Alexandria Component Library - AI Agent Guide
**Version:** 1.0.0 **Version:** 1.0.0\
**Last Updated:** October 4, 2025 **Last Updated:** October 4, 2025
This guide provides comprehensive instructions for AI agents working with the Alexandria UI component library. Following these guidelines ensures consistency, maintainability, and proper integration with the existing codebase. This guide provides comprehensive instructions for AI agents working with the
Alexandria UI component library. Following these guidelines ensures consistency,
maintainability, and proper integration with the existing codebase.
--- ---
## Core Principles ## Core Principles
### 1. Always Check Before Creating ### 1. Always Check Before Creating
Before creating any new UI component, **you must** : Before creating any new UI component, **you must** :
1. Search the existing component library in `src/lib/a/` 1. Search the existing component library in `src/lib/a/`
2. Review `alexandria-components.json` for available components 2. Review `alexandria-components.json` for available components
3. Check if an existing component can be reused or extended 3. Check if an existing component can be reused or extended
4. Only create new components when absolutely necessary 4. Only create new components when absolutely necessary
### 2. Use alexandria-components.json as Your Reference ### 2. Use alexandria-components.json as Your Reference
The `alexandria-components.json` file is the **single source of truth** for all available components. It contains:
The `alexandria-components.json` file is the **single source of truth** for all
available components. It contains:
- Complete component inventory (18 components across 5 categories) - Complete component inventory (18 components across 5 categories)
- Full prop definitions with types and defaults - Full prop definitions with types and defaults
- Usage examples and patterns - Usage examples and patterns
@ -26,13 +33,16 @@ The `alexandria-components.json` file is the **single source of truth** for all
**Always consult this file first** when selecting components. **Always consult this file first** when selecting components.
### 3. Maintain TSDoc Documentation Standards ### 3. Maintain TSDoc Documentation Standards
All components use **TSDoc format** for documentation. You must maintain this standard when creating or modifying components.
All components use **TSDoc format** for documentation. You must maintain this
standard when creating or modifying components.
--- ---
## Component Inventory ## Component Inventory
### Available Categories ### Available Categories
1. **Primitives** (8 components) - Basic UI building blocks 1. **Primitives** (8 components) - Basic UI building blocks
2. **Navigation** (2 components) - App navigation elements 2. **Navigation** (2 components) - App navigation elements
3. **Forms** (4 components) - Input and editing interfaces 3. **Forms** (4 components) - Input and editing interfaces
@ -44,7 +54,9 @@ All components use **TSDoc format** for documentation. You must maintain this st
## Component Selection Workflow ## Component Selection Workflow
### Step 1: Identify the Need ### Step 1: Identify the Need
Determine what UI functionality is required: Determine what UI functionality is required:
- User input? → Check **Forms** category - User input? → Check **Forms** category
- Display content? → Check **Cards** category - Display content? → Check **Cards** category
- Navigation? → Check **Navigation** category - Navigation? → Check **Navigation** category
@ -59,7 +71,9 @@ For example: Finding a component for user profiles
- Result: AProfilePreview and ANostrUser are available - Result: AProfilePreview and ANostrUser are available
### Step 3: Review Component Props ### Step 3: Review Component Props
Check the component's props in `alexandria-components.json` : Check the component's props in `alexandria-components.json` :
```json ```json
{ {
"name": "AEventPreview", "name": "AEventPreview",
@ -82,6 +96,7 @@ Check the component's props in `alexandria-components.json`:
``` ```
### Step 4: Review Examples ### Step 4: Review Examples
Check the `examples` array in `alexandria-components.json` for usage patterns. Check the `examples` array in `alexandria-components.json` for usage patterns.
--- ---
@ -111,7 +126,6 @@ Every component **must** include TSDoc comments following this exact format:
* < ComponentName requiredProp = {value} optionalProp = {value} > < / ComponentName > * < ComponentName requiredProp = {value} optionalProp = {value} > < / ComponentName >
* ``` * ```
* *
*
* @features * @features
* - Feature 1 * - Feature 1
* - Feature 2 * - Feature 2
@ -126,24 +140,25 @@ Every component **must** include TSDoc comments following this exact format:
### TSDoc Tags Reference ### TSDoc Tags Reference
| Tag | Purpose | Required | Example | | Tag | Purpose | Required | Example |
|-----|---------|----------|---------| | --------- ------- | ------ ------------------------ | - ---------- | --------------------------------------------- |
| `@fileoverview` | Component name and description | ✅ Yes | `@fileoverview AAlert Component - Alexandria` | | `@fileoverview` | Component name and description | ✅ Yes | `@fileoverview AAlert Component - Alexandria` |
| `@component` | Marks file as Svelte component | ✅ Yes | `@component` | | `@component` | Marks file as Svelte component | ✅ Yes | `@component` |
| `@category` | Component category | ✅ Yes | `@category Primitives` | | `@category` | Component category | ✅ Yes | `@category Primitives` |
| `@prop` | Define component properties | ✅ Yes | `@prop {string} [color] - Alert color theme` | | `@prop` | Define component properties | ✅ Yes | `@prop {string} [color] - Alert color theme` |
| `@example` | Usage examples with code | ✅ Yes | See format above | | `@example` | Usage examples with code | ✅ Yes | See format above |
| `@features` | List key functionality | ✅ Yes | `- Responsive layout` | | `@features` | List key functionality | ✅ Yes | `- Responsive layout` |
| `@accessibility` | Accessibility notes | ✅ Yes | `- ARIA compliant` | | `@accessibility` | Accessibility notes | ✅ Yes | `- ARIA compliant` |
| `@since` | Version introduced | ⚠️ `@since 1.0.0` | | `@since` | Version introduced | ⚠️ `@since 1.0.0` |
--- ---
## Component Import Patterns ## Component Import Patterns
### Import ### Import
```typescript ```typescript
import { AAlert, AEventPreview, AMarkupForm } from '$lib/a' ; import { AAlert, AEventPreview, AMarkupForm } from "$lib/a" ;
``` ```
--- ---
@ -153,12 +168,14 @@ import { AAlert, AEventPreview, AMarkupForm } from '$lib/a';
### When to Create a New Component ### When to Create a New Component
**DO create a new component when:** **DO create a new component when:**
- No existing component provides the required functionality - No existing component provides the required functionality
- The component will be reused in 3+ places - The component will be reused in 3+ places
- It represents a distinct, standalone UI pattern - It represents a distinct, standalone UI pattern
- It follows the Alexandria design system - It follows the Alexandria design system
**DON'T create a new component when:** **DON'T create a new component when:**
- An existing component can be configured to meet needs - An existing component can be configured to meet needs
- It's only used once (keep in parent component) - It's only used once (keep in parent component)
- It's too generic (use Flowbite components directly) - It's too generic (use Flowbite components directly)
@ -171,7 +188,8 @@ import { AAlert, AEventPreview, AMarkupForm } from '$lib/a';
- [ ] **Name** following convention: `A[ComponentName].svelte` - [ ] **Name** following convention: `A[ComponentName].svelte`
- [ ] **Add TSDoc** documentation following standard format - [ ] **Add TSDoc** documentation following standard format
- [ ] **Create** component file in correct category folder - [ ] **Create** component file in correct category folder
- [ ] **Add styles** to appropriate `/src/styles/a/` CSS file (or create new file if needed) - [ ] **Add styles** to appropriate `/src/styles/a/` CSS file (or create new
file if needed)
- [ ] **Import new CSS file** in `app.css` if created - [ ] **Import new CSS file** in `app.css` if created
- [ ] **Export** component in `index.ts` - [ ] **Export** component in `index.ts`
- [ ] **Update** `alexandria-components.json` (run parse script) - [ ] **Update** `alexandria-components.json` (run parse script)
@ -227,7 +245,9 @@ let {
## Updating alexandria-components.json ## Updating alexandria-components.json
### When to Update ### When to Update
You **must** update `alexandria-components.json` whenever: You **must** update `alexandria-components.json` whenever:
- A new component is created - A new component is created
- Component props are added, modified, or removed - Component props are added, modified, or removed
- Component examples are updated - Component examples are updated
@ -246,12 +266,15 @@ You **must** update `alexandria-components.json` whenever:
4. **Commit** both the component file and updated JSON 4. **Commit** both the component file and updated JSON
### Parser Script Location ### Parser Script Location
- **File:** `src/lib/a/parse-components.js` - **File:** `src/lib/a/parse-components.js`
- **Purpose:** Extracts TSDoc from all `.svelte` files in the library - **Purpose:** Extracts TSDoc from all `.svelte` files in the library
- **Output:** `alexandria-components.json` - **Output:** `alexandria-components.json`
### Manual Updates (When Necessary) ### Manual Updates (When Necessary)
If the parser doesn't capture something correctly: If the parser doesn't capture something correctly:
1. First, try to fix the TSDoc format 1. First, try to fix the TSDoc format
2. Re-run the parser 2. Re-run the parser
3. Only manually edit JSON as last resort 3. Only manually edit JSON as last resort
@ -262,7 +285,9 @@ If the parser doesn't capture something correctly:
## Design System Integration ## Design System Integration
### Theme Compatibility ### Theme Compatibility
All Alexandria components support: All Alexandria components support:
- Light and dark themes - Light and dark themes
- "Leather" aesthetic (warm browns, tans) - "Leather" aesthetic (warm browns, tans)
- Flowbite-based styling - Flowbite-based styling
@ -271,6 +296,7 @@ All Alexandria components support:
### Styling Guidelines ### Styling Guidelines
**DO:** **DO:**
- Use Tailwind CSS classes - Use Tailwind CSS classes
- Leverage Flowbite Svelte components as base - Leverage Flowbite Svelte components as base
- Follow existing color patterns in library - Follow existing color patterns in library
@ -278,12 +304,14 @@ All Alexandria components support:
- Test in both light and dark modes - Test in both light and dark modes
**DON'T:** **DON'T:**
- Add arbitrary custom CSS without justification - Add arbitrary custom CSS without justification
- Override Flowbite's accessibility features - Override Flowbite's accessibility features
- Hard-code colors (use theme tokens) - Hard-code colors (use theme tokens)
- Create layout inconsistencies - Create layout inconsistencies
### Component Styling Pattern ### Component Styling Pattern
```svelte ```svelte
<!-- Use Flowbite component as base --> <!-- Use Flowbite component as base -->
< Alert color = "info" class = "leather-theme" > < Alert color = "info" class = "leather-theme" >
@ -297,9 +325,11 @@ All Alexandria components support:
### **Mandatory Styling Rules** ### **Mandatory Styling Rules**
⚠️ `/src/styles/a/` folder.** ⚠️ `/src/styles/a/`
folder.**
**DO NOT add `<style>` blocks inside component `.svelte` files unless absolutely necessary for component-scoped styles that cannot be reused.** **DO NOT add `<style>` blocks inside component `.svelte` files unless absolutely
necessary for component-scoped styles that cannot be reused.**
### Directory Structure ### Directory Structure
@ -325,7 +355,9 @@ src/
### Styling Workflow ### Styling Workflow
#### 1. **Determine Component Category** #### 1. **Determine Component Category**
Identify which category your component belongs to: Identify which category your component belongs to:
- `primitives/` → `styles/a/primitives.css` - `primitives/` → `styles/a/primitives.css`
- `forms/` → `styles/a/forms.css` - `forms/` → `styles/a/forms.css`
- `cards/` → `styles/a/cards.css` - `cards/` → `styles/a/cards.css`
@ -333,14 +365,18 @@ Identify which category your component belongs to:
- `reader/` → `styles/a/reader.css` - `reader/` → `styles/a/reader.css`
#### 2. **Check if Style File Exists** #### 2. **Check if Style File Exists**
Before adding styles, verify the corresponding CSS file exists in `src/styles/a/` :
Before adding styles, verify the corresponding CSS file exists in
`src/styles/a/` :
**Existing files:** **Existing files:**
- ✅ `styles/a/cards.css` - ✅ `styles/a/cards.css`
- ✅ `styles/a/forms.css` - ✅ `styles/a/forms.css`
- ✅ `styles/a/primitives.css` - ✅ `styles/a/primitives.css`
**Files to create when needed:** **Files to create when needed:**
- ⚠️ `styles/a/nav.css` (create for navigation components) - ⚠️ `styles/a/nav.css` (create for navigation components)
- ⚠️ `styles/a/reader.css` (create for reader components) - ⚠️ `styles/a/reader.css` (create for reader components)
@ -349,12 +385,14 @@ Before adding styles, verify the corresponding CSS file exists in `src/styles/a/
If the CSS file doesn't exist for your category: If the CSS file doesn't exist for your category:
**Step A: Create the file** **Step A: Create the file**
```bash ```bash
# Create the new CSS file # Create the new CSS file
type nul > src\styles\a\nav.css type nul > src\styles\a\nav.css
``` ```
**Step B: Add the CSS structure** **Step B: Add the CSS structure**
```css ```css
/* src/styles/a/nav.css */ /* src/styles/a/nav.css */
/* Alexandria Navigation Component Styles */ /* Alexandria Navigation Component Styles */
@ -362,19 +400,18 @@ type nul > src\styles\a\nav.css
@layer components {@layer components {
/* ANavbar styles */ /* ANavbar styles */
.navbar-alexandria { .navbar-alexandria {
@apply /* your Tailwind classes */; @apply ; /* your Tailwind classes */
} }
/* AFooter styles */ /* AFooter styles */
.footer-alexandria { .footer-alexandria {
@apply /* your Tailwind classes */; @apply ; /* your Tailwind classes */
} }
} }
``` ```
**Step C: Import in app.css** **Step C: Import in app.css** Add the import to `src/app.css` in the correct
Add the import to `src/app.css` in the correct location, after existing imports. location, after existing imports.
#### 4. **Add Component Styles** #### 4. **Add Component Styles**
@ -431,6 +468,7 @@ let { color = "info", dismissable = false } = $props();
### CSS Organization Best Practices ### CSS Organization Best Practices
#### Naming Conventions #### Naming Conventions
- Use descriptive, component-specific class names - Use descriptive, component-specific class names
- Prefix with component name or category - Prefix with component name or category
- Use `-leather` or `-alexandria` suffix for themed styles - Use `-leather` or `-alexandria` suffix for themed styles
@ -441,6 +479,7 @@ let { color = "info", dismissable = false } = $props();
- `.form-input-alexandria` - `.form-input-alexandria`
#### File Structure Within CSS Files #### File Structure Within CSS Files
Organize styles by component within each file: Organize styles by component within each file:
```css ```css
@ -451,38 +490,39 @@ Organize styles by component within each file:
* AMarkupForm Component * AMarkupForm Component
* ======================================== * / * ======================================== * /
.markup-form-container { .markup-form-container {
@apply /* styles */; @apply ; /* styles */
} }
.markup-form-header { .markup-form-header {
@apply /* styles */; @apply ; /* styles */
} }
/* ======================================== /* ========================================
* ACommentForm Component * ACommentForm Component
* ======================================== * / * ======================================== * /
.comment-form-wrapper { .comment-form-wrapper {
@apply /* styles */; @apply ; /* styles */
} }
.comment-form-textarea { .comment-form-textarea {
@apply /* styles */; @apply ; /* styles */
} }
/* ======================================== /* ========================================
* ATextareaWithPreview Component * ATextareaWithPreview Component
* ======================================== * / * ======================================== * /
.textarea-preview-container { .textarea-preview-container {
@apply /* styles */; @apply ; /* styles */
} }
.textarea-toolbar { .textarea-toolbar {
@apply /* styles */; @apply ; /* styles */
} }
} }
``` ```
#### Use Tailwind @apply Directive #### Use Tailwind @apply Directive
Prefer `@apply` with Tailwind utilities over custom CSS: Prefer `@apply` with Tailwind utilities over custom CSS:
```css ```css
@ -505,6 +545,7 @@ Prefer `@apply` with Tailwind utilities over custom CSS:
### When Component-Scoped Styles Are Acceptable ### When Component-Scoped Styles Are Acceptable
Use `<style>` blocks in `.svelte` files ONLY when: Use `<style>` blocks in `.svelte` files ONLY when:
1. **Truly unique** - Style is used nowhere else and never will be 1. **Truly unique** - Style is used nowhere else and never will be
2. **Animation keyframes** - Component-specific animations 2. **Animation keyframes** - Component-specific animations
3. **CSS variables** - Component-specific custom properties 3. **CSS variables** - Component-specific custom properties
@ -543,11 +584,13 @@ Use `<style>` blocks in `.svelte` files ONLY when:
**Step 1:** Check if `styles/a/nav.css` exists (it doesn't) **Step 1:** Check if `styles/a/nav.css` exists (it doesn't)
**Step 2:** Create the file **Step 2:** Create the file
```bash ```bash
type nul > src\styles\a\nav.css type nul > src\styles\a\nav.css
``` ```
**Step 3:** Add styles to the new file **Step 3:** Add styles to the new file
```css ```css
/* src/styles/a/nav.css */ /* src/styles/a/nav.css */
/* Alexandria Navigation Component Styles */ /* Alexandria Navigation Component Styles */
@ -583,15 +626,17 @@ type nul > src\styles\a\nav.css
``` ```
**Step 4:** Import in app.css **Step 4:** Import in app.css
```css ```css
/* src/app.css */ /* src/app.css */
@import "./styles/a/cards.css";@import "./styles/a/cards.css";
@import "./styles/a/forms.css";@import "./styles/a/forms.css";
@import "./styles/a/primitives.css";@import "./styles/a/primitives.css";
@import "./styles/a/nav.css"; /* ← NEW */@import "./styles/a/nav.css"; /* ← NEW */
``` ```
**Step 5:** Use in component **Step 5:** Use in component
```svelte ```svelte
<!-- src/lib/a/nav/ANavbar.svelte --> <!-- src/lib/a/nav/ANavbar.svelte -->
< script lang = "ts" > < script lang = "ts" >
@ -612,6 +657,7 @@ import { Navbar } from "flowbite-svelte";
## Testing Requirements ## Testing Requirements
### Component Testing ### Component Testing
When creating or modifying components: When creating or modifying components:
1. **Visual Testing** 1. **Visual Testing**
@ -640,11 +686,13 @@ When creating or modifying components:
## Common Patterns & Best Practices ## Common Patterns & Best Practices
### Bindable Props ### Bindable Props
Use `$bindable` for two-way data binding: Use `$bindable` for two-way data binding:
```typescript ```typescript
let { let {
value = $bindable(""), value = $bindable(""),
isOpen = $bindable(false) isOpen = $bindable(false),
} = $props< { } = $props< {
value?: string; value?: string;
isOpen?: boolean; isOpen?: boolean;
@ -652,11 +700,13 @@ let {
``` ```
### Event Handlers ### Event Handlers
Use optional function props for callbacks: Use optional function props for callbacks:
```typescript ```typescript
let { let {
onSubmit = async () => {}, onSubmit = async () => {},
onClick onClick,
} = $props< { } = $props< {
onSubmit?: (data: string) => Promise< void > ; onSubmit?: (data: string) => Promise< void > ;
onClick?: () => void; onClick?: () => void;
@ -664,6 +714,7 @@ let {
``` ```
### Conditional Rendering ### Conditional Rendering
```svelte ```svelte
{#if showContent} {#if showContent}
< div > Content< / div > < div > Content< / div >
@ -671,7 +722,9 @@ let {
``` ```
### Snippets (Svelte 5) ### Snippets (Svelte 5)
For flexible content slots: For flexible content slots:
```typescript ```typescript
@prop {snippet} children - Main content (required)@prop {snippet} children - Main content (required)
@prop {snippet} [title] - Optional title section@prop {snippet} [title] - Optional title section
@ -688,18 +741,21 @@ For flexible content slots:
## Common Mistakes to Avoid ## Common Mistakes to Avoid
### DON'T: Create duplicate components ### DON'T: Create duplicate components
```typescript ```typescript
// Bad: Creating new component without checking // Bad: Creating new component without checking
export default AUserCard.svelte // AProfilePreview already exists! export default AUserCard.svelte; // AProfilePreview already exists!
``` ```
### DO: Use existing components ### DO: Use existing components
```typescript ```typescript
// Good: Use existing component // Good: Use existing component
import { AProfilePreview } from '$lib/a' ; import { AProfilePreview } from "$lib/a" ;
``` ```
### DON'T: Skip TSDoc documentation ### DON'T: Skip TSDoc documentation
```svelte ```svelte
<!-- Bad: No documentation --> <!-- Bad: No documentation -->
< script > < script >
@ -708,6 +764,7 @@ let { prop } = $props();
``` ```
### DO: Add complete TSDoc ### DO: Add complete TSDoc
```svelte ```svelte
<!-- Good: Complete documentation --> <!-- Good: Complete documentation -->
< script > < script >
@ -720,12 +777,14 @@ let { prop } = $props();
``` ```
### DON'T: Forget to update JSON ### DON'T: Forget to update JSON
```bash ```bash
# Bad: Only editing component, not updating JSON # Bad: Only editing component, not updating JSON
# (Other agents won't know about your changes!) # (Other agents won't know about your changes!)
``` ```
### DO: Always run the parser ### DO: Always run the parser
```bash ```bash
# Good: Update JSON after changes # Good: Update JSON after changes
cd src/lib/a cd src/lib/a
@ -733,12 +792,14 @@ node parse-components.js
``` ```
### DON'T: Use generic component names ### DON'T: Use generic component names
```typescript ```typescript
// Bad: Could be anything // Bad: Could be anything
export UserDisplay.svelte export UserDisplay.svelte
``` ```
### DO: Follow naming convention ### DO: Follow naming convention
```typescript ```typescript
// Good: Clearly part of Alexandria library // Good: Clearly part of Alexandria library
export ANostrUser.svelte export ANostrUser.svelte
@ -749,6 +810,7 @@ export ANostrUser.svelte
## Integration with Application ## Integration with Application
### Directory Structure ### Directory Structure
``` ```
src/lib/a/ src/lib/a/
├── AGENTS.md ← This file ├── AGENTS.md ← This file
@ -778,9 +840,11 @@ src/lib/a/
## Examples: Component Selection Scenarios ## Examples: Component Selection Scenarios
### Scenario 1: Displaying User Information ### Scenario 1: Displaying User Information
**Need:** Show user profile with avatar and bio **Need:** Show user profile with avatar and bio
**Process:** **Process:**
1. Check `alexandria-components.json` for "user" or "profile" 1. Check `alexandria-components.json` for "user" or "profile"
2. Find: `ANostrUser` (compact) and `AProfilePreview` (full card) 2. Find: `ANostrUser` (compact) and `AProfilePreview` (full card)
3. Choose based on needs: 3. Choose based on needs:
@ -788,6 +852,7 @@ src/lib/a/
- Full profile card: `AProfilePreview` - Full profile card: `AProfilePreview`
**Solution:** **Solution:**
```svelte ```svelte
< AProfilePreview < AProfilePreview
{npub} {npub}
@ -797,14 +862,17 @@ src/lib/a/
``` ```
### Scenario 2: Creating a Comment Form ### Scenario 2: Creating a Comment Form
**Need:** Allow users to write and submit comments **Need:** Allow users to write and submit comments
**Process:** **Process:**
1. Check `alexandria-components.json` under "Forms" 1. Check `alexandria-components.json` under "Forms"
2. Find: `ACommentForm` - "Comment creation with markup support" 2. Find: `ACommentForm` - "Comment creation with markup support"
3. Review props: `content` , `placeholder` , `onSubmit` 3. Review props: `content` , `placeholder` , `onSubmit`
**Solution:** **Solution:**
```svelte ```svelte
< ACommentForm < ACommentForm
bind:content={commentText} bind:content={commentText}
@ -814,14 +882,17 @@ src/lib/a/
``` ```
### Scenario 3: Showing Event Cards ### Scenario 3: Showing Event Cards
**Need:** Display nostr events in a feed **Need:** Display nostr events in a feed
**Process:** **Process:**
1. Check `alexandria-components.json` under "Cards" 1. Check `alexandria-components.json` under "Cards"
2. Find: `AEventPreview` - "Event preview cards with metadata and actions" 2. Find: `AEventPreview` - "Event preview cards with metadata and actions"
3. Review configurable options: `showContent` , `truncateContentAt` , etc. 3. Review configurable options: `showContent` , `truncateContentAt` , etc.
**Solution:** **Solution:**
```svelte ```svelte
{#each events as event} {#each events as event}
< AEventPreview < AEventPreview
@ -834,14 +905,17 @@ src/lib/a/
``` ```
### Scenario 4: Alert/Notification ### Scenario 4: Alert/Notification
**Need:** Show success message after save **Need:** Show success message after save
**Process:** **Process:**
1. Check "Primitives" category 1. Check "Primitives" category
2. Find: `AAlert` - "Themed alert messages with dismissal options" 2. Find: `AAlert` - "Themed alert messages with dismissal options"
3. Review color options and dismissable prop 3. Review color options and dismissable prop
**Solution:** **Solution:**
```svelte ```svelte
{#if saveSuccessful} {#if saveSuccessful}
< AAlert color = "success" dismissable = {true} > < AAlert color = "success" dismissable = {true} >
@ -855,24 +929,28 @@ src/lib/a/
## Troubleshooting ## Troubleshooting
### Component Not Found ### Component Not Found
1. Verify component exists in `alexandria-components.json` 1. Verify component exists in `alexandria-components.json`
2. Check import statement syntax 2. Check import statement syntax
3. Ensure component is exported in `index.ts` 3. Ensure component is exported in `index.ts`
4. Check file path matches category structure 4. Check file path matches category structure
### Props Not Working ### Props Not Working
1. Check prop name spelling in `alexandria-components.json` 1. Check prop name spelling in `alexandria-components.json`
2. Verify prop type matches expected type 2. Verify prop type matches expected type
3. Check if prop is bindable (use `bind:` prefix if needed) 3. Check if prop is bindable (use `bind:` prefix if needed)
4. Review component TSDoc for usage examples 4. Review component TSDoc for usage examples
### Styling Issues ### Styling Issues
1. Verify theme mode (light/dark) is set correctly 1. Verify theme mode (light/dark) is set correctly
2. Check if custom classes conflict with Flowbite 2. Check if custom classes conflict with Flowbite
3. Ensure Tailwind classes are being applied 3. Ensure Tailwind classes are being applied
4. Test in isolation to identify conflicts 4. Test in isolation to identify conflicts
### Documentation Out of Sync ### Documentation Out of Sync
1. Run parser script: `node parse-components.js` 1. Run parser script: `node parse-components.js`
2. Verify TSDoc format is correct 2. Verify TSDoc format is correct
3. Check for syntax errors in TSDoc comments 3. Check for syntax errors in TSDoc comments
@ -883,20 +961,25 @@ src/lib/a/
## Additional Resources ## Additional Resources
### Related Files ### Related Files
- **README.md** : User-facing library documentation - **README.md** : User-facing library documentation
- **index.ts** : Component export definitions - **index.ts** : Component export definitions
- **parse-components.js** : TSDoc extraction script - **parse-components.js** : TSDoc extraction script
- **alexandria-components.json** : Generated component registry - **alexandria-components.json** : Generated component registry
### External Documentation ### External Documentation
- [Flowbite Svelte ](https://flowbite-svelte.com/ ) - Base component library - [Flowbite Svelte ](https://flowbite-svelte.com/ ) - Base component library
- [Tailwind CSS ](https://tailwindcss.com/ ) - Styling framework - [Tailwind CSS ](https://tailwindcss.com/ ) - Styling framework
- [TSDoc ](https://tsdoc.org/ ) - Documentation standard - [TSDoc ](https://tsdoc.org/ ) - Documentation standard
- [Svelte 5 Docs ](https://svelte.dev/docs ) - Svelte framework - [Svelte 5 Docs ](https://svelte.dev/docs ) - Svelte framework
### Nostr-Specific ### Nostr-Specific
- [NDK Documentation ](https://github.com/nostr-dev-kit/ndk ) - Nostr Development Kit
- [NIPs ](https://github.com/nostr-protocol/nips ) - Nostr Implementation Possibilities - [NDK Documentation ](https://github.com/nostr-dev-kit/ndk ) - Nostr Development
Kit
- [NIPs ](https://github.com/nostr-protocol/nips ) - Nostr Implementation
Possibilities
--- ---
@ -911,7 +994,8 @@ Before creating or modifying any UI component:
- [ ] Named component with `A` prefix (e.g., `AComponentName` ) - [ ] Named component with `A` prefix (e.g., `AComponentName` )
- [ ] Added complete TSDoc documentation - [ ] Added complete TSDoc documentation
- [ ] Followed TSDoc format exactly as documented - [ ] Followed TSDoc format exactly as documented
- [ ] Included all required tags (@fileoverview, @component , @category , @prop , @example , @features , @accessibility ) - [ ] Included all required tags (@fileoverview, @component , @category , @prop ,
@example , @features , @accessibility )
- [ ] Added component export to `index.ts` - [ ] Added component export to `index.ts`
- [ ] Ran `node parse-components.js` to update JSON - [ ] Ran `node parse-components.js` to update JSON
- [ ] Tested component in light and dark themes - [ ] Tested component in light and dark themes
@ -922,17 +1006,21 @@ Before creating or modifying any UI component:
## Summary ## Summary
1. **Always search first** - Check `alexandria-components.json` before creating anything 1. **Always search first** - Check `alexandria-components.json` before creating
2. **Use TSDoc religiously** - Every component must have complete TSDoc documentation anything
2. **Use TSDoc religiously** - Every component must have complete TSDoc
documentation
3. **Update the JSON** - Run parser script after any component changes 3. **Update the JSON** - Run parser script after any component changes
4. **Follow naming conventions** - `A` prefix, PascalCase, descriptive names 4. **Follow naming conventions** - `A` prefix, PascalCase, descriptive names
5. **Maintain consistency** - Match existing patterns and style 5. **Maintain consistency** - Match existing patterns and style
7 . **Don't reinvent** - Reuse existing components whenever possible6 . **Don't reinvent** - Reuse existing components whenever possible
**Remember:** The goal is to maintain a cohesive, well-documented, and easily discoverable **Remember:** The goal is to maintain a cohesive, well-documented, and easily
component library that serves the entire Alexandria application ecosystem. discoverable component library that serves the entire Alexandria application
ecosystem.
--- ---
**Questions or Issues?** **Questions or Issues?**\
Refer to this guide, review existing components for patterns, or check the main README.md for additional context. Refer to this guide, review existing components for patterns, or check the main
README.md for additional context.
buttercat1791
5 months ago