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
### 1. Always Check Before Creating
Before creating any new UI component, **you must**:
1. Search the existing component library in `src/lib/a/`
2. Review `alexandria-components.json` for available components
3. Check if an existing component can be reused or extended
4. Only create new components when absolutely necessary
### 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)
- Full prop definitions with types and defaults
- Usage examples and patterns
@ -26,13 +33,16 @@ The `alexandria-components.json` file is the **single source of truth** for all
@@ -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.
### 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
### Available Categories
1. **Primitives** (8 components) - Basic UI building blocks
2. **Navigation** (2 components) - App navigation elements
3. **Forms** (4 components) - Input and editing interfaces
@ -44,7 +54,9 @@ All components use **TSDoc format** for documentation. You must maintain this st
@@ -44,7 +54,9 @@ All components use **TSDoc format** for documentation. You must maintain this st
## Component Selection Workflow
### Step 1: Identify the Need
Determine what UI functionality is required:
- User input? → Check **Forms** category
- Display content? → Check **Cards** category
- Navigation? → Check **Navigation** category
@ -59,7 +71,9 @@ For example: Finding a component for user profiles
@@ -59,7 +71,9 @@ For example: Finding a component for user profiles
- Result: AProfilePreview and ANostrUser are available
### Step 3: Review Component Props
Check the component's props in `alexandria-components.json`:
```json
{
"name": "AEventPreview",
@ -82,6 +96,7 @@ Check the component's props in `alexandria-components.json`:
@@ -82,6 +96,7 @@ Check the component's props in `alexandria-components.json`:
```
### Step 4: Review Examples
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:
@@ -111,7 +126,6 @@ Every component **must** include TSDoc comments following this exact format:
@ -126,24 +140,25 @@ Every component **must** include TSDoc comments following this exact format:
@@ -126,24 +140,25 @@ Every component **must** include TSDoc comments following this exact format:
### TSDoc Tags Reference
| Tag | Purpose | Required | Example |
|-----|---------|----------|---------|
| `@fileoverview` | Component name and description | ✅ Yes | `@fileoverview AAlert Component - Alexandria` |
| `@component` | Marks file as Svelte component | ✅ Yes | `@component` |
necessary for component-scoped styles that cannot be reused.**
### Directory Structure
@ -325,7 +355,9 @@ src/
@@ -325,7 +355,9 @@ src/
### Styling Workflow
#### 1. **Determine Component Category**
Identify which category your component belongs to:
- `primitives/` → `styles/a/primitives.css`
- `forms/` → `styles/a/forms.css`
- `cards/` → `styles/a/cards.css`
@ -333,14 +365,18 @@ Identify which category your component belongs to:
@@ -333,14 +365,18 @@ Identify which category your component belongs to:
- `reader/` → `styles/a/reader.css`
#### 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:**
- ✅ `styles/a/cards.css`
- ✅ `styles/a/forms.css`
- ✅ `styles/a/primitives.css`
**Files to create when needed:**
- ⚠️`styles/a/nav.css` (create for navigation 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/
@@ -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:
**Step A: Create the file**
```bash
# Create the new CSS file
type nul > src\styles\a\nav.css
```
**Step B: Add the CSS structure**
```css
/* src/styles/a/nav.css */
/* Alexandria Navigation Component Styles */
@ -362,19 +400,18 @@ type nul > src\styles\a\nav.css
@@ -362,19 +400,18 @@ type nul > src\styles\a\nav.css
@layer components {
/* ANavbar styles */
.navbar-alexandria {
@apply /* your Tailwind classes */;
@apply; /* your Tailwind classes */
}
/* AFooter styles */
.footer-alexandria {
@apply /* your Tailwind classes */;
@apply; /* your Tailwind classes */
}
}
```
**Step C: Import in app.css**
Add the import to `src/app.css` in the correct location, after existing imports.
**Step C: Import in app.css** Add the import to `src/app.css` in the correct
location, after existing imports.
#### 4. **Add Component Styles**
@ -431,6 +468,7 @@ let { color = "info", dismissable = false } = $props();
@@ -431,6 +468,7 @@ let { color = "info", dismissable = false } = $props();
### CSS Organization Best Practices
#### Naming Conventions
- Use descriptive, component-specific class names
- Prefix with component name or category
- Use `-leather` or `-alexandria` suffix for themed styles
@ -441,6 +479,7 @@ let { color = "info", dismissable = false } = $props();
@@ -441,6 +479,7 @@ let { color = "info", dismissable = false } = $props();
- `.form-input-alexandria`
#### File Structure Within CSS Files
Organize styles by component within each file:
```css
@ -451,38 +490,39 @@ Organize styles by component within each file:
@@ -451,38 +490,39 @@ Organize styles by component within each file:
* AMarkupForm Component
* ======================================== */
.markup-form-container {
@apply /* styles */;
@apply; /* styles */
}
.markup-form-header {
@apply /* styles */;
@apply; /* styles */
}
/* ========================================
* ACommentForm Component
* ======================================== */
.comment-form-wrapper {
@apply /* styles */;
@apply; /* styles */
}
.comment-form-textarea {
@apply /* styles */;
@apply; /* styles */
}
/* ========================================
* ATextareaWithPreview Component
* ======================================== */
.textarea-preview-container {
@apply /* styles */;
@apply; /* styles */
}
.textarea-toolbar {
@apply /* styles */;
@apply; /* styles */
}
}
```
#### Use Tailwind @apply Directive
Prefer `@apply` with Tailwind utilities over custom CSS:
```css
@ -505,6 +545,7 @@ Prefer `@apply` with Tailwind utilities over custom CSS:
@@ -505,6 +545,7 @@ Prefer `@apply` with Tailwind utilities over custom CSS:
### When Component-Scoped Styles Are Acceptable
Use `<style>` blocks in `.svelte` files ONLY when:
1. **Truly unique** - Style is used nowhere else and never will be
A comprehensive, project-scoped component library for the Alexandria nostr application. All components are built on Flowbite Svelte and Tailwind CSS, providing consistent theming and accessibility across the application.
A comprehensive, project-scoped component library for the Alexandria nostr
application. All components are built on Flowbite Svelte and Tailwind CSS,
providing consistent theming and accessibility across the application.
> **For AI Agents & Detailed Guidelines:** See [AGENTS.md](./AGENTS.md) for complete workflow instructions, styling architecture, and component creation guidelines.
> **For AI Agents & Detailed Guidelines:** See [AGENTS.md](./AGENTS.md) for
> complete workflow instructions, styling architecture, and component creation
buttercat1791
5 months ago